CDF Normalizer — Image Harmonization using robust restricted CDF matching

Git

What it is

CDF Normalizer is an open-source library (MIT) that implements robust restricted CDF matching for image harmonization. It was developed primarily for MRI, but the method is generic and suitable for other imaging modalities. The algorithm fits input CDFs to template CDFs using curve-fitting with smooth dual-scaling and optional tail-shrinking to preserve local variability while aligning global intensity structure.

Repository: https://gitlab.fi.muni.cz/cbia/libs-public/cdf-normalizer

This approach does not ruin local variability and individual important features. The transformation of image intensities is non-linear but still “smooth and elastic”, as compared to other known histogram matching algorithms. Nonlinear transformation allows for a very good match to the template. At the same time, elasticity constraints help to preserve local variability among individual inputs, which may encode important features for subsequent machine-learning processing. The pre-defined template CDF offers a better and more intuitive control for the input data transformation compared to other methods, especially ML-based ones. Even though we developed our method for MRI images, the method is generic enough to apply to other types of imaging data.

Highlights

Robust CDF-based harmonization that preserves diagnostically-relevant local deviations.
Smooth dual-scaling with sigmoidal blending avoids artifacts and distortion.
Tail-shrinking to constrain intensity ranges (e.g., map to 12-bit) without harsh clipping.
Lightweight, analytical method — no neural networks required.
Well-suited for federated learning and multi-site preprocessing pipelines.

Technical summary

Core operations:
- compute foreground CDF → fit to template CDF using non-linear dual-scaling transformation → optionally apply tail-shrinking LUTs.
Template preparation:
- anyhow you like :-)
- e.g., use a single representative image, or average CDF from a training set.
Recommended default control points (experiments):
- π_B=(0.1, 500), π_M=(0.5, 1650), π_T=(0.99, 3300) — for mapping of intensities into 12-bit range (1..4095).
Outputs:
- harmonized images (same dtype/range as target), ready for downstream ML tasks.

CDF normalizer overview

Quick start (clone & install)

git clone https://gitlab.fi.muni.cz/cbia/libs-public/cdf-normalizer.git
cd cdf-normalizer
pip install -e .

See the repository README for exact API, CLI tools and examples.

Example (illustrative)

### Illustrative example — check repo for exact API and names
from cdf_normalizer import CDFNormalizer, TemplateCDF
img = load_my_nifti("patient_T2.nii.gz")

template = TemplateCDF.from_training_set(["ref1.nii.gz","ref2.nii.gz"], control_points=((0.1,500),(0.5,1650),(0.99,3300)))
norm = CDFNormalizer(template=template, tail_shrinking=True)

harm_img = norm.harmonize(img)
save_my_nifti(harm_img, "patient_T2_harmonized.nii.gz")

FAQ

Q1 — Is it open-source?
Yes — MIT license.

Q2 — Do I need GPU?
No — algorithmic, CPU-friendly.

Q3 — Will it remove pathology?
No — designed to preserve local deviations, but validate on pathological cases.

Q4 — Is it suitable for diffusion MRI?
Yes — method is generic for different channels/modalities.

Citation & contact

If you use this tool, please cite the following paper:

R. Stoklasa, “Image Harmonization Using Robust Restricted CDF Matching,” 2025 IEEE 22nd International Symposium on Biomedical Imaging (ISBI), Houston, TX, USA, 2025, pp. 1-5, doi: 10.1109/ISBI60581.2025.10981263.

Repository: https://gitlab.fi.muni.cz/cbia/libs-public/cdf-normalizer

Acknowledgement

This project was partially funded by the Ministry of Health of the Czech Republic (Grant No. NU21-08-00359) and the Ministry of Education, Youth and Sports of the Czech Republic (Project No. LM2023050).

Credits

Roman Stoklasa, Ph.D. (author and developer)