# cdalinghaus-mthesis/trackastra_x architecture

> Architecture diagram of the GitHub repository cdalinghaus-mthesis/trackastra_x, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cdalinghaus-mthesis/trackastra_x
- Repository: https://github.com/cdalinghaus-mthesis/trackastra_x

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input
    Input["Raw Images & Masks"]:::external

    %% Core Layers
    subgraph "Data Ingestion Layer"
        DI["Data Ingestion\n(trackastra/data)"]:::core
    end

    subgraph "Model Layer"
        ML["Transformer Model\n(trackastra/model)"]:::core
    end

    subgraph "Tracking Layer"
        TL["Tracking Algorithms\n(trackastra/tracking)"]:::core
    end

    subgraph "Output & Visualization"
        TrackGraph["Graph Construction\n(trackastra/tracking/track_graph.py)"]:::core
        ConfigExample["Example Config\n(scripts/example_config.yaml)"]:::core
    end

    subgraph "API & CLI"
        CLINode["CLI Interface\n(trackastra/cli.py)"]:::cli
        Scripts["Scripts Suite\n(scripts/)"]:::cli
    end

    subgraph "Utilities & Shared Helpers"
        Utils["Shared Utilities\n(trackastra/utils/utils.py)"]:::core
    end

    subgraph "External Integrations"
        Napari["Napari Plugin"]:::external
        Docker["Docker Image"]:::external
        TrackMate["Fiji TrackMate"]:::external
        PyPIConda["PyPI / Conda"]:::external
    end

    subgraph "Tests & Validation Suite"
        Tests["tests/"]:::test
    end

    subgraph "Documentation & Config"
        README["README.md"]:::doc
        DocsDir["docs/"]:::doc
        PyProj["pyproject.toml"]:::doc
        SetupCfg["setup.cfg"]:::doc
        CIWorkflow[".github/workflows/python-package-conda.yml"]:::doc
    end

    %% Data Flow
    Input -->|"NumPy arrays / CTC"| DI
    DI -->|"PyTorch Tensors"| ML
    ML -->|"Association Scores"| TL
    TL -->|"TrackGraph Object"| TrackGraph
    TrackGraph -->|"CTC / Napari Tracks"| ConfigExample

    %% API & CLI interactions
    CLINode --> DI
    CLINode --> ML
    CLINode --> TL
    CLINode --> TrackGraph
    Scripts --> DI
    Scripts --> ML
    Scripts --> TL
    Scripts --> TrackGraph

    %% Utilities usage
    Utils --> DI
    Utils --> ML
    Utils --> TL

    %% External integrations
    TrackGraph --> Napari
    TrackGraph --> Docker
    TrackGraph --> TrackMate
    TrackGraph --> PyPIConda

    %% Tests & Docs
    Tests -.-> DI
    Tests -.-> ML
    Tests -.-> TL
    Tests -.-> CLINode
    Tests -.-> Scripts

    README -.-> DI
    README -.-> ML
    README -.-> TL
    README -.-> CLINode

    DocsDir -.-> Tests
    PyProj -.-> Scripts
    SetupCfg -.-> CLINode
    CIWorkflow -.-> Tests

    %% Click Events
    click DI "https://github.com/cdalinghaus-mthesis/trackastra_x/tree/main/trackastra/data/"
    click ML "https://github.com/cdalinghaus-mthesis/trackastra_x/tree/main/trackastra/model/"
    click TL "https://github.com/cdalinghaus-mthesis/trackastra_x/tree/main/trackastra/tracking/"
    click CLINode "https://github.com/cdalinghaus-mthesis/trackastra_x/blob/main/trackastra/cli.py"
    click Scripts "https://github.com/cdalinghaus-mthesis/trackastra_x/tree/main/scripts/"
    click TrackGraph "https://github.com/cdalinghaus-mthesis/trackastra_x/blob/main/trackastra/tracking/track_graph.py"
    click ConfigExample "https://github.com/cdalinghaus-mthesis/trackastra_x/blob/main/scripts/example_config.yaml"
    click Utils "https://github.com/cdalinghaus-mthesis/trackastra_x/blob/main/trackastra/utils/utils.py"
    click Tests "https://github.com/cdalinghaus-mthesis/trackastra_x/tree/main/tests/"
    click README "https://github.com/cdalinghaus-mthesis/trackastra_x/blob/main/README.md"
    click DocsDir "https://github.com/cdalinghaus-mthesis/trackastra_x/tree/main/docs/"
    click PyProj "https://github.com/cdalinghaus-mthesis/trackastra_x/blob/main/pyproject.toml"
    click SetupCfg "https://github.com/cdalinghaus-mthesis/trackastra_x/blob/main/setup.cfg"
    click CIWorkflow "https://github.com/cdalinghaus-mthesis/trackastra_x/blob/main/.github/workflows/python-package-conda.yml"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef cli fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px
    classDef test fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef doc fill:#DDA0DD,stroke:#000,stroke-width:1px
```
