opentps.core.data.plan package

Module contents

class FidObjective(roi=None, metric=None, limitValue=0.0, weight=1.0)

Bases: object

This class is used to store a Fidelity Objective.

Variables:

  • metric (FitObjective.Metrics) – metric to use for the objective

  • limitValue (float (default: 0.)) – limit value for the metric

  • weight (float (default: 1.)) – weight of the objective

  • robust (bool) – if True, the objective is robust

  • kind (str (default: "Soft")) – kind of the objective : “Soft” or “Hard”

  • maskVec (np.ndarray) – mask vector

  • roi (ROIContour or ROIMask) – region of interest

  • roiName (str) – name of the region of interest

class Metrics(value)

Bases: Enum

An enumeration.

DMAX = 'DMax'
DMEAN = 'DMean'
DMIN = 'DMin'
property roi
property roiName: str
class ObjectivesList

Bases: object

This class is used to store the objectives of a plan. A plan can have multiple objectives. An objective can be a Fidelity Objective or an Exotic Objective.

Variables:

  • fidObjList (list of FidObjective) – list of Fidelity Objectives

  • exoticObjList (list of ExoticObjective) – list of Exotic Objectives

  • targetName (str) – name of the target

  • targetPrescription (float) – prescription dose of the target

addExoticObjective(weight)

Add an Exotic Objective to the list.

Parameters:

weight (float) – weight of the objective

addFidObjective(roi, metric, limitValue, weight, kind='Soft', robust=False)

Add a Fidelity Objective to the list.

Parameters:

  • roi (ROIContour or ROIMask) – region of interest

  • metric (FitObjective.Metrics or str) – metric to use for the objective : “DMin”, “DMax” or “DMean” or FitObjective.Metrics.DMIN, FitObjective.Metrics.DMAX or FitObjective.Metrics.DMEAN

  • limitValue (float) – limit value for the metric

  • weight (float) – weight of the objective

  • kind (str (default: “Soft”)) – kind of the objective : “Soft” or “Hard”

  • robust (bool (default: False)) – if True, the objective is robust

Raises:

ValueError – if the metric is not supported

append(objective)

Append an objective to the list.

Parameters:

objective (FidObjective or ExoticObjective) – objective to append

Raises:

ValueError – if the objective is not a FidObjective or an ExoticObjective

setTarget(roiName, prescription)

Set the target name and prescription dose.

Parameters:

  • roiName (str) – name of the target

  • prescription (float) – prescription dose of the target

class PlanDesign

Bases: PatientData

This class is used to store the plan design. It inherits from PatientData.

Variables:

  • spotSpacing (float (default: 5.0)) – spacing between spots in mm

  • layerSpacing (float (default: 5.0)) – spacing between layers in mm

  • targetMargin (float (default: 5.0)) – margin around the target in mm

  • scoringVoxelSpacing (float or list of float) – spacing of the scoring grid in mm

  • targetMask (ROIMask) – mask of the target

  • proximalLayers (int (default: 1)) – number of proximal layers

  • distalLayers (int (default: 1)) – number of distal layers

  • layersToSpacingAlignment (bool (default: False)) – if True, the spacing between layers is aligned with the scoring grid

  • calibration (AbstractCTCalibration) – calibration of the CT for stopping power conversion

  • ct (CTImage (default: None)) – CT image

  • beamNames (list of str) – list of beam names

  • gantryAngles (list of float) – list of gantry angles

  • couchAngles (list of float) – list of couch angles

  • rangeShifters (list of RangeShifter) – list of range shifters

  • objectives (ObjectivesList) – list of objectives

  • beamlets (list of Beamlet) – list of beamlets

  • beamletsLET (list of Beamlet) – list of beamlets with LET

  • robustness (Robustness) – robustness evaluation

buildPlan()

Builds a plan from the plan design

Returns:

plan

Return type:

RTPlan

createBeams(plan)

Creates the beams of the plan

Parameters:

plan (RTPlan) – plan

defineTargetMaskAndPrescription()

Defines the target mask and the prescription

initializeBeams(plan)

Initializes the beams of the plan

Parameters:

plan (RTPlan) – plan

property scoringGridSize
property scoringOrigin
property scoringVoxelSpacing: Sequence[float]
setScoringParameters(scoringGridSize: Sequence[int] | None = None, scoringSpacing: Sequence[float] | None = None, scoringOrigin: Sequence[int] | None = None, adapt_gridSize_to_new_spacing=False)

Sets the scoring parameters

