Detection Refiners

class byotrack.implementation.detector.refiners.DetectionsFilter(*, min_area=0.0, max_area=inf, min_intensity=0.0, max_intensity=inf, min_peak=0.0)

Bases: DetectionsRefiner

Filter detections based on simple intensity and size criteria.

If images have multiple channels, channels are averaged into a single per-pixel intensity.

Note: Detections out of the field of view have an area and intensity of 0.

min_area

Minimum area (pixels) to be kept in the segmentation

Type:

float

max_area

Minimum area (pixels) to be kept in the segmentation

Type:

float

min_intensity

Minimum intensity (summed) to be kept in the segmentation

Type:

float

max_intensity

Maximum intensity (summed) to be kept in the segmentation

Type:

float

min_peak

Minimum peak intensity to be kept in the segmentation

Type:

float

apply(detections, frame=None)

Refines Detections of the given frame.

Parameters:

  • detections (byotrack.DetectionsLike) – Detections to refine

  • frame (np.ndarray | None) – The associated frame of the video (optional) Shape: ([D, ]H, W, C) Default: None

Returns:

Refined detections

Return type:

byotrack.Detections

class byotrack.implementation.detector.refiners.Watershed(maximum_footprint: ndarray | None = None, maximum_dilation: ndarray | None = None, min_peak_intensity=0.0)

Bases: object

Peak extraction and watershed labeling.

Warning: This part is still experimental and may change in the following versions

The algorithm works in 2 steps:

  1. Local maxima extraction that will defined the new labels. These are defined on a given image, or from the distance transform of binary mask to label. Neighboring local maxima are clustered with ndi.label to reduce oversegmentation (with a binary dilation to bridge over small gaps).

  2. Watershed algorithm is used to label each pixel in the mask with its corresponding peak

maximum_footprint

Binary kernel to use for maximum filtering. Local maxima are defined as pixels that are equal or above all their neighbors defined in this kernel. Shape: ([d, ]h, w), dtype: bool By default, the footprint is a 3x3 square/cube (considering only direct neighbors, including diagonal ones)

Type:

np.ndarray | None

maximum_dilation

Apply binary dilation to the local maxima mask before running ndi.label. Connected local maxima are merged in a single label before running watershed. Shape: ([d, ]h, w), dtype: bool By default, dilation is not applied. Only direct maxima neighbors (including diagonal ones) are merged.

Type:

np.ndarray | None

min_peak_intensity

Filter local maxima based on their intensity.

Type:

float

peak_mask(image: ndarray, mask: ndarray) → ndarray

Extract local maxima (peaks) in the image, that are included in mask.

Peaks are returned as a boolean image

watershed(mask: ndarray, source_map: ndarray | None = None) → ndarray

Run watershed on the given mask.

If source_map is not given, the distance map of the mask is used to find local maxima and use watershed.

Parameters:

  • mask (np.ndarray) – Binary segmentation to label into instance segmentation. Shape: ([D, ]H, W), dtype: np.uint8 (or bool)

  • source_map (np.ndarray | None) – “Intensity” value for each pixel of the mask. Local maxima are extracted from this map and watershed fills the segmentation based on these intensities. Shape: ([D, ], H, W), dtype: np.float

Returns:

Instance segmentation (label) for the given mask

Shape: ([D, ]H, W), dtype: np.int32

Return type:

np.ndarray

class byotrack.implementation.detector.refiners.WatershedRefiner(watershed: Watershed, mode: Mode = Mode.EDT, sigma=0.0)

Bases: DetectionsRefiner

Apply Watershed to the given segmentation.

It will convert the instance segmentation of Detections into a binary one, and then apply watershed labeling (see Watershed).

Note that confidence and labels are not preserved by the current implementation.

Warning: This is still experimental and this may change in future versions

Parameters:

  • watershed (Watershed) – Watershed labeler to use

  • mode (WatershedRefiner.Mode) – Watershed mode. INTENSITY uses images, EDT distance transforms and EDT_LABEL distance transforms by label (avoiding under-segmentation).

  • sigma (float) – Apply Gaussian smoothing on the frame intensities before running Watershed. Only used for INTENSITY mode. Default: 0.0 (no smoothing)

class Mode(*values)

Bases: Enum

Watershed Mode.

  • INTENSITY: Use the averaged intensity in the image to find local maxima and solve watershed

  • EDT: Use the distance transform of the binary segmentation

  • EDT_LABEL: Use the distance transform computed by label in the original segmentation. This ensure

    that at least on maxima is found by label, avoiding merging neighboring labels. (More costly)

apply(detections, frame=None)

Refines Detections of the given frame.

Parameters:

  • detections (byotrack.DetectionsLike) – Detections to refine

  • frame (np.ndarray | None) – The associated frame of the video (optional) Shape: ([D, ]H, W, C) Default: None

Returns:

Refined detections

Return type:

byotrack.Detections