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 particle

A track is defined by an (non-unique) 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)

identifier

Identifier of the track (non-unique)

Type:

int

start

Starting frame of the track

Type:

int

points

Positions (i, j) of the particle (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 2-way merges (such as cell divisions in a reversed temporal order). The target track should start on the frame following the end of this track. 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). The parent track should end one frame before the start of this track. This should not be used to do tracklet stitching (See DistStitcher for such use cases) Default: -1

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) → 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 (Optional[Tuple[int, int]]) – 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 | PathLike) → None

Save a collection of tracks to path

Format: pt (pytorch)

{
    "offset": int
    "ids": Tensor (N, ), int64
    "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 | PathLike) → List[Track]

Load a collection of tracks from path

Parameters:

path (str | os.PathLike) – Input path

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

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. 2 tracks should have the same merge id to a third one starting right after the two ended.

2. 2 tracks should have the same parent id to a third one finishing right before the two started.

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)

byotrack.api.tracks.update_detection_ids(tracks: Collection[Track], detections_sequence: Sequence[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).