Parameters:

  • scoringGridSize (Sequence[int]) – scoring grid size

  • scoringSpacing (Sequence[float]) – scoring spacing

  • scoringOrigin (Sequence[float]) – scoring origin

  • adapt_gridSize_to_new_spacing (bool) – If True, automatically adapt the gridSize to the new spacing

class PlanIonBeam

Bases: object

This class is used to store the information of an ion beam.

Variables:

  • layers (list of PlanIonLayer) – list of layers

  • name (str) – name of the beam

  • isocenterPosition (list of float (default: [0, 0, 0])) – isocenter position of the beam

  • mcsquareIsocenter (list of float (default: [0, 0, 0])) – isocenter position of the beam for MCSquare

  • gantryAngle (float (default: 0.0)) – gantry angle of the beam

  • couchAngle (float (default: 0.0)) – couch angle of the beam

  • id (int (default: 0)) – id of the beam

  • rangeShifter (RangeShifter (optional)) – range shifter of the beam

  • seriesInstanceUID (str) – series instance UID of the beam

  • spotMUs (list of float) – list of spot MUs

  • spotIrradiationTimes (list of float) – list of spot irradiation times

  • spotXY (np.ndarray) – array of spot XY positions

  • spotTimes (np.ndarray) – array of spot times

  • numberSpots (int) – number of spots

  • meterset (float) – meterset of the beam

appendLayer(layer: PlanIonLayer)

Append a layer to the list of layers.

Parameters:

layer (PlanIonLayer) – layer to append

copy()
createEmptyBeamWithSameMetaData()

Create an empty beam with the same metadata (gantry angle, couch angle, etc.).

property layers: Sequence[PlanIonLayer]
property meterset: float
property numberOfSpots: int
removeLayer(layer: PlanIonLayer | Sequence[PlanIonLayer])

Remove a layer from the list of layers.

Parameters:

layer (PlanIonLayer or list of PlanIonLayer) – layer to remove

reorderLayers(order: str | Sequence[int] | None = 'decreasing')

Reorder the layers.

Parameters:

order (str or list of int (default: ‘decreasing’)) – order of the layers. If ‘decreasing’ or ‘scanAlgo’, the layers are ordered by decreasing nominal energy. If a list of int, the layers are ordered according to the list.

simplify(threshold: float = 0.0)

Simplify the layers by removing spots with a weight below the given threshold.

Parameters:

threshold (float (default: 0.0)) – threshold below which spots are removed

property spotIrradiationDurations
property spotMUs
property spotTimings
property spotXY: ndarray
class PlanIonLayer(nominalEnergy: float = 0.0)

Bases: object

This class is used to store the layer of a ionBeam.

Variables:

  • nominalEnergy (float (default: 0.0)) – nominal energy of the layer

  • spots (list of PlanIonSpot) – list of spots

  • spotX (np.ndarray) – x coordinates of the spots

  • spotY (np.ndarray) – y coordinates of the spots

  • spotXY (np.ndarray) – x and y coordinates of the spots

  • spotMUs (np.ndarray) – MUs of the spots

  • spotWeights (np.ndarray) – weights of the spots

  • spotTimings (np.ndarray) – timings of the spots

  • spotIrradiationDurations (np.ndarray) – irradiation durations of the spots

  • meterset – meterset of the layer

  • numberOfSpots (int) – number of spots

  • numberOfPaintings (int (default: 1)) – number of paintings

  • rangeShifterSettings (RangeShifterSettings) – range shifter settings

  • seriesInstanceUID (str) – series instance UID

  • spotsPeakPosInDcmCoords (list of np.ndarray) – peak positions of the spots in DICOM coordinates

  • spotsPeakPosInTargetSystem (list of np.ndarray) – peak positions of the spots in target system coordinates

addToSpot(x: float | Sequence[float], y: float | Sequence[float], mu: float | Sequence[float], startTime: float | Sequence[float] | None = None, irradiationDuration: float | Sequence[float] | None = None)

Adds MU to a spot or multiple spots.

Parameters:

  • x (float or Sequence[float]) – x coordinate of the spot(s)

  • y (float or Sequence[float]) – y coordinate of the spot(s)

  • mu (float or Sequence[float]) – MU of the spot(s)

  • startTime (float or Sequence[float] (optional)) – start time of the spot(s)

  • irradiationDuration (float or Sequence[float] (optional)) – irradiation duration of the spot(s)

