funtracks.actions

Action

Action(tracks: Tracks)

Base class for all actions that can be applied to Tracks.

Two types of actions exist: - BasicAction: Atomic operations that directly modify tracks and trigger annotations - ActionGroup: Composite operations that contain and execute BasicActions

A modular change that can be applied to the given Tracks. The tracks must be passed in at construction time so that metadata needed to invert the action can be extracted. The change should be applied in the init function.

Parameters:

Name	Type	Description	Default
tracks	Tracks	The tracks that this action will edit	required

inverse

inverse() -> Action

Get the inverse of this action. Calling this function does undo the action, since the change is applied in the action constructor.

Raises:

Type	Description
NotImplementedError	if the inverse is not implemented in the subclass

Returns:

Name	Type	Description
Action	Action	An action that un-does this action, bringing the tracks back to the exact state it had before applying this action.

ActionGroup

ActionGroup(tracks: Tracks, actions: list[Action])

Bases: Action

Composite action that contains and executes multiple Actions.

ActionGroups are high-level operations that encapsulate application logic. They can contain BasicActions or other ActionGroups. They are not passed to annotators - only the BasicActions they contain are. Examples: UserAddNode, UserDeleteEdge, etc.

A group of actions that is also an action.

This is useful for creating composite actions from atomic BasicActions or other ActionGroups. Composite actions can contain application logic and can be un-done as a group.

Parameters:

Name	Type	Description	Default
tracks	Tracks	The tracks that this action will edit	required
actions	list[Action]	A list of actions contained within the group, in the order in which they should be executed. Can be BasicActions or ActionGroups.	required

AddEdge

AddEdge(
    tracks: Tracks,
    edge: Edge,
    attributes: dict[str, Any] | None = None,
)

Bases: BasicAction

Action for adding a new edge. Endpoints must exist already.

Create an action to add a new edge, with optional attributes.

Parameters:

Name	Type	Description	Default
tracks	Tracks	The Tracks to add the edge to	required
edge	Edge	The edge to add (source, target)	required
attributes	dict[str, Any] | None	Edge attributes to set. If any computed features are provided, they will be overridden by the Annotator. Defaults to None.	None

inverse

inverse() -> BasicAction

Delete edges

AddNode

AddNode(
    tracks: Tracks, node: Node, attributes: dict[str, Any]
)

Bases: BasicAction

Action for adding new nodes.

All node attributes (including mask and bbox if applicable) should be provided in the attributes dict.

Create an action to add a new node.

Parameters:

Name	Type	Description	Default
tracks	Tracks	The Tracks to add the node to.	required
node	Node	A node id.	required
attributes	dict[str, Any]	Node attributes including time, tracklet_id, and optionally position, mask, bbox, etc.	required

Raises:

Type	Description
ValueError	If time attribute is not in attributes.
ValueError	If track_id is not in attributes.
ValueError	If neither position nor a mask feature is in attributes.

inverse

inverse() -> BasicAction

Invert the action to delete nodes instead

BasicAction

BasicAction(tracks: Tracks)

Bases: Action

Atomic action that directly modifies tracks and triggers annotation updates.

BasicActions are the primitive operations that annotators listen to and respond to. Examples: AddNode, DeleteEdge, UpdateNodeSeg, etc.

DeleteEdge

DeleteEdge(tracks: Tracks, edge: Edge)

Bases: BasicAction

Action for deleting an edge. Edge must exist already.

Action for deleting an edge. Edge must exist already.

Parameters:

Name	Type	Description	Default
tracks	Tracks	The tracks to delete the edge from	required
edge	Edge	The edge to delete	required

Raises: ValueError: If the edge does not exist on the graph

inverse

inverse() -> BasicAction

Restore edge and their attributes

DeleteNode

DeleteNode(tracks: Tracks, node: Node)

Bases: BasicAction

Action of deleting an existing node.

Saves all node feature values so the action can be inverted.

Low-level action — not meant to be used directly. It soft-deletes only the node itself (incident edges are dropped from the view by remove_node_from_view but keep solution=True in graph_full). Managing the incident edges' solution flags is the responsibility of the enclosing user action (UserDeleteNode), which soft-deletes each incident edge with its own DeleteEdge first. Applying a bare DeleteNode to a node that still has in-solution edges therefore leaves graph_full's edge flags inconsistent with graph_solution — always go through the user action.

inverse

inverse() -> BasicAction

Invert this action to re-add the node with its saved attributes.

UpdateNodeAttrs

UpdateNodeAttrs(
    tracks: Tracks, node: Node, attrs: dict[str, Any]
)

Bases: BasicAction

Action for user updates to node attributes. Cannot update protected attributes (time, area, track id), as these are controlled by internal application logic.

Parameters:

Name	Type	Description	Default
tracks	Tracks	The tracks to update the node attributes for	required
node	Node	The node to update the attributes for	required
attrs	dict[str, Any]	A mapping from attribute name to list of new attribute values for the given nodes.	required

Raises:

Type	Description
ValueError	If a protected attribute is in the given attribute mapping.

inverse

inverse() -> BasicAction

Restore previous attributes

UpdateNodeSeg

UpdateNodeSeg(
    tracks: Tracks,
    node: Node,
    mask: Mask,
    added: bool = True,
    mask_key: str = td.DEFAULT_ATTR_KEYS.MASK,
)

Bases: BasicAction

Action for updating the segmentation associated with a node.

New nodes call AddNode with mask instead of this action.

Parameters:

Name	Type	Description	Default
tracks	Tracks	The tracks to update the segmentations for	required
node	Node	The node with updated segmentation	required
mask	Mask	The mask that was updated for the node	required
added	bool	If the provided mask were added (True) or deleted (False) from this node. Defaults to True	True
mask_key	str	The feature key for the mask column. Defaults to the standard mask key.	MASK

inverse

inverse() -> BasicAction

Restore previous attributes

UpdateTrackIDs

UpdateTrackIDs(
    tracks: Tracks,
    start_node: Node,
    tracklet_id: int | None = None,
    lineage_id: int | None = None,
)

Bases: BasicAction

Update tracklet ID and optionally lineage ID starting from a node.

This action captures the old IDs before updating, enabling proper undo/redo. The actual ID updates are performed by TrackAnnotator via notify_annotators().

The two updates have different scopes: - Tracklet ID: Updated for the linear track segment starting at start_node, following successors until a division is encountered or the track ends. - Lineage ID: Updated for the entire weakly connected component containing start_node, including all downstream branches after divisions.

Parameters:

Name	Type	Description	Default
tracks	Tracks	The tracks to update	required
start_node	Node	The node ID of the first node to update.	required
tracklet_id	int | None	The new tracklet id to assign to the track segment.	None
lineage_id	int | None	The new lineage id to assign to the connected component. If None, lineage ID is not updated. Defaults to None.	None

inverse

inverse() -> BasicAction

Restore the previous tracklet_id and lineage_id.

__getattr__

__getattr__(name: str)

Provide backwards compatibility for deprecated names.