VALIS: Automated Whole Slide Image Registration

VALIS (Virtual Alignment of pathoLogy Image Series) is a fully automated pipeline designed to register whole slide images (WSI) using rigid and/or non-rigid transformations. It is capable of working with over 300 image formats by leveraging Bio-Formats, OpenSlide, libvips, and scikit-image.

Key capabilities include:

• Automated Registration: A multi-step pipeline including image normalization, feature detection, optimal ordering, rigid registration, and non-rigid registration.
• High-Resolution Refinement: Support for micro-registration using higher resolution versions of images to align fine features.
• Output Formats: Registered images can be saved as ome.tiff slides, which are widely supported in software like QuPath and HALO.
• Data Transformation: Transformations can be used to warp full-resolution slides, merge non-RGB slides into multiplexed images, or warp point data (e.g., cell centroids, polygon vertices).
• WSI Utilities: Tools for reading slides at multiple resolutions, converting them to numpy arrays or pyvips.Image objects, slicing regions of interest, and converting slides to ome.tiff while preserving metadata.

VALIS is a fully automated pipeline designed to register whole slide images (WSI) using rigid and/or non-rigid transformations. It is particularly useful for aligning pathology image series to a common reference, allowing for the creation of highly multiplexed images or the warping of point data (like cell centroids) across different slides.

Key capabilities include:

• Automated Registration: Handles image conversion, normalization, feature detection, and matching.
• Multi-resolution Support: Performs registration across different pyramid levels, including optional 'micro-registration' for high-resolution micro-features.
• Flexible Transformations: Supports rigid registration (serial alignment) and non-rigid registration (either sequential or groupwise via SimpleElastix).
• WSI Handling: Uses Bio-Formats, OpenSlide, and libvips to support over 300 image formats.
• Output Formations: Registered images can be saved as ome.tiff slides, which are widely supported by software like QuPath and HALO.

The VALIS registration pipeline follows a specific automated sequence to align a stack of images:

1. Conversion: Images/slides are converted to numpy arrays (typically using lower resolution pyramid levels to manage memory).
2. Preprocessing: Images are converted to single-channel, normalized, and masked to focus on tissue.
3. Feature Matching: Image features are detected and matched between all pairs.
4. Ordering: If the input order is unknown, images are optimally ordered based on feature similarity.
5. Reference Selection: Images are aligned towards a reference image. If no reference is specified, the image at the center of the stack is used.
6. Rigid Registration: Performed serially. Each image is aligned towards the reference (e.g., if the 5th image is the reference, image 4 aligns to 5, then 3 aligns to the registered 4, etc.). This can be optionally updated using MicroRigidRegistrar with higher resolution images.
7. Non-Rigid Registration: Uses a mask derived from rigid registration to extract high-resolution tissue. It supports two modes:
   • Sequential alignment towards the reference.
   • Groupwise registration (requires SimpleElastix to be installed).
8. Micro-registration (Optional): A second non-rigid pass using even higher resolution images to align micro-features.
9. Error Estimation: Calculated via the distance between registered matched features in full-resolution images.

The SlideReader class and its subclasses provide a unified interface for reading slide data into different formats. All readers support the following core methods:

• slide2vips: Converts the slide to a VIPS image object.
• slide2image: Converts the slide to a standard image object.
• create_metadata: Generates a MetaData object for the slide.

Available reader implementations:

• BioFormatsSlideReader: Uses BioFormats (requires JVM management via init_jvm()).
• VipsSlideReader: Uses libvips for efficient image handling.
• FlattenedPyramidReader: A specialized VipsSlideReader for flattened pyramid structures.
• ImageReader: A general-purpose reader inheriting from SlideReader.
• get_slide_reader: A utility function to retrieve an appropriate reader instance.

from valis.slide_io import get_slide_reader

reader = get_slide_reader("path/to/slide")
vips_img = reader.slide2vips()
image = reader.slide2image()
metadata = reader.create_metadata()

For improved quality, you can use higher resolution images for both rigid and non-rigid steps.

1. High-Res Rigid Registration: Initialize Valis with micro_rigid_registrar_cls=MicroRigidRegistrar. This updates the rigid registration by finding matches in higher-resolution versions.
2. High-Res Non-Rigid Registration: Use register_micro with a calculated max_non_rigid_registration_dim_px based on your desired resolution fraction.

import numpy as np
from valis import registration
from valis.micro_rigid_registrar import MicroRigidRegistrar

# 1. High resolution rigid registration
registrar = registration.Valis(
    slide_src_dir=slide_src_dir, 
    results_dst_dir=results_dst_dir, 
    micro_rigid_registrar_cls=MicroRigidRegistrar
)
rigid_registrar, non_rigid_registrar, error_df = registrar.register()

# 2. Calculate size for 25% full resolution non-rigid registration
img_dims = np.array([s.slide_dimensions_wh[0] for s in registrar.slide_dict.values()])
min_max_size = np.min([np.max(d) for d in img_dims])
# ... (logic to find max_img_w/h) ...
micro_reg_size = np.floor(min_max_size * 0.25).astype(int)

# 3. High resolution non-rigid registration
registrar.register_micro(max_non_rigid_registration_dim_px=micro_reg_size)

After registration, VALIS can merge multiple slides into a single composite image. This is intended for non-RGB images like multi-channel immunofluorescence (e.g., CyCIF rounds).

Key Considerations:

• Channel Naming: You can provide a dictionary channel_name_dict where key=filename and value=list of channel names. If not provided, names default to "channel (filename)" (e.g., "DAPI (round1)").
• Duplicate Handling: By default, if a channel (like DAPI) exists in multiple images, only the first instance is merged. To include all instances, set drop_duplicates=False in warp_and_merge_slides.

Workflow:

1. Initialize registration.Valis(slide_src_dir, results_dst_dir).
2. Run registrar.register() to perform registration.
3. Define a mapping for channel names.
4. Call registrar.warp_and_merge_slides() to generate the merged OME-TIFF.

import torch
from valis import registration
slide_src_dir = "/path/to/slides"
results_dst_dir = "./slide_merging_example"
merged_slide_dst_f = "./slide_merging_example/merged_slides.ome.tiff"

registrar = registration.Valis(slide_src_dir, results_dst_dir)
rigid_registrar, non_rigid_registrar, error_df = registrar.register()

# Example channel name mapping function
def cnames_from_filename(src_f):
    # Note: Implementation depends on your specific filenames
    return ["DAPI", "CD20", "FOXP3"]

channel_name_dict = {f: cnames_from_filename(f) for f in registrar.original_img_list}
merged_img, channel_names, ome_xml = \
    registrar.warp_and_merge_slides(merged_slide_dst_f,
                                    channel_name_dict=channel_name_dict,
                                    drop_duplicates=True)

registration.kill_jvm()