Tracks

class byotrack.api.tracks.Track(start: int, points: Tensor, identifier: int | None = None, detection_ids: Tensor | None = None, *, merge_id: int = -1, parent_id: int = -1)

Bases: object

Track for a given target.

A track is defined by a positive identifier, a starting frame and a succession of positions. In a detect-then-track context, a track can optionally contains the detection identifiers for each time frame (-1 if non-linked to any particular detection at this time frame)

It supports target splitting and merging through a mapping between tracks with parent_id and merge_id attributes. By construction, when a track splits, it terminates (and the children are born).

identifier

Identifier of the track (positive)

Type:

int

start

Starting frame of the track

Type:

int

points

Positions (i, j) of the target (from starting frame to ending frame) Shape: (T, dim), dtype: float32

Type:

torch.Tensor

detection_ids

Detection id for each time frame (-1 if unknown or non-linked to a particular detection at this time frame) Shape: (T,), dtype: int32

Type:

torch.Tensor

merge_id

Optional identifier to the merged track. This allows to handle merges (such as cell divisions in a reversed temporal order). At least one other track should share the same merge_id. This should not be used to do tracklet stitching (See DistStitcher for such use cases) Default: -1 (Merged to no one)

Type:

int

parent_id

cell divisions). At least one other track should share the same parent_id. This should not be used to do tracklet stitching (See DistStitcher for such use cases) Default: -1 (No parent)

Type:

int

property dim: int

Return the dimension (2D or 3D) of the track.

overlaps_with(other: Track, tolerance=0) → bool

Test if this track overlaps with another one in time.

Parameters:

• other (Track) – The other track

• tolerance (int) – Time tolerance before detecting an overlap. Default: 0 (no tolerance)

static tensorize(tracks: Collection[Track], frame_range: tuple[int, int] | None = None) → torch.Tensor

Convert a collection of tracks into a tensor on a given frame_range.

Useful view of the data to speedup some mathematical operations

Parameters:

• tracks (Collection[Track]) – A collection of tracks (usually from the same video)

• frame_range (tuple[int, int] | None) – Frame range (start included, end excluded) If None, the minimal range to hold all points is computed

Returns:

Tracks data in a single tensor

Shape: (T, N, dim), dtype: float32

Return type:

torch.Tensor

static save(tracks: Collection[Track], path: str | os.PathLike) → None

Save a collection of tracks to path.

Format: pt (pytorch)

{
    "offset": int
    "ids": Tensor (N, ), int32
    "points": Tensor (T, N, dim), float32
    "det_ids": Tensor (T, N), int32
    "merge_ids": Tensor (N, ), int32
    "parent_ids": Tensor (N, ), int32
}

Parameters:

• tracks (Collection[Track]) – Tracks to save

• path (str | os.PathLike) – Output path

static load(path: str | os.PathLike) → list[Track]

Load a collection of tracks from path.

Parameters:

path (str | os.PathLike) – Input path

Returns:

Loaded tracks

Return type:

list[Track]

static check_tracks(tracks: Collection[Track], *, warn=False) → None

Performs additional consistency checks that cannot be done at the Track level.

It will check that each track in the Collection has a different identifier. And it will check that merge_ids and parent_ids are correctly defined:

1. Several tracks should have the same merge id to another following one.

2. Several tracks should have the same parent id to another preceding one.

Parameters:

• tracks (Collection[Track]) – Collection of tracks to check

• warn (bool) – Will only raise a warning instead of an Exception

static reverse(tracks: Collection[Track], video_length=-1) → list[Track]

Reverse tracks in time.

It will keep the same order for tracks and the same identifiers. Points are in reversed orders. A merge id becomes a parent id (and vice versa).

Parameters:

• tracks (Collection[Track]) – Collection of tracks to reverse

• video_length (int) – Optional length of the video. If not provided, it is inferred from the last tracked object. Default: -1 (inferred from tracks)

Returns:

Reversed tracks

Return type:

list[Track]

byotrack.api.tracks.update_detection_ids(tracks: Collection[Track], detections_sequence: Sequence[byotrack.Detections], *, threshold=1e-05, use_segmentation=True) → None

Update the detections_ids attribute of each track inplace.

For each frame and each track, a perfectly matching detection is searched (the track position should be equal to the detection position). If a match is found, it is registered in the detections_ids attribute.

This is useful to fill the detection_ids attributes after a wrapping linking code (See EMHT or TrackMate). For this code to work, the linking algorithm that produces tracks should use the detection position as the track position without using any temporal/spatial smoothing.

Parameters:

• tracks (Collection[Track]) – The tracks to update inplace.

• detections_sequence (Sequence[byotrack.Detections]) – Detections for the different frames It should directly be the detections used in the linking algorithm.

• threshold (float) – Distance threshold for matching with a detection. Should be small to enforce a perfect match. Default: 1e-5.

• use_segmentation (bool) – Extract the mean position from the segmentation property instead of relying on the position property (Icy and Fiji are only given the segmentation).

TrackingGraph

class byotrack.api.tracking_graph.TrackingGraph(*args, backend=None, **kwargs)

Bases: DiGraph

Directed tracking graph.

An alternative view over tracks where each detection is a node and temporal continuity/split/merge relations are edges. Provides conversion to/from the default byotrack.Track format and can bridge to other tracking formats.

Note: TrackingGraph should only be created through the two provided builders: from_tracks and

from_nx, as they will sanitize and check the data format, allowing its usage across ByoTrack.

Node attributes:

• t: frame index

• [z, ]y, x: detection position (z is optional; 3D only)

• track_id: positive identifier of the track (optional)

• detection_id: source detection id (optional, -1 if unknown)

Edge attributes (optional):

• split: True if the edge represents a split

• merge: True if the edge represents a merge

static from_tracks(tracks: Collection[byotrack.Track]) → TrackingGraph

Build a graph from byotrack.Track objects.

Each track becomes a linear chain (one node per defined point). Split/merge relations are added as edges between the end of a parent and the start of the child track.

Parameters:

tracks (Collection[Track]) – Tracks to convert.

Returns:

The constructed graph.

Return type:

TrackingGraph

static from_nx(nx_graph: DiGraph, *, frame_key='t', x_key='x', y_key='y', z_key='z', track_key='track_id', detection_key='detection_id', merge_key='merge', split_key='split') → TrackingGraph

Sanitize and convert a generic NetworkX DiGraph to a TrackingGraph.

Copies nodes/edges and remaps attribute keys. Validates that all edges are forward in time. Split/merge flags are imported if present and also inferred from in/out degrees.

Parameters:

• nx_graph (nx.DiGraph) – Source graph.

• *_key (str) – Node and edge attribute names to read from nx_graph.

Returns:

The sanitized tracking graph.

Return type:

TrackingGraph

to_tracks() → list[Track]

Convert the graph into byotrack.Track objects.

Linear segments (paths without split/merge) become tracks. Gaps inside a segment are encoded as NaNs. Track ids are reused when consistent, otherwise new unique ids are assigned. Split/merge relations set parent_id/merge_id.

Returns:

Tracks reconstructed from the graph.

Return type:

list[Track]