Topas extensions - topasmc/dicom-interface GitHub Wiki

Two TOPAS extensions were written to communicate RTI library, TsRTIonComponents, which is a TOPAS geometry component and TsRTIonSource, which is a TOPAS source component. Users don't have to edit neither of those files but control using TOPAS parameters.

TsRTIonComponent

Files are TsRTIonComponent.hh/.cc

The TOPAS parameters to use this extension are shown below (see rti/topas/ui/templates/beam.txt).

# ----------------
# Geometry definition
# Follows are mandatory input parameters
# ----------------
s:Ge/RTION/Type     = "TsRTIonComponents"
s:Ge/RTION/Parent   = "IEC_F"
s:Ge/RTION/File     = "RTIP.dcm" #or "RTIBTR.dcm"
s:Ge/RTION/BeamName = "beam1"
# or
#i:Ge/RTION/BeamNumber = 0 

# ----------------
# Position of isocenter w.r.t mother volume
# ----------------
d:Ge/RTION/TransX  = 0 mm
d:Ge/RTION/TransY  = 0 mm
d:Ge/RTION/TransZ  = 0 mm

# ----------------
# Isocenter position from DICOM
# These are changeable parameters
# it can be assigned to TransX/Y/Z
# ex) Ge/RTION/TransX = IsoCenterX mm
# ----------------
dc:Ge/RTION/IsoCenterX  = 0 mm
dc:Ge/RTION/IsoCenterY  = 0 mm
dc:Ge/RTION/IsoCenterZ  = 0 mm

# ----------------
# Rotation angles of beamline & couch
# ----------------
d:Ge/RTION/RotCollimator      = 0.0 deg
d:Ge/RTION/RotGantry          = 0.0 deg
d:Ge/RTION/RotPatientSupport  = 0.0 deg
d:Ge/RTION/RotIEC2DICOM       = 0.0 deg

# ----------------
# Rotation angles from DICOM
# These are changeable parameters
# it can be assigned to rotation angles above
# ex) Ge/RTION/RotGantry = Ge/RTION/GantryAngle deg
# ----------------
dc:Ge/RTION/CollimatorAngle     = 0 deg
dc:Ge/RTION/GantryAngle         = 0 deg
dc:Ge/RTION/PatientSupportAngle = 0 deg
dc:Ge/RTION/Iec2DicomAngle      = 0 deg
# Users can override the rotation for their own purpose.
# ex) Most of QA simulation runs without rotations.

# -----------------
# Patient CT directory
# this is optional but useful to locate isocenter w.r.t patient coordinate system.
# see patient application below
# -----------------
s:Ge/RTION/ImgDirectory = your_ct_directory

# -----------------
# Material information for subcomponents,
# Range shifter and aperture
# -----------------
s:Ge/RTION/rangeshifter/Material = "RS_Lucite"
s:Ge/RTION/Block/Material        = "G4_BRASS"
s:Ge/RTION/Compensator/Material  = ""
s:Ge/RTION/Snout/Material        = ""

# -----------------
# Create geometry as parallel
# Needs to create this geometry as mass-parallel 
# when patient calculation is performed.
# -----------------
b:Ge/RTION/IsParallel            = "F"

# -----------------
# Optional parameters to switch on/off to creat sub-components.
# -----------------
b:Ge/RTION/IncludeDoseGridIfExist     = "F" 
b:Ge/RTION/IncludeSnoutIfExist        = "T"
b:Ge/RTION/IncludeRangeshifterIfExist = "T"
b:Ge/RTION/IncludeBlockIfExist        = "T"
b:Ge/RTION/IncludeCompensatorIfExist  = "T"

TsRTIonSource

Files are TsRTISource.hh/.cc and TsRTISourceGenerator.hh/.cc

The TOPAS parameters to use this extension are shown below (see rti/topas/ui/templates/beam.txt).

