itasc.tracking_ultrack.db_query

Read-only Ultrack database helpers for napari preview tooling.

Functions

annotation_name(value)
finalize_hierarchy_nodes(nodes, frame, *, ...)
greedy_color_classes(node_ids, edges)	Partition node_ids into classes with no intra-class edge (greedy graph coloring).
link_annotation_counts(db_path[, ...])	Return link annotation counts for the whole DB or one node's incident links.
node_annotation_metadata(nodes)
node_mask_and_bbox(node)
node_preview_metadata(nodes)
paint_nodes(nodes, plane_shape)
query_connected_nodes(db_path, selected_node_id)
query_distinct_heights(db_path)
query_frame_range(db_path)	Return sorted distinct frame indices present in the database.
query_hierarchy_cut_states(db_path, frame, *)
query_middle_frame(db_path)
query_node_edges(db_path, node_id)	Return raw, un-collapsed per-link edges incident to node_id.
query_union_color_classes(db_path, frame, ...)	Group the size-union_size candidates of frame into color classes of mutually non-overlapping candidates (a greedy graph coloring of the shared-atom overlap graph from OverlapDB).
query_union_sizes(db_path, frame)	Distinct atom-union sizes (height = number of merged atoms) present in frame, sorted ascending.
render_hierarchy_cut(db_path, frame, height, ...)
render_hierarchy_cut_state(db_path, frame, ...)
render_union_partition(db_path, frame, ...)	Full-frame partition for one horizontal slider position: the candidates in color_node_ids painted as merged regions, with the leftover territory filled by the largest available unions (size ≤ union_size) so regions outside this merge group still show at their most-merged state instead of as raw atoms.
summary_text(db_path, frame)

Classes

HierarchyCutState(node_ids, height)
NodeEdge(neighbor_id, weight, annotation, ...)
NodeEdges(selected_id, selected_t, ...)
UltrackDbPreview(labels, status, ...)

class itasc.tracking_ultrack.db_query.HierarchyCutState(node_ids, height)

Bases: object

Parameters:

• node_ids (tuple[int, ...])

• height (float | None)

node_ids: tuple[int, ...]

height: float | None

class itasc.tracking_ultrack.db_query.UltrackDbPreview(labels, status, probabilities, label_to_node_id, node_id_to_label, node_annotations)

Bases: object

Parameters:

• labels (ndarray)

• status (str)

• probabilities (dict[int, float])

• label_to_node_id (dict[int, int])

• node_id_to_label (dict[int, int])

• node_annotations (dict[int, str])

labels: ndarray

status: str

probabilities: dict[int, float]

label_to_node_id: dict[int, int]

node_id_to_label: dict[int, int]

node_annotations: dict[int, str]

as_tuple()

itasc.tracking_ultrack.db_query.query_middle_frame(db_path)

Return type:

int | None

Parameters:

db_path (Path)

itasc.tracking_ultrack.db_query.query_frame_range(db_path)

Return sorted distinct frame indices present in the database.

Return type:

tuple[int, ...]

Parameters:

db_path (Path)

itasc.tracking_ultrack.db_query.query_connected_nodes(db_path, selected_node_id)

Return type:

tuple[dict[int, float], dict[int, float]]

Parameters:

• db_path (Path)

• selected_node_id (int)

class itasc.tracking_ultrack.db_query.NodeEdge(neighbor_id, weight, annotation, direction, neighbor_t, neighbor_prob, neighbor_annot, weight_is_null=False)

Bases: object

Parameters:

• neighbor_id (int)

• weight (float)

• annotation (str)

• direction (str)

• neighbor_t (int)

• neighbor_prob (float)

• neighbor_annot (str)

• weight_is_null (bool)

neighbor_id: int

weight: float

annotation: str

direction: str

neighbor_t: int

neighbor_prob: float

neighbor_annot: str

weight_is_null: bool = False

class itasc.tracking_ultrack.db_query.NodeEdges(selected_id, selected_t, selected_prob, selected_annot, edges)

Bases: object

Parameters:

• selected_id (int)

• selected_t (int)

• selected_prob (float)

• selected_annot (str)

• edges (tuple[NodeEdge, ...])

selected_id: int

selected_t: int

selected_prob: float

selected_annot: str

edges: tuple[NodeEdge, ...]

itasc.tracking_ultrack.db_query.query_node_edges(db_path, node_id)

Return raw, un-collapsed per-link edges incident to node_id.

Unlike query_connected_nodes() (which multiplies weights when a neighbor pair shares multiple links), each LinkDB row becomes its own NodeEdge, so per-edge weights stay legible. Pure read.

