Segmentation

Image segmentation modules for filtering, labeling, marker detection, and network analysis.

Filtering

Multi-scale Frangi filtering for detecting vesselness and tubular structures.

filtering

Frangi-like vesselness filter for 3D/4D microscopy image data.

This module provides the Filter class, which implements a multi-scale Frangi filtering approach optimized for large datasets with optional GPU acceleration.

Filter

Filter(im_info, num_t=None, remove_edges=False, min_radius_um=0.25, max_radius_um=1.0, alpha_sq=0.5, beta_sq=0.5, frob_thresh=None, frob_thresh_division=2, viewer=None, device='auto', low_memory=False, max_chunk_voxels=int(1000000.0), max_threshold_samples=int(1000000.0))

Frangi-like vesselness filter for 3D or 4D microscopy image data, optimized for large datasets and optional GPU acceleration.

Parameters:

Name	Type	Description	Default
im_info	ImInfo	Image metadata and file paths.	required
num_t	int	Number of timepoints to process. If None, inferred from image.	None
remove_edges	bool	If True, aggressively zero out bounding-box edges.	False
min_radius_um	float	Expected structure radius range in micrometers.	0.25
max_radius_um	float	Expected structure radius range in micrometers.	0.25
alpha_sq	float	Frangi parameters controlling sensitivity to blobness and plate-likeness.	0.5
beta_sq	float	Frangi parameters controlling sensitivity to blobness and plate-likeness.	0.5
frob_thresh	float or None	If given, fixed Frobenius norm threshold. Otherwise auto-estimated.	None
viewer	object or None	Optional GUI viewer with a .status attribute.	None
device	(auto, cpu, gpu)	Backend selection. "auto" uses GPU if available, otherwise CPU. "cpu" forces NumPy/Scipy, and "gpu" forces CuPy/CuPyX (error if unavailable).	"auto"
low_memory	bool	If True, prefer strategies that reduce peak memory at the cost of speed (e.g. smaller eigen-decomposition chunks).	False
max_chunk_voxels	int	Maximum number of voxels per processing chunk and eigen-decomposition chunk.	int(1000000.0)
max_threshold_samples	int	Maximum number of samples to use when estimating thresholds (triangle / Otsu) from very large arrays.	int(1000000.0)

run

run(mask=True)

Main entry point: run the Frangi filter over the image.

---

Labelling

Threshold-based semantic and instance segmentation.

labelling

Semantic and instance segmentation for microscopy images.

This module provides the Label class for thresholding-based segmentation with optimizations for large volumes and optional GPU acceleration.

Label

Label(im_info, num_t=None, threshold=None, otsu_thresh_intensity=False, viewer=None, chunk_z=None, flush_interval=1, min_radius_um=0.25, threshold_sampling_pixels=1000000, histogram_nbins=256, device='auto', low_memory=False, max_chunk_voxels=int(1000000.0))

A class for semantic and instance segmentation of microscopy images using thresholding techniques, optimized for large volumes and optional GPU acceleration.

Parameters:

Name	Type	Description	Default
im_info	ImInfo	Image metadata and paths.	required
num_t	int	Number of timepoints to process.	None
threshold	float or None	Fixed intensity threshold for segmentation (if not using Otsu).	None
otsu_thresh_intensity	bool	Whether to apply Otsu's method for intensity thresholding.	False
viewer	object or None	Viewer object for displaying status.	None
chunk_z	int or None	If not None and image has Z, process each timepoint in Z-chunks of this size instead of the full volume. If None and low_memory is True, a chunk size is inferred from max_chunk_voxels.	None
flush_interval	int	How often (in frames) to flush the output memmap to disk.	1
min_radius_um	float	Minimum expected object radius in micrometers. Labels smaller than the area/volume of a circle/sphere with this radius are removed.	0.25
threshold_sampling_pixels	int	Maximum number of pixels sampled when computing global thresholds to reduce histogram cost for very large volumes.	1000000
histogram_nbins	int	Number of bins to use in histogram-based thresholding.	256
device	(auto, cpu, gpu)	Backend selection. "auto" uses GPU if available, otherwise CPU.	"auto"
low_memory	bool	If True, prefer chunked Z processing to reduce peak memory usage.	False
max_chunk_voxels	int	Target maximum number of voxels per Z-chunk when low_memory is True and chunk_z is not specified.	int(1000000.0)

run

run()

Main method to execute the full segmentation process over the image data.

---

Mocap Marking

Motion capture marker detection using distance transforms and multi-scale peak detection.

mocap_marking

Motion capture marker generation for microscopy images.

This module provides the Markers class for detecting and marking key points in segmented structures using distance transforms and multi-scale peak detection.

Notes

• Distance and border outputs are always saved because downstream steps depend on them.
• The border mask is the outside shell, computed as dilation(mask) XOR mask.

Markers

Markers(im_info, num_t=None, min_radius_um=0.2, max_radius_um=1, use_im='distance', num_sigma=5, viewer=None, prefer_gpu=True, peak_min_distance=2, device='auto', low_memory=False, max_chunk_voxels=int(1000000.0))

