core-registration 1.0.0

CORE - A Cell-Level Coarse-to-Fine Image Registration Engine for Multi-stain Image Alignment

CORE - A Cell-Level Coarse-to-Fine Image Registration Engine for Multi-stain Image Alignment

News

📢 November 2025 — CORE Released as Open-Source The first public release of CORE, a unified coarse-to-fine multi-stain image registration engine, is now available. This release includes prompt-guided mask generation, accelerated features based coarse alignment, nuclei-level refinement, and real-time deformation visualization.

📝 November 2025 — Updated Preprint Available on arXiv. The team has released an updated version of the CORE preprint, expanding on the architecture, benchmarks, and qualitative results. Check out the newest version here: arXiv:2403.05780.

🎥 New TIAViz Integration Demo - Added a full registration workflow demo showing real-time deformation fields and alignment quality inside TIAViz, enabling seamless analysis for whole-slide images.

🧪 Sample Notebooks Added - End-to-end Jupyter notebooks for coarse and fine alignment have been added, making it easier for users to experiment with CORE immediately.

Introduction

CORE is a fast and accurate coarse-to-fine image registration engine designed for aligning multi-stain whole-slide images. It combines prompt-based tissue masking, rapid coarse alignment, and nuclei-level fine registration to deliver precise cell-level correspondence across stains. With real-time deformation visualization and easy integration, CORE enables reliable multi-stain analysis for digital pathology workflows.

Features

• Prompt-based Tissue Mask Extraction.
• Fast coarse level multi-stain image registration.
• Fine-grained Nuclei-level precise alignment on re-stained sections and tissue alignment on consecutive sections.
• Real time deformation estimation and Registration visualisation.

CORE VISUALIZATION

Installation

Option 1: Install via pip (Recommended)

pip install core-registration

Or install from source with all optional dependencies:

pip install core-registration[all]

Option 2: Install from source

1. Clone the repo:

   git clone https://github.com/eshasadia/CORE.git
   cd CORE
   

2. Create and activate conda environment:

   conda env create -f environment.yml
   conda activate core
   

3. Install the package in development mode:

   pip install -e .
   

Option 3: Using pip requirements

pip install -r requirements.txt
pip install -e .

Set API Keys as Environment Variables

1. For our prompt-based tissue mask generation. You must set the VisionAgent API key as environment variables. Each operating system offers different ways to do this. Here is the code for setting the variables:

export VISION_AGENT_API_KEY="your-api-key"

2. For UNet based tissue mask extraction we have made the weights publicly available on hugging face. CORE

Configuration

Edit config.py to set your file paths and resolution parameters:

# Update these paths to match your data
SOURCE_WSI_PATH = "/path/to/your/source_wsi.tiff"
TARGET_WSI_PATH = "/path/to/your/target_wsi.tiff"

Usage

Example of both coarse and fine registration have been placed under the notebooks folder.

How to Cite

@misc{nasir2025corecelllevelcoarsetofine,
      title={CORE - A Cell-Level Coarse-to-Fine Image Registration Engine for Multi-stain Image Alignment}, 
      author={Esha Sadia Nasir and Behnaz Elhaminia and Mark Eastwood and Catherine King and Owen Cain and Lorraine Harper and Paul Moss and Dimitrios Chanouzas and David Snead and Nasir Rajpoot and Adam Shephard and Shan E Ahmed Raza},
      year={2025},
      eprint={2511.03826},
      archivePrefix={arXiv},
      primaryClass={q-bio.QM},
      url={https://arxiv.org/abs/2511.03826}, 
}

CORE Registration DEMO