Tracking

Temporal tracking modules for object tracking across timepoints.

Label Tracking

Track labeled objects across timepoints using flow interpolation.

all_tracks_for_label

Label tracking across timepoints using flow interpolation.

This module provides the LabelTracks class for tracking labeled objects over time using forward and backward flow interpolation.

LabelTracks

LabelTracks(im_info, num_t=None, label_im_path=None)

A class to track labeled objects over multiple timepoints in a microscopy image using flow interpolation.

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.
`label_im_path`	`str`	Path to the labeled instance image.
`im_memmap`	`ndarray or None`	Memory-mapped original image data.
`label_memmap`	`ndarray or None`	Memory-mapped labeled instance image data.

Methods:

Name	Description
`initialize`	Initializes memory-mapped data for both the raw image and the labeled instance image.
`run`	Runs the tracking process for labeled objects across timepoints, both forward and backward.

Initializes the LabelTracks class with image metadata, timepoints, and label image path.

Parameters:

Name	Type	Description	Default
`im_info`	`ImInfo`	An instance of the ImInfo class containing image metadata and paths.	required
`num_t`	`int`	Number of timepoints in the image (default is None, in which case it is inferred from the image metadata).	`None`
`label_im_path`	`str`	Path to the labeled instance image. If not provided, defaults to the 'im_instance_label' path in `im_info`.	`None`

initialize

initialize()

Initializes memory-mapped data for both the raw image and the labeled instance image.

This method prepares the image data and the labeled data for processing, mapping them into memory.

run

run(label_num=None, start_frame=0, end_frame=None, min_track_num=0, skip_coords=1, max_distance_um=0.5)

Runs the tracking process for labeled objects across timepoints, using flow interpolation.

This method uses forward and backward interpolation to track objects across multiple frames, starting from a given frame. It can also track specific labels or all labels in the image.

Parameters:

Name	Type	Description	Default
`label_num`	`int`	Label number to track. If None, all labels are tracked (default is None).	`None`
`start_frame`	`int`	The starting frame from which to begin tracking (default is 0).	`0`
`end_frame`	`int`	The ending frame for the tracking. If None, tracks until the last frame (default is None).	`None`
`min_track_num`	`int`	Minimum track number to assign to the coordinates (default is 0).	`0`
`skip_coords`	`int`	The interval at which coordinates are sampled (default is 1).	`1`
`max_distance_um`	`float`	Maximum distance allowed for interpolation (in micrometers, default is 0.5).	`0.5`

Returns:

Type	Description
`tuple`	A list of tracks and a dictionary of track properties.

Flow Interpolation

Optical flow vector interpolation for temporal tracking.

flow_interpolation

Flow vector interpolation for temporal tracking in microscopy images.

This module provides interpolation of optical flow vectors between timepoints with optimizations for large datasets and optional GPU acceleration.

FlowInterpolator

FlowInterpolator(im_info, num_t=None, max_distance_um=0.5, forward=True)

A class for interpolating flow vectors between timepoints in microscopy images using precomputed flow data.

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.
`max_distance_um`	`float`	Maximum distance allowed for interpolation (in micrometers).
`forward`	`bool`	Indicates if the interpolation is performed in the forward direction (True) or backward direction (False).
`scaling`	`tuple`	Scaling factors for Z, Y, and X dimensions.
`shape`	`tuple`	Shape of the input image.
`im_memmap`	`ndarray or None`	Memory-mapped original image data.
`flow_vector_array`	`ndarray or None`	Precomputed flow vector array loaded from disk.
`current_t`	`int or None`	Cached timepoint for the current flow vector calculation.
`check_rows`	`ndarray or None`	Flow vector data for the current timepoint.
`check_coords`	`ndarray or None`	Coordinates corresponding to the flow vector data for the current timepoint.
`current_tree`	`cKDTree or None`	KDTree for fast lookup of nearby coordinates in the current timepoint.
`debug`	`dict or None`	Debugging information for tracking processing steps.

Methods:

