How mathonco/valis works
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: registration.py Registration · serial_rigid.py Rigid pass · serial_non_rigid.py Non-rigid pass · slide_io.py Slide I/O
Components 18
Core package
Main VALIS registration pipeline and supporting modules.
- Registration · Top-level entry point that coordinates slide ingestion, rigid alignment, non-rigid refinement, and export.
valis/registration.py - Slide I/O · Boundary to external slide readers and OME-TIFF-friendly image access.
valis/slide_io.py - Preprocess · Converts slides into registration-ready representations, normalizes appearance, and builds tissue masks.
valis/preprocessing.py - Feature detect · Extracts image features used to estimate relative alignment between slides.
valis/feature_detectors.py - Feature match · Matches detected features across slides to support transform estimation.
valis/feature_matcher.py - Rigid pass · Main serial rigid registration flow that orders slides and aligns them through a reference chain.
valis/serial_rigid.py - Affine refine · Refines rigid transforms, including affine adjustment logic.
valis/affine_optimizer.py - Micro rigid · Higher-resolution rigid refinement stage for local detail alignment.
valis/micro_rigid_registrar.py - Non-rigid pass · Runs deformation-based registration after the rigid stage.
valis/serial_non_rigid.py - Deform regs · Implements non-rigid registration backends and groupwise/Elastix-style options.
valis/non_rigid_registrars.py - Warp export · Applies transforms to slides, ROIs, annotations, points, and associated images.
valis/warp_tools.py - Visualize · Visualization and debugging support for masks, matches, deformation, and final alignment.
valis/viz.py - SuperGlue · Optional learned feature matching backend with bundled SuperPoint/SuperGlue weights.
valis/superglue_models/matching.py - Slide tools · Helper routines for slide-level operations and metadata handling.
valis/slide_tools.py
Examples
End-to-end usage scenarios and generated artifacts.
- IHC example · End-to-end registration workflow for IHC slide sets.
examples/register_ihc.py - CyCIF merge · Example workflow for registering and merging CyCIF slides.
examples/register_and_merge_cycif.py - Warp demos · Examples for warping points, annotations, and associated images.
examples/warp_points.py - Expected out · Representative registration outputs such as processed images, overlaps, masks, deformation fields, and registered OME-TIFFs.
examples/expected_results
Connections 20
- 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.