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 | PathLike) → List[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))

# Optionnally, 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 (Union[str, os.PathLike]) – Path to the tracks data
Returns:: Saved tracks
Return type:: List[byotrack.Track]

byotrack.dataset.ctc.save_detections(path: str | PathLike, detections_sequence: Sequence[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 (Union[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)

Draw disks on the segmentation

Args

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 | PathLike, tracks: Collection[Track], detections_sequence: Sequence[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)

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 (Union[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 (Optional[Tuple[int, ...]]) – 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)