Install locally
create_env.cmd
install_cuda.cmd
.venv\Scripts\python tools\download_models.py
.venv\Scripts\python tools\prepare_publicdata.py
.venv\Scripts\python wrapper.py --local --infolder publicdata/plates \
--outfolder outputfolder --device cuda --model general_2dSetup requires uv and creates Python 3.11. CUDA setup installs matching PyTorch 2.11.0 and torchvision 0.26.0 wheels with CUDA 12.6. Use --device cpu for CPU inference. Run install_sam2.cmd before selecting the optional SAM2 model.
Input contract
Use NGFF 0.4 / Zarr v2 directories with explicit t/y/x axes, optional c/z, positive spatial scales and physical spatial units. The root must declare a plate and wells with listed image fields. Each field needs at least two frames, Z absent or singleton, and instance labels on the same grid. Labels must match image dimensions, transforms and units. Channel numbers are one-based. Calibration must be in NGFF; an OME-XML file alone is insufficient for this adapter.
Only HCS plates with 2D time series are accepted. Standalone images, static fields and volumes are rejected; nothing is projected. Use --label labels_cells (alias --labels) to select one label by its case-insensitive name. Without a name, track only the first label in the NGFF label registry; legacy stores without a registry use alphabetical order. Missing or ambiguous names fail before inference. Original unselected labels are preserved. all is a literal name, not a wildcard. Source stores are read-only. Materialize labels-only overlays with corresponding source pixels before use.
Pretrained models
| Model | Dimensions | Requirements |
|---|---|---|
| general_2d | 2D | General-purpose association transformer |
| ctc | 2D plate fields | CTC association model |
| general_2d_w_SAM2_features | 2D | Optional etultra/SAM2 packages and cached SAM2.1 backbone |
Parameters
| Flag | Default | Meaning |
|---|---|---|
| --labels | all | All label groups or comma-separated names |
| --channel | 1 | One image channel for association features |
| --mode | greedy | greedy, greedy_nodiv or ilp |
| --device | auto | auto, cuda, cpu or mps |
| --model-dir | models | Local verified cache |
| --max-memory-gb | 4 | Array preflight in GiB; graph/model costs are additional |
| --workers | 0 | Feature workers; zero uses the main process |
| --batch-size | 1 | Prediction batch size |
| --movie | false | 2D tracking and Divisualisation MP4s per plate; optional runtime required |
| --movie-fps | 12 | Playback rate, separate from acquisition time |
Output semantics
Each source publishes a result directory with its copied OME-Zarr, tracking.sqlite, fields.csv, tracks.csv, observations.csv, links.csv and provenance.json. Trajectory labels live under labels/<source_name>_tracks. Optional tracking_movie.mp4, spacetime_movie.mp4 and movie.json contain sequential Divisualisation spacetime segments per field and label set. The vertical display axis is time, not physical Z; no independent error scoring is implied. Original pixels and labels are preserved. Existing destinations cannot be overwritten. Failures retain a hidden partial directory and FAILED.json.
Join using field_id and track_id. IDs identify CTC tracklets: gaps and divisions start new segments. parent_kind distinguishes gap continuation from division. Observations retain original instance IDs. Coordinates apply ordered transforms in micrometers; speed uses micrometers per second with calibrated time, otherwise per frame. Singleton speeds are NULL. Inference uses the original pixel grid; output calibration does not resample anisotropic voxels.
Bilayers and BIOMERO
config.yaml follows the CISegmentation descriptor pattern. python bilayers_cli.py validate checks the descriptor; generate prints its command. Stage images at /data/in, outputs at /data/out and cached models at /opt/models. The descriptor uses cellularimagingcf/w_citrackastra:v0.1.1, including all model weights and movie support.
Result stores live one level inside each source result directory. The integration must discover stores recursively and attach their SQLite/CSV companions. Verify this mapping in your installed BIOMERO version. Production OMERO/Slurm roundtrip validation has not been performed.
Divisualisation movie
Install install_movie.cmd and add --movie true. This uses the actual Divisualisation SpacetimeLift renderer, with a conventional 2D tracking MP4 and a spacetime MP4 per plate. Plate fields and label sets play as sequential segments. Windows uses a hidden native OpenGL context; the Docker runtime uses Xvfb/Mesa for unattended Linux rendering.
Docker images and separate models
cellularimagingcf/w_citrackastra:v0.1.1 contains the complete CUDA/SAM2 workflow, local weights and both movie renderers. Use v0.1.1-runtime with a read-only model cache mounted at /opt/models, or reuse the data-only cellularimagingcf/citrackastra-models:v0.1.1 image in a multi-stage build. See Docker commands and the release artifacts and validation reports.
Cite the method
Benjamin Gallusser and Martin Weigert, Trackastra: Transformer-based cell tracking for live-cell microscopy, ECCV 2024. Cite SAM2 and Trackastra-et-Ultra when using SAM2 features. See NOTICE for sources and licenses.