OpenPINT

OpenPINT — Open-source Planning for Isoeffective Nuclear Treatments

OpenPINT is an open-source treatment planning system for nuclear therapies that integrates Monte Carlo dose calculations with modular dosimetric and radiobiological models for photon-isoeffective dose evaluation.

Key Features

• Convert MCNP and PHITS mesh tallies into BNCT dose component volumes (bin/sim_result_2_nifti.py, bin/sim_PHITS_result_2_nifti.py).
• Aggregate and weight multiple BNCT irradiation fractions (bin/bnct_fractions_sum.py).
• Resample hadron therapy dose maps and convert to biologically effective dose (bin/hadron_dose_2_bed.py).
• Build BNCT treatment plans from structured Excel workbooks and compute dose, TCP, NTCP, and DVH metrics (OpenPINT/treatment.py).
• Generate limiting-organ masks from CT volumes and exclusion masks (bin/nib_organ_at_risk.py).

Installation

OpenPINT targets Python 3.9 or newer.

From PyPI (after publication)

python3 -m pip install OpenPINT

To include support for Excel treatment-plan files:

python3 -m pip install "OpenPINT[excel]"

From GitHub

python3 -m pip install "git+https://github.com/ipostuma/OpenPINT.git"

To include support for Excel treatment-plan files:

python3 -m pip install "OpenPINT[excel] @ git+https://github.com/ipostuma/OpenPINT.git"

To install a specific branch, tag, or commit, append its Git reference:

python3 -m pip install "git+https://github.com/ipostuma/OpenPINT.git@main"

From a local clone

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install .

To include support for Excel treatment-plan files:

python3 -m pip install ".[excel]"

For an editable development installation:

python3 -m pip install -e ".[excel]"

Using Conda

conda create -n openpint python=3.9
conda activate openpint
conda install -c conda-forge --file requirements.txt
python3 -m pip install --no-deps .

Excel support: Reading treatment plans from XLSX files relies on the optional openpyxl dependency, installed by the excel extra. It remains listed in requirements.txt for the Conda workflow.

Usage

The toolkit can be used from the command line or as a Python library. All CLI scripts live in bin/ and expect the repository root on PYTHONPATH (handled internally by the scripts).

CLI scripts in bin/

• sim_result_2_nifti.py: Reads an MCNP mesh tally file, maps it to the CT geometry using the provided simulation box shape/offset, and writes BNCT component volumes (*_B10.nii.gz, *_N14.nii.gz, *_n.nii.gz, *_g.nii.gz).
• sim_PHITS_result_2_nifti.py: Same conversion workflow as above for PHITS outputs, using four mesh files provided in fixed component order (B10, N14, n, g).
• bnct_fractions_sum.py: Loads a fractions CSV (w, B10, N14, n, g columns), computes weighted averages across fractions, and saves one summed NIfTI per component.
• bnct_tp_eval.py: Loads a BNCT plan from Excel and prints treatment-evaluation metrics, including limiting OAR irradiation time, dose components at the limiting point, maximum IsoE dose, and TCP summaries.
• hadron_dose_2_bed.py: Resamples a hadron dose map to the planning CT grid and converts physical dose to BED using the provided fraction count and alpha/beta ratio.
• nib_mask_subtract.py: Performs voxel-wise mask subtraction (mask1 \\ mask2) to generate a shell-like mask and saves it as <mask1>-<mask2>_shell.nii.gz.
• nib_organ_at_risk.py: Builds a limiting-organ mask by excluding air below a CT threshold and excluding voxels from masks listed in a CSV (mask_path, foreground_value).

Import the package

The primary Python import namespace is OpenPINT. The former BNCTDosimetry namespace remains available temporarily as a deprecated compatibility wrapper. After installation, OpenPINT can be imported from any working directory without setting PYTHONPATH.

Converting MCNP tallies

python3 bin/sim_result_2_nifti.py \
    path/to/mcnp_msh.out \
    path/to/ct_scan.nii.gz \
    100 100 120 \
    12 12 48 \
    -o output_prefix

This command produces output_prefix_{B10,N14,n,g}.nii.gz volumes aligned with the CT image.

Summing BNCT fractions

python3 bin/bnct_fractions_sum.py \
    path/to/fractions_folder \
    fractions.csv \
    --time_normalization 30.0 \
    --output_path results/

fractions.csv must contain the dose component filenames and weighting factors for each fraction.

Resampling hadron dose maps

python3 bin/hadron_dose_2_bed.py \
    hadron_dose.nii.gz \
    planning_ct.nii.gz \
    30 \
    2.0 \
    --output_path results/

The script resamples the hadron dose to the CT grid and stores an _BED.nii.gz file.

Python API example

from OpenPINT.treatment import BNCT

plan = BNCT("patient_plan.xlsx")
plan.set_irradiation_time()
isoe_dose = plan.get_isoeffective_dose(n=1)
tcp = plan.get_TCP("HN_Rwigema_Gonzalez")
print("Max IsoE dose:", isoe_dose.max())
print("TCP values:", tcp)

Synthetic patient generation

from OpenPINT import SyntheticPatientGenerator, save_masks

generator = SyntheticPatientGenerator(
    shape=(120, 120, 120),
    spacing=(1.0, 1.0, 1.0),
    patient_radius_mm=30,
    cylinder_height_mm=90,
    sphere_radius_mm=10,
    sphere_distance_mm=5,
    skull_thickness_mm=5,
    skin_thickness_mm=3,
)

masks = generator.generate_masks()
save_masks(masks, "./outputs", scale_mm=(1.0, 1.0, 1.0))

Input data expectations

• Dose and mask volumes must be provided as NIfTI files (*.nii or *.nii.gz).
• BNCT treatment plans are stored in Excel with worksheets ct, GTV, CTV, PTV, HOM, and dose (see OpenPINT/treatment.py).
• Monte Carlo mesh outputs must follow the formats parsed by OpenPINT/dose/io/read_mcnp_mesh.py or OpenPINT/dose/io/read_phits_mesh.py.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on developing, testing, and submitting changes.

Testing

Automated tests can be run with Python's built-in unittest:

python -m unittest discover -s tests

Changelog

Release history is documented in CHANGELOG.md.

Code of Conduct

We expect everyone participating in the project to follow the Code of Conduct.

Disclaimer

This software is not a certified medical device or clinical treatment-planning system. It is intended for research, education, and methodological validation only. It must not be used for clinical decision-making, patient treatment, or regulatory submissions without independent validation, commissioning, quality assurance, and applicable regulatory approval.

License

This project is licensed under the European Union Public Licence v1.2 (EUPL-1.2). See LICENSE for the full text and THIRD_PARTY_NOTICES.md for bundled third-party licenses.

Roadmap & To-Do

• Expand testing coverage for radiobiological models and CLI scripts.
• Extend documentation with end-to-end examples using sample datasets.
• Publish an initial tagged release and register a DOI via INFN Open Access Repository.

If you build something with OpenPINT or have ideas for improvements, open an issue or start a discussion!