Cell Tracking Challenge (CTC)

IOs for CTC datasets [10].

We provide loading and saving functions for detections and tracks.

class byotrack.dataset.ctc.GroundTruthDetector(batch_size=20, *, add_true_frames=False)

Bases: BatchDetector

Converts a ‘ground-truth’ video of segmentation into byotrack Detections.

The video should not be normalized and each pixel is expected to be an integer.

Example:

# Load the segmentation video, it can be directly loaded from any folder containing tiff images
video = byotrack.Video("dataset/01_ERR_SEG")  # Load segmentation for CLB
# video = byotrack.Video("dataset/01_GT/SEG")  # Load ground-truth segmentation
# video = byotrack.Video("dataset/01_RES/TRA")  # Load predicted tracks segmentation

detector = GroundTruthDetector()

detections_sequence = detector.run(video)
detect(batch: ndarray) → list[Detections]

Apply the detection on a batch of frames.

By default, the frame ids are set from 0 to n-1 with n the size of the batch. The aggregattion of batches and frame ids correction is automatically handled when called the run method.

Parameters:

batch (np.ndarray) – Batch of video frames Shape: (B, [D, ]H, W, C)

Returns:

Detections for each given frame

Return type:

Sequence[byotrack.Detections]

byotrack.dataset.ctc.load_tracks(path: str | os.PathLike) → list[byotrack.Track]

Load saved tracks at the CTC format [10].

The CTC format for tracks consists of one tiff file for each frame which contains the segmentation of active tracks on the frame and a text file containing track ids, start and end frames and parent track.

First the code parses the segmentation tiff files (either “man*{frame_id}.tif” or “mask{frame_id}.tif”) and recovers all the known positions (plus the associated detections_ids) of the tracks. Then it parses the metadata in the txt file (either “man_track.txt” or “res_track.txt”) and validate the tracks creation.

See the official documentation of CTC at https://public.celltrackingchallenge.net/documents/Naming%20and%20file%20content%20conventions.pdf

Tracks with parent are not supported yet.

Example:

import byotrack
import byotrack.visualize
from byotrack.dataset import ctc

# Load the video and normalize it
video = byotrack.Video("dataset/01")  # Load videos
video.set_transform(byotrack.VideoTransformConfig(aggregate=True, normalize=True))

# Optionally, load ground-truth segmentations (may take a lot of RAM)
detections_sequence = ctc.GroundTruthDetector().run(byotrack.Video("dataset/01_GT/TRA"))

# Load ground-truth tracks
tracks = ctc.load_tracks("dataset/01_GT/TRA")

# Visualize everything
byotrack.visualize.InteractiveVisualizer(video, detections_sequence, tracks)
Parameters:

path (str | os.PathLike) – Path to the tracks data

Returns:

Saved tracks

Return type:

list[byotrack.Track]

byotrack.dataset.ctc.save_detections(path: str | os.PathLike, detections_sequence: Sequence[byotrack.Detections], *, as_res=True, as_seg=False, n_digit=4) → None

Save detections in the CTC format [10].

It will save one tiff image for each frame containing the segmentation of objects.

See the official documentation of CTC at https://public.celltrackingchallenge.net/documents/Naming%20and%20file%20content%20conventions.pdf

Parameters:

  • path (str | os.PathLike) – Folder path where to store the .tif files

  • detections_sequence (Sequence[byotrack.Detections]) – Detections for each frame

  • as_res (bool) – Whether to store as a results or as a ground-truth. Ground-truth are stored as “man_trackT.tif” Results as “maskT.tif” Default: True

  • as_seg (bool) – Only for ground-truth: file names are “man_segT.tif” instead of “man_trackT.tif” Default: False

  • n_digit (int) – Number of digit used to encode time in file names. Default: 4

byotrack.dataset.ctc.draw_disk(segmentation: ndarray, positions: ndarray, identifiers: ndarray, radius: ndarray, *, anisotropy=1.0, overwrite=False) → None

Draw disks on the segmentation.

Parameters:

  • segmentation (np.ndarray) – Segmentation image to draw on Shape: (D, H, W), dtype: uint16

  • positions (np.ndarray) – Positions of the disks’ centers Shape: (n, d), dtype: float32

  • identifiers (np.ndarray) – Identifier of each disk Shape: (n,), dtype: uint16

  • radius (np.ndarray) – Radius of each disk Shape: (n, ), dtype: float32)

  • anisotropy (float) – Relative size of a pixel along the depth dimension versus height/width dimensions. Default: 1.0

  • overwrite (bool) – Overwrite pixels that are already written (!=0) Default: False

byotrack.dataset.ctc.save_tracks(path: str | os.PathLike, tracks: Collection[byotrack.Track], detections_sequence: Sequence[byotrack.Detections] = (), *, as_res=True, as_seg=False, default_radius=3.0, last=0, shape: tuple[int, ...] | None = None, n_digit=4, anisotropy=1.0, overwrite_detections=False) → None

Save tracks in the CTC format [10].

It will save one tiff image for each frame containing the segmentation of objects and a metadata txt file describing the tracks identifiers, start/end frames and parents.

Parent information is not supported yet.

When no detections_sequence is given, tracks segmentations are simply drawn as disk with default_radius at the track localization. When detections_sequence is given, then for tracks without detections associated, a disk is drawn with default_radius (set at 0 to drop this behavior), otherwise the detection segmentation is used.

For smarter behaviors, one can directly modify the segmentation before saving.

See the official documentation of CTC at https://public.celltrackingchallenge.net/documents/Naming%20and%20file%20content%20conventions.pdf

Parameters:

  • path (str | os.PathLike) – Folder path where to store the .tif files

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

  • detections_sequence (Sequence[byotrack.Detections]) – Optional detections for each frame Default: ()

  • as_res (bool) – Whether to store as a results or as a ground-truth. Ground-truth are stored as “man_trackT.tif” and “man_track.txt” Results as “maskT.tif” and “res_track.txt” Default: True

  • as_seg (bool) – Only for ground-truth: file names are “man_segT.tif” instead of “man_trackT.tif” Note that it will also store the meta data to allow reloading the tracks. Default: False

  • default_radius (float) – Radius of drawn disk when no segmentation is available. Default: 5.0 (pixels)

  • last (int) – Overwrite last frame to consider Default: 0 (Will compute it from the last tracked particles)

  • shape (tuple[int, ...] | None) – Optional shape. Required when no detections_sequence is provided Default: None

  • n_digit (int) – Number of digit used to encode time in file names. Default: 4

  • anisotropy (float) – Relative size of a pixel along the depth dimension versus height/width dimensions. Default: 1.0

  • overwrite_detections (bool) – Overwrite the segmentation of objects with disk. Default: False (Disk are only drawn on background)