Name	Description
`_allocate_memory`	Allocates memory and loads the precomputed flow vector array.
`_get_t`	Determines the number of timepoints to process.
`_get_nearby_coords`	Finds nearby coordinates within a defined radius from the given coordinates using a KDTree.
`_get_vector_weights`	Computes the weights for nearby flow vectors based on their distances and costs.
`_get_final_vector`	Computes the final interpolated vector for each coordinate using distance-weighted vectors.
`interpolate_coord`	Interpolates the flow vector at the given coordinates and timepoint.
`_initialize`	Initializes the FlowInterpolator by allocating memory and setting the timepoints.

Initializes the FlowInterpolator with image metadata and interpolation 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`
`max_distance_um`	`float`	Maximum distance allowed for interpolation (in micrometers, default is 0.5).	`0.5`
`forward`	`bool`	Indicates if the interpolation is performed in the forward direction (default is True).	`True`

interpolate_coord

interpolate_coord(coords, t)

Interpolates the flow vector at the given coordinates and timepoint.

Parameters:

Name	Type	Description	Default
`coords`	`ndarray`	Input coordinates for interpolation.	required
`t`	`int`	Timepoint index.	required

Returns:

Type	Description
`ndarray`	Interpolated flow vectors at the given coordinates and timepoint.

interpolate_all_forward

interpolate_all_forward(coords, start_t, end_t, im_info, min_track_num=0, max_distance_um=0.5)

Interpolates coordinates forward in time across multiple timepoints using flow vectors.

Parameters:

Name	Type	Description	Default
`coords`	`ndarray`	Array of input coordinates to track.	required
`start_t`	`int`	Starting timepoint.	required
`end_t`	`int`	Ending timepoint.	required
`im_info`	`ImInfo`	An instance of the ImInfo class containing image metadata and paths.	required
`min_track_num`	`int`	Minimum track number to assign to coordinates (default is 0).	`0`
`max_distance_um`	`float`	Maximum distance allowed for interpolation (in micrometers, default is 0.5).	`0.5`

Returns:

Type	Description
`tuple`	List of tracks and associated track properties.

interpolate_all_backward

interpolate_all_backward(coords, start_t, end_t, im_info, min_track_num=0, max_distance_um=0.5)

Interpolates coordinates backward in time across multiple timepoints using flow vectors.

Parameters:

Name	Type	Description	Default
`coords`	`ndarray`	Array of input coordinates to track.	required
`start_t`	`int`	Starting timepoint.	required
`end_t`	`int`	Ending timepoint.	required
`im_info`	`ImInfo`	An instance of the ImInfo class containing image metadata and paths.	required
`min_track_num`	`int`	Minimum track number to assign to coordinates (default is 0).	`0`
`max_distance_um`	`float`	Maximum distance allowed for interpolation (in micrometers, default is 0.5).	`0.5`

Returns:

Type	Description
`tuple`	List of tracks and associated track properties.

Hu Moment Tracking

Hu moment-based tracking for robust object identification across frames.

hu_tracking

Hu moment-based tracking for labeled objects across timepoints.

This module provides the HuMomentTracking class for tracking objects using Hu moment invariants and optical flow interpolation.

HuMomentTracking

HuMomentTracking(im_info, num_t=None, max_distance_um=1.0, viewer=None, device='auto', mode='auto', max_dense_pairs=int(10000000.0), max_dense_roi_voxels_cpu=int(50000000.0), max_dense_roi_voxels_gpu=int(20000000.0), low_memory=False)

A class for tracking objects in microscopy images using Hu moments and distance-based matching.

This version is optimized for: - Large images (memory-aware ROI extraction, streaming modes). - Optional GPU acceleration (via CuPy). - Fallback to sparse KDTree-based matching when dense matching is too large.

Attributes:

Name	Type	Description
`im_info`	`ImInfo`	An object containing image metadata and memory-mapped image data.
`device`	`{auto, cpu, gpu}`	Backend selection. "auto" uses GPU if available, otherwise CPU.
`device_type`	`str`	Resolved backend type ("cuda" or "cpu").
`num_t`	`int`	Number of timepoints in the image.
`max_distance_um`	`float`	Maximum allowed velocity (micrometers/second), scaled by time resolution for per-frame distance.
`low_memory`	`bool`	If True, prefer streaming ROI extraction and sparse matching to reduce peak memory.
`scaling`	`tuple`	Scaling factors for Z, Y, and X dimensions.
`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.
`im_distance_memmap`	`ndarray or None`	Memory-mapped distance transform data.
`im_marker_memmap`	`ndarray or None`	Memory-mapped marker data for object tracking.
`flow_vector_array_path`	`str or None`	Path to save the flow vector array.

