Source code for src.cp_anywhere.segment

"""Object segmentation, implemented against CellProfiler 4.2.8's
``IdentifyPrimaryObjects`` module (and the shared ``Threshold`` module it
uses) as the compatibility oracle.

Declared scope: every global and adaptive threshold operation (Manual,
Otsu two/three-class, Li, Robust Background, Sauvola), log transform,
threshold smoothing, declumping/watershed (Intensity/Shape/Propagate),
hole filling (including nested-object absorption), border exclusion,
and size/count filtering -- see ``spec/segmentation-modules.md`` for
the exact settings mapping and the explicit remaining gaps (not silent
approximations).

CellProfiler's own ``Threshold`` module hard-bounds ``manual_threshold``
and ``threshold_range`` to ``[0, 1]`` and assumes images have been
rescaled to that range (its default ``Image(..., convert=True)`` divides
integer-dtype pixels by their dtype's max value; float-dtype pixels are
never rescaled). ``identify_primary_objects`` reproduces that default
behavior automatically (``rescale=True``) so passing a raw ``uint8``/
``uint16`` image works exactly like a default CellProfiler pipeline,
with no manual conversion needed.

The result chains directly into :func:`cp_anywhere.measure`::

    seg = cp_anywhere.identify_primary_objects(dna_image, threshold="otsu")
    result = cp_anywhere.measure({"DNA": dna_image}, {"Cells": seg.labels})
"""

from __future__ import annotations

from dataclasses import dataclass

import numpy as np

_MIN_DIAMETER_DEFAULT = 0.0
_MAX_DIAMETER_DEFAULT = float("inf")
_EXPECTED_NDIM = 2
_RESCALE_DIVISORS = {
    np.dtype("uint8"): 255.0,
    np.dtype("uint16"): 65535.0,
    np.dtype("uint32"): 4294967295.0,
}


