segmentation package

segmentation_tools

towbintools.segmentation.segmentation_tools.double_threshold_segmentation(image: ndarray, pixelsize: float, minimal_object_area_um2: float = 422.5) → ndarray[source]

Segment an image using the custom iterative Otsu threshold.

Computes a threshold with _custom_threshold_otsu() (which iteratively refines the Otsu threshold using Mode-Limited Mean histogram cropping) and removes small objects.

Parameters:

  • image (np.ndarray) – 2D grayscale input image.

  • pixelsize (float) – Physical pixel size (µm/px), used to convert minimal_object_area_um2 to pixels.

  • minimal_object_area_um2 (float, optional) – Minimum object area in µm² below which objects are removed. (default: 422.5)

Returns:

Binary mask of shape (H, W) with dtype uint8.

Return type:

np.ndarray

towbintools.segmentation.segmentation_tools.edge_based_segmentation(image: ndarray, pixelsize: float, gaussian_filter_sigma: float = 1, kernel_size: int = 30, final_threshold_percentile: float = 87.5, minimal_object_area_um2: float = 422.5, **kwargs) → ndarray[source]

Optimized edge-based segmentation using Scharr edge detection and intensity thresholding.

Computes Scharr edges, closes edge contours with a morphological ellipse kernel, then thresholds by a percentile of pixels along the closed contour boundary.

Parameters:

  • image (np.ndarray) – 2D grayscale input image.

  • pixelsize (float) – Physical pixel size (µm/px), used to convert minimal_object_area_um2 to pixels.

  • gaussian_filter_sigma (float, optional) – Sigma for the Gaussian pre-smoothing applied before Scharr edge detection. (default: 1)

  • kernel_size (int, optional) – Diameter of the elliptical structuring element used for morphological closing of edge contours. (default: 30)

  • final_threshold_percentile (float, optional) – Percentile of contour-boundary pixel intensities used as the final threshold. (default: 87.5)

  • minimal_object_area_um2 (float, optional) – Minimum object area in µm² below which objects are removed. (default: 422.5)

  • **kwargs – Ignored (accepted for API compatibility).

Returns:

Binary mask of shape (H, W) with dtype np.uint8.

Return type:

np.ndarray

Raises:

ValueError – If the input image is not 2D.

towbintools.segmentation.segmentation_tools.get_segmentation_function(method: str, pixelsize: float | None = None, **kwargs) → Callable[source]

Return a segmentation callable configured for the specified method.

Parameters:

  • method (str) – Segmentation method. Supported values: "edge_based", "double_threshold", "threshold".

  • pixelsize (float, optional) – Physical pixel size (µm/px). Required for "edge_based" and "double_threshold"; optional for "threshold". (default: None)

  • **kwargs – Additional keyword arguments forwarded to the segmentation function (e.g. gaussian_filter_sigma for "edge_based").

Returns:

A function segment_fn(image) -> np.ndarray that applies the

configured segmentation method to a 2D image.

Return type:

callable

Raises:

ValueError – If method is not recognized or pixelsize is None for "edge_based".

towbintools.segmentation.segmentation_tools.segment_image(image: str | ndarray, method: str, channels: list[int] | None = None, pixelsize: float | None = None, is_stack: bool = True, **kwargs) → ndarray[source]

Segment an image using the specified method.

Accepts either a file path (TIFF) or a NumPy array. When is_stack is True, the segmentation function is applied plane-by-plane along axis 0.

Parameters:

  • image (str or np.ndarray) – Input image path or array. A string is interpreted as a path to a TIFF file.

  • method (str) – Segmentation method. Supported: "edge_based", "double_threshold", "threshold".

  • channels (list[int], optional) – Channel indices to keep when reading a multi-channel TIFF. (default: None)

  • pixelsize (float, optional) – Physical pixel size (µm/px). Required for "edge_based" and "double_threshold". (default: None)

  • is_stack (bool, optional) – If True, iterate over planes along axis 0. (default: True)

  • **kwargs – Additional keyword arguments forwarded to the segmentation function.

Returns:

Binary mask as uint8 array. When is_stack is True,

shape is (N, H, W); otherwise (H, W).

Return type:

np.ndarray

Raises:

ValueError – If method is not recognized or pixelsize is None for "edge_based".

towbintools.segmentation.segmentation_tools.threshold_segmentation(image: ndarray, pixelsize: float, method: str = 'otsu', minimal_object_area_um2: float = 422.5, **kwargs) → ndarray[source]

Segment an image using a global threshold computed by a standard algorithm.

Supported thresholding algorithms: "otsu", "li", "yen", "triangle".

Parameters:

  • image (np.ndarray) – 2D grayscale input image.

  • pixelsize (float) – Physical pixel size (µm/px), used to convert minimal_object_area_um2 to pixels.

  • method (str, optional) – Thresholding algorithm to use. (default: "otsu")

  • minimal_object_area_um2 (float, optional) – Minimum object area in µm² below which objects are removed. (default: 422.5)

  • **kwargs – Ignored (accepted for API compatibility).

Returns:

Binary mask of shape (H, W) with dtype uint8.

Return type:

np.ndarray

Raises:

ValueError – If method is not one of the supported algorithms.