normalize-histopathology

Purpose: This package is built to correct faded, discolored Hematoxylin and Eosin (H&E) histopathology scans so archieved slides can be re-analyzed without the need to restain and rescan. The input for this package is a 3-channel (RGB) H&E scan in TIFF format. The core algorithm is Reinhard color transfer with a balanced channel-based correction to avoid artifacts. The output is a 3-channel (RGB) color- and contrast-corrected TIFF, saved as the original filename in the output directory.

Left: original scan. Right: scan corrected by normalize-histopathology.

Installation

pip install normalize-histopathology
# or
uv pip install normalize-histopathology

Usage

1. Install normalize-histopathology into an activated virtual environment

uv venv .venv
source .venv/bin/activate
uv pip install normalize-histopathology

2. Run H&E normalization

normalize-histopathology --input-dir /path/to/original_scans --output-dir /path/to/corrected_scans

Each scan is color-normalized against the default reference slide's precomputed statistics — no reference image needs to be supplied. You can check the default reference (HE_ref.tif). To normalize against your own reference slide, provide --ref-path as below:

normalize-histopathology --input-dir /path/to/original_scans --output-dir /path/to/corrected_scans \
    --ref-path /path/to/your_reference.tif

CLI arguments:

• --ref-path to normalize against your own reference TIFF instead of the default
• --pattern to change which filenames are matched (repeatable; default: *.tif, *.tiff, *.TIF, *.TIFF)
• --hmin-scale R G B to override the per-channel auto-contrast lower-bound scale (default: 0.75 0.5 0.333)
• --debug to print per-image shape/range diagnostics

Troubleshooting tips:

• Input scans should be 3-channel RGB TIFFs; channel-first (3, H, W) TIFFs are handled automatically.
• Very washed-out scans with little tissue contrast left to recover may need a customized --ref-path matched more closely to your stain batch or a caustomized hmin scale.
• Make sure you visually check a few corrected outputs before batch-processing an entire cohort.

Additional details on the method

Correction runs in two steps:

Acknowledgement

This tool builds on the Reinhard et al. color transfer method ("Color Transfer between Images", IEEE CG&A, 2001). Many thanks to the scientists and engineers behind that foundational work.

Cite normalize-histopathology

If normalize-histopathology has been useful to your research, please cite our package:

Cao, T. (2026). normalize-histopathology (Version 0.1.0) [Computer software]. Python Package Index. https://pypi.org/project/normalize-histopathology/

Feedback and Questions

We acknowledge that there is no perfect model, but there are some useful ones. We hope to keep improving our tool and support other scientists in their imaging analysis. If you have any feedback, questions, and comments, please send me an email.

License

MIT License

Copyright (c) 2026 Thao Cao