CoReg: A Python Package for Histology Image Coregistration

Author: Junyang Deng

CoReg is a lightweight Python package for performing coregistration of whole-slide histology images. It is designed to align serial sections, such as a Hematoxylin and Eosin (H&E) stained slide with a corresponding Immunohistochemistry (IHC) slide.

The pipeline operates on down-sampled thumbnails for efficiency, using a contour-based method to find the optimal affine transformation that maps the moving image onto the template image.

Key Features

• Automatic tissue detection and masking from whole-slide thumbnails.
• Robust contour extraction and matching for slides containing one or more tissue sections.
• Calculates the 2x3 affine transformation matrix (M) using an iterative optimization process.
• Provides Intersection over Union (IOU) as a metric for registration quality.
• Includes helper functions for visualizing tissue overlays and contour alignments.
• Built on OpenSlide, OpenCV, and scikit-image.

Installation

Step 1: Install the Python Package

You can install the coreg package and its Python dependencies directly from GitHub using pip:

pip install git+https://github.com/DamarisDeng/coregistration.git

Step 2: Install the OpenSlide System Dependency

To read whole-slide images, coreg depends on the OpenSlide C library. This is a non-Python dependency that must be installed separately on your system. The package will install successfully without it, but it will raise an error when you try to import it.

Using Conda (Recommended): If you are using an Anaconda or Miniconda environment, this is the easiest way to install the dependency:

conda install -c conda-forge openslide

For developers, you can clone the repository and install it in editable mode:

git clone https://github.com/DamarisDeng/coregistration.git
cd coregistration
# Remember to install the OpenSlide system dependency as described above
pip install -e .

Quick Start

Here is a basic example of how to register an IHC slide to an H&E slide.

# Import the primary classes and functions from the package
import coreg
# 1. Define the paths to your whole-slide images
he_path = 'path/to/your/template_slide.svs'
ihc_path = 'path/to/your/moving_slide.svs'
study_id = 'patient_001'

# 2. Create an ImagePair object to manage the data
# The 'moving_name' is used to identify the slide type in results
pair = coreg.ImagePair(study_id=study_id, template_path=he_path, moving_path=ihc_path)
pair.moving_name = 'CD8_IHC'

print(f"Processing registration for {pair.study_id}...")

# 3. Run the coregistration pipeline
results = coreg.process_registration_pair(pair)

# 4. Access the registration results
# The results are stored in a pandas DataFrame within the ImagePair object.
if pair.coreg_df is not None and not pair.coreg_df.empty:
    print("Registration successful!")
    
    # Print the DataFrame containing results for all matched regions
    print(pair.coreg_df[['region', 'iou', 'box']].round(3))
    
    # Get the affine matrix 'M' for the first registered region
    # This matrix is for the thumbnail resolution (default 4x)
    affine_matrix_4x = pair.get_M(region=0)
    
    print("\nAffine Matrix (M) for region 0 at 4x:")
    print(affine_matrix_4x)

Package API Overview

• coreg.core: Contains the main user-facing classes (ImagePair, ImagePairList) and the primary pipeline function (process_registration_pair).
• coreg.utils: Includes helper functions for image processing (tissue_mask), transformations (align, convert_affine_matrix_resolution), and metrics (calculate_IOU_all).
• coreg.viz: Provides visualization tools for debugging and final output, such as visualize_tissue_overlay and plot_contours_transformed.

Dependencies

• numpy
• pandas
• opencv-python
• scikit-image
• matplotlib
• openslide-python

License

This project is licensed under the MIT License. See the LICENSE file for details.