funtracks.data_model.tracks

Tracks

Tracks(
    graph: GraphView,
    time_attr: str | None = None,
    pos_attr: str
    | tuple[str, ...]
    | list[str]
    | None = None,
    tracklet_attr: str | None = None,
    lineage_attr: str | None = None,
    scale: list[float] | None = None,
    ndim: int | None = None,
    features: FeatureDict | None = None,
    _segmentation: GraphArrayView | None = None,
)

A set of tracks consisting of a graph and an optional segmentation.

The graph nodes represent detections and must have a time attribute and position attribute. Edges in the graph represent links across time.

Attributes:

Name	Type	Description
graph	GraphView	A graph with nodes representing detections and and edges representing links across time.
features	FeatureDict	Dictionary of features tracked on graph nodes/edges.
annotators	AnnotatorRegistry	List of annotators that compute features.
scale	list[float] | None	How much to scale each dimension by, including time.
ndim	int	Number of dimensions (3 for 2D+time, 4 for 3D+time).

Initialize a Tracks object.

Parameters:

Name	Type	Description	Default
graph	GraphView	tracksdata directed graph with nodes as detections and edges as links.	required
time_attr	str | None	Graph attribute name for time. Defaults to "time" if None.	None
pos_attr	str | tuple[str, ...] | list[str] | None	Graph attribute name(s) for position. Can be: - Single string for one attribute containing position array - List/tuple of strings for multi-axis (one attribute per axis) Defaults to "pos" if None.	None
tracklet_attr	str | None	Graph attribute name for tracklet/track IDs. Defaults to "track_id" if None.	None
lineage_attr	str | None	Graph attribute name for lineage IDs. Defaults to "lineage_id" if None.	None
scale	list[float] | None	Scaling factors for each dimension (including time). If None, all dimensions scaled by 1.0.	None
ndim	int | None	Number of dimensions (3 for 2D+time, 4 for 3D+time). If None, inferred from segmentation or scale.	None
features	FeatureDict | None	Pre-built FeatureDict with feature definitions. If provided, time_attr/pos_attr/tracklet_attr are ignored. Assumes that all features in the dict already exist on the graph (will be activated but not recomputed). If None, core computed features (pos, area, track_id) are auto-detected by checking if they exist on the graph.	None
_segmentation	GraphArrayView | None	Internal parameter for reusing an existing GraphArrayView instance. Not intended for public use.	None

add_feature

add_feature(key: str, feature: Feature) -> None

Add a feature to the features dictionary and perform graph operations.

This is the preferred way to add new features as it ensures both the features dictionary is updated and any necessary graph operations are performed.

Parameters:

Name	Type	Description	Default
key	str	The key for the new feature	required
feature	Feature	The Feature object to add	required

delete_feature

delete_feature(key: str) -> None

Delete a feature from the features dictionary and perform graph operations.

This is the preferred way to delete features as it ensures both the features dictionary is updated and any necessary graph operations are performed.

Parameters:

Name	Type	Description	Default
key	str	The key for the feature to delete	required

disable_features

disable_features(feature_keys: list[str]) -> None

Disable multiple features from computation.

Removes features from annotators and FeatureDict.

Parameters:

Name	Type	Description	Default
feature_keys	list[str]	List of feature keys to disable	required

Raises:

Type	Description
KeyError	If any feature is not available (raised by annotators)

enable_features

enable_features(
    feature_keys: list[str], recompute: bool = True
) -> None

Enable multiple features for computation efficiently.

Adds features to annotators and FeatureDict, optionally computes their values.

Parameters:

Name	Type	Description	Default
feature_keys	list[str]	List of feature keys to enable	required
recompute	bool	If True, compute feature values. If False, assume values already exist in graph and just register the feature.	True

Raises:

Type	Description
KeyError	If any feature is not available (raised by annotators)

get_available_features

get_available_features() -> dict[str, Feature]

Get all features that can be computed across all annotators.

Returns:

Type	Description
dict[str, Feature]	Dictionary mapping feature keys to Feature definitions

get_mask

get_mask(node: Node) -> Mask | None

Get the segmentation mask associated with a given node.

.. deprecated:: 1.0 set_time will be removed in funtracks v2.0. Use update_node_attrs([node], {tracks.features.time_key: [time]}) instead.

Parameters:

Name	Type	Description	Default
node	Node	The node to get the mask for.	required

Returns:

Type	Description
Mask | None	Mask | None: The segmentation mask for the node, or None if no
Mask | None	segmentation is available.

get_position

get_position(node: Node, incl_time=False) -> list

Get position of a single node. Uses a direct per-node query — do not use in a loop over many nodes; use get_positions() instead.

get_positions

get_positions(
    nodes: Iterable[Node], incl_time: bool = False
) -> np.ndarray

Get the positions of nodes in the graph. Optionally include the time frame as the first dimension. Raises an error if any of the nodes are not in the graph.

NOTE: fetches all nodes in the graph internally. Optimised for bulk use. For a single node use get_position() instead.

Parameters:

Name	Type	Description	Default
node	Iterable[Node]	The node ids in the graph to get the positions of	required
incl_time	bool	If true, include the time as the first element of each position array. Defaults to False.	False

Returns:

Type	Description
ndarray	np.ndarray: A N x ndim numpy array holding the positions, where N is the number of nodes passed in

get_time

get_time(node: Node) -> int

Get the time frame of a given node. Raises an error if the node is not in the graph.

Parameters:

Name	Type	Description	Default
node	Any	The node id to get the time frame for	required

Returns:

Name	Type	Description
int	int	The time frame that the node is in

get_times

get_times(nodes: Iterable[Node]) -> Sequence[int]

Batch fetch times for many nodes in one query. NOTE: fetches all nodes in the graph internally. Optimised for bulk use. For a single node use get_time() instead.

in_degree

in_degree(nodes: ndarray | None = None) -> np.ndarray

Get the in-degree edge_ids of the nodes in the graph.

notify_annotators

notify_annotators(action: BasicAction) -> None

Notify annotators about an action so they can recompute affected features.

Delegates to the annotator registry which broadcasts to all annotators. The action contains all necessary information about which elements to update.

Parameters:

Name	Type	Description	Default
action	BasicAction	The action that triggered this notification	required

redo

redo() -> bool

Redo the last undone action from the action history.

Returns:

Name	Type	Description
bool	bool	True if an action was redone, False if there were no actions to redo

set_positions

set_positions(nodes: Iterable[Node], positions: ndarray)

Set the location of nodes in the graph. Optionally include the time frame as the first dimension. Raises an error if any of the nodes are not in the graph.

Parameters:

Name	Type	Description	Default
nodes	Iterable[node]	The node ids in the graph to set the location of.	required
positions	ndarray	An (ndim, num_nodes) shape array of positions to set.	required
incl_time	bool	If true, time is the first column and is included in ndim. Defaults to False.	required

undo

undo() -> bool

Undo the last performed action from the action history.

Returns:

Name	Type	Description
bool	bool	True if an action was undone, False if there were no actions to undo