API reference

find_sources(A; kwargs...) -> xs, ys

Detect sources in a single 2-D image and return their x and y coordinates.

This is the simple one-shot API. For repeated processing of many images, use SourceExtractor and extract_sources! to reuse prepared buffers.

Example

xs, ys = find_sources(image)

find_sources!(extractor, A) -> xs, ys

Run a prepared SourceExtractor and return x/y coordinates.

This method reuses the extractor's prepared buffers.

SourceExtractor

Prepared high-level source-extraction pipeline.

A SourceExtractor owns all reusable state required for:

1. DoG filtering
2. local-maximum source detection
3. optional ROI extraction

The extractor is prepared for the size and backend of the array used to construct it. Repeated calls to extract_sources! reuse the same buffers.

If roi_size === nothing, no ROI storage is allocated and only source indices and scores are produced.

SourceExtractionResult

Result returned by extract_sources!.

The result references storage owned by its SourceExtractor. A subsequent call to extract_sources! using the same extractor may overwrite the data.

Use copy(source_indices(result)), copy(source_scores(result)), or copy(source_rois(result)) if the data must persist independently.

extract_sources!(extractor, A)

Run the complete prepared source-extraction pipeline.

The operation consists of:

1. DoG filtering
2. local-maximum detection
3. optional ROI extraction from the original input array

The returned SourceExtractionResult references the extractor's reusable buffers and is overwritten by subsequent calls using the same extractor.

For CUDA arrays, obtaining the source count requires a small device-to-host synchronization before ROI extraction.

source_count(result)

Return the number of detected sources.

source_indices(result)

Return a view containing the valid detected source indices.

source_scores(result)

Return a view containing the valid source scores.

source_rois(result)

Return a view containing the valid extracted ROIs.

Returns nothing if the SourceExtractor was constructed without roi_size.

LocalMaximaDetector(threshold; radius=1, strict=true)

Detector for identifying local maxima above threshold.

A candidate pixel must be greater than all pixels inside a (2radius + 1) × (2radius + 1) neighborhood when strict=true.

The detection radius is encoded in the detector type so that small fixed neighborhoods can be specialized by the compiler.

DetectionWorkspace

Preallocated storage for detected source positions, scores, and count.

The underlying storage may reside on the CPU or another backend such as CUDA.

detect_sources!(
    indices,
    scores,
    A,
    detector;
    border=radius(detector),
)

Detect local maxima in the 2-D array A.

Detected source positions are written into the preallocated indices array and their corresponding image values into scores.

Returns the number of detected sources.

No allocations are required when the supplied output buffers have sufficient capacity.

detect_sources!(indices, scores, A::AbstractArray{T,3}, detector)

Detect sources independently in every frame of an x × y × frame array.

Local-maxima comparisons are performed only within each frame.

DoG(sigma1, sigma2)

Difference-of-Gaussians filter specification.

sigma1 is the width of the narrower Gaussian and sigma2 the width of the broader Gaussian.

prepare_dog(array_type, size, dog)

Prepare the separable Gaussian components of a Difference-of-Gaussians filter for a given array type and size.

This operation may allocate. The returned object is intended to be reused.

dog_kernel!(dst, prepared)

Materialize a prepared Difference-of-Gaussians kernel into dst.

prepare_filter(A, dog)

Prepare an FFT-based Difference-of-Gaussians filter for arrays with the same size and type as A.

All FFT plans, Fourier-domain kernel data, and working buffers are allocated during this step and reused during filtering.

filter_sources!(prepared, A)

Apply a prepared source-enhancement filter to A.

The returned array is an internal reusable buffer owned by prepared. Its contents will be overwritten by the next call using the same prepared filter.

filter_sources!(dst, A, prepared)

Apply the prepared filter and copy the result into dst.

extract_rois!(rois, A, indices, n)

Extract fixed-size 2-D ROIs centered on the first n source positions.

rois must have dimensions

(roi_x, roi_y, max_sources)

and both ROI dimensions must be odd.

Returns n.

extract_rois!(rois, A, workspace::DetectionWorkspace, n)

Extract ROIs using source indices stored in a detection workspace.