# mathonco/valis architecture

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

- Interactive diagram: https://gitdiagram.com/mathonco/valis
- Repository: https://github.com/mathonco/valis

## Overview

1. **What this repository is**
   VALIS is a Python package for registering whole-slide pathology image series. Its core job is to take a stack of very large slide images, estimate transformations between them, and then warp or merge the slides into aligned outputs, typically saved as OME-TIFF.

2. **Top-level architecture**
   The codebase is centered around the `valis/` package, with supporting examples, documentation, and tests. The package is organized as a pipeline: slide ingestion, preprocessing, feature detection/matching, rigid registration, non-rigid registration, warping/export, and visualization.

3. **Slide ingestion and image access**
   `valis/slide_io.py` and related slide tools are the boundary to external image formats and WSI readers. The README says the project relies on Bio-Formats, OpenSlide, libvips, and scikit-image to read over 300 formats and to access pyramid levels. This layer converts slide data into NumPy arrays or pyvips images and supports ROI extraction and metadata-preserving OME-TIFF conversion.

4. **Preprocessing and masking**
   `valis/preprocessing.py` prepares slides for registration by converting them to single-channel representations, normalizing appearance, and generating tissue masks. This is important because the pipeline is designed for large, heterogeneous pathology slides where registration should focus on tissue rather than background.

5. **Feature detection and matching**
   `valis/feature_detectors.py` and `valis/feature_matcher.py` form the correspondence-estimation layer. They detect image features and match them across slides to estimate relative alignment. The repo also contains `valis/superglue_models/`, which indicates an optional learned matching backend using SuperPoint/SuperGlue weights bundled with the package.

6. **Rigid registration pipeline**
   `valis/serial_rigid.py` implements the main rigid alignment flow described in the README: images are ordered, a reference slide is chosen, and each slide is aligned serially toward that reference. The architecture is sequence-based rather than all-to-one independent registration, which lets each step use the already-registered neighbor as the local target.

7. **Affine refinement and micro-rigid alignment**
   `valis/affine_optimizer.py` provides optimization logic for refining transforms, likely including mutual-information-based adjustments mentioned in the README. `valis/micro_rigid_registrar.py` adds a higher-resolution refinement stage for rigid alignment when finer detail is needed.

8. **Non-rigid registration**
   `valis/non_rigid_registrars.py` and `valis/serial_non_rigid.py` handle deformation-based alignment after rigid registration. The pipeline uses tissue masks and bounding boxes from the rigid stage to crop higher-resolution regions and then perform non-rigid alignment. The README also notes an optional groupwise mode that depends on SimpleElastix.

9. **Warping and downstream coordinate transfer**
   `valis/warp_tools.py` is the transformation application layer. It warps full-resolution slides, associated images, and point/annotation data such as cell centroids or polygon vertices. This is the main downstream boundary where registration results become usable outputs for analysis.

10. **Visualization and inspection**
   `valis/viz.py` provides visual inspection and debugging support for registration results. In a repo like this, visualization is part of the workflow boundary: it helps users validate masks, feature matches, deformation fields, and final alignments.

11. **Examples as integration scenarios**
   The `examples/` directory shows the intended end-to-end flows: register IHC, register and merge CyCIF, warp annotation images, warp points, and handle high-resolution or associated images. These scripts are important because they reveal the package’s external-facing architecture better than the library modules alone: users typically start from a slide directory, run the registration pipeline, and then export warped slides or transformed annotations.

12. **Outputs and artifact structure**
   The example outputs in `examples/expected_results/` show the main artifact categories produced by the pipeline: processed images, masks, overlaps, rigid registration results, non-rigid registration results, deformation fields, summaries, and registered OME-TIFF slides. That directory structure is a good guide for an architecture diagram because it reflects the pipeline’s internal stages and persisted outputs.

13. **Tooling, packaging, and delivery**
   The repo is packaged as a Python distribution (`pyproject.toml`), validated by `tests/`, documented via Sphinx in `docs/`, and automated through GitHub Actions CI plus a PyPI publish workflow. A Dockerfile and `docker/` utilities indicate containerized usage and weight downloading for model assets. The presence of `uv.lock` suggests reproducible dependency locking.

