# franciscrickinstitute/muvis-align architecture

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

- Interactive diagram: https://gitdiagram.com/franciscrickinstitute/muvis-align
- Repository: https://github.com/franciscrickinstitute/muvis-align

## Overview

##### Project type and purpose
- muvis-align is a command-line driven, scientific image-registration pipeline built on top of the multiview-stitcher library.
- It reads microscopy image stacks in various formats, applies pre-processing and one of several registration algorithms, computes metrics, and writes aligned output. It also supports HPC batch runs and a Napari plugin for in-GUI previews.

##### File structure to extract architectural elements
- Top-level executable layer:
- run.py – main CLI entry point
- run_hpc*.sh – HPC wrapper scripts
- Configuration/resources layer:
- .yml files under resources/ – parameter sets for different datasets
- Core pipeline code (src/):
- Pipeline.py – orchestrator class that ties everything together
- MVSRegistration(.py) – adapter to multiview-stitcher core functionality
- MVSRegistrationNapari.py – Napari-specific extension
- src/image/ – image-I/O and preprocessing abstractions
- src/registration_methods/ – plug-in registry of multiple algorithms (ANTs, CPD, CV-features, dummy, etc.)
- src/metrics.py – metric computations on registration results
- utilities (Timer, constants, util.py)
- Testing layer (test/): unit and integration tests
- Environment and dependency definitions (requirements.txt, environment.yml)

##### Sketch out the main components and their interactions
a. CLI & orchestration
- run.py parses command-line arguments and a selected YAML config → instantiates Pipeline → kicks off execution
- HPC scripts simply call run.py with pre-set config files in batch loops.
b. Pipeline core
- Pipeline coordinates:
- loading parameters (YAML → internal constants)
- selecting and instantiating an image source via a factory (e.g., TiffDaskSource, ZarrDaskSource)
- calling MVSRegistration, which in turn delegates to a chosen registration method from registration_methods/
- collecting registration metrics (RegistrationMetrics + metrics.py)
- writing output volumes to disk or downstream storage
c. Image I/O and helpers
- src/image classes handle reading from different backends (OME-TIFF, Zarr, Video, raw Tiff)
- helper modules (ome_helper, ome_ngff_helper etc.) handle format specifics
d. Registration methods plug-in
- RegistrationMethod abstract base class → concrete implementations (ANTs3Din2D, CPD, etc.)
- Each method receives pre-processed image data, returns estimated transforms
e. Metrics
- After transforms are computed/applied, metrics.py evaluates alignment quality
f. Napari integration
- MVSRegistrationNapari exposes a GUI hook for on-the-fly preview
g. Testing
- Tests drive individual modules or full pipeline in isolation, validating I/O, algorithms, metrics

##### Architectural patterns and design principles
- Pipeline pattern: distinct stages (I/O → preprocess → register → metrics → write)
- Strategy/Plugin pattern: registration methods are interchangeable classes inheriting from a common interface.
- Factory pattern for image source selection based on config.
- Separation of concerns: core orchestration (Pipeline) does not embed I/O or algorithm details, it delegates to dedicated modules.
- Config-driven behavior: all pipeline parameters come from external YAML files.

