# uncbiag/unigradicon architecture

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

- Interactive diagram: https://gitdiagram.com/uncbiag/unigradicon
- Repository: https://github.com/uncbiag/unigradicon

## Overview

##### Project type and purpose
- This is a Python-based full-stack research tool. It ships as a library (`src/unigradicon`), a set of CLI executables (`unigradicon-register`, `unigradicon-warp`), training scripts (`training/*.py`), and a Slicer extension. Its purpose is to perform medical image registration via pre-trained foundation models (uniGradICON, multiGradICON) and to fine-tune/train new models.

##### File structure
- Top-level:
- `src/unigradicon/` – the core package containing submodules for commands, model definition, IO, loss, utilities.
- `training/` – dataset loaders (`dataset.py`, `dataset_multi.py`) and training entrypoints (`train.py`, `train_multi.py`).
- `demos/` – usage examples and figures.
- `tests/` – unit tests covering CLI argument parsing, ITK interface, requirement syncing.
- Project metadata (`pyproject.toml`, `requirements.txt`, `setup.cfg`) and CI workflows under `.github/workflows`.

##### README for additional insights
- It describes three main usage modes: CLI, Colab notebook, Slicer extension.
- Internally, images and transforms are handled via ITK; models are PyTorch networks; weights are auto-downloaded from GitHub.
- The registration pipeline consists of model inference plus optional instance-optimization (IO) loops with configurable similarity measures and loss function masking.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI["CLI Entrypoints"]:::ui
        Notebook["Colab Notebook"]:::ui
        Slicer["3D Slicer Extension"]:::ui
    end

    %% Core Application
    subgraph "Application Layer"
        Dispatcher["Command Dispatcher"]:::module
    end

    %% Core Library Modules
    subgraph "Domain Layer"
        IO["IO Module"]:::module
        ModelLoader["Model Loader"]:::module
        IOloop["Instance-Optimization Loop"]:::module
        Loss["Similarity & Loss Modules"]:::module
        Warper["Warping Engine"]:::module
    end

    %% Training Subsystem
    subgraph "Training Sub-System"
        DataLoader1["DataLoader (single)"]:::module
        DataLoader2["DataLoader (multi)"]:::module
        Train1["train.py"]:::module
        Train2["train_multi.py"]:::module
        Checkpoints[(Checkpoint Storage)]:::storage
    end

    %% External Dependencies
    subgraph "External Dependencies"
        PyTorch[PyTorch]:::external
        ITK[ITK]:::external
        NumSci["NumPy/SciPy"]:::external
        HDF5[HDF5]:::external
        Argparse["Argparse/Click"]:::external
    end

    %% Storage
    subgraph "Storage"
        FS[(Local File System)]:::storage
        Weights[(Model Weights Repository)]:::storage
    end

    %% Supporting Components
    Demos["Demo Files"]:::code
    Tests["Unit Tests"]:::code
    CI["CI/CD Workflows"]:::code
    Metadata["Project Metadata"]:::code

    %% Data Flow - Inference
    CLI -->|invoke| Dispatcher
    Notebook -->|imports or shells out| Dispatcher
    Slicer -->|imports core library| Dispatcher

    Dispatcher -->|load images| IO
    IO -->|fixed/moving images| ITK
    Dispatcher -->|load weights| ModelLoader
    ModelLoader -->|uses| PyTorch
    ModelLoader --> IOloop
    IOloop -->|computes loss| Loss
    Loss -->|uses| NumSci
    IOloop -->|optimizes| PyTorch
    IOloop --> Warper
    Warper -->|warp images| IO
    IO -->|write outputs| FS
    IO -->|save transforms| HDF5
    Weights -->|download weights| ModelLoader

    %% Training Flow
    Train1 -->|uses| DataLoader1
    Train2 -->|uses| DataLoader2
    Train1 -->|load modules| ModelLoader
    Train2 -->|load modules| ModelLoader
    Train1 -->|train loop| PyTorch
    Train2 -->|train loop| PyTorch
    Train1 --> Checkpoints
    Train2 --> Checkpoints

    %% Supporting
    Demos -->|examples| Dispatcher
    Tests -->|verify| Dispatcher
    Tests -->|verify| IO
    Tests -->|verify| ModelLoader
    CI -->|runs| Tests
    Metadata -->|defines deps| Argparse
    Metadata -->|defines deps| PyTorch
    Metadata -->|defines deps| ITK

    %% Click Events
    click CLI "https://github.com/uncbiag/unigradicon/blob/main/setup.cfg"
    click Dispatcher "https://github.com/uncbiag/unigradicon/tree/main/src/unigradicon/"
    click IO "https://github.com/uncbiag/unigradicon/blob/main/src/unigradicon/io.py"
    click ModelLoader "https://github.com/uncbiag/unigradicon/blob/main/src/unigradicon/model.py"
    click IOloop "https://github.com/uncbiag/unigradicon/blob/main/src/unigradicon/instance_optimization.py"
    click Loss "https://github.com/uncbiag/unigradicon/blob/main/src/unigradicon/loss.py"
    click Warper "https://github.com/uncbiag/unigradicon/blob/main/src/unigradicon/warp.py"
    click DataLoader1 "https://github.com/uncbiag/unigradicon/blob/main/training/dataset.py"
    click DataLoader2 "https://github.com/uncbiag/unigradicon/blob/main/training/dataset_multi.py"
    click Train1 "https://github.com/uncbiag/unigradicon/blob/main/training/train.py"
    click Train2 "https://github.com/uncbiag/unigradicon/blob/main/training/train_multi.py"
    click Demos "https://github.com/uncbiag/unigradicon/tree/main/demos/"
    click Tests "https://github.com/uncbiag/unigradicon/tree/main/tests/"
    click CI "https://github.com/uncbiag/unigradicon/tree/main/.github/workflows/"
    click Metadata "https://github.com/uncbiag/unigradicon/blob/main/pyproject.toml"
    click Metadata "https://github.com/uncbiag/unigradicon/blob/main/requirements.txt"
    click Metadata "https://github.com/uncbiag/unigradicon/blob/main/setup.cfg"

    %% Styles
    classDef ui fill:#f9f,stroke:#333,stroke-width:1px,shape:parallelogram
    classDef module fill:#bbf,stroke:#333,stroke-width:1px
    classDef external fill:#fea,stroke:#333,stroke-width:1px,shape:cloud
    classDef storage fill:#afa,stroke:#333,stroke-width:1px,shape:cylinder
    classDef code fill:#ddd,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
