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

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], *, using_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

• using_segmentation (bool) – Whether to use the segmentation to compute position of detections or use position if available. (Icy and Fiji are only given the segmentation) It uses the mean position (not the median).