TrackMate

Wrapper around TrackMate [6, 7, 8]

class byotrack.implementation.linker.trackmate.trackmate.TrackMateParameters(allow_gap_closing: bool = True, allow_track_splitting: bool = False, allow_track_merging: bool = False, alternative_linking_cost_factor: float = 1.05, blocking_value: float = inf, cutoff_percentile: float = 0.9, max_frame_gap: int = 2, linking_max_distance: float = 15.0, gap_closing_max_distance: float = 15.0, merging_max_distance: float = 15.0, splitting_max_distance: float = 15.0, kalman_search_radius: float | None = None)

Bases: object

Parameters of TrackMate [7, 8].

We do not support Features penalties yet. Moreover track splitting and merging is currently not supported in ByoTrack.

To use kalman filtering in addition to sparse lap tracking, set the kalman_search_radius value. By default, no kalman filtering is used.

The main parameters to set are:

  • linking_max_distance: The distance threshold for frame-to-frame linking.

  • max_frame_gap and gap_closing_max_distance: The temporal and spatial distances for track stitching.

  • kalman_search_radius: The distance threshold for kalman linking (Switch to AdvancedKalmanTracker).

allow_gap_closing

Use a second lap to solve tracklet stitching (Closing temporal gap between previously established tracks) Default: True

Type:

bool

allow_track_splitting

NOT SUPPORTED (Useful for cell tracking) Default: False

Type:

bool

allow_track_merging

NOT SUPPORTED (To allow split and remerge and handle split detections) Default: False

Type:

bool

alternative_linking_cost_factor

Alternative linking cost Default: 1.05

Type:

float

blocking_value

Cost for mon-physical, forbidden links. Default: inf

Type:

float

cutoff_percentile

Cutoff percentile Default: 0.9

Type:

float

max_frame_gap

The max difference in frames between two spots to allow for linking. For instance a value of 2 means that the tracker will be able to make a link between a spot in frame t and a successor spots in frame t+2, effectively bridging over one missed detection in one frame. Default: 2 (1 missed detections)

Type:

int

linking_max_distance

The max distance between two consecutive spots, in physical units, allowed for creating links. If using kalman filters: this is the initial search radius, in physical units, specifying how far two spots can be apart when initiating new tracks. (See kalman_search_radius) Default: 15.0

Type:

float

gap_closing_max_distance

Gap-closing max spatial distance. The max distance between two spots, in physical units, allowed for creating links over missing detections. Default: 15.0

Type:

float

merging_max_distance

Unused. Track merging max spatial distance. Default: 15.0

Type:

float

splitting_max_distance

Unused. Track splitting max spatial distance. Default: 15.0

Type:

float

kalman_search_radius

Set this parameter to use the AdvancedKalmanTracker. The max search radius specifying how far from a predicted position the tracker should look for candidate spots. Default: None (Without kalman filters)

Type:

float | None

save(path: str | os.PathLike) → None

Save the parameters to the given path.

Uses json format.

Parameters:

path (str | os.PathLike) – Path to the output file

class byotrack.implementation.linker.trackmate.trackmate.TrackMateLinker(fiji_path: str | os.PathLike, specs: TrackMateParameters)

Bases: Linker

Run TrackMate [7, 8] from Fiji [6].

Wrapper around TrackMate, using Fiji headless call. Supports 2D and 3D frames.

About TrackMate: It is a global distance minimization tracking. It supports multiple algorithms. We have wrapped the more advanced ones (SparseLapTracker and AdvancedKalmanTracker that both follows [7]). It solves frame-to-frame GDM between detections. And then solve a GDM between tracklets to correct them (stitch, merge, split). The AdvancedKalmanTracker additionally uses kalman filters to estimate velocities of particles.

Here we rely on the handmade ImageJ script “_trackmate.py” that expects detections as instance segmentation and the hyperparameters of the linking process.

We do not support track splitting and merging yet, neither the use of feature-based cost.

The workflow is:

  1. Save detections to segmentation format

  2. Run the Fiji script

  3. [In Fiji] Read segmentation, load parameters, extract detections, run linking [5], export tracks to xml

  4. Read Fiji tracks and return

Note

This implementation requires Fiji to be installed (https://imagej.net/downloads)

Note

In case of missed detections, positions are filled with nan. To fill nan with true values, use an Interpolator

runner

Fiji runner

Type:

byotrack.fiji.FijiRunner

specs

Parameters specifications of the algorithm

Type:

TrackmateParameters

run(video, detections_sequence: Sequence[byotrack.Detections]) → list[byotrack.Track]

Run the linker on a whole video.

Parameters:

  • video (Sequence[np.ndarray] | np.ndarray) – Sequence of T frames (array). Each array is expected to have a shape ([D, ]H, W, C)

  • detections_sequence (Sequence[byotrack.Detections]) – Detections for each frame Detections is expected for each frame of the video, in the same order. (Note that for a given frame, the Detections can be empty)

Returns:

Tracks of particles

Return type:

Collection[byotrack.Track]