funtracks.user_actions.user_connect_nodes

UserConnectNodes

UserConnectNodes(
    tracks: Tracks,
    nodes: Iterable[Node],
    linear: bool = False,
    force: bool = False,
    _top_level: bool = True,
)

Bases: ActionGroup

Connect a selection of nodes, according to the division rules or linearly.

The selected nodes are sorted by time and connected pairwise, so that they form one chain. Pairs that are connected already are left alone, so a partly connected selection is completed rather than rebuilt. Skip edges are allowed, as well as existing outgoing edges. If the source of a new edge has no successor yet, the tracklet id of the first (earliest) node propagates along the whole chain.

A source that already has exactly one successor outside of the selection is handled according to linear. By default (linear = False), a division is created there, and the regular division track id rules apply. With linear=True that existing edge is treated as a conflict instead, so that the selection ends up as one linear track without divisions. Outgoing edges of the last node of the chain are never touched, since no new edge is added there.

See :class:UserDisconnectNodes for the inverse action.

Parameters:

Name	Type	Description	Default
tracks	Tracks	The tracks to connect the nodes in.	required
nodes	Iterable[Node]	The nodes to connect. At least two nodes are required, and no two nodes may be in the same time point.	required
linear	bool	Whether to connect the nodes into a linear track, treating existing outgoing edges of the sources as conflicts instead of creating divisions. Defaults to False.	False
force	bool	Whether to force the action by removing conflicting edges. Defaults to False.	False
_top_level	bool	If True, add this action to the history and emit refresh. Set to False when used as a sub-action inside a compound action. Defaults to True.	True

Raises:

Type	Description
InvalidActionError	If fewer than two distinct nodes are given, if a node is not in the solution graph, if two nodes share a time point, or if the nodes are connected already (all never forceable). If connecting would conflict with existing edges, a forceable InvalidActionError is raised unless force is True.

has_division_choice

has_division_choice(
    tracks: Tracks, nodes: Iterable[Node]
) -> bool

Whether connecting these nodes linearly differs from connecting them with divisions, i.e. whether it is worth asking the user which one they want.

Returns False for a selection that cannot be connected at all, or that has nothing left to connect.