phenotypic.detect.CannyDetector

class phenotypic.detect.CannyDetector(sigma: float = 1.0, low_threshold: float = 0.1, high_threshold: float = 0.2, use_quantiles: bool = True, min_size: int = 50, invert_edges: bool = True, connectivity: int = 1)

Bases: ThresholdDetector

Canny edge-based object detection for microbial colonies.

Applies the Canny edge detector to identify colony boundaries, then labels the enclosed regions as individual objects. The Canny algorithm uses a multi-stage process: Gaussian smoothing, gradient calculation, non-maximum suppression, and hysteresis thresholding to produce thin, connected edges that robustly delineate colony perimeters even in noisy or unevenly illuminated images.

Use cases (agar plates): - Detect well-separated colonies with clear boundaries on solid media where

edge sharpness dominates over intensity differences.

• Handle plates with variable illumination or low contrast that challenge intensity-based thresholding (e.g., translucent colonies on light agar).

• Segment colonies with heterogeneous internal texture or pigmentation that might fragment under watershed or simple thresholding.

• Robustly trace colony perimeters when background subtraction is imperfect or when agar texture is pronounced.

Caveats: - Canny assumes objects are defined by edges. Colonies with very diffuse or

gradual boundaries (e.g., fuzzy/mucoid colonies) may yield incomplete or fragmented edges, resulting in under-segmentation or missed objects.

• Overlapping or touching colonies may be outlined as a single contiguous edge, causing multiple colonies to merge into one object. Pre-blur or increase sigma to regularize boundaries, or use watershed refinement post- detection to split merged regions.

• Threshold tuning is critical: too aggressive and noise dominates, too conservative and colony boundaries vanish. use_quantiles=True often provides a safer starting point.

• Does not inherently handle intensity-based segmentation; if colonies differ mainly in brightness (not edges), consider Otsu or watershed instead.

• May detect plate edges, dust, or scratches as spurious boundaries. Use min_size filtering and ensure clean agar surfaces or pre-mask the plate region if needed.

Parameters:

• sigma (float)

• low_threshold (float)

• high_threshold (float)

• use_quantiles (bool)

• min_size (int)

• invert_edges (bool)

• connectivity (int)

sigma

Standard deviation for Gaussian smoothing applied before edge detection, controlling pre-smoothing intensity. Higher values reduce noise sensitivity and suppress spurious edges from agar granularity or scanner artifacts, but may blur fine colony boundaries or merge nearby colonies if set too high. Start with 1–2 for high-resolution images; increase for noisier scans.

Type:

float

low_threshold

Lower bound for hysteresis thresholding. Raising this suppresses weak edges from noise or faint texture but may fragment colony boundaries if edges are dim. Lowering it recovers more boundary detail but risks false edges. If use_quantiles=True, this is a fraction (0–1) of gradient values; if False, an absolute gradient magnitude.

Type:

float

high_threshold

Upper bound for hysteresis thresholding. Strong edges above this seed the edge traces; too high and faint colonies lose boundaries, too low and noise creates spurious edges. Adjust relative to low_threshold to control edge connectivity.

Type:

float

use_quantiles

When True, thresholds are interpreted as quantiles of the gradient distribution (e.g., 0.1 = 10th percentile), making behavior more robust to image-specific intensity ranges. When False, thresholds are absolute gradient magnitudes, requiring manual tuning per imaging setup.

Type:

bool

min_size

Minimum pixel area to retain as an object after labeling regions enclosed by edges. Increase to remove dust, debris, or imaging artifacts; decrease to capture very small colonies. Setting too high discards genuine small colonies.

Type:

int

invert_edges

If True (default), regions between edges (i.e., enclosed areas) are labeled as objects, suitable for detecting solid colonies. When False, edges themselves are labeled (useful for atypical cases like ring-shaped colonies or debugging edge quality).

Type:

bool

connectivity

Connectivity level for labeling regions (1 for 4-connected, 2 for 8-connected in 2D). Higher connectivity merges diagonally adjacent pixels into the same object, which can join fragmented colony regions but may also merge nearby colonies touching at corners.

Type:

int

Methods

__init__
apply	Binarizes the given image gray using the Yen threshold method.
dispose_widgets	Drop references to the UI widgets.
sync_widgets_from_state	Push internal state into widgets.
widget	Return (and optionally display) the root widget.

__init__(sigma: float = 1.0, low_threshold: float = 0.1, high_threshold: float = 0.2, use_quantiles: bool = True, min_size: int = 50, invert_edges: bool = True, connectivity: int = 1)

Parameters:

• sigma (float) – Gaussian smoothing strength before edge detection. Start with 1-2 for clean images; increase for noisy scans to suppress spurious edges. Keep below typical colony radius to avoid merging.

• low_threshold (float) – Lower hysteresis threshold. If use_quantiles=True, a fraction (e.g., 0.1 = retain edges stronger than 10% of gradients). If False, an absolute gradient magnitude. Increase to suppress weak edges from noise; decrease to recover faint colony boundaries.

• high_threshold (float) – Upper hysteresis threshold. Seeds edge traces. If use_quantiles=True, a fraction (e.g., 0.2 = top 80% gradients); if False, an absolute magnitude. Raise to focus on strong boundaries; lower to include fainter edges. Must exceed low_threshold.

• use_quantiles (bool) – Interpret thresholds as quantiles (True, default) or absolute values (False). Quantiles adapt to image contrast automatically, reducing manual tuning.

• min_size (int) – Minimum object area in pixels. Increase to filter out dust, debris, and small artifacts; decrease to retain tiny colonies.

• invert_edges (bool) – If True (default), label enclosed regions as objects (colonies). If False, label edge pixels (for atypical cases like ring colonies or edge quality checks).

• connectivity (int) – Connectivity for labeling regions (1 or 2 in 2D). Higher values merge diagonally touching pixels, useful for bridging fragmented boundaries but may merge touching colonies.

__del__()

Automatically stop tracemalloc when the object is deleted.

__getstate__()

Prepare the object for pickling by disposing of any widgets.

This ensures that UI components (which may contain unpickleable objects like input functions or thread locks) are cleaned up before serialization.

Note

This method modifies the object state by calling dispose_widgets(). Any active widgets will be detached from the object.

apply(image, inplace=False)

Binarizes the given image gray using the Yen threshold method.

This function modifies the arr image by applying a binary mask to its enhanced gray (enh_gray). The binarization threshold is automatically determined using Yen’s method. The resulting binary mask is stored in the image’s objmask attribute.

Parameters:

image (Image) – The arr image object. It must have an enh_gray attribute, which is used as the basis for creating the binary mask.

Returns:

The arr image object with its objmask attribute updated

to the computed binary mask other_image.

Return type:

Image

dispose_widgets() → None

Drop references to the UI widgets.

Return type:

None

sync_widgets_from_state() → None

Push internal state into widgets.

Return type:

None

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.