funtracks.candidate_graph.utils

add_cand_edges

add_cand_edges(
    cand_graph: BaseGraph,
    max_edge_distance: float,
    node_frame_dict: None | dict[int, list[Any]] = None,
    iou_dict: dict[int, dict[int, float]] | None = None,
) -> None

Add candidate edges to a candidate graph by connecting all nodes in adjacent frames that are closer than max_edge_distance.

Parameters:

Name	Type	Description	Default
`cand_graph`	`BaseGraph`	Candidate graph with only nodes populated. Will be modified in-place to add edges.	required
`max_edge_distance`	`float`	Maximum distance that objects can travel between frames. All nodes within this distance in adjacent frames will by connected with a candidate edge.	required
`node_frame_dict`	`dict[int, list[Any]] \| None`	A mapping from frames to node ids. If not provided, it will be computed from cand_graph. Defaults to None.	`None`
`iou_dict`	`dict[int, dict[int, float]] \| None`	Pre-computed IOU values as a map from source node_id -> {target node_id -> iou}. When provided, the iou value is included directly in each edge dict passed to bulk_add_edges, avoiding a separate per-edge update pass after insertion. Defaults to None (no iou attribute added).	`None`

create_kdtree

create_kdtree(
    cand_graph: BaseGraph, node_ids: list[Any]
) -> KDTree

Create a kdtree with the given nodes from the candidate graph. Will fail if provided node ids are not in the candidate graph.

Parameters:

Name	Type	Description	Default
`cand_graph`	`BaseGraph`	A candidate graph	required
`node_ids`	`list[Any]`	The nodes within the candidate graph to include in the KDTree. Useful for limiting to one time frame. Must be a list (not a generic iterable) to preserve order for correct mapping of query_ball_tree results back to node ids.	required

Returns:

Name	Type	Description
`KDTree`	`KDTree`	A KDTree containing the positions of the given nodes, in the same order as node_ids.

nodes_from_points_list

nodes_from_points_list(
    points_list: ndarray, scale: list[float] | None = None
) -> tuple[td.graph.BaseGraph, dict[int, list[Any]]]

Extract candidate nodes from a list of points. Uses the index of the point in the list as its unique id. Returns a tracksdata graph with only nodes, and also a dictionary from frames to node_ids for efficient edge adding.

Parameters:

Name	Type	Description	Default
`points_list`	`ndarray`	An NxD numpy array with N points and D (3 or 4) dimensions. Dimensions should be in order (t, [z], y, x).	required
`scale`	`list[float] \| None`	Amount to scale the points in each dimension (including time). Only needed if the provided points are in "voxel" coordinates instead of world coordinates. Defaults to None, which implies the data is isotropic.	`None`

Returns:

Type	Description
`tuple[BaseGraph, dict[int, list[Any]]]`	tuple[td.graph.BaseGraph, dict[int, list[Any]]]: A candidate graph with only nodes, and a mapping from time frames to node ids.

nodes_from_segmentation

nodes_from_segmentation(
    segmentation: ndarray,
    scale: list[float] | None = None,
    mask: bool = True,
    t_start: int = 0,
) -> tuple[td.graph.BaseGraph, dict[int, list[Any]]]

Extract candidate nodes from a segmentation. Returns a tracksdata graph with only nodes, and also a dictionary from frames to node_ids for efficient edge adding.

Each node will have the following attributes

t
pos
area
mask (if mask=True): cropped boolean mask (tracksdata Mask object)
bbox (if mask=True): bounding box as [min_0, ..., max_0, ...] int array

Parameters:

Name	Type	Description	Default
`segmentation`	`ndarray`	A numpy array with integer labels and dimensions (t, [z], y, x). Labels must be unique across time, and the label will be used as the node id. If the labels are not unique, preprocess with funtracks.utils.ensure_unique_labels before calling this function.	required
`scale`	`list[float] \| None`	The scale of the segmentation data in all dimensions (including time, which should have a dummy 1 value). Will be used to rescale the point locations and attribute computations. Defaults to None, which implies the data is isotropic.	`None`
`mask`	`bool`	Whether to include mask and bbox attributes for each node. Uses regionprop.image (already computed by regionprops at no extra cost) and regionprop.bbox. Including them here avoids a separate write pass over all nodes later. Defaults to True.	`True`
`t_start`	`int`	The time value to assign to the first frame of the segmentation. Frame i will get t = t_start + i. Useful when the segmentation is a slice of a larger array and nodes need absolute time values. Defaults to 0.	`0`

Returns:

Type	Description
`tuple[BaseGraph, dict[int, list[Any]]]`	tuple[td.graph.BaseGraph, dict[int, list[Any]]]: A candidate graph with only nodes, and a mapping from time frames to node ids.