# ----------------
# Beamsource definition
# Follows are mandatory input parameters
# ----------------
s:So/RTION/Type       = "TsRTIonSource" 
s:So/RTION/Componenet = "IEC_F"
s:So/RTION/File       = Ge/RTION/File 
i:So/RTION/BeamNumber = Ge/RTION/BeamNumber
d:So/RTION/SID        = 39.0 cm          #where the beam starts
u:So/RTION/ParticlesPerHistory = 100000 #one-history corresponds 100_000 real protons
# b:So/RTION/NormalizeHistoriesPerDose = "T"  #not yet implemented (July 29, 2019)
# ----------------
# Position of isocenter w.r.t mother volume
# ShiftX/Y/Z is RTION source specific parameters
# ----------------
d:So/RTION/ShiftX = 0.0 mm 
d:So/RTION/ShiftY = 0.0 mm 
d:So/RTION/ShiftZ = 0.0 mm 

# ----------------
# Isocenter position from DICOM
# These are changeable parameters
# it can be assigned to TransX/Y/Z
# ex) So/RTION/ShiftX = So/RTION/IsoCenterX mm
# ----------------
dc:So/RTION/IsoCenterX  = 0 mm
dc:So/RTION/IsoCenterY  = 0 mm
dc:So/RTION/IsoCenterZ  = 0 mm

# ----------------
# Rotation angles of beamline & couch
# ----------------
d:So/RTION/RotCollimator      = 0.0 deg 
d:So/RTION/RotGantry          = 0.0 deg 
d:So/RTION/RotIEC2DICOM       = 0.0 deg 
d:So/RTION/RotPatientSupport  = 0.0 deg 

# ----------------
# Rotation angles from DICOM
# These are changeable parameters
# it can be assigned to rotation angles above
# ex) So/RTION/RotGantry = So/RTION/GantryAngle deg
# ----------------
dc:So/RTION/CollimatorAngle     = 0 deg
dc:So/RTION/Iec2DicomAngle      = 0 deg
dc:So/RTION/GantryAngle         = 0 deg
dc:So/RTION/PatientSupportAngle = 0 deg

Note that the total number of histories simulated in TOPAS equals the number of protons of a beamlet (i.e. the meterset weight from the rtplan.dcm file) divided by the variable ParticlesPerHistory (user-set in the TOPAS input file).

Applications

This section shows an example to utilize RTI with TOPAS for clinical applications. It does not require complicated scripts that reads in DICOM files and output to TOPAS input parameters. But we still need some of DICOM related information, such as file name and beam name. For those information, please take a look DICOM_variables.txt.

Figure Parameter file chain for TOPAS applications, plan and QA.

For patient calculations,

$ topas plan_hu_view.txt

You can run simulation by clicking 'run' button (left top) on GUI. You will see like following image.

If you don't need visualization anymore, you can just run topas.

$ topas plan_hu.txt

For QA calculations, you will see water box instead of CT.

$ topas QA_view.txt

As plan example, you can simply perform QA simulation without visualization.

$ topas QA.txt

Patient calculation

In this example, the patient doesn't move. Instead, the beamline and beamsource are rotating and moving around the patient. This requires mapping coordinate system from IEC to DICOM, i.e., they are 90 degree rotated around x-axis. See below image.

Figure Cooridnate transform from IEC to DICOM used in this example.

Patient positioning

Patient position is fixed. see blow.

s:Ge/Patient/Type     = "TsDicomPatient"
s:Ge/Patient/Parent   = "IEC_F"
s:Ge/Patient/Material = "G4_WATER"
s:Ge/Patient/DicomDirectory      = Rt/RTION/CTDirectory

d:Ge/Patient/TransX   = 0.0 mm 
d:Ge/Patient/TransY   = 0.0 mm
d:Ge/Patient/TransZ   = 0.0 mm 

d:Ge/Patient/RotX     = 0. deg
d:Ge/Patient/RotY     = 0. deg
d:Ge/Patient/RotZ     = 0. deg