[docs] @dataclass(frozen=True) class SegmentationResult: """Labels and diagnostics from one :func:`identify_primary_objects` call.""" labels: np.ndarray """2D integer label array, same shape as the input image; 0 is background.""" small_removed_labels: np.ndarray """Labels after the small-object filter only (large objects still present), matching CellProfiler's ``objects.small_removed_segmented``.""" unedited_labels: np.ndarray """Labels before border, size, count, or final hole filtering.""" object_count: int threshold: float """The threshold value actually applied, after correction/clamping, in the same units as the (possibly rescaled) pixels this was run on.""" threshold_map: np.ndarray | None = None """Corrected 2D Adaptive threshold array; None for Global thresholding.""" guide_threshold: float | None = None """Corrected global guide used to constrain Adaptive thresholds."""
def _rescale_divisor(dtype: np.dtype) -> float: try: return _RESCALE_DIVISORS[dtype] except KeyError as error: raise TypeError( f"rescale=True does not support dtype {dtype}; pass rescale=False " "and interpret threshold values in the image's own raw units, " "or pre-convert the image to uint8/uint16/uint32 yourself" ) from error def _resolve_threshold( threshold: str | float | int, array: np.ndarray, *, rescale: bool, is_integer_dtype: bool, ) -> tuple[str, float | None, np.ndarray | None]: """Map the public ``threshold`` argument to a native method/value/ integer_pixels triple, validating the 'otsu_integer' + rescale combo.""" if isinstance(threshold, (int, float)) and not isinstance(threshold, bool): return "manual", float(threshold), None if threshold == "otsu": return "otsu", None, None if threshold == "otsu_integer": if rescale and is_integer_dtype: raise ValueError( "threshold='otsu_integer' requires rescale=False " "(rescaling turns integer pixels into floats, which " "defeats the exact-bincount integer histogram)" ) if not is_integer_dtype: raise TypeError("threshold='otsu_integer' requires an integer dtype image") return "otsu_integer", None, np.ascontiguousarray(array, dtype=np.int64) if threshold == "otsu_three_class": return "otsu_three_class", None, None if threshold == "li": return "li", None, None if threshold == "robust_background": return "robust_background", None, None if threshold == "sauvola": return "sauvola", None, None raise ValueError( "threshold must be 'otsu', 'otsu_integer', 'otsu_three_class', 'li', " "'robust_background', 'sauvola', or a numeric value" )
[docs] def identify_primary_objects( image: object, *, mask: object | None = None, threshold: str | float | int = "otsu", rescale: bool = True, threshold_correction_factor: float = 1.0, threshold_range: tuple[float, float] | None = None, exclude_size: bool = False, min_diameter: float = _MIN_DIAMETER_DEFAULT, max_diameter: float = _MAX_DIAMETER_DEFAULT, exclude_border_objects: bool = False, maximum_object_count: int | None = None, fill_holes: str = "never", threshold_smoothing_scale: float = 0.0, assign_middle_to_foreground: bool = True, robust_background_lower_outlier_fraction: float = 0.05, robust_background_upper_outlier_fraction: float = 0.05, robust_background_averaging_method: str = "mean", robust_background_variance_method: str = "sd", robust_background_number_of_deviations: float = 2.0, log_transform: bool = False, threshold_scope: str = "global", adaptive_window_size: int = 50, unclump_method: str = "none", watershed_method: str = "none", smoothing_filter_size: float | None = None, maxima_suppression_size: float | None = None, low_resolution_maxima: bool = False, ) -> SegmentationResult: """Segment one 2D grayscale image into labeled primary objects. ``rescale`` (default ``True``) matches CellProfiler's own default image loading: integer-dtype images (``uint8``/``uint16``/``uint32``) are divided by their dtype's max value before thresholding, exactly like CellProfiler's ``Image(..., convert=True)``; float-dtype images are never rescaled (also matching CellProfiler). Set ``rescale=False`` to operate on raw pixel values directly instead (matching this project's measurement API's own ``convert=False`` convention). ``threshold`` is ``"otsu"`` (two-class, global, 256-bin histogram -- CellProfiler's default algorithm for any already-float pixel data, which is what every image becomes after rescaling), ``"otsu_integer"`` (exact one-bin-per-value histogram; only valid with ``rescale=False`` on an integer-dtype image -- matches CellProfiler's Otsu only if CellProfiler would also have skipped rescaling), ``"otsu_three_class"`` (a 128-bin, 3-class histogram split; ``assign_middle_to_foreground`` picks the lower split, i.e. the middle class counts as foreground, when ``True`` (default), or the upper split when ``False``, matching CellProfiler's ``"Foreground"``/``"Background"`` setting), ``"li"`` (Li's iterative Minimum Cross-Entropy threshold, matching ``skimage.filters.threshold_li`` with CellProfiler's own tolerance formula), ``"robust_background"`` (a trimmed mean/median/mode -- ``robust_background_averaging_method`` -- plus a multiple -- ``robust_background_number_of_deviations`` -- of the standard deviation or MAD -- ``robust_background_variance_method`` -- computed after discarding ``robust_background_lower_outlier_fraction``/ ``robust_background_upper_outlier_fraction`` of the lowest/highest pixels; matches ``Threshold.get_threshold_robust_background`` exactly, including its quirk where a zero lower-fraction also disables the upper trim), ``"sauvola"`` (a local mean/standard- deviation formula over a sliding window, only valid with ``threshold_scope="adaptive"`` -- matches ``skimage.filters.threshold_sauvola``; CellProfiler's own ``global_operation`` Choice does not even include Sauvola, so this raises if combined with ``threshold_scope="global"``), or a numeric manual threshold value, interpreted in the same units as the (possibly rescaled) pixels actually compared against it. ``threshold_scope`` (default ``"global"``) matches ``Threshold.threshold_scope``: ``"global"`` applies one scalar threshold to the whole image; ``"adaptive"`` instead computes a per-pixel threshold map by splitting the image into ``adaptive_window_size``-sized blocks (computing a block threshold with the same algorithm named by ``threshold`` -- or a direct sliding-window Sauvola computation, which has no block/spline step), blending the block grid across the image with a tensor-product B-spline (matching ``scipy.interpolate.RectBivariateSpline``), and finally clamping the result to ``[0.7, 1.5] * guide_threshold`` (the ordinary global threshold, used only as a bound; for ``"sauvola"`` this guide is computed via ``"li"``, matching CellProfiler's own shared branch). ``threshold_map`` (a same-shape array) and ``guide_threshold`` on the returned :class:`SegmentationResult` are ``None`` unless ``threshold_scope="adaptive"``; ``"manual"`` and ``"otsu_integer"`` are not supported with adaptive scope (CellProfiler's own ``local_operation`` Choice does not include either). ``log_transform`` (default ``False``) matches CellProfiler's ``Threshold.log_transform`` setting, meaningful only when ``threshold`` is ``"otsu"``, ``"otsu_three_class"``, or ``"li"`` (CellProfiler itself only exposes this setting for those global operations; it is silently ignored for ``"otsu_integer"``, ``"robust_background"``, and numeric manual thresholds, matching CellProfiler's own behavior). When enabled, the threshold is computed on a log-transformed, ``[0, 1]``-rescaled copy of the *entire* image (not just the masked subset) and mapped back before ``threshold_correction_factor``/clamping, exactly matching ``centrosome.threshold.log_transform``/``inverse_log_transform``. ``exclude_size``/``min_diameter``/``max_diameter`` match CellProfiler's ``IdentifyPrimaryObjects`` size filter: objects whose pixel area falls outside ``pi * diameter^2 / 4`` for the given diameter bounds are removed. ``exclude_border_objects`` (``IdentifyPrimaryObjects.exclude_border_objects``) removes any object touching the image border (or, if ``mask`` is given and nothing touches the image border directly, any object touching the mask's own border instead). ``maximum_object_count`` (``IdentifyPrimaryObjects.maximum_object_count``, only enforced when not ``None``) erases every object if the final count exceeds this value, matching CellProfiler's ``LIMIT_ERASE``. ``fill_holes`` (``IdentifyPrimaryObjects.fill_holes``) is one of ``"never"`` (default), ``"after_declump_only"`` (fills background holes enclosed by a single object, after border/size filtering), or ``"after_thresholding_and_declump"`` (also fills holes in the binary foreground mask before labeling, limited to area < ``max_diameter^2``). A background region bordered by two or more *different* objects (not fully enclosed by one) is left unfilled, matching ``centrosome.cpmorphology.fill_labeled_holes`` exactly, including its handling of a small object fully nested inside a larger one (absorbed into the enclosing label) and multi-level nested holes. ``threshold_smoothing_scale`` (``Threshold.threshold_smoothing_scale``, default ``0.0`` -- no smoothing) blurs the image used for the foreground/background comparison (not the value used to *compute* the threshold, which is always the unsmoothed image) with a Gaussian of ``sigma = threshold_smoothing_scale / 0.6744 / 2.0``, matching CellProfiler's ``apply_threshold`` exactly, including its mask-bleed-over correction near the image border. ``unclump_method``/``watershed_method`` (``IdentifyPrimaryObjects.unclump_method``/``watershed_method``) separate touching objects after initial labeling and before border/size filtering -- matching ``separate_neighboring_objects``'s exact position in CellProfiler's pipeline. ``unclump_method`` is ``"none"`` (default; no separation), ``"intensity"`` (find local intensity maxima in a Gaussian-smoothed copy of the image), or ``"shape"`` (find local maxima of the Euclidean distance transform of the foreground, jittered with CellProfiler's own fixed-seed(0) legacy-RNG noise to break exact ties). ``watershed_method`` is ``"none"`` (default), ``"intensity"`` (watershed on ``1 - image``), ``"shape"`` (watershed on the negated distance transform -- reuses the *same* jittered transform computed above when ``unclump_method="shape"`` too, matching CellProfiler's own ``if distance_transformed_image is None`` check), or ``"propagate"`` (``centrosome.propagate.propagate``, a distinct non-watershed algorithm; ignores both image and distance-transform inputs, geometric distance only). Both must be set to something other than ``"none"`` for separation to actually run, matching CellProfiler's own ``UN_NONE``/``WA_NONE`` no-op check. ``smoothing_filter_size``/``maxima_suppression_size`` override CellProfiler's own automatic formulas (``2.35 * min_diameter / 3.5`` and ``min_diameter / 1.5`` respectively) when given explicitly, matching ``automatic_smoothing``/``automatic_suppression`` set to ``False`` with an explicit ``Float`` Setting value. ``low_resolution_maxima`` (``IdentifyPrimaryObjects.low_res_maxima``) only takes effect when ``min_diameter > 10.0`` (CellProfiler's own gate); when both are true, maxima are found on a downsampled copy of the image for speed -- not yet implemented, raises if triggered. """ from cp_anywhere import _native array = np.asarray(image) if array.ndim != _EXPECTED_NDIM or 0 in array.shape: raise ValueError("image must be a nonempty 2D array") rows, cols = array.shape is_integer_dtype = array.dtype.kind in "iu" if rescale and is_integer_dtype: divisor = _rescale_divisor(array.dtype) pixels = np.ascontiguousarray(array, dtype=np.float64) / divisor else: pixels = np.ascontiguousarray(array, dtype=np.float64) method, threshold_value, integer_pixels = _resolve_threshold( threshold, array, rescale=rescale, is_integer_dtype=is_integer_dtype ) if threshold_range is None: threshold_range = ( (0.0, 1.0) if (rescale and is_integer_dtype) else (-np.inf, np.inf) ) mask_array = None if mask is not None: mask_array = np.ascontiguousarray(np.asarray(mask), dtype=bool) if mask_array.shape != array.shape: raise ValueError("mask must have the image shape") raw = _native.identify_primary_objects( pixels, rows, cols, method, threshold_value=threshold_value, integer_pixels=integer_pixels, mask=mask_array, threshold_correction_factor=threshold_correction_factor, threshold_range_min=threshold_range[0], threshold_range_max=threshold_range[1], exclude_size=exclude_size, min_diameter=min_diameter, max_diameter=max_diameter, exclude_border_objects=exclude_border_objects, maximum_object_count=maximum_object_count, fill_holes=fill_holes, threshold_smoothing_scale=threshold_smoothing_scale, assign_middle_to_foreground=assign_middle_to_foreground, robust_background_lower_outlier_fraction=robust_background_lower_outlier_fraction, robust_background_upper_outlier_fraction=robust_background_upper_outlier_fraction, robust_background_averaging_method=robust_background_averaging_method, robust_background_variance_method=robust_background_variance_method, robust_background_number_of_deviations=robust_background_number_of_deviations, log_transform=log_transform, threshold_scope=threshold_scope, adaptive_window_size=adaptive_window_size, unclump_method=unclump_method, watershed_method=watershed_method, smoothing_filter_size=smoothing_filter_size, maxima_suppression_size=maxima_suppression_size, low_resolution_maxima=low_resolution_maxima, ) return SegmentationResult( labels=raw["labels"].reshape(array.shape), small_removed_labels=raw["small_removed_labels"].reshape(array.shape), unedited_labels=raw["unedited_labels"].reshape(array.shape), object_count=int(raw["object_count"]), threshold=float(raw["threshold"]), threshold_map=( None if raw["threshold_map"] is None else raw["threshold_map"].reshape(array.shape) ), guide_threshold=raw["guide_threshold"], )
[docs] @dataclass(frozen=True) class SecondaryObjectsResult: """Final and pre-filter secondary-object labels.""" small_removed_labels: np.ndarray """Pre-filter labels in the original seed numbering, used by neighbors.""" labels: np.ndarray """2D integer label array, same shape as the input image; 0 is background.""" threshold: float | None """The secondary image's own applied threshold; ``None`` for ``method="distance_n"``, which never thresholds an image.""" @property def unedited_labels(self) -> np.ndarray: """CellProfiler stores the same grown layer as unedited and small-removed.""" return self.small_removed_labels
[docs] def identify_secondary_objects( image: object, primary_labels: object, *, primary_labels_in: object | None = None, method: str = "propagation", mask: object | None = None, threshold: str | float | int = "otsu", rescale: bool = True, threshold_correction_factor: float = 1.0, threshold_range: tuple[float, float] | None = None, threshold_smoothing_scale: float = 0.0, log_transform: bool = False, threshold_scope: str = "global", adaptive_window_size: int = 50, assign_middle_to_foreground: bool = True, robust_background_lower_outlier_fraction: float = 0.05, robust_background_upper_outlier_fraction: float = 0.05, robust_background_averaging_method: str = "mean", robust_background_variance_method: str = "sd", robust_background_number_of_deviations: float = 2.0, regularization_factor: float = 0.05, distance_to_dilate: float = 10.0, fill_holes: bool = False, ) -> SecondaryObjectsResult: """Grow a secondary object (e.g. ``"Cells"``) around each primary object (e.g. ``"Nuclei"``), matching CellProfiler 4.2.8's ``IdentifySecondaryObjects`` module. ``image`` is the secondary stain image (e.g. a cell-membrane or whole-cell marker); ``primary_labels`` is the final, kept primary object set (e.g. :attr:`SegmentationResult.labels` from :func:`identify_primary_objects`) -- a grown secondary object is kept only if its seed primary object survived there. ``primary_labels_in`` accepts the unedited primary labels, before size or border filtering. Pass :attr:`SegmentationResult.unedited_labels` from the upstream primary result. The Rust core retains edge-touching seeds and removes other seed pixels wherever ``primary_labels`` is zero, matching CellProfiler. Grown regions are mapped to retained primary IDs by overlap, so renumbered primaries stay aligned. If omitted, the kept primary array supplies the seeds; excluded edge objects cannot participate because their pixels are unavailable. ``method`` is ``"propagation"`` (the module's own default: weighted shortest-path region growing, bounded by a threshold of ``image``, steered by ``regularization_factor`` -- 0 favors image intensity, larger values favor Euclidean geometry) or ``"distance_n"`` (a fixed-radius Euclidean expansion bounded by ``distance_to_dilate``, with no image or threshold involved at all), or ``"watershed_image"`` (watershed on inverted intensity within the threshold foreground and seed mask). ``"distance_b"`` and ``"watershed_gradient"`` are not supported. ``threshold``/``rescale``/``threshold_correction_factor``/ ``threshold_range``/``threshold_smoothing_scale``/``log_transform``/ ``threshold_scope``/``adaptive_window_size``/ ``assign_middle_to_foreground``/``robust_background_*`` all match :func:`identify_primary_objects`'s own identically-named parameters exactly (the secondary image's threshold uses the same machinery, with no size/border/declump filtering applied to it -- matching ``IdentifySecondaryObjects``'s own plain threshold-and- binarize step). Ignored entirely for ``method="distance_n"``. ``fill_holes`` uses CellProfiler's labeled-hole graph, but changes only background pixels. Existing nested foreground labels survive. ``small_removed_labels`` retains the grown labels before filtering, in the original seed numbering, for downstream neighbor measurements. """ from cp_anywhere import _native array = np.asarray(image) if array.ndim != _EXPECTED_NDIM or 0 in array.shape: raise ValueError("image must be a nonempty 2D array") rows, cols = array.shape primary_array = _label_array(primary_labels, array.shape) labels_in_array = ( primary_array if primary_labels_in is None else _label_array(primary_labels_in, array.shape) ) if method not in ("propagation", "distance_n", "watershed_image"): msg = ( f"Unsupported secondary method {method!r}; " "use propagation, distance_n, or watershed_image" ) raise ValueError(msg) is_integer_dtype = array.dtype.kind in "iu" if rescale and is_integer_dtype: divisor = _rescale_divisor(array.dtype) pixels = np.ascontiguousarray(array, dtype=np.float64) / divisor else: pixels = np.ascontiguousarray(array, dtype=np.float64) threshold_method, threshold_value, integer_pixels = _resolve_threshold( threshold, array, rescale=rescale, is_integer_dtype=is_integer_dtype ) if threshold_range is None: threshold_range = ( (0.0, 1.0) if (rescale and is_integer_dtype) else (-np.inf, np.inf) ) mask_array = None if mask is not None: mask_array = np.ascontiguousarray(np.asarray(mask), dtype=bool) if mask_array.shape != array.shape: raise ValueError("mask must have the image shape") raw = _native.identify_secondary_objects( pixels, rows, cols, labels_in_array, primary_array, method, threshold_method, threshold_value=threshold_value, integer_pixels=integer_pixels, mask=mask_array, threshold_correction_factor=threshold_correction_factor, threshold_range_min=threshold_range[0], threshold_range_max=threshold_range[1], threshold_smoothing_scale=threshold_smoothing_scale, log_transform=log_transform, threshold_scope=threshold_scope, adaptive_window_size=adaptive_window_size, assign_middle_to_foreground=assign_middle_to_foreground, robust_background_lower_outlier_fraction=robust_background_lower_outlier_fraction, robust_background_upper_outlier_fraction=robust_background_upper_outlier_fraction, robust_background_averaging_method=robust_background_averaging_method, robust_background_variance_method=robust_background_variance_method, robust_background_number_of_deviations=robust_background_number_of_deviations, regularization_factor=regularization_factor, distance_to_dilate=distance_to_dilate, fill_holes=fill_holes, ) return SecondaryObjectsResult( labels=raw["labels"].reshape(array.shape), small_removed_labels=raw["small_removed_labels"].reshape(array.shape), threshold=raw["threshold"], )
[docs] @dataclass(frozen=True) class TertiaryObjectsResult: """Tertiary labels, preserving the larger object's label numbering.""" labels: np.ndarray
[docs] def identify_tertiary_objects( primary_labels: object, secondary_labels: object, *, shrink_primary: bool = True, ) -> TertiaryObjectsResult: """Subtract smaller objects from larger objects on the same 2D grid. With ``shrink_primary=True`` (CellProfiler's default), retain the smaller objects' one-pixel, eight-connected outline. With ``False``, remove every smaller-object pixel. Output IDs are the larger objects' IDs, not newly numbered connected components. Inputs are never modified. Crop/resize metadata and parent measurements are not provided by this array API; grids must already match. """ from cp_anywhere import _native primary = _tertiary_label_array(primary_labels) secondary = _tertiary_label_array(secondary_labels) if primary.shape != secondary.shape: raise ValueError("primary and secondary label arrays must have matching shapes") rows, cols = secondary.shape labels = _native.identify_tertiary_objects( primary, secondary, rows, cols, shrink_primary=shrink_primary ) return TertiaryObjectsResult(labels=labels.reshape(secondary.shape))
def _tertiary_label_array(value: object) -> np.ndarray: array = np.asarray(value) if array.ndim != _EXPECTED_NDIM or 0 in array.shape: raise ValueError("label arrays must be nonempty 2D arrays") if array.dtype.kind not in "iu" or np.any(array < 0): raise ValueError("label arrays must contain nonnegative integers") if np.any(array > np.iinfo(np.uint32).max): raise ValueError("label arrays must fit in uint32") return np.ascontiguousarray(array, dtype=np.uint32) def _label_array(value: object, shape: tuple[int, ...]) -> np.ndarray: array = np.ascontiguousarray(np.asarray(value), dtype=np.uint32) if array.shape != shape: raise ValueError("label arrays must have the image shape") return array