itasc.cellpose.track_laptrack

Link per-frame native masks across time with laptrack, Qt-free.

The standalone itasc-cellpose tool segments each frame independently (itasc.cellpose.native_masks), producing labels that are not consistent across time. This module closes that gap: it computes per-frame centroids, runs a linear-assignment tracker (laptrack) to link objects between consecutive frames, and relabels the stack so a tracked object keeps one id over its whole lifetime.

laptrack (and pandas) are imported lazily inside track_masks(), so importing this module — and the centroid / relabel helpers, which only need numpy + scikit-image — does not require the optional [laptrack] extra.

Module attributes

COORDINATE_COLS

Centroid coordinate columns used for linking; z is constant for 2D input.

Functions

build_track_dataframe(masks_tzyx)

Build a per-object centroid table from a (T, Z, Y, X) label stack.

relabel_by_tracks(masks_tzyx, track_of)

Relabel (T, Z, Y, X) masks by a (frame, orig_label) -> track_id map.

stitch_z(masks_tzyx, *[, iou_threshold])

Stitch per-plane labels into z-coherent 3-D objects, per timepoint.

track_axiswise(masks_tzyx, *[, ...])

Axis-by-axis linking: stitch z (overlap) then track t (motion).

track_masks(masks_tzyx, *[, max_distance, ...])

Link per-frame masks across time and return a track-consistent stack.
itasc.cellpose.track_laptrack.build_track_dataframe(masks_tzyx)[source]

Build a per-object centroid table from a (T, Z, Y, X) label stack.

Returns a pandas.DataFrame with columns frame, label, z, y, x (one row per labelled object per frame). z is always present and is constant 0 for single-slice (2D) input, so linking is uniform.

Parameters:

masks_tzyx (ndarray)

itasc.cellpose.track_laptrack.relabel_by_tracks(masks_tzyx, track_of)[source]

Relabel (T, Z, Y, X) masks by a (frame, orig_label) -> track_id map.

Output labels are track_id + 1 (so tracks start at 1 and background stays 0). Original labels absent from track_of are dropped to 0.

Return type:

ndarray

Parameters:
itasc.cellpose.track_laptrack.stitch_z(masks_tzyx, *, iou_threshold=0.25)[source]

Stitch per-plane labels into z-coherent 3-D objects, per timepoint.

Input (T, Z, Y, X) masks are labelled independently in every z-plane; this links labels across adjacent z by IoU so an object spanning several planes shares one id within its frame (background 0). For Z == 1 it is a no-op (returns an int32 copy). Cross-time uniqueness is left to the tracker.

Return type:

ndarray

Parameters:
itasc.cellpose.track_laptrack.track_masks(masks_tzyx, *, max_distance=15.0, max_frame_gap=0)[source]

Link per-frame masks across time and return a track-consistent stack.

max_distance is the maximum centroid displacement (in pixels, over z/y/x) allowed for a link; max_frame_gap > 0 enables gap-closing over that many missed frames. Output is (T, Z, Y, X) int32 with labels stable across time (background 0).

Return type:

ndarray

Parameters:
itasc.cellpose.track_laptrack.track_axiswise(masks_tzyx, *, max_distance=15.0, max_frame_gap=0, stitch_iou=0.25)[source]

Axis-by-axis linking: stitch z (overlap) then track t (motion).

Per-plane native masks are first stitched through z by IoU (stitch_z()) so an object becomes one 3-D label per frame, then linked across time by centroid (track_masks()). For single-slice (Z == 1) input the stitch is a no-op and this reduces to plain time tracking.

Stitching z (where adjacent planes overlap) and tracking t (where objects move) use the right metric for each axis; the shorter leading axis is taken as z upstream (see itasc.cellpose.shape.to_canonical_tzyx()).

Return type:

ndarray

Parameters:
itasc.cellpose.track_laptrack.COORDINATE_COLS = ['z', 'y', 'x']

Centroid coordinate columns used for linking; z is constant for 2D input.