Beamline positioning Instead, the beamline rotates first. The rotation angles are given from DICOM and then beamline center is located to treatment isocenter by following.

# ---
# Rotation RTIon components (only beamline components) 
# ---
Ge/RTION/RotCollimator      = Ge/RTION/CollimatorAngle deg
Ge/RTION/RotGantry          = Ge/RTION/GantryAngle deg
Ge/RTION/RotPatientSupport  = -1.0 * Ge/RTION/PatientSupportAngle deg
Ge/RTION/RotIEC2DICOM       = 90 deg

# ---
# Position RTIon components (only beamline component)
# ---
Ge/RTION/TransX = Ge/RTION/IsoCenterX - Ge/RTION/ImgCenterX mm
Ge/RTION/TransY = Ge/RTION/IsoCenterY - Ge/RTION/ImgCenterY mm
Ge/RTION/TransZ = Ge/RTION/IsoCenterZ - Ge/RTION/ImgCenterZ mm

If the plan has a rtdose, rtdose is automatically created as follow.

# ---
# Dosegrid
# ---
s:Ge/RTION/rtdosefile   = Rt/RTION/DoseFile 
b:Ge/RTION/IncludeDoseGridIfExist = "T"

Beamsource positioning Same process is applied to beamsource too. See below.

# ---
# Rotation RTIon source
# ---
So/RTION/RotCollimator      = So/RTION/CollimatorAngle deg
So/RTION/RotGantry          = So/RTION/GantryAngle deg
So/RTION/RotPatientSupport  = -1.0 * So/RTION/PatientSupportAngle deg
So/RTION/RotIEC2DICOM       = 90  deg

# ---
# Shift  beamsource to aim patient's treatment isocenter.
# ---
So/RTION/ShiftX = So/RTION/IsoCenterX - So/RTION/ImgCenterX mm
So/RTION/ShiftY = So/RTION/IsoCenterY - So/RTION/ImgCenterY mm
So/RTION/ShiftZ = So/RTION/IsoCenterZ - So/RTION/ImgCenterZ mm

Water phantom calculation

As the beam.txt already overwrite all angles to zero and no shifts on isocenter, there are nothing to do for positioning beamline and beamsource.

Just a water phantom geometry is created. For more detail, see QA.txt.

####################################################
#----------------- Waterphantom --------------------
####################################################
# Initially waterphantom center is iso
s:Ge/WaterPhantomTop/Type   = "Group"
s:Ge/WaterPhantomTop/Parent = "IEC_F"
d:Ge/WaterPhantomTop/TransX = 0 mm
d:Ge/WaterPhantomTop/TransY = 0 mm
d:Ge/WaterPhantomTop/TransZ = 0.0 cm
d:Ge/WaterPhantomTop/RotX   = 0 deg
d:Ge/WaterPhantomTop/RotY   = 0 deg
d:Ge/WaterPhantomTop/RotZ   = 0 deg

#--- Water phantom target
s:Ge/WaterPhantom/Type="TsBox"
s:Ge/WaterPhantom/Parent="WaterPhantomTop"
#Water: I-value 75 eV
#G4_Water: I-value: 78, ICRU 75 +- 3 eV
s:Ge/WaterPhantom/Material="G4_WATER"
d:Ge/WaterPhantom/HLX= 17.5 cm
d:Ge/WaterPhantom/HLY= 17.5 cm
d:Ge/WaterPhantom/HLZ= 19 cm
d:Ge/WaterPhantom/TransX = 0. cm
d:Ge/WaterPhantom/TransY = 0. cm
d:Ge/WaterPhantom/TransZ = Ge/WaterPhantom/HLZ  cm * -1.0
d:Ge/WaterPhantom/RotX = 0. deg
d:Ge/WaterPhantom/RotY = 0. deg
d:Ge/WaterPhantom/RotZ = 0. deg
s:Ge/WaterPhantom/Color = "blue"