Metadata-Version: 2.4
Name: chromadose
Version: 0.9.1
Summary: Modern multichannel radiochromic film dosimetry
Author-email: Christopher Finch <cptfinch@gmail.com>
Maintainer-email: Christopher Finch <cptfinch@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/cptfinch/chromadose
Project-URL: Documentation, https://cptfinch.github.io/chromadose/
Project-URL: Repository, https://github.com/cptfinch/chromadose
Project-URL: Issues, https://github.com/cptfinch/chromadose/issues
Project-URL: Changelog, https://github.com/cptfinch/chromadose/blob/main/CHANGELOG.md
Keywords: radiochromic,dosimetry,film,multichannel,medical physics,radiotherapy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: tifffile>=2023.1
Requires-Dist: matplotlib>=3.7
Provides-Extra: dicom
Requires-Dist: pydicom>=2.4; extra == "dicom"
Provides-Extra: ann-gpu
Requires-Dist: torch>=2.0; extra == "ann-gpu"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
Dynamic: license-file

# chromadose

[![PyPI](https://img.shields.io/pypi/v/chromadose.svg)](https://pypi.org/project/chromadose/)
[![Python](https://img.shields.io/pypi/pyversions/chromadose.svg)](https://pypi.org/project/chromadose/)
[![CI](https://github.com/cptfinch/chromadose/actions/workflows/ci.yml/badge.svg)](https://github.com/cptfinch/chromadose/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Docs](https://img.shields.io/badge/docs-mkdocs--material-blue)](https://cptfinch.github.io/chromadose/)
[![Status](https://img.shields.io/pypi/status/chromadose.svg)](https://pypi.org/project/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](DISCLAIMER.md) for the full statement.

## Methods

| Method | Reference | Description |
|---|---|---|
| **Micke** | Micke, Lewis, Yu (2011) | Original multichannel method — Newton refinement |
| **Mayer** | Mayer et al. (2012) | Analytical optimization with disturbance correction |
| **Multigaussian** | Mendez et al. (2018) | MLE on multivariate Gaussian N(mu(D), Sigma(D)) |
| **ANN** | Chang et al. (2025) | Neural network with ensemble uncertainty |

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

## Quick Start

```python
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

```python
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

```python
from chromadose.io import generate_report

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

## CLI

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

```bash
pip install chromadose
```

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

| Method | 550x500 image | Notes |
|---|---|---|
| Mayer | 0.04s | Analytical — fastest |
| Micke | 0.14s | Newton refinement |
| Multigaussian | 4.7s | Dense grid + parabolic interpolation |
| ANN | ~1s | Depends on ensemble size |

## 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