Return type:

NodeEdges

Parameters:

• db_path (Path)

• node_id (int)

itasc.tracking_ultrack.db_query.link_annotation_counts(db_path, selected_node_id=None)

Return link annotation counts for the whole DB or one node’s incident links.

Return type:

dict[str, int]

Parameters:

• db_path (Path)

• selected_node_id (int | None)

itasc.tracking_ultrack.db_query.summary_text(db_path, frame)

Return type:

str

Parameters:

• db_path (Path)

• frame (int)

itasc.tracking_ultrack.db_query.query_distinct_heights(db_path)

Return type:

tuple[float, ...]

Parameters:

db_path (Path)

itasc.tracking_ultrack.db_query.query_union_sizes(db_path, frame)

Distinct atom-union sizes (height = number of merged atoms) present in frame, sorted ascending. Drives the vertical “union size” slider: index 0 is the finest (1 atom = individual atoms), higher indices merge more atoms.

Return type:

tuple[int, ...]

Parameters:

• db_path (Path)

• frame (int)

itasc.tracking_ultrack.db_query.query_union_color_classes(db_path, frame, union_size)

Group the size-union_size candidates of frame into color classes of mutually non-overlapping candidates (a greedy graph coloring of the shared-atom overlap graph from OverlapDB).

Each returned class is a tuple of node ids that can be painted together in one full-frame partition without conflict, so every candidate of this size is shown in exactly one class while keeping the number of classes (= horizontal slider positions) small. Returns () if no candidates of this size exist.

Return type:

tuple[tuple[int, ...], ...]

Parameters:

• db_path (Path)

• frame (int)

• union_size (int)

itasc.tracking_ultrack.db_query.greedy_color_classes(node_ids, edges)

Partition node_ids into classes with no intra-class edge (greedy graph coloring). Welsh–Powell order (highest degree first) keeps the class count low; ids preserve their original order within each class. Pure helper, no DB.

Return type:

tuple[tuple[int, ...], ...]

Parameters:

• node_ids (list[int])

• edges (Iterable[tuple[int, int]])

itasc.tracking_ultrack.db_query.render_union_partition(db_path, frame, color_node_ids, *, plane_shape, union_size=None)

Full-frame partition for one horizontal slider position: the candidates in color_node_ids painted as merged regions, with the leftover territory filled by the largest available unions (size ≤ union_size) so regions outside this merge group still show at their most-merged state instead of as raw atoms.

union_size caps how merged the leftover fill may be; when None it is taken from the selected candidates (their height), defaulting to atoms only.

Return type:

UltrackDbPreview

Parameters:

• db_path (Path)

• frame (int)

• color_node_ids (Iterable[int])

• plane_shape (tuple[int, int])

• union_size (int | None)

itasc.tracking_ultrack.db_query.query_hierarchy_cut_states(db_path, frame, *, source_index=None)

Return type:

tuple[HierarchyCutState, ...]

Parameters:

• db_path (Path)

• frame (int)

• source_index (int | None)

itasc.tracking_ultrack.db_query.render_hierarchy_cut(db_path, frame, height, *, plane_shape)

Return type:

UltrackDbPreview

Parameters:

• db_path (Path)

• frame (int)

• height (float)

• plane_shape (tuple[int, int])

itasc.tracking_ultrack.db_query.render_hierarchy_cut_state(db_path, frame, state, *, plane_shape)

Return type:

UltrackDbPreview

Parameters:

• db_path (Path)

• frame (int)

• state (HierarchyCutState)

• plane_shape (tuple[int, int])

itasc.tracking_ultrack.db_query.finalize_hierarchy_nodes(nodes, frame, *, plane_shape, empty_msg, status_suffix)

Return type:

UltrackDbPreview

Parameters:

• nodes (Iterable)

• frame (int)

• plane_shape (tuple[int, int])

• empty_msg (str)

• status_suffix (str)

itasc.tracking_ultrack.db_query.annotation_name(value)

Return type:

str

itasc.tracking_ultrack.db_query.node_preview_metadata(nodes)

Return type:

tuple[dict[int, float], dict[int, int], dict[int, int]]

itasc.tracking_ultrack.db_query.node_annotation_metadata(nodes)

Return type:

dict[int, str]

itasc.tracking_ultrack.db_query.paint_nodes(nodes, plane_shape)

Return type:

ndarray

Parameters:

plane_shape (tuple[int, int])

itasc.tracking_ultrack.db_query.node_mask_and_bbox(node)