appendSpot(x: float | Sequence[float], y: float | Sequence[float], mu: float | Sequence[float], startTime: float | Sequence[float] | None = None, irradiationDuration: float | Sequence[float] | None = None)

Appends a spot or multiple spots to the layer.

Parameters:

  • x (float or Sequence[float]) – x coordinate of the spot(s)

  • y (float or Sequence[float]) – y coordinate of the spot(s)

  • mu (float or Sequence[float]) – MU of the spot(s)

  • startTime (float or Sequence[float] (optional)) – start time of the spot(s)

  • irradiationDuration (float or Sequence[float] (optional)) – irradiation duration of the spot(s)

copy()
createEmptyLayerWithSameMetaData()

Creates an empty layer with the same metadata (e.g. range shifter settings) as the current layer.

property meterset: float
property numberOfSpots: int
removeSpot(x: float | Sequence[float], y: float | Sequence[float])

Removes a spot or multiple spots from the layer.

Parameters:

  • x (float or Sequence[float]) – x coordinate of the spot(s)

  • y (float or Sequence[float]) – y coordinate of the spot(s)

removeZeroMUSpots(threshold)

Removes spots with a mu below a threshold.

Parameters:

threshold (float) – the threshold below which spots are removed

reorderSpots(order: str | Sequence[int] = 'scanAlgo')

Reorders the spots in the layer.

Parameters:

order (str or Sequence[int]) – the way the spots are sorted. If str, the following options are available:

  • ‘scanAlgo’: the way scanAlgo sort spots in a serpentine fashion

  • ‘timing’: sort according to the start time of the spots

If Sequence[int], the spots a reordered according to the order of the indices

Raises:

ValueError – if the order is not recognized:

setSpot(x: float | Sequence[float], y: float | Sequence[float], mu: float | Sequence[float], startTime: float | Sequence[float] | None = None, irradiationDuration: float | Sequence[float] | None = None)

Sets a spot or multiple spots to the layer.

Parameters:

  • x (float or Sequence[float]) – x coordinate of the spot(s)

  • y (float or Sequence[float]) – y coordinate of the spot(s)

  • mu (float or Sequence[float]) – MU of the spot(s)

  • startTime (float or Sequence[float] (optional)) – start time of the spot(s)

  • irradiationDuration (float or Sequence[float] (optional)) – irradiation duration of the spot(s)

simplify(threshold: float = 0.0)

Simplifies the layer by merging duplicate spots and removing spots with a mu below a threshold.

Parameters:

threshold (float (default: 0.0)) – the threshold below which spots are removed

spotDefinedInXY(x: float | Sequence[float], y: float | Sequence[float]) → Tuple[bool, int]

Checks if a spot or multiple spots are defined in the layer.

Parameters:

  • x (float or Sequence[float]) – x coordinate of the spot(s)

  • y (float or Sequence[float]) – y coordinate of the spot(s)

Returns:

exist – True if the spot(s) exist in the layer, False otherwise

Return type:

bool or Sequence[bool]

property spotIrradiationDurations: ndarray
property spotMUs: ndarray
property spotTimings: ndarray
property spotWeights: ndarray
property spotX: Sequence[float]
property spotXY: Iterable[Tuple[float, float]]
property spotY: Sequence[float]
property spots
class PlanIonSpot

Bases: object

A single ion spot in a layer of a beam.

Variables:

  • spotXY (list) – List of x,y coordinates of the spot in the beam’s coordinate system.

  • id (int) – Spot ID.

  • beamID (int (default 0)) – Beam ID.

  • layerID (int (default 0)) – Layer ID.

  • voxels (list) – List of voxels that are hit by the spot.

  • energy (float (default 0.0)) – Energy of the spot.

  • peakPosInDicomCoords (list) – Peak position of the spot in the DICOM coordinate system.

  • peakPosInTargetSystem (list) – Peak position of the spot in the target coordinate system.

  • spotWeight (int (default 0)) – Spot weight.

  • spotTiming (int (default 0)) – Spot timing.

class RTPlan(name='RTPlan', patient=None)

Bases: PatientData

Class for storing the data of a single RTPlan. Inherits from PatientData.