Internal tuning parameters

mode : {"auto", "dense", "sparse"} Matching mode. "auto" selects dense for small problems, sparse for large ones. max_dense_pairs : int Maximum number of pairwise matches (N_post * N_pre) before switching to sparse matching. max_dense_roi_voxels_cpu : int Rough upper bound on total ROI voxels for dense ROI extraction on CPU. max_dense_roi_voxels_gpu : int Rough upper bound on total ROI voxels for dense ROI extraction on GPU.

run

run()

Main method to execute the Hu moment-based tracking process over the image data.

Voxel Reassignment

Voxel-level tracking and label reassignment across timepoints.

voxel_reassignment

Voxel reassignment across timepoints using flow interpolation.

This module provides the VoxelReassigner class for tracking and reassigning voxel labels across time using forward and backward flow interpolation.

VoxelReassigner

VoxelReassigner(im_info, num_t=None, viewer=None, store_running_matches=True, max_refine_iterations=3, device='auto', low_memory=False, max_query_points=int(1000000.0), max_bruteforce_pairs=int(10000000.0))

A class for voxel reassignment across time points using forward and backward flow interpolation.

This optimized version: - Streams over timepoints instead of holding all voxel coordinates in memory. - Reuses a single set of voxel matches between timepoints for all label types. - Avoids large intermediate dense arrays where possible. - Optionally stores running matches for downstream analysis. - Supports CPU/GPU matching with memory-aware chunking and fallbacks. - Assigns labels using weighted votes from forward/backward interpolations.

Parameters:

Name	Type	Description	Default
`im_info`	`ImInfo`	Image metadata and memory-mapped data.	required
`num_t`	`int`	Number of timepoints in the dataset. If None, it is inferred from the image metadata.	`None`
`viewer`	`Any`	Optional viewer for visualization / status updates.	`None`
`store_running_matches`	`bool`	If True, store per-frame voxel matches (may be large for big datasets). Matches are stored as one best source per target voxel.	`True`
`max_refine_iterations`	`int`	Maximum number of vote iterations to assign labels at t+1 from t. Set to 1 for a single pass.	`3`
`device`	`(auto, cpu, gpu)`	Backend selection for nearest-neighbor matching.	`"auto"`
`low_memory`	`bool`	If True, prefer lower-memory matching strategies at the cost of speed.	`False`
`max_query_points`	`int`	Maximum number of points per KDTree query chunk.	`int(1000000.0)`
`max_bruteforce_pairs`	`int`	Maximum number of pairwise distances to compute in GPU brute-force mode.	`int(10000000.0)`

match_voxels

match_voxels(vox_prev, vox_next, t)

Builds candidate voxel matches between two consecutive timepoints using both forward and backward interpolation.

Parameters:

Name	Type	Description	Default
`vox_prev`	`ndarray`	Voxels from the previous timepoint (N0, D).	required
`vox_next`	`ndarray`	Voxels from the next timepoint (N1, D).	required
`t`	`int`	Current timepoint index.	required

Returns:

Type	Description
`tuple`	(candidate_prev, candidate_next, distances) where candidates include all valid forward/backward interpolated matches.

run

run()

Main method to execute voxel reassignment for both branch and object labels.

This implementation: - initializes reassigned labels at t=0 for both branch and object labels. - for each pair of consecutive timepoints, computes forward/backward interpolation candidates once (based on the union of labeled voxels). - assigns labels at t+1 using weighted votes from all candidates.