Metadata-Version: 2.5
Name: normalize-histopathology
Version: 0.1.0
Summary: Correct faded, discolored H&E histopathology scans (color + contrast) without physically restaining the slide.
Project-URL: Homepage, https://github.com/ThaoCao/kidneystructureanalysis
Author-email: Thao Cao <thaocao97@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: H&E,color normalization,histopathology,pathology,stain normalization,whole slide imaging
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Requires-Dist: numpy
Requires-Dist: opencv-python-headless
Requires-Dist: tifffile
Description-Content-Type: text/markdown

# 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](https://ieeexplore.ieee.org/document/946629) 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.

![Before and after H&E color normalization](https://raw.githubusercontent.com/ThaoCao/kidneystructureanalysis/main/normalize_histopathology/assets/before_after.jpg)

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

## Installation

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

## Usage

### 1. Install `normalize-histopathology` into an activated virtual environment

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

### 2. Run H&E normalization

```bash
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:

```bash
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:

| Step | What it does |
|------|--------------|
| 1. Reinhard LAB normalization | Matches the scan's LAB-space color mean/std to a reference slide, correcting for stain fading and batch-to-batch color drift. |
| 2. Per-channel auto-contrast | Independently rescales each R, G, B channel's histogram, ignoring white background peaks (e.g. slide background). |


## 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](mailto:thaocao97@gmail.com).

## License
MIT License

Copyright (c) 2026 Thao Cao
