itasc.tracking_ultrack.db_build

Shared Ultrack database construction pipeline.

Functions

annotate_database_from_corrections(...[, ...])	Apply correction-derived annotations to data.db and rescore nodes.
apply_annotations_and_score(working_dir, ...)	Reset annotations on an existing data.db, apply corrections, and rescore.
build_atom_union_database(atoms_path, ...[, ...])	Build candidate data.db from atoms.tif via a merge tree + branching.
build_ultrack_database(contour_maps_path, ...)	Build candidate data.db from canonical Ultrack segmentation + linking.

Classes

AnnotateAndScoreReport([fake_nodes, ...])
AtomUnionDatabaseBuildReport([total_nodes, ...])	Result of atom-union candidate-building + linking (stage ②).
UltrackDatabaseBuildReport()	Result of candidate-building (segmentation + linking).

class itasc.tracking_ultrack.db_build.UltrackDatabaseBuildReport

Bases: object

Result of candidate-building (segmentation + linking). No annotation state.

class itasc.tracking_ultrack.db_build.AtomUnionDatabaseBuildReport(total_nodes=0, total_overlaps=0, n_frames=0)

Bases: object

Result of atom-union candidate-building + linking (stage ②).

Parameters:

• total_nodes (int)

• total_overlaps (int)

• n_frames (int)

total_nodes: int = 0

total_overlaps: int = 0

n_frames: int = 0

class itasc.tracking_ultrack.db_build.AnnotateAndScoreReport(fake_nodes=0, anchor_nodes=0, anchor_links=0, scored_nodes=0, seed_nodes=0, anchor_incident_links_inserted=0, anchor_tail_links_annotated=0, injected_homemade_anchors=0)

Bases: object

Parameters:

• fake_nodes (int)

• anchor_nodes (int)

• anchor_links (int)

• scored_nodes (int)

• seed_nodes (int)

• anchor_incident_links_inserted (int)

• anchor_tail_links_annotated (int)

• injected_homemade_anchors (int)

fake_nodes: int = 0

anchor_nodes: int = 0

anchor_links: int = 0

scored_nodes: int = 0

seed_nodes: int = 0

anchor_incident_links_inserted: int = 0

anchor_tail_links_annotated: int = 0

injected_homemade_anchors: int = 0

itasc.tracking_ultrack.db_build.apply_annotations_and_score(working_dir, cfg, *, score_signal_path, corrections=None, validated_tracks=None, tracked_labels=None, progress_cb=None)

Reset annotations on an existing data.db, apply corrections, and rescore.

Runs after candidate-building (segmentation + linking) and before solve. The candidate set itself is left untouched; only node_annot, link.annotation and node_prob change. Safe to call repeatedly when the user toggles validations or anchors.

Return type:

AnnotateAndScoreReport

Parameters:

• working_dir (str | Path)

• cfg (TrackingConfig)

• score_signal_path (str | Path)

• corrections (list[Correction] | None)

• validated_tracks (dict[int, set[int]] | None)

• tracked_labels (ndarray | None)

• progress_cb (Callable[[str], None] | None)

itasc.tracking_ultrack.db_build.annotate_database_from_corrections(working_dir, cfg, *, score_signal_path, corrections=None, validated_tracks=None, tracked_labels=None, progress_cb=None)

Apply correction-derived annotations to data.db and rescore nodes.

Return type:

AnnotateAndScoreReport

Parameters:

• working_dir (str | Path)

• cfg (TrackingConfig)

• score_signal_path (str | Path)

• corrections (list[Correction] | None)

• validated_tracks (dict[int, set[int]] | None)

• tracked_labels (ndarray | None)

• progress_cb (Callable[[str], None] | None)

itasc.tracking_ultrack.db_build.build_atom_union_database(atoms_path, working_dir, cfg, progress_cb=None, *, contour_maps_path=None, cancel=None)

Build candidate data.db from atoms.tif via a merge tree + branching.

Reads atoms.tif (written by stage ①). Per frame it builds a backbone watershed-style merge tree over the atom RAG (atoms as leaves, walls weighted by ridge strength) plus branch candidates admitted most-ambiguous-first up to cfg.atom_overlap_budget overlap pairs — see atoms.build_atom_merge_tree / atoms.branch_unions. Every candidate’s total area is capped at cfg.atom_union_max_area. NodeDB + OverlapDB rows are stream-inserted in chunks, then linking runs.

contour_maps_path supplies the ridge weights: the residual contour is recomputed from it using the AtomParams embedded in atoms.tif (the stage-① output contract is unchanged — atoms.tif remains the sole artifact). When omitted, walls are treated as equally weighted, so the backbone degrades to a deterministic area-ordered tree.

Return type:

AtomUnionDatabaseBuildReport

Parameters:

• atoms_path (str | Path)

• working_dir (str | Path)

• cfg (TrackingConfig)

• progress_cb (Callable[[str], None] | None)

• contour_maps_path (str | Path | None)

• cancel (Callable[[], bool] | None)

itasc.tracking_ultrack.db_build.build_ultrack_database(contour_maps_path, foreground_masks_path, working_dir, cfg, progress_cb=None)

Build candidate data.db from canonical Ultrack segmentation + linking.

Produces NodeDB / LinkDB / OverlapDB rows with all annotations UNKNOWN and no node-prob scores. Pair with apply_annotations_and_score before run_solve to ingest validations/anchors.

Return type:

UltrackDatabaseBuildReport

Parameters:

• contour_maps_path (str | Path)

• foreground_masks_path (str | Path)

• working_dir (str | Path)

• cfg (TrackingConfig)

• progress_cb (Callable[[str], None] | None)