How franciscrickinstitute/muvis-align works
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.