itasc.tracking_ultrack.reseed

Re-solve with validated tracks using annotated Ultrack seed nodes.

The validate-and-resolve loop lets the user lock in confirmed cell tracks (validated_tracks), then re-solve the rest of the stack — possibly with tweaked parameters — without losing the validated work.

The contract for validated_tracks is dict[int, set[int]] where keys are cell IDs and values are the set of frames at which that cell is validated. This is independent of the on-disk JSON shape (which is managed separately by itasc.tracking_ultrack.validation_state).

prune_validated_overlaps and _build_frame_masks are kept for existing unit tests and ad hoc use. merge_validated_into_export is called at the end of resolve_with_canonical_segment to paste validated IDs back.

Functions

merge_validated_into_export(exported_labels, ...)

Paste validated masks back onto the solver's exported labelmap.

prune_validated_overlaps(working_dir, ...)

Delete NodeDB rows that overlap any validated mask and cascade to OverlapDB.
itasc.tracking_ultrack.reseed.prune_validated_overlaps(working_dir, validated_tracks, tracked_labels)[source]

Delete NodeDB rows that overlap any validated mask and cascade to OverlapDB.

Parameters:

  • working_dir (str | Path) – Ultrack working directory containing data.db.

  • validated_tracks (dict[int, set[int]]) – {cell_id: {frames}} — which frames each validated cell spans.

  • tracked_labels (ndarray) – Current corrected labelmap, shape (T, Y, X) or (T, Z, Y, X).

Returns:

Number of NodeDB rows deleted.

Return type:

int

Notes

Conflict criterion: any pixel intersection between a candidate node’s 2D footprint and any validated cell mask at the same frame counts as a conflict. The node (and all OverlapDB rows referencing it) is deleted.

The 3D node masks stored in NodeDB are stored as (1, h, w) crops (the ingest convention in ingest.py). We squeeze the Z=1 dimension for the 2D intersection test. True 3D (Z > 1) is currently not supported; the bbox test gracefully falls back to a bounding-box-only check in that case.

Both NodeDB and referencing OverlapDB rows are deleted in a single SQLite transaction to preserve DB consistency.

itasc.tracking_ultrack.reseed.merge_validated_into_export(exported_labels, validated_tracks, tracked_labels)[source]

Paste validated masks back onto the solver’s exported labelmap.

Validated cell_id values are reserved and pasted back with their original IDs so the validation store remains stable across resolve runs. If the solver independently used a reserved validated ID elsewhere, those solver pixels are moved to a fresh ID before the validated mask is pasted. Validated pixels overwrite any conflicting content in the exported labelmap.

Parameters:

  • exported_labels (ndarray) – Labelmap produced by Ultrack export, shape (T, Y, X) or (T, Z, Y, X). Modified in place and returned.

  • validated_tracks (dict[int, set[int]]) – {cell_id: {frames}} from the validation store.

  • tracked_labels (ndarray) – Current corrected labelmap (same spatial shape as exported_labels). The source of ground-truth masks.

Returns:

(merged_labelmap, id_map) where id_map maps original validated IDs to changed output IDs. The normal path preserves validated IDs, so id_map is usually empty. The labelmap is the same array as exported_labels, modified in place.

Return type:

tuple[ndarray, dict[int, int]]