##### Putting it all together
- Below, show the Metrics and Output Writer.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    UserScheduler["User / Scheduler"]:::external
    CLI["CLI Runner<br/>(run.py)"]:::io
    HPC["HPC Wrapper Scripts"]:::io

    %% Configuration
    Config["Config Loader<br/>(resources/*.yml)"]:::io

    %% Core Pipeline
    subgraph "Pipeline Core" 
        direction TB
        Pipeline["Pipeline Orchestrator<br/>(Pipeline.py)"]:::core
        ImageFactory["Image Source Factory"]:::io
        Preproc["Preprocessing Modules"]:::core
        RegCore["Registration Core<br/>(MVSRegistration)"]:::core
        Metrics["Metrics Computation"]:::core
        Output["Output Writer"]:::core
    end

    %% Napari Adapter
    Napari["Napari GUI Adapter<br/>(MVSRegistrationNapari)"]:::io

    %% Registration Methods Plugin Cluster
    subgraph "Registration Methods" 
        direction TB
        RM_ABS["RegistrationMethod<br/>(abstract)"]:::plugin
        ANTs["ANTs3Din2D"]:::plugin
        CPD["CPD"]:::plugin
        CvFeat["CvFeatures"]:::plugin
        Dummy["Dummy"]:::plugin
        SkFeat["SkFeatures"]:::plugin
    end

    %% External Libraries
    subgraph "External Dependencies"
        direction TB
        MVSCore["multiview-stitcher"]:::external
        ANTsLib["ANTs"]:::external
        CPDLib["CPD"]:::external
        OpenCV["OpenCV"]:::external
        SciPy["SciPy"]:::external
        Dask["Dask"]:::external
    end

    %% Test Suite
    TestSuite["Test Suite<br/>(test/*)"]:::test

    %% Connections
    UserScheduler --> CLI
    UserScheduler --> HPC
    CLI -->|reads| Config
    CLI -->|invokes| Pipeline
    HPC --> CLI
    Pipeline -->|loads params| Config
    Pipeline --> ImageFactory
    ImageFactory -->|provides data| Preproc
    Preproc --> RegCore
    RegCore -->|delegates to| RM_ABS
    RM_ABS --> ANTs
    RM_ABS --> CPD
    RM_ABS --> CvFeat
    RM_ABS --> Dummy
    RM_ABS --> SkFeat
    RegCore --> Metrics
    Metrics --> Output
    RegCore --> Napari
    %% External usage
    RegCore --> MVSCore
    ANTs --> ANTsLib
    CPD --> CPDLib
    ImageFactory --> Dask
    CvFeat --> OpenCV
    CvFeat --> SciPy
    %% Testing hooks
    TestSuite -.-> CLI
    TestSuite -.-> Pipeline
    TestSuite -.-> ImageFactory
    TestSuite -.-> RegCore
    TestSuite -.-> Metrics
    TestSuite -.-> Napari

    %% Click Events
    click CLI "https://github.com/franciscrickinstitute/muvis-align/blob/main/run.py"
    click HPC "https://github.com/franciscrickinstitute/muvis-align/blob/main/run_hpc.sh"
    click HPC "https://github.com/franciscrickinstitute/muvis-align/blob/main/run_hpc_EM04768.sh"
    click HPC "https://github.com/franciscrickinstitute/muvis-align/blob/main/run_hpc_EM04788.sh"
    click Config "https://github.com/franciscrickinstitute/muvis-align/tree/main/resources/"
    click Pipeline "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/Pipeline.py"
    click RegCore "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/MVSRegistration.py"
    click Napari "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/MVSRegistrationNapari.py"
    click ImageFactory "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/image/DaskSource.py"
    click ImageFactory "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/image/TiffDaskSource.py"
    click ImageFactory "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/image/ZarrDaskSource.py"
    click ImageFactory "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/image/Video.py"
    click ImageFactory "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/image/source_helper.py"
    click Preproc "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/image/flatfield.py"
    click Preproc "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/image/color_conversion.py"
    click Preproc "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/image/ome_helper.py"
    click Preproc "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/image/ome_ngff_helper.py"
    click Preproc "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/image/ome_tiff_helper.py"
    click Preproc "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/image/ome_zarr_helper.py"
    click Preproc "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/image/ome_zarr_util.py"
    click Preproc "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/image/util.py"
    click RM_ABS "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/registration_methods/RegistrationMethod.py"
    click ANTs "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/registration_methods/RegistrationMethodANTs3Din2D.py"
    click CPD "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/registration_methods/RegistrationMethodCPD.py"
    click CvFeat "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/registration_methods/RegistrationMethodCvFeatures.py"
    click Dummy "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/registration_methods/RegistrationMethodDummy.py"
    click SkFeat "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/registration_methods/RegistrationMethodSkFeatures.py"
    click Metrics "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/registration_methods/RegistrationMetrics.py"
    click Metrics "https://github.com/franciscrickinstitute/muvis-align/blob/main/src/metrics.py"
    click TestSuite "https://github.com/franciscrickinstitute/muvis-align/tree/main/test/"

    %% Styles
    classDef core fill:#e0f7fa,stroke:#006064,color:#006064
    classDef io fill:#e8f5e9,stroke:#1b5e20,color:#1b5e20
    classDef plugin fill:#fff3e0,stroke:#e65100,color:#e65100
    classDef external fill:#eceff1,stroke:#37474f,color:#37474f
    classDef test stroke-dasharray: 5 5,stroke:#424242,fill:none;color:#424242
```
