beamio

Read, write, and convert acquired or modelled radiotherapy beam measurements using a shared NumPy-based data model.

Supported formats

PTW BEAMSCAN/Mephysto (.mcc) and SNC SunSCAN 3D (.snctxt) are planned and are not implemented in this release.

Installation

Requires Python 3.12 or newer. NumPy is installed automatically.

python -m pip install beamio

Read and convert beam data

from beamio.rfa import BeamDataFactory, IBAAccept6
from beamio.tps.raystation import Raystation

# Detect and parse an IBA Accept ASCII file.
beam = BeamDataFactory.from_file("measurements.asc")
# Or select the reader explicitly:
# beam = IBAAccept6("measurements.asc").parse()

for measurement in beam.measurements:
    print(measurement.type, measurement.energy, measurement.field_size)
    print(measurement.positions, measurement.doses)

# Conversion copies measurements and metadata; save writes the target format.
converted = beam.convert(Raystation)
converted.save("measured_curves.csv")

# RayStation CSV files use the explicit reader.
curves = Raystation("measured_curves.csv").parse()

BeamData provides parse(), save(), and convert(). Each Measurement contains NumPy positions and doses arrays, a MeasurementType, a RadiationType, energy, SSD, field size, scan endpoints, and a metadata dictionary. The shared spatial fields use millimetres. Dose values retain the input scale; conversion does not normalize or calibrate them.

Conversion transfers the shared model and copies metadata, but format-specific writers may use defaults or omit unsupported metadata. In particular, the RayStation writer generates its default file header (including an export time) rather than preserving the input header. IBA parsing removes non-finite sample pairs, sorts and deduplicates positions, and rounds start coordinates to 0.2 mm with values within 0.2 mm of zero set to zero. IBA output rounds coordinates to 0.1 mm. These operations mean that a save is not a byte-for-byte round trip.

Development

python -m venv .venv

Activate the environment with .venv\Scripts\Activate.ps1 in PowerShell or source .venv/bin/activate on macOS/Linux, then run:

python -m pip install -e ".[dev]"
python -m pytest
python -m build
python -m twine check --strict dist/*
python tools/check_dist.py

The tests generate synthetic measurements in temporary directories. CI tests the installed wheel on Linux, Windows, and macOS and rebuilds the wheel from the source distribution. Tests follow the source areas they exercise, with complete conversions under tests/integration.

beamio uses Conventional Commits and Python Semantic Release. Changes merged to main pass CI before automatic versioning, release-note generation, GitHub releases, and PyPI publishing. pyproject.toml is the version source; beamio.__version__ reads the installed distribution metadata.

Documentation

• Architecture and shared data model
• Format support and conversion behavior
• Development and contribution workflow
• Testing guide
• Versioning, TestPyPI, and releasing
• Release notes

License

GNU General Public License version 2 only (GPL-2.0-only); see LICENSE.