How cdalinghaus-mthesis/trackastra_x works
Project Type & Purpose
• Trackastra is an open-source Python library + CLI + scripts for cell tracking in microscopy.
• Core functionality: load time-lapse images & segmentations, run a transformer model to predict associations, apply linking algorithms (greedy or ILP), and output tracked cell lineages.
File Structure
Top-level:
– scripts/ (training, evaluation, example config)
– trackastra/ (core package)
• cli.py
• data/ (I/O, augmentations, utility routines, resources)
• model/ (model definition, API, pretrained model loader, prediction)
• tracking/ (tracking algorithms: greedy, ILP, graph-building)
• utils/ (shared utilities)
– tests/ (unit tests)
– docs/, README.md, pyproject.toml, CI config, Docker support
Extract Key Architecture Insights from README
• Core transformer model (Trackastra) loads pretrained weights.
• Two primary workflows:
a. Inference (API / CLI / Napari plugin / Docker / Fiji TrackMate)
b. Training (scripts/train.py, config-driven, CTC format input)
• Optional ILP linking via external motile + solver backends (Gurobi or SCIP).
• Data flow: images + masks → model track(...) → track_graph → output formats (CTC, Napari tracks).
Main Components & Their Relationships
A. Data Ingestion Layer
• Elements: scripts/example_config.yaml, trackastra/data/data.py, augmentations.py, utils.py
• Role: read image stacks, segmentation masks (CTC format or NumPy arrays), apply augmentations/preprocessing.
B. Model Layer
• Elements: trackastra/model/model.py, model_api.py, pretrained.py
• Role: define the Transformer architecture, load weights, run forward pass to compute association scores.
C. Tracking Layer
• Elements: trackastra/tracking/tracking.py, ilp.py, track_graph.py
• Role: build a graph of cell detections across frames, apply greedy or ILP linking to produce track graphs.
D. API & CLI
• Elements: trackastra/cli.py, scripts/*.py, entry_points in setup.cfg
• Role: expose command-line interface (trackastra track), Python API (Trackastra.from_pretrained, model.track), scripts for training & evaluation.
E. Output & Visualization
• Formats: CTC challenge format, Napari tracks, Docker container outputs, Fiji TrackMate plugin
• Elements: graph_to_ctc, graph_to_napari_tracks, Dockerfile usage
F. External Dependencies
• PyTorch, NumPy, motile (ILP), Gurobi/SCIP, Napari plugin, Docker images, Fiji/TrackMate integration
Architectural Patterns & Principles
– Layered architecture: Data → Model → Tracking → Output
– Modular separation: each subpackage has a single responsibility
– Dependency injection: device choice (CPU/GPU/MPS), optional ILP module
– Extensibility points: new linking modes, new data augmentations, plugin interfaces
Additional Elements
– Tests suite & CI (GitHub Actions workflow) as validation pipeline
– Packaging & distribution components (PyPI, conda, Docker Hub)
– Documentation & examples directory