phenotypic.refine.SeparateObjects#

class phenotypic.refine.SeparateObjects(min_distance: int = 10)[source]

Bases: ObjectRefiner

Separate touching or merged colonies using distance-transform watershed segmentation.

Finds peaks in the Euclidean distance transform as seed markers for watershed region growing. For GridImages, peaks are constrained to one per grid cell; for regular Images, peaks are detected globally with minimum distance spacing. Effectively individualizes colonies that were merged by thresholding.

Parameters:

min_distance (int) – Minimum pixel distance between peaks for regular Images. Ignored for GridImages (one peak per cell). Typical range: 5–50. Higher values reduce over-segmentation; lower values detect more peaks. Default: 10.

Returns:

Input image with objmap refined so that touching colonies are separated into distinct labeled regions.

Return type:

Image

Raises:

ValueError – If no peaks are detected or the image lacks detection results.

Best For:

  • GridImage plates (96-well, 384-well, pinned cultures) where touching colonies need individualization.

  • Post-detection refinement when thresholding merges adjacent colonies into a single detection.

  • Variable colony sizes where the distance transform naturally adapts peak strength to colony diameter.

  • Non-grid images using global peak detection with spacing constraints.

Consider Also:

  • MaskOpener for gentle separation of lightly touching colonies without watershed.

  • MaskEroder for uniform inward shrinking that may separate touching edges.

  • GridAlignmentRefiner when off-grid artifacts are the main concern rather than merged colonies.

See also

How To: Merge Fragmented Detections for separation and merging workflows. Refinement Strategies for a comparison of colony separation approaches.

Methods

__init__

Initialize SeparateObjects with distance-based peak detection.

apply

Applies the operation to an image, either in-place or on a copy.

widget

Return (and optionally display) the root widget.
__init__(min_distance: int = 10)[source]

Initialize SeparateObjects with distance-based peak detection.

Parameters:

min_distance (int) – Minimum pixel distance between peaks for regular Images. Ignored for GridImages (one peak per cell). Default 10.

__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)

Applies the operation to an image, either in-place or on a copy.

Parameters:

  • image (Image) – The arr image to apply the operation on.

  • inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

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.

This Page