Utilities — napari_easytrack.utils

Utilities for btrack Tracking

Data Loading: - Load multiple skeleton/segmentation files (time series) - Load single 3D/4D stacks - Auto-detection of data format (labeled vs binary) - Flexible cropping and channel selection - Support for 3D+T data (T, Z, Y, X)

Segmentation Processing: - Clean segmentation (remove fragments) - Reassign disconnected components - Quality control operations

Usage:

from utils import load_segmentation, clean_segmentation

# Load any format automatically seg = load_segmentation(‘path/to/data.tif’)

# Clean segmentation cleaned = clean_segmentation(seg)

napari_easytrack.utils.clean_segmentation(segmentation, verbose=True, min_size=5)

Clean segmentation by: 1. Keeping only the largest connected component per label 2. Reassigning smaller fragments and small labels to neighbors :param segmentation: 3D array (T, Y, X) or 4D array (T, Z, Y, X) with integer labels :param verbose: If True, print progress information :param min_size: Minimum number of pixels/voxels for a label (default: 5)

Returns:

Cleaned segmentation with same shape and dtype

napari_easytrack.utils.load_files_from_pattern(directory, pattern='*.tif', convert_to_labels=True, crop_edges=False, crop_pixels=2, keep_z=True)

Load multiple image files matching a pattern (e.g., time series).

Parameters:

  • directory – Path to directory containing files

  • pattern – Glob pattern to match files (e.g., ‘CorrSkel_t*.tif’)

  • convert_to_labels – If True, convert binary/skeleton to labeled regions

  • crop_edges – If True, crop top and bottom edges

  • crop_pixels – Number of pixels to crop from top/bottom

  • keep_z – If True and files are 3D, keep Z dimension (output: T, Z, Y, X) If False and files are 3D, take max projection (output: T, Y, X)

Returns:

3D numpy array (T, Y, X) if files are 2D or keep_z=False 4D numpy array (T, Z, Y, X) if files are 3D and keep_z=True

napari_easytrack.utils.load_segmentation(path, pattern='*.tif', convert_to_labels=True, crop_edges=False, crop_pixels=2, keep_z=True)

Smart loader that automatically determines format and loads appropriately.

Parameters:

  • path – Either a directory (for multiple files) or a file path (for single stack)

  • pattern – Glob pattern (only used if path is a directory)

  • convert_to_labels – Convert binary/skeleton to labeled regions

  • crop_edges – Crop top/bottom edges

  • crop_pixels – Amount to crop

  • keep_z – For 3D data, keep Z dimension (True) or max project (False)

Returns:

3D numpy array (T/Z, Y, X) or 4D array (T, Z, Y, X) for 3D+T data

Examples

# Load single stack seg = load_segmentation(‘data/stack.tif’)

# Load multiple files seg = load_segmentation(‘data/timelapse/’, pattern=’frame_*.tif’)

# Load 3D+T data seg = load_segmentation(‘data/3d_timelapse/’, keep_z=True)

napari_easytrack.utils.load_single_stack(file_path, convert_to_labels=True, crop_edges=False, crop_pixels=2)

Load a single 3D/4D stack file.

Handles various formats: - (T, Y, X) or (Z, Y, X) - simple 3D - (T, C, Y, X) - time with channels - (T, Z, Y, X) - time with Z-slices

Parameters:

  • file_path – Path to stack file

  • convert_to_labels – If True, convert binary/skeleton to labeled regions (automatically skipped if already labeled)

  • crop_edges – If True, crop edges

  • crop_pixels – Pixels to crop from top/bottom

Returns:

3D numpy array

napari_easytrack.utils.remove_small_labels(segmentation, min_pixels=3, verbose=True)

Remove labels that have fewer than min_pixels in each timepoint. For 4D data (T, Z, Y, X): checks size per 3D volume at each timepoint For 3D data (T, Y, X): checks size per 2D slice at each timepoint

Reassigns their pixels to neighboring labels.

Parameters:

  • segmentation – 3D array (T, Y, X) or 4D array (T, Z, Y, X) with integer labels

  • min_pixels – Minimum pixels/voxels for a label to keep per timepoint (default: 3)

  • verbose – If True, print progress information

Returns:

Cleaned segmentation with same shape and dtype