Variables:

  • name (str (default: "RTPlan")) – Name of the RTPlan.

  • patient (Patient) – Patient object to which the RTPlan belongs.

  • deliveredProtons (float) – Number of protons delivered in the plan.

  • beams (list of PlanIonBeam) – List of beams in the plan.

  • layers (list of PlanIonLayer) – List of layers in the plan.

  • spotMUs (np.ndarray) – Array of spot monitor units.

  • spotTimings (np.ndarray) – Array of spot timings.

  • spotIrradiationDurations (np.ndarray) – Array of spot irradiation durations.

  • spotXY (np.ndarray) – Array of spot XY coordinates.

  • meterset (float) – Total number of monitor units in the plan.

  • beamCumulativeMetersetWeight (np.ndarray) – Array of beam cumulative meterset weights.

  • layerCumulativeMetersetWeight (np.ndarray) – Array of layer cumulative meterset weights.

  • meterset – Total number of monitor units in the plan.

  • numberOfSpots (int) – Number of spots in the plan.

  • numberOffractionsPlanned (int (default: 1)) – Number of fractions planned.

appendBeam(beam: PlanIonBeam)
appendLayer(beam: PlanIonBeam, layer: PlanIonLayer)

Assign a particular layer (beam, layer) to plan

Parameters:

  • beam (PlanIonBeam) – The beam of the layer to assign

  • layer (PlanIonLayer) – The layer to assign

appendSpot(beam: PlanIonBeam, layer: PlanIonLayer, spot_index: int)

Assign a particular spot (beam, layer, spot_index) to plan

Parameters:

  • beam (PlanIonBeam) – The beam of the spot to assign

  • layer (PlanIonLayer) – The layer of the spot to assign

  • spot_index (int) – The index of the spot to assign

property beamCumulativeMetersetWeight: ndarray
property beams: Sequence[PlanIonBeam]
copy()
createEmptyPlanWithSameMetaData()

Create an empty plan with the same metadata as the current plan

property layerCumulativeMetersetWeight: ndarray
property layers: Sequence[PlanIonLayer]
property meterset: float
property numberOfFractionsPlanned: int
property numberOfSpots: int
removeBeam(beam: PlanIonBeam)
reorderPlan(order_layers='decreasing', order_spots='scanAlgo')

Reorder the plan by reordering each beam

Parameters:

  • order_layers (str or list of int (default: ‘decreasing’)) – order of the layers. If ‘decreasing’ or ‘scanAlgo’, the layers are ordered by decreasing nominal energy. If a list of int, the layers are ordered according to the list.

  • order_spots (str or Sequence[int] (default: ‘scanAlgo’)) –

    the way the spots are sorted.
    If str, the following options are available:

    • ‘scanAlgo’: the way scanAlgo sort spots in a serpentine fashion

    • ‘timing’: sort according to the start time of the spots

    If Sequence[int], the spots a reordered according to the order of the indices

simplify(threshold: float = 0.0)

Simplify the plan by removing duplicate beams and simplifying each beam

Parameters:

threshold (float (default 0.0)) – The threshold to use for simplifying each beam

property spotIrradiationDurations: ndarray
property spotMUs: ndarray
property spotTimings: ndarray
property spotXY: ndarray
class RangeShifter(material='PMMA', density=1.0, WET=40.0, type='binary')

Bases: object

RangeShifter class

Variables:

  • ID (str) – RangeShifter ID.

  • type (str (default 'binary')) – RangeShifter type.

  • material (str (default 'PMMA')) – RangeShifter material for MCsquare.

  • density (float (default 1.0)) – RangeShifter density for MCsquare.

  • WET (float (default 40.0)) – RangeShifter water equivalent thickness for MCsquare.

mcsquareFormatted(materials) → str

String representation of the RangeShifter for MCsquare.

Parameters:

materials (dict) – List of materials for MCsquare.

Returns:

s – String representation of the RangeShifter for MCsquare.

Return type:

str

class ScanAlgoPlan(plan: RTPlan, Gantry: str, beamID=0, sort_spots='true')

Bases: object

Class to create a plan with Protheus Plus or Protheus One accelerator from IBA

Parameters:

Gantry (str) – Gantry angle of the accelerator. Can be “PPlus” or “POne”

getLayers(plan, Gantry, beamID)

Function to get the layers of the plan

Parameters:

  • plan (RTPlan) – Plan to be converted

  • Gantry (str) – Gantry angle of the accelerator. Can be “PPlus” or “POne” for Protheus Plus or Protheus One accelerator from IBA.

  • beamID (int) – ID of the beam to be converted

Returns:

beamDict – Dictionary with the layers of the plan

Return type:

dict

load(file_path)

Function to load a plan from a json file

Parameters:

file_path (str) – Path to load the plan

save(file_path)

Function to save the plan in a json file

Parameters:

file_path (str) – Path to save the plan