itasc.cellpose.retrack

DB-free greedy retracker for the standalone segment + track corrector.

This mirrors the constrained retracker in itasc.tracking_ultrack (which ships in a separate itasc-tracking distribution the standalone itasc-cellpose tool does not depend on), reduced to the validation-free case the standalone needs: starting from the current frame, every later frame’s labels are re-linked to the already-retracked neighbour toward the start frame by the same additive similarity score (area ratio + centroid-corrected IoU - distance), matched greedily best-first. Unmatched target cells receive fresh ids. There is no locked/validated/reserved concept here — the standalone has no validation store — so the algorithm is purely the geometric re-linking.

Everything here is Qt-free and depends only on numpy/scipy/skimage, so it ships inside the cellpose distro tree and is unit-testable without a viewer.

Functions

centroid_corrected_iou_from_coords(...)	IoU after shifting the target so its centroid matches the source's.
retrack_frame(ref_labels, target_labels, *)	Remap every target id to its best-matching reference id by similarity.
retrack_stack(stack, *, start_frame, direction)	Retrack a time-first (T, Y, X) stack outward from start_frame.
similarity_score(*, area_ratio, ...)	Additive similarity score (higher = more preferred).

itasc.cellpose.retrack.centroid_corrected_iou_from_coords(src_coords, src_centroid, target_coords, target_centroid)

IoU after shifting the target so its centroid matches the source’s.

Return type:

float

Parameters:

• src_coords (ndarray)

• src_centroid (ndarray)

• target_coords (ndarray)

• target_centroid (ndarray)

itasc.cellpose.retrack.similarity_score(*, area_ratio, centroid_corrected_iou, distance, area_weight, iou_weight, distance_weight)

Additive similarity score (higher = more preferred).

Shape terms are positive rewards in [0, 1]; distance is a raw pixel penalty, so the score can go negative for far candidates.

Return type:

float

Parameters:

• area_ratio (float)

• centroid_corrected_iou (float)

• distance (float)

• area_weight (float)

• iou_weight (float)

• distance_weight (float)

itasc.cellpose.retrack.retrack_frame(ref_labels, target_labels, *, max_dist_px=50.0, area_weight=1.0, iou_weight=1.0, distance_weight=0.05)

Remap every target id to its best-matching reference id by similarity.

Each target cell takes its highest-scoring still-free reference cell (greedy best-first), among reference cells whose centroid is within max_dist_px. Targets with no eligible reference get a fresh id above all existing ids, so no two cells ever collide. Returns a relabelled copy of target_labels (input arrays are not mutated).

Return type:

ndarray

Parameters:

• ref_labels (ndarray)

• target_labels (ndarray)

• max_dist_px (float)

• area_weight (float)

• iou_weight (float)

• distance_weight (float)

itasc.cellpose.retrack.retrack_stack(stack, *, start_frame, direction, max_dist_px=50.0, area_weight=1.0, iou_weight=1.0, distance_weight=0.05)

Retrack a time-first (T, Y, X) stack outward from start_frame.

The start frame is kept as the anchor; each later frame in direction is re-linked (retrack_frame()) to the already-retracked neighbour toward the start frame, so corrected ids propagate. Returns a new stack; the input is not mutated.

Return type:

ndarray

Parameters:

• stack (ndarray)

• start_frame (int)

• direction (Literal['forward', 'backward'])

• max_dist_px (float)

• area_weight (float)

• iou_weight (float)

• distance_weight (float)