zea.tracking

Tracking module.

This module provides point tracking algorithms for 2D and 3D data.

Classes:

  • BaseTracker: Abstract base class for trackers.

  • LucasKanadeTracker: Pyramidal Lucas-Kanade tracker (2D/3D).

  • SegmentationTracker: Segmentation-based tracker using contour matching.

Classes

BaseTracker([ndim])

Abstract base class for point tracking algorithms.

LucasKanadeTracker([win_size, max_level, ...])

Lucas-Kanade optical flow tracker.

SegmentationTracker(model[, preprocess_fn, ...])

Segmentation-based tracker.
class zea.tracking.BaseTracker(ndim=2, **kwargs)[source]

Bases: ABC

Abstract base class for point tracking algorithms.

This class defines the interface for tracking algorithms in the zea package. Implementations should handle both 2D and 3D tracking where applicable.

Parameters:

  • ndim (int) – Number of dimensions (2 for 2D, 3 for 3D).

  • **kwargs – Tracker-specific parameters.

Initialize the tracker with parameters.

abstractmethod track(prev_frame, next_frame, points)[source]

Track points from prev_frame to next_frame.

Parameters:

  • prev_frame – Previous frame/volume of shape (H, W) or (D, H, W).

  • next_frame – Next frame/volume of shape (H, W) or (D, H, W).

  • points – Points to track, shape (N, ndim) in (y, x) or (z, y, x) format.

Returns:

Tracked point locations, shape (N, ndim).

Return type:

new_points

track_sequence(frames, initial_points)[source]

Track points through a sequence of frames.

Parameters:

  • frames (List) – List of frames/volumes to track through.

  • initial_points – Starting points in first frame, shape (N, ndim).

Return type:

List

Returns:

List of N arrays, where each array has shape (T, ndim) containing the trajectory of one point through all T frames.

class zea.tracking.LucasKanadeTracker(win_size=(32, 32), max_level=3, max_iterations=30, epsilon=0.01, **kwargs)[source]

Bases: BaseTracker

Lucas-Kanade optical flow tracker.

Implements pyramidal Lucas-Kanade optical flow tracking.

Parameters:

  • win_size (Tuple[int, ...]) – Window size (height, width) for 2D or (depth, height, width) for 3D.

  • max_level (int) – Number of pyramid levels (0 means no pyramid).

  • max_iterations (int) – Maximum iterations per pyramid level.

  • epsilon (float) – Convergence threshold for iterative solver.

  • **kwargs – Additional parameters.

Example

>>> from zea.tracking import LucasKanadeTracker
>>> import numpy as np

>>> tracker = LucasKanadeTracker(win_size=(32, 32), max_level=3)
>>> frame1 = np.random.rand(100, 100).astype("float32")
>>> frame2 = np.random.rand(100, 100).astype("float32")
>>> points = np.array([[50.5, 55.2], [60.1, 65.8]], dtype="float32")
>>> new_points = tracker.track(frame1, frame2, points)
>>> new_points.shape
(2, 2)

Initialize custom Lucas-Kanade tracker.

track(prev_frame, next_frame, points)[source]

Track points using custom pyramidal Lucas-Kanade.

Parameters:

  • prev_frame – Previous frame/volume (tensor), shape (H, W) for 2D or (D, H, W) for 3D.

  • next_frame – Next frame/volume (tensor), shape (H, W) for 2D or (D, H, W) for 3D.

  • points – Points to track (tensor), shape (N, ndim) in (y, x) or (z, y, x) format.

Returns:

Tracked points as tensor, shape (N, ndim).

Return type:

Tuple

class zea.tracking.SegmentationTracker(model, preprocess_fn=None, postprocess_fn=None)[source]

Bases: BaseTracker

Segmentation-based tracker.

This tracker segments each frame independently and finds the closest points on the segmented contour to the previous frame’s points.

Parameters:

  • model – Segmentation model with a call method.

  • preprocess_fn (callable) – Optional preprocessing function to apply to frames before segmentation.

  • postprocess_fn (callable) – Optional postprocessing function to apply to segmentation output, which should return a binary mask of the target structure.

Initialize segmentation-based tracker.

track(prev_frame, next_frame, points)[source]

Track points by segmenting next_frame and finding closest contour points.

Parameters:

  • prev_frame – Previous frame (not used, kept for interface compatibility).

  • next_frame – Next frame to segment, shape (H, W).

  • points – Points from previous frame, shape (N, 2) in (row, col) format.

Returns:

Closest points on next frame’s contour, shape (N, 2).

Return type:

new_points