# royerlab/ultrack architecture

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

- Interactive diagram: https://gitdiagram.com/royerlab/ultrack
- Repository: https://github.com/royerlab/ultrack

## Overview

##### Main Components
- Configuration & Setup: Represented by modules under “ultrack/config” and top-level configuration files (e.g., napari.yaml, pyproject.toml). This part manages global settings and parameters.
- Client Interfaces:
– CLI: Found in “ultrack/cli”, which includes various command scripts for tasks such as segmentation, tracking, database operations, and server launching.
– API: Located in “ultrack/api”, exposing programmatic access to core tracking functionality.
– UI/Visualization: The integration with napari (as shown in the usage example) and the “ultrack/widgets” folder with widgets for interactive exploration and configuration.
- Core Tracking Engine:
– Core processing routines in “ultrack/core” – these include segmentation, linking, and matching routines.
– Segmentation and Tracking: Organized within “ultrack/core/segmentation” and “ultrack/core/linking” for handling image segmentation uncertainty and subsequently linking detections.
– Solver Module: In “ultrack/core/solve” and its submodules (e.g., the heuristic and MIP solvers), this component encapsulates the optimization routines (often integrating with Gurobi).
- Image Processing & Machine Learning:
– Modules under “ultrack/imgproc” and “ultrack/ml” cover pre-processing, flow estimation, intensity measurement, and potential ML-based classification.
- Data Management & Export:
– Components for exporting results or converting internal data to common formats can be found in “ultrack/core/export”.
– The database module in “ultrack/core” and “ultrack/api/database” handles storage of segmentation and tracking data.
- Utilities & Miscellaneous:
– Helper modules under “ultrack/utils” provide common functionality (e.g., array manipulation, multiprocessing, CUDA interfacing).
- External Integrations:
– Docker files (in the “docker” folder) which illustrate deployment in CPU/GPU environments.
– Integration with third-party tools (e.g., napari, Gurobi, FiJi) and environment setups featured in examples and dependency files.

##### Relationships and Interactions
- The CLI and API components act as gateways – they receive user inputs (either command-line arguments or API calls), initialize configuration, and then invoke the Core Tracking Engine.
- In the Core Tracking Engine, data flows from preprocessing (handled by “ultrack/imgproc” and “ultrack/ml”) into the segmentation module. Once segmented, the linking components (“ultrack/core/linking”) associate segments over time.
- The Solver Module within “ultrack/core/solve” then refines the tracking by solving optimization problems, using either heuristic routines or MIP solvers (Gurobi integration).
- Results are passed to the Export/Data Management layer for persistence and further analysis (e.g., generating tracks for visualization).
- The UI/Visualization component (through napari and “ultrack/widgets”) optionally consumes the export data, providing an interactive view of tracks and segmentation masks.

##### Architectural Patterns and Design Principles
- Layered Architecture: Clearly segment the configuration, communication interfaces (CLI/API), core processing, and visualization/export layers. This separation of concerns ensures modularity.
- Modular Design: Each component is self-contained (e.g., dedicated directories/modules for segmentation, linking, and solving), enabling ease of testing and future extension.
- Integration via Clear API: Using the API modules, the design supports both scripting and interactive usage (e.g., via napari plugins).

##### Relevant Technologies and Frameworks
- Python-based modules and configurations.
- Docker containers (cpu and gpu versions) used for deployment.
- External dependencies such as Gurobi (for solving), napari (for visualization), and conda environments (for reproducible builds).

- Clear Labels: Name each component (e.g., “Configuration Module”, “CLI Interface”, “Core Tracking Engine – Segmentation”, “Core Tracking Engine – Solver”, “Visualization and Widgets”).
- Related Components: For example, group all “ultrack/core” submodules together, and clearly show their interactions with image processing (“ultrack/imgproc”) and export (“ultrack/core/export”).

– Frontend & Interfaces (CLI, API, UI/napari)
– Core Processing (segmentation, linking, solver modules)
– Data/Export & External Integrations (database, Docker deployment, third-party libraries)
- External dependencies such as “Gurobi” and “napari” to show how they integrate into the respective components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Layer 1: Configuration & Setup"
        CFG["Configuration Module"]:::config
    end

    subgraph "Layer 2: Interfaces"
        CLI["CLI Interface"]:::interface
        API["API Interface"]:::interface
        UI["UI/Visualization"]:::interface
    end

    subgraph "Layer 3: Core Processing"
        SEG["Segmentation Module"]:::core
        LNK["Linking & Matching Module"]:::core
        SOL["Solver Module"]:::core
    end

    subgraph "Layer 4: Data Management & External Integrations"
        EXP["Export Module"]:::data
        DB["Database Module"]:::data
        EXT_DOCKER["Docker Deployment"]:::external
        EXT_GUROBI["Gurobi Integration"]:::external
    end

    subgraph "Support Modules"
        IMG["Image Processing"]:::support
        ML["Machine Learning"]:::support
        UTIL["Utilities & Miscellaneous"]:::support
    end

    %% Connections between Layers
    CFG --> CLI
    CFG --> API
    CFG --> UI

    CLI --> SEG
    API --> SEG

    IMG --> SEG
    ML --> SEG

    SEG --> LNK
    LNK --> SOL
    SOL --> EXP
    SOL --> DB

    CLI --> DB
    API --> DB

    UI --> EXP

    SOL --> EXT_GUROBI

    EXT_DOCKER -.-> CFG
    EXT_DOCKER -.-> CLI
    EXT_DOCKER -.-> API
    EXT_DOCKER -.-> UI

    %% Styles
    classDef config fill:#FCE4EC,stroke:#AD1457,stroke-width:2px;
    classDef interface fill:#E3F2FD,stroke:#1565C0,stroke-width:2px;
    classDef core fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px;
    classDef data fill:#FFF3E0,stroke:#EF6C00,stroke-width:2px;
    classDef external fill:#FFEBEE,stroke:#C62828,stroke-width:2px;
    classDef support fill:#EDE7F6,stroke:#5E35B1,stroke-width:2px;

    class CFG config;
    class CLI,API,UI interface;
    class SEG,LNK,SOL core;
    class EXP,DB data;
    class EXT_DOCKER,EXT_GUROBI external;
    class IMG,ML,UTIL support;

    %% Click Events
    click CFG "https://github.com/royerlab/ultrack/tree/main/ultrack/config"
    click CLI "https://github.com/royerlab/ultrack/tree/main/ultrack/cli"
    click API "https://github.com/royerlab/ultrack/tree/main/ultrack/api"
    click UI "https://github.com/royerlab/ultrack/tree/main/ultrack/widgets"
    click SEG "https://github.com/royerlab/ultrack/tree/main/ultrack/core/segmentation"
    click LNK "https://github.com/royerlab/ultrack/tree/main/ultrack/core/linking"
    click SOL "https://github.com/royerlab/ultrack/tree/main/ultrack/core/solve"
    click IMG "https://github.com/royerlab/ultrack/tree/main/ultrack/imgproc"
    click ML "https://github.com/royerlab/ultrack/tree/main/ultrack/ml"
    click UTIL "https://github.com/royerlab/ultrack/tree/main/ultrack/utils"
    click EXP "https://github.com/royerlab/ultrack/tree/main/ultrack/core/export"
    click DB "https://github.com/royerlab/ultrack/blob/main/ultrack/api/database.py"
    click EXT_DOCKER "https://github.com/royerlab/ultrack/tree/main/docker"
    click EXT_GUROBI "https://github.com/royerlab/ultrack/blob/main/ultrack/core/solve/mip_solver.py"
```
