Steering: Beam Geometry#

The steering information (stf) describes the physical geometry of all treatment beams: their directions, the positions of individual pencil beams / spots, and — for particle therapy — the energy layers within each beam.

Generating the steering information#

generate_stf() reads beam directions and other settings from the plan’s prop_stf dictionary and produces a fully validated SteeringInformation object:

from pyRadPlan import generate_stf, IonPlan

pln = IonPlan(radiation_mode="protons", machine="Generic")
pln.prop_stf = {
    "gantry_angles": [0, 90, 270],   # degrees; one beam per angle
    "couch_angles":  [0,  0,   0],
    "bixel_width":   5,              # mm lateral spot spacing
    "generator":     "IMPT",         # default for ions
}

stf = generate_stf(ct, cst, pln)

The generator can be selected explicitly via prop_stf["generator"]. Available generators include:

IMPT — Intensity-modulated particle therapy (ions). Produces energy-layer spot maps that cover the target.
ionSingleSpot — A single particle spot, useful for focused tests and debugging.
photonIMRT, photonOpenFields, photonSingleBixel — Photon steering generators for IMRT-like, open-field, and single-bixel setups.
VHEE — Very-high-energy electron steering.

Object hierarchy#

The steering information is organized as a three-level hierarchy:

SteeringInformation
└── Beam  (one per gantry/couch angle pair)
    └── Ray  (one per lateral pencil-beam position)
        └── Beamlet  (one per energy / focus setting)

SteeringInformation#

SteeringInformation is the top-level container.

Attribute	Description
`beams`	List of `Beam` objects.
`num_of_beams`	Total number of beams.
`num_of_rays`	Total ray count across all beams.
`total_number_of_bixels`	Total beamlet count. This is the column dimension of the dose influence matrix.
`bixel_beam_index_map`	Integer array mapping every global bixel index to its beam index.

Beam#

Beam represents a single irradiation direction.

Attribute	Description
`gantry_angle`	Gantry rotation in degrees (IEC convention).
`couch_angle`	Couch rotation in degrees.
`bixel_width`	Lateral spot spacing in mm.
`sad`	Source-to-axis distance in mm.
`iso_center`	Isocenter coordinates `[x, y, z]` in world coordinates.
`source_point`	Source position in world coordinates.
`rays`	List of `Ray` objects.

Ray#

Ray represents one lateral pencil-beam direction within a beam.

Attribute	Description
`ray_pos`	Ray position in world coordinates (mm).
`ray_pos_bev`	Ray position in beam’s-eye-view (BEV) coordinates.
`beamlets`	List of `Beamlet` objects (one per energy layer).

Beamlet#

Beamlet is the smallest unit — a single pencil beam at a fixed energy.

Attribute	Description
`energy`	Beam energy in MeV.
`weight`	Initial fluence weight (updated by the optimizer).
`num_particles_per_mu`	Conversion factor from monitor units to particle count.
`min_mu` / `max_mu`	Monitor-unit bounds for the optimizer.
`range_shifter`	Optional range-shifting device description.

Coordinate systems#

pyRadPlan uses the LPS (Left-Posterior-Superior) coordinate system for world coordinates, consistent with DICOM and SimpleITK. Beam’s-eye-view (BEV) coordinates follow the IEC 61217 convention.

matRad interoperability#

matrad_stf = stf.to_matrad()  # list of dicts, one per beam