A class for generating motion capture markers in microscopy images using distance transforms and peak detection.

Optimizations: - Uses distance_transform_edt instead of KD-tree for distance transform. - Streams over scales for LoG (no large 4D arrays). - Uses morphological non-max suppression instead of KD-tree for peak pruning. - Supports GPU via CuPy/CuPyX with automatic fallback to CPU on OOM. - Optional low-memory chunking for LoG and NMS while preserving results.

Attributes:

Name	Type	Description
im_info	ImInfo	An object containing image metadata and memory-mapped image data.
num_t	int	Number of timepoints in the image.
min_radius_um	float	Minimum radius of detected objects in micrometers.
max_radius_um	float	Maximum radius of detected objects in micrometers.
min_radius_px	float	Minimum radius of detected objects in pixels.
max_radius_px	float	Maximum radius of detected objects in pixels.
use_im	str	Specifies which image to use for peak detection ('distance' or 'frangi').
num_sigma	int	Number of sigma steps for multi-scale filtering.
shape	tuple	Shape of the input image.
im_memmap	ndarray or None	Memory-mapped original image data.
im_frangi_memmap	ndarray or None	Memory-mapped Frangi-filtered image data.
label_memmap	ndarray or None	Memory-mapped label data from instance segmentation.
im_marker_memmap	ndarray or None	Memory-mapped output for motion capture markers.
im_distance_memmap	ndarray or None	Memory-mapped output for distance transform.
im_border_memmap	ndarray or None	Memory-mapped output for image borders.
debug	dict or None	Debugging information for tracking the marking process.
viewer	object or None	Viewer object for displaying status during processing.
device	{auto, cpu, gpu}	Backend selection. "auto" uses GPU if available, otherwise CPU.
low_memory	bool	If True, prefer chunked LoG and NMS to reduce peak memory at the cost of speed.
max_chunk_voxels	int	Maximum voxels per chunk when low-memory mode is used.
use_gpu	bool	Whether to use the GPU backend (if available). Automatically set to False on GPU OOM.
peak_min_distance	int	Minimum separation (in pixels) between peaks in morphological NMS.

Initializes the Markers object with image metadata and marking parameters.

Parameters:

Name	Type	Description	Default
im_info	ImInfo	An instance of the ImInfo class, containing metadata and paths for the image file.	required
num_t	int	Number of timepoints to process. If None, defaults to the number of timepoints in the image.	None
min_radius_um	float	Minimum radius of detected objects in micrometers (default is 0.20).	0.2
max_radius_um	float	Maximum radius of detected objects in micrometers (default is 1).	1
use_im	str	Specifies which image to use for peak detection ('distance' or 'frangi', default is 'distance').	'distance'
num_sigma	int	Number of sigma steps for multi-scale filtering (default is 5).	5
viewer	object or None	Viewer object for displaying status during processing (default is None).	None
prefer_gpu	bool	Whether to prefer GPU backend when available (default is True).	True
peak_min_distance	int	Minimum distance (in pixels) between peaks for NMS (default is 2).	2
device	(auto, cpu, gpu)	Backend selection. "auto" uses GPU if available, otherwise CPU.	"auto"
low_memory	bool	If True, prefer chunked LoG and NMS to reduce memory at the cost of speed.	False
max_chunk_voxels	int	Maximum number of voxels per chunk for low-memory processing.	int(1000000.0)

xp property

xp

Array module for the current backend.

ndi_backend property

ndi_backend

Ndimage backend for the current backend.

run

run()

Main method to execute the motion capture marking process over the image data.

This method allocates memory, sets sigma values, and runs the marking process for all timepoints.

---

Networking

Network skeletonization and topological analysis.

networking

Network skeletonization and analysis for microscopy images.

This module provides the Network class for skeletonizing network-like structures and analyzing their topology with optimized CPU/GPU processing.

Network

Network(im_info, num_t=None, min_radius_um=0.2, max_radius_um=1, viewer=None, device='auto', low_memory=False, max_chunk_voxels=int(1000000.0))

Optimized class for analyzing and skeletonizing network-like structures in 3D or 4D microscopy images.

This version focuses on: - Reduced CPU/GPU thrashing. - Vectorized neighborhood operations (no Python per-voxel loops on large arrays). - More memory-friendly local-max detection. - More efficient branch relabeling using distance transforms on per-object crops. - Graceful degradation when GPU memory is insufficient (CPU/chunked fallback).

Parameters:

Name	Type	Description	Default
im_info	ImInfo	Image metadata and paths.	required
num_t	int	Number of timepoints to process. Defaults to all timepoints.	None
min_radius_um	float	Minimum radius of detected objects in micrometers.	0.2
max_radius_um	float	Maximum radius of detected objects in micrometers.	1
viewer	object or None	Viewer object for status reporting.	None
device	(auto, cpu, gpu)	Backend selection for connectivity computations.	"auto"
low_memory	bool	If True, use chunked CPU fallbacks for local neighborhood operations.	False
max_chunk_voxels	int	Maximum voxels per chunk for low-memory paths.	int(1000000.0)

run

run()

Execute the full network analysis pipeline.