vista.algorithms.detectors.cfar.CFAR

class vista.algorithms.detectors.cfar.CFAR(background_radius, ignore_radius, threshold_deviation, min_area=1, max_area=1000, annulus_shape='circular', detection_mode='above', search_radius=None)[source]

Detector that uses local standard deviation-based thresholding to find blobs.

Uses CFAR (Constant False Alarm Rate) approach where each pixel is compared to a multiple of the standard deviation in its neighborhood. The neighborhood is defined as an annular ring (background radius excluding ignore radius).

Can detect pixels above threshold, below threshold, or both (absolute deviation). Uses FFT-based convolution for efficient computation of local statistics.

Parameters:

  • background_radius (int) – Outer radius for neighborhood statistics calculation (pixels)

  • ignore_radius (int) – Inner radius to exclude from neighborhood (pixels)

  • threshold_deviation (float) – Number of standard deviations above/below mean for detection threshold

  • min_area (int, optional) – Minimum detection blob area in pixels, by default 1

  • max_area (int, optional) – Maximum detection blob area in pixels, by default 1000

  • annulus_shape (str, optional) – Shape of the annulus (‘circular’ or ‘square’), by default ‘circular’

  • detection_mode (str, optional) – Detection mode, by default ‘above’: - ‘above’: Detect pixels brighter than threshold (mean + threshold*std) - ‘below’: Detect pixels darker than threshold (mean - threshold*std) - ‘both’: Detect pixels deviating from mean in either direction

  • search_radius (int, optional) – When specified, only keep the blob whose weighted centroid is closest to the search_center (or image center) and within this radius. Used for chip-based detection where only blobs near the center are of interest. By default None (keep all blobs)

name

Algorithm name (“Constant False Alarm Rate”)

Type:

str

kernel

Pre-computed annular kernel for convolution

Type:

ndarray

n_pixels

Number of pixels in the annular neighborhood

Type:

int

__call__(image, search_center=None)[source]

Process single image and return detections as (rows, columns)

process_chip(chip, search_center=None)[source]

Process chip and return (signal_mask, noise_std) for track extraction

Notes

  • Detection threshold formula (above mode): pixel > mean + threshold_deviation * std

  • Detection threshold formula (below mode): pixel < mean - threshold_deviation * std

  • Detection threshold formula (both mode): |pixel - mean| > threshold_deviation * std

  • Detected pixels are grouped into connected blobs using 8-connectivity

  • Blobs are filtered by area (min_area <= area <= max_area)

  • Blob centroids are returned as sub-pixel coordinates

  • Kernel FFT is cached by image shape for efficiency

Examples

>>> from vista.algorithms.detectors.cfar import CFAR
>>> cfar = CFAR(background_radius=10, ignore_radius=3,
...             threshold_deviation=3.0, min_area=1, max_area=100)
>>> # Process single frame
>>> rows, columns = cfar(image)
>>> # Process chip with search radius
>>> signal_mask, noise_std = cfar.process_chip(chip, search_center=(chip_size//2, chip_size//2))
__init__(background_radius, ignore_radius, threshold_deviation, min_area=1, max_area=1000, annulus_shape='circular', detection_mode='above', search_radius=None)[source]

Methods

__init__(background_radius, ignore_radius, ...)

process_chip(chip[, search_center])

Process a chip and return detailed signal information.

Attributes

name

name = 'Constant False Alarm Rate'
__init__(background_radius, ignore_radius, threshold_deviation, min_area=1, max_area=1000, annulus_shape='circular', detection_mode='above', search_radius=None)[source]
__call__(image, search_center=None)[source]

Process a single image and return detection centroids.

Parameters:

  • image (ndarray) – 2D image array to process

  • search_center (tuple, optional) – (row, col) for search_radius filtering. If None and search_radius is set, uses image center. If search_radius is None, this parameter is ignored.

Returns:

  • rows (ndarray) – Array of detection centroid row coordinates

  • columns (ndarray) – Array of detection centroid column coordinates

process_chip(chip, search_center=None)[source]

Process a chip and return detailed signal information.

This method is designed for track extraction, where both the signal mask and noise statistics are needed.

Parameters:

  • chip (ndarray) – 2D image chip (may contain NaN values at edges)

  • search_center (tuple, optional) – (row, col) for search_radius filtering. If None and search_radius is set, uses chip center. If search_radius is None, this parameter is ignored.

Returns:

  • signal_mask (ndarray) – Boolean mask of signal pixels (same shape as chip)

  • noise_std (float) – Noise standard deviation at chip center

Notes

  • NaN values in the chip are replaced with 0 for processing and masked out

  • Uses search_radius to filter blobs (keeps closest by weighted centroid)

  • Returns full signal mask (all pixels in the blob), not just centroids