itasc.tracking_ultrack.swap_candidate

Functions

cycle_index(count, current, *, larger)	Next index when cycling an area-sorted candidate list.
list_swap_candidates(*, db_path, frame, ...)	Return the matched node's nesting lineage around source_mask.
nearest_area_index(candidates, area)	Index of the candidate whose area is closest to area.

Classes

SwapCandidate(node_id, mask_2d, bbox, ...)

class itasc.tracking_ultrack.swap_candidate.SwapCandidate(node_id, mask_2d, bbox, centroid, area)

Bases: object

Parameters:

• node_id (int)

• mask_2d (ndarray)

• bbox (tuple[int, int, int, int])

• centroid (tuple[float, float])

• area (int)

node_id: int

mask_2d: ndarray

bbox: tuple[int, int, int, int]

centroid: tuple[float, float]

area: int

itasc.tracking_ultrack.swap_candidate.list_swap_candidates(*, db_path, frame, source_mask, frame_shape, protected_mask=None)

Return the matched node’s nesting lineage around source_mask.

Matches source_mask to the best-overlapping Ultrack node at frame, then walks the candidate containment lattice recorded in OverlapDB: every node that overlaps the matched node and is nested with it — a superset (larger merged segment that contains it) or a subset (smaller fragment it contains) — plus the matched node itself, returned sorted by area. Partially-overlapping neighbours (siblings/cousins) are excluded: they are different cells, so swapping onto them would relocate the cell rather than resize it. Z/C cycle through this area-sorted lineage by index.

OverlapDB is populated by both database builders (atom-union enumeration and canonical Ultrack segmentation), whereas hier_parent_id is only set by the latter — so the overlap lattice is the portable source of structure.

Return type:

list[SwapCandidate]

Parameters:

• db_path (Path)

• frame (int)

• source_mask (ndarray)

• frame_shape (tuple[int, int])

• protected_mask (ndarray | None)

itasc.tracking_ultrack.swap_candidate.nearest_area_index(candidates, area)

Index of the candidate whose area is closest to area.

Used to seed the cursor on the lineage member that best matches the currently displayed (matched) cell, so the first Z/C step moves relative to it.

Return type:

int

Parameters:

• candidates (tuple[SwapCandidate, ...] | list[SwapCandidate])

• area (int)

itasc.tracking_ultrack.swap_candidate.cycle_index(count, current, *, larger)

Next index when cycling an area-sorted candidate list.

larger steps toward bigger areas (higher index), otherwise toward smaller areas (lower index); both directions wrap around.

Return type:

int

Parameters:

• count (int)

• current (int)

• larger (bool)