Tracks

class byotrack.api.tracks.Track(start: int, points: Tensor, identifier: int | None = None, detection_ids: Tensor | None = None, merge_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 of the resulting merged tracks. (This features is experimental. Its goal is to handle cell divisions in a reversed temporal order) Default: -1 (Merged to no one)

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
}

Parameters:

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

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

static load(path: str | PathLike) → Collection[Track]

Load a collection of tracks from path

Parameters:

path (str | os.PathLike) – Input path

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)