chromadose

Modern multichannel radiochromic film dosimetry in Python.

chromadose implements all major multichannel film dosimetry methods in one library, with built-in uncertainty estimation, gamma analysis, and PDF reporting.

⚠️ Research use only — not a medical device. chromadose is open-source software for academic research and method development in radiochromic film dosimetry. It is not intended for diagnosis, treatment planning, or clinical decision-making, and has not been evaluated by the FDA, MHRA, or any Notified Body under EU MDR. Clinical use is the sole responsibility of a qualified medical physicist operating under their institution's QA programme. See DISCLAIMER.md for the full statement.

Methods

The Multigaussian implementation is the first open-source version of this method.

Quick Start

import chromadose as cd
from chromadose.core.image import load_tiff
from chromadose.methods import MickeSolver

# Load and calibrate
film = load_tiff("treatment_film.tif")
cal = cd.Calibration.from_arrays(
    doses=[0, 0.5, 1, 2, 4, 7, 9],
    red_pixels=red_means,
    green_pixels=green_means,
    blue_pixels=blue_means,
)

# Convert to dose
solver = MickeSolver()
dose_map = solver.solve(film, cal.result)
print(f"Max dose: {dose_map.dose.max():.2f} Gy")

Gamma Analysis

from chromadose.analysis import gamma_2d

result = gamma_2d(
    reference=tps_dose,
    evaluated=dose_map.dose,
    dose_criteria=3.0,        # 3%
    distance_criteria_mm=3.0, # 3mm
)
print(f"Pass rate: {result.pass_rate * 100:.1f}%")

PDF Reports

from chromadose.io import generate_report

generate_report(
    "qa_report.pdf",
    dose_map,
    gamma_result=result,
    title="IMRT QA Report",
    patient_id="PATIENT001",
)

CLI

chromadose calibrate --films cal*.tif --doses 0 0.5 1 2 4 7 9 -o cal.json
chromadose solve --film treatment.tif --cal cal.json --method micke -o dose.npy
chromadose gamma --measured dose.npy --reference tps.npy --criteria 3/3
chromadose report --measured dose.npy --reference tps.npy -o report.pdf

Installation

pip install chromadose

Optional extras:

pip install chromadose[dicom]    # DICOM RT Dose import
pip install chromadose[ann-gpu]  # PyTorch GPU acceleration for ANN
pip install chromadose[dev]      # Development tools

Features

• 4 dosimetry methods with a unified API
• Uncertainty estimation built into every method
• 2D gamma analysis (Low 1998) with global/local dose criteria
• Dose profiles — row, column, or arbitrary line extraction
• Film-to-TPS registration — automatic or manual rigid alignment
• DICOM RT Dose import with resampling to film grid
• PDF QA reports — dose maps, gamma, profiles in one document
• CLI — full pipeline from command line
• 6-channel Multigaussian — uses pre-irradiation scans for improved accuracy
• Fully vectorized — no per-pixel Python loops
• Pure Python — numpy + scipy only (torch optional for GPU)

Performance

Requirements

• Python >= 3.11
• numpy >= 1.24
• scipy >= 1.10
• tifffile >= 2023.1
• matplotlib >= 3.7

References

1. Micke A, Lewis DF, Yu X. "Multichannel film dosimetry with nonuniformity correction." Med. Phys. 2011;38(5):2523-34.
2. Mayer RR, et al. "An improved dose response function for multichannel film dosimetry." Med. Phys. 2012;39(12):7596-602.
3. Mendez I, Polsak A, Hudej R, Casar B. "The Multigaussian method: a new approach to mitigating spatial heterogeneities with multichannel radiochromic film dosimetry." Phys. Med. Biol. 2018;63(17):175013.
4. Chang L-Y, et al. "GANN: a generalized artificial neural network for multichannel radiochromic film dosimetry." Phys. Med. Biol. 2025.
5. Low DA, et al. "A technique for the quantitative evaluation of dose distributions." Med. Phys. 1998;25(5):656-61.

License

MIT