14. **Main boundary to external systems**
   The most important external dependencies are image-format libraries and optional registration backends: Bio-Formats/OpenSlide/libvips for I/O, scikit-image for image processing, SuperGlue/SuperPoint weights for learned matching, and SimpleElastix for groupwise non-rigid registration. The architecture is therefore a hybrid of classical image registration, optional learned feature matching, and format-conversion/export tooling centered on pathology WSI workflows.

Main entry points: [`valis/registration.py`](https://github.com/mathonco/valis/blob/main/valis/registration.py) (Registration), [`valis/serial_rigid.py`](https://github.com/mathonco/valis/blob/main/valis/serial_rigid.py) (Rigid pass), [`valis/serial_non_rigid.py`](https://github.com/mathonco/valis/blob/main/valis/serial_non_rigid.py) (Non-rigid pass), [`valis/slide_io.py`](https://github.com/mathonco/valis/blob/main/valis/slide_io.py) (Slide I/O)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core package"]
  node_registration["Registration<br/>orchestrator<br/>[registration.py]"]
  node_slide_io["Slide I/O<br/>wsi I/O<br/>[slide_io.py]"]
  node_preprocessing["Preprocess<br/>masking<br/>[preprocessing.py]"]
  node_feature_detectors["Feature detect<br/>keypoints"]
  node_feature_matcher["Feature match<br/>correspondence<br/>[feature_matcher.py]"]
  node_serial_rigid["Rigid pass<br/>serial rigid<br/>[serial_rigid.py]"]
  node_affine_optimizer["Affine refine<br/>optimization"]
  node_micro_rigid_registrar["Micro rigid<br/>fine rigid"]
  node_serial_non_rigid["Non-rigid pass<br/>serial non-rigid"]
  node_non_rigid_registrars["Deform regs<br/>deformation models"]
  node_warp_tools["Warp export<br/>transforms<br/>[warp_tools.py]"]
  node_viz["Visualize<br/>inspection<br/>[viz.py]"]
  node_superglue_models["SuperGlue<br/>learned matching<br/>[matching.py]"]
  node_slide_tools["Slide tools<br/>utilities<br/>[slide_tools.py]"]
end

subgraph group_examples["Examples"]
  node_example_register_ihc["IHC example<br/>workflow<br/>[register_ihc.py]"]
  node_example_merge_cycif["CyCIF merge<br/>workflow"]
  node_example_warping["Warp demos<br/>workflow<br/>[warp_points.py]"]
  node_expected_results["Expected out<br/>artifacts"]
end

subgraph group_delivery["Docs & tooling"]
end

node_registration -->|"loads slides"| node_slide_io
node_registration -->|"prepares tissue"| node_preprocessing
node_registration -->|"rigid stage"| node_serial_rigid
node_registration -->|"deform stage"| node_serial_non_rigid
node_registration -->|"exports outputs"| node_warp_tools
node_registration -->|"inspects results"| node_viz
node_preprocessing -->|"reads pixels"| node_slide_io
node_serial_rigid -->|"detects features"| node_feature_detectors
node_serial_rigid -->|"matches features"| node_feature_matcher
node_serial_rigid -->|"refines transform"| node_affine_optimizer
node_serial_rigid -->|"fine rigid"| node_micro_rigid_registrar
node_serial_rigid -->|"checks alignment"| node_viz
node_serial_non_rigid -->|"deforms tissue"| node_non_rigid_registrars
node_serial_non_rigid -->|"warps data"| node_warp_tools
node_feature_matcher -->|"optional backend"| node_superglue_models
node_example_register_ihc -->|"uses pipeline"| node_registration
node_example_merge_cycif -->|"uses pipeline"| node_registration
node_example_warping -->|"transforms annotations"| node_warp_tools
node_expected_results -.->|"shows outputs"| node_registration
node_slide_tools -->|"assists I/O"| node_slide_io

click node_registration "https://github.com/mathonco/valis/blob/main/valis/registration.py"
click node_slide_io "https://github.com/mathonco/valis/blob/main/valis/slide_io.py"
click node_preprocessing "https://github.com/mathonco/valis/blob/main/valis/preprocessing.py"
click node_feature_detectors "https://github.com/mathonco/valis/blob/main/valis/feature_detectors.py"
click node_feature_matcher "https://github.com/mathonco/valis/blob/main/valis/feature_matcher.py"
click node_serial_rigid "https://github.com/mathonco/valis/blob/main/valis/serial_rigid.py"
click node_affine_optimizer "https://github.com/mathonco/valis/blob/main/valis/affine_optimizer.py"
click node_micro_rigid_registrar "https://github.com/mathonco/valis/blob/main/valis/micro_rigid_registrar.py"
click node_serial_non_rigid "https://github.com/mathonco/valis/blob/main/valis/serial_non_rigid.py"
click node_non_rigid_registrars "https://github.com/mathonco/valis/blob/main/valis/non_rigid_registrars.py"
click node_warp_tools "https://github.com/mathonco/valis/blob/main/valis/warp_tools.py"
click node_viz "https://github.com/mathonco/valis/blob/main/valis/viz.py"
click node_superglue_models "https://github.com/mathonco/valis/blob/main/valis/superglue_models/matching.py"
click node_slide_tools "https://github.com/mathonco/valis/blob/main/valis/slide_tools.py"
click node_example_register_ihc "https://github.com/mathonco/valis/blob/main/examples/register_ihc.py"
click node_example_merge_cycif "https://github.com/mathonco/valis/blob/main/examples/register_and_merge_cycif.py"
click node_example_warping "https://github.com/mathonco/valis/blob/main/examples/warp_points.py"
click node_expected_results "https://github.com/mathonco/valis/tree/main/examples/expected_results"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_registration,node_slide_io,node_preprocessing,node_feature_detectors,node_feature_matcher,node_serial_rigid,node_affine_optimizer,node_micro_rigid_registrar,node_serial_non_rigid,node_non_rigid_registrars,node_warp_tools,node_viz,node_superglue_models,node_slide_tools toneBlue
class node_example_register_ihc,node_example_merge_cycif,node_example_warping,node_expected_results toneAmber
```

## Components

### Core package

Main VALIS registration pipeline and supporting modules.

- [Registration](https://github.com/mathonco/valis/blob/main/valis/registration.py): orchestrator · Top-level entry point that coordinates slide ingestion, rigid alignment, non-rigid refinement, and export. · `valis/registration.py`
- [Slide I/O](https://github.com/mathonco/valis/blob/main/valis/slide_io.py): wsi I/O · Boundary to external slide readers and OME-TIFF-friendly image access. · `valis/slide_io.py`
- [Preprocess](https://github.com/mathonco/valis/blob/main/valis/preprocessing.py): masking · Converts slides into registration-ready representations, normalizes appearance, and builds tissue masks. · `valis/preprocessing.py`
- [Feature detect](https://github.com/mathonco/valis/blob/main/valis/feature_detectors.py): keypoints · Extracts image features used to estimate relative alignment between slides. · `valis/feature_detectors.py`
- [Feature match](https://github.com/mathonco/valis/blob/main/valis/feature_matcher.py): correspondence · Matches detected features across slides to support transform estimation. · `valis/feature_matcher.py`
- [Rigid pass](https://github.com/mathonco/valis/blob/main/valis/serial_rigid.py): serial rigid · Main serial rigid registration flow that orders slides and aligns them through a reference chain. · `valis/serial_rigid.py`
- [Affine refine](https://github.com/mathonco/valis/blob/main/valis/affine_optimizer.py): optimization · Refines rigid transforms, including affine adjustment logic. · `valis/affine_optimizer.py`
- [Micro rigid](https://github.com/mathonco/valis/blob/main/valis/micro_rigid_registrar.py): fine rigid · Higher-resolution rigid refinement stage for local detail alignment. · `valis/micro_rigid_registrar.py`
- [Non-rigid pass](https://github.com/mathonco/valis/blob/main/valis/serial_non_rigid.py): serial non-rigid · Runs deformation-based registration after the rigid stage. · `valis/serial_non_rigid.py`
- [Deform regs](https://github.com/mathonco/valis/blob/main/valis/non_rigid_registrars.py): deformation models · Implements non-rigid registration backends and groupwise/Elastix-style options. · `valis/non_rigid_registrars.py`
- [Warp export](https://github.com/mathonco/valis/blob/main/valis/warp_tools.py): transforms · Applies transforms to slides, ROIs, annotations, points, and associated images. · `valis/warp_tools.py`
- [Visualize](https://github.com/mathonco/valis/blob/main/valis/viz.py): inspection · Visualization and debugging support for masks, matches, deformation, and final alignment. · `valis/viz.py`
- [SuperGlue](https://github.com/mathonco/valis/blob/main/valis/superglue_models/matching.py): learned matching · Optional learned feature matching backend with bundled SuperPoint/SuperGlue weights. · `valis/superglue_models/matching.py`
- [Slide tools](https://github.com/mathonco/valis/blob/main/valis/slide_tools.py): utilities · Helper routines for slide-level operations and metadata handling. · `valis/slide_tools.py`

### Examples

End-to-end usage scenarios and generated artifacts.

- [IHC example](https://github.com/mathonco/valis/blob/main/examples/register_ihc.py): workflow · End-to-end registration workflow for IHC slide sets. · `examples/register_ihc.py`
- [CyCIF merge](https://github.com/mathonco/valis/blob/main/examples/register_and_merge_cycif.py): workflow · Example workflow for registering and merging CyCIF slides. · `examples/register_and_merge_cycif.py`
- [Warp demos](https://github.com/mathonco/valis/blob/main/examples/warp_points.py): workflow · Examples for warping points, annotations, and associated images. · `examples/warp_points.py`
- [Expected out](https://github.com/mathonco/valis/tree/main/examples/expected_results): artifacts · Representative registration outputs such as processed images, overlaps, masks, deformation fields, and registered OME-TIFFs. · `examples/expected_results`

## Connections

- Registration → Slide I/O: loads slides · Acquires slide imagery and metadata before registration.
- Registration → Preprocess: prepares tissue · Creates registration-ready channels and masks.
- Registration → Rigid pass: rigid stage · Runs the main rigid alignment pipeline.
- Registration → Non-rigid pass: deform stage · Runs the deformation-based refinement stage.
- Registration → Warp export: exports outputs · Uses estimated transforms to produce registered slides and transferred annotations.
- Registration → Visualize: inspects results · Supports visual validation of masks, matches, and alignments.
- Preprocess → Slide I/O: reads pixels · Uses slide access to extract regions and pyramid levels.
- Rigid pass → Feature detect: detects features · Finds correspondences for transform estimation.
- Rigid pass → Feature match: matches features · Pairs features across slides for rigid alignment.
- Rigid pass → Affine refine: refines transform · Optimizes the rigid/affine solution.
- Rigid pass → Micro rigid: fine rigid · Optionally performs higher-resolution rigid refinement.
- Rigid pass → Visualize: checks alignment · Provides visual feedback for rigid registration.
- Non-rigid pass → Deform regs: deforms tissue · Selects and runs the non-rigid backend.
- Non-rigid pass → Warp export: warps data · Applies deformation fields to slide-level and point-level outputs.
- Feature match → SuperGlue: optional backend · Can delegate matching to learned SuperPoint/SuperGlue models.
- IHC example → Registration: uses pipeline · Demonstrates the standard IHC registration flow.
- CyCIF merge → Registration: uses pipeline · Demonstrates registering and merging CyCIF series.
- Warp demos → Warp export: transforms annotations · Shows point, ROI, and associated-image warping.
- Expected out → Registration: shows outputs · Documents the major persisted artifacts created by the pipeline.
- Slide tools → Slide I/O: assists I/O · Provides helper functionality around slide handling.
