Warning, /geant4/examples/advanced/ICRP110_HumanPhantoms/README is written in an unsupported language. File is not indexed.
0001 =======================================================================
0002 Geant4 - ICRP110_HumanPhantoms Example
0003 =======================================================================
0004
0005 The ICRP110_HumanPhantoms example is developed and mantained by Susanna Guatelli, Matthew Large and Alessandra Malaroda,
0006 Centre For Medical Radiation Physics (CMRP), University of Wollongong, NSW, Australia, and John Allison, Geant4 Associates International
0007 and University of Manchester, UK.
0008
0009 Contacts:
0010 - susanna@uow.edu.au
0011 - mjl970@uowmail.edu.au
0012 - malaroda@uow.edu.au
0013 - John.Allison@g4ai.org
0014
0015 The example is based on the extended/medical/DICOM example
0016
0017 The authors acknowledge that this application of the ICRP110 human phantoms have been implemented in Geant4 with the kind permission of
0018 the International Commission on Radiological Protection (ICRP).
0019
0020 ----------------------------------------------------------------------------------------------------
0021 --------------------------------------> Introduction <----------------------------------------------
0022 ----------------------------------------------------------------------------------------------------
0023
0024 This application models the ICRP110 reference computational human phantoms [1] in a Geant4 simulation and calculates
0025 the dose in individual voxels and in entire organs.
0026
0027 The human male phantom, provided kindly by the ICRP, is created from a whole-body clinical CT image set of a 38yr old
0028 individual with height 176 cm and mass approximately 70 kg. Similarly, the human female phantom was created from a set of
0029 whole body CT images of a 43yr old individual with height 163 cm and weight 60 kg. The CT scans were acquired with both
0030 individuals laying supine and with arms resting parallel alongside the body. Both sets of CT data were then scaled to
0031 closely approximate the ICRP adult Reference Male and Reference Female, defined in previous ICRP publications [2, 3].
0032
0033 [1] HG Menzel, C Clement, and P DeLuca. ICRP publication 110. "Realistic reference phantoms:
0034 an icrp/icru joint effort: A report of adult reference computational phantoms", Annals of the
0035 ICRP, 39(2):1, 2009. URL: http://www.icrp.org/publication.asp?id=icrp%20publication%20110.
0036
0037 [2] Valetin J 2002 Basic anatomical and physiological data for use in radiological protection:
0038 reference values: ICRP Publication 89 Ann. ICRP vol. 32 (Oxford: Elsevier) pp 1-277.
0039
0040 [3] Valetin J 2007 The 2007 recommendations of the international commission on radiological
0041 protection Ann. ICRP vol 37 (Oxford: Elsevier) pp 1-133.
0042
0043 The table below summarises the key features of the male and female voxelised human phantoms.
0044
0045 PROPERTY AM AF
0046 _____________________________________
0047 Height (m) 1.76 1.63
0048
0049 Mass(Kg) 73.0 60.0
0050
0051 Slice Thickness(mm) 8.0 4.84
0052
0053 Voxel in-plane- 2.137 1.775
0054 -resolution (mm)
0055
0056 Voxels along x 254 299
0057 (i.e. columns)
0058
0059 Voxels along y 127 137
0060 (i.e. rows)
0061
0062 Number of Slices 222 348
0063 (i.e. along z)
0064 ______________________________________
0065
0066 ----------------------------------------------------------------------------------------------------
0067 ------------------------------> Application Sub-Folder Structure <----------------------------------
0068 ----------------------------------------------------------------------------------------------------
0069
0070 - '/src': where the source .cc files are stored
0071
0072 - '/include': where header .hh files are stored
0073
0074 - '/ICRPdata': where the phantom data files (*.dat) and slice files are stored.
0075 It is downloaded automatically from URL https://cern.ch/geant4-data/datasets/examples/advanced/ICRP110Phantoms/ICRPdata.tar.gz
0076 during the configuration via cmake.
0077
0078 Phantom data files containing the voxelisation of each phantom, as well as files
0079 containing the definitions of the phantom organs and materials used within geant4
0080 code can be found in the folder /ICRPdata.
0081
0082 All data files used for this phantom were obtained from the ICRP's website on publication 110 under "Supplementary Data"
0083 - https://www.icrp.org/publication.asp?id=ICRP%20Publication%20110.
0084
0085 ----------------------------------------------------------------------------------------------------
0086 ----------------------------------> ICRP110Phantoms Data <------------------------------------------
0087 ----------------------------------------------------------------------------------------------------
0088
0089 Within the '/ICRPdata' directory, the following sub-directories are contained:
0090
0091 -> /ICRPdata/ : contains '*Data.dat' files which list the number of phantom slices to
0092 simulate and the order in which to stack the phantom slices.
0093
0094 -> /ICRPdata/ICRP110_g4dat/AM/ : contains the individual male phantom slice files.
0095
0096 -> /ICRPdata/ICRP110_g4dat/AF/ : contains the individual female phantom slice files.
0097
0098 -> /ICRPdata/ICRP110_g4dat/P110_data_V1.2
0099
0100 The final directory contains the raw ICRP110 phantom data as obtained from the ICRP110 publication website [1];
0101 5 files within folders for the AM and AF phantoms are given. These files are described as follows in the
0102 supplementary data's included README file.
0103
0104 The array of organ identification numbers (in ASCII format); the file names are:
0105 AM.dat
0106 AF.dat
0107
0108 A list of individually segmented structures, their identification numbers, and assigned media (Appendix A in ICRP110); the file names are:
0109 AM_organs.dat
0110 AF_organs.dat
0111
0112 A list of the media, their elemental compositions and densities (Appendix B in ICRP110);
0113 the file names are:
0114 AM_media.dat
0115 AF_media.dat
0116
0117 The mass ratios of bone constituents (trabecular bone, red and yellow bone marrow) in the spongiosa regions;
0118 the file names are:
0119 AM_spongiosa.dat
0120 AF_spongiosa.dat
0121
0122 The mass ratios of blood in various body tissues; the file names are:
0123 AM_blood.dat
0124 AF_blood.dat
0125
0126 The primary data files AM.dat and AF.dat contain an array of organ identification numbers ranging from 0 to 141.
0127 Each number respresents the organ associated with each voxel within the phantom. Within these files, the organ IDs
0128 are listed slice by slice, within each slice row by row, within each row column by column. That means, the column
0129 index changes fastest, then the row index, then the slice index - in other words, the phantom voxels first increase
0130 along x, then along y and finally along z. Slice numbers increase from the toes up to the vertex of the body;
0131 row numbers increase from front to back; and column numbers increase from right to left side.
0132
0133 For use in this application, the original AM.dat and AF.dat files containing the organ identification numbers of
0134 all voxels of the phantom were sub-divided into many files with each representing a single phantom slice along z.
0135 As such, each file represents a 2D phantom slice containing x,y voxel positions and organ identification numbers
0136 of each voxel. This allows for subsections of the phantom to be simulated as required by the user, removing the
0137 need to simulate the entire phantom every time when this may not nessecrily be needed by the user. This also will
0138 allow for reductions in the simulation time depending on what portion of the total phantom is simulated by the user.
0139 This feature was achieved via a code developed by Dr Alessandra Malaroda, University of Wollongong, Australia in 2017.
0140
0141 The AM human phantom is voxelised in x,y,z with 254 x 127 x 222 voxels with dimensions 2.137 x 2.137 x 8 mm.
0142 The AF human phantom is voxelised in x,y,z with 299 x 137 x 348 voxels with dimensions 1.775 x 1.775 x 4.84 mm.
0143
0144 ----------------------------------------------------------------------------------------------------
0145 ---------------------------------------> How to compile and run <-----------------------------------
0146 ----------------------------------------------------------------------------------------------------
0147
0148 - Create a build folder for the phantom run
0149 % mkdir build/
0150
0151 - Navigate to inside the build folder and initialise Geant4
0152 % cmake ../
0153
0154 The ICRP110 phantom data will be automatically downloaded from https://cern.ch/geant4-data/datasets/examples/advanced/ICRP110Phantoms/ICRPdata.tar.gz
0155
0156 - Compile and link to generate the executable (in your CMAKE build directory):
0157 % make
0158 This should make two executables - ICRP110phantoms and ICRP110standalone.
0159
0160 - Execute the application in 'interactive' mode with visualization:
0161 % ./ICRP110phantoms
0162
0163 - Execute the "standalone" application in 'interactive' mode with visualization:
0164 % ./ICRP110standalone
0165 This allows you to visualise the phantom without the overhead of the run manager and initialising all the physics tables.
0166 Of course, you cannot run or visualise trajectories.
0167
0168 - Execute the application in 'batch' mode from macro files:
0169 % ./ICRP110phantoms female_head.in
0170
0171 -----------------------------
0172 AVAILABLE MACRO FILES
0173 -----------------------------
0174 For the users convenience, macro files have been created which are designed to construct partial head
0175 and trunk phantoms for both the male and female models. These macro files can be called upon in batch
0176 mode when executing the application as specified above. If the user wishes to construct a completed/full
0177 male or female phantom, the macros male.in and female.in can be called upon, respectively.
0178
0179 - male_head.in/female_head.in : Creates a partial head phantom for the male and female, respectively.
0180 - male_trunk.in/female_trunk.in : Creates a partial trunk phantom for the male and female, respectively.
0181 - male.in : Creates full male ICRP110 phantom. This can be modified along with 'ICRPdata/MaleData.dat'
0182 if the user wishes to create their own custom partial phantom section.
0183 - female.in : Creates full female ICRP110 phantom. This can be modified along with
0184 'ICRPdata/FemaleData.dat' if the user wishes to create their own custom partial phantom section.
0185 - openGLVis.mac : macro for visualisation with openGL.
0186 - vis.mac (default) : Executed by default when the simulation is run in 'interactive' mode.
0187 - primary.mac : Contains the definition of the primary radiation field.
0188
0189 At the very top of the various '.in' macro files (pre-initialization), there are a series of commands
0190 which define the sex and section of the phantom to create. These commands are listed below:
0191
0192 o /phantom/setPhantomSex <option> : Passes sex of phantom to Detector Construction
0193 o /phantom/setScoreWriterSex <option> : Passes sex of phantom to User Score Writer
0194
0195 o /phantom/setPhantomSection <option> : Passes section of phantom to Detector Construction
0196 o /phantom/setScoreWriterSection <option> Passes section of phantom to User Score Writer
0197
0198 Available options for the first 2 commands are: male or female.
0199 Avalable options for the last 2 commands are: head, trunk or full.
0200
0201 In the event that the macro called upon by the user when executing the application in 'batch' mode
0202 does not contain these commands (default case), the application sets phantom sex to female and the section as the head.
0203
0204 WARNING: the phantom model can be chosen only in the initialization phase of the simulation!!!
0205 It cannot be changed during the run session. This feature will be implemented in the next future.
0206
0207 ----------------------------------------------------------------------------------------------------
0208 ----------------------------------> Creating a Custom Phantom <------------------------------------
0209 ----------------------------------------------------------------------------------------------------
0210
0211 If the user wishes to construct a customised section of the phantom (i.e. a single slice, the legs, etc),
0212 he/she has to create a specific macro or edit the ones provided. The recommended method for a custom male
0213 phantom is outlined as follows.
0214
0215 The user should edit the macro 'male.in' and the data file
0216 'MaleData.dat'. Firstly, in 'FemaleData.dat', there are 2 simple ways in which the user can
0217 select a custom range of phantom slices to simulate:
0218
0219 1. The very first entry of each Data.dat indicates how many slices to simulate.
0220 Changing this number will determine the number of slices to construct.
0221
0222 2. Further down in the Data.dat files (beginning at line 61) is the name of the first slice to simulate, followed
0223 by successive slices. Changing the slice file orders here will allow various subsections of the human
0224 phantom to be simulated. As an indication the following phantom subsections have been identified for the
0225 male phantom below.
0226
0227 --> AM_Slice1.g4dat to AM_Slice20.g4dat: Feet to ankles
0228
0229 --> AM_Slice21.g4dat to AM_Slice121.g4dat: Ankles to hips
0230
0231 --> AM_Slice169.g4dat: Single chest slice with good visualisation
0232 of lungs, ribs, heart.
0233
0234 --> AM_Slice182.g4dat to AM_Slice222.g4dat: Neck and Head
0235
0236 NOTE: o Always order phantom slices beginning with the lowest number and increasing
0237 in slice number going down the .dat files.
0238 o Always use consecutive/adjacent slices when simulating multiple slices.
0239 o The default number of slices for both male and female phantoms is set to 10
0240 and starts at the feet of each phantom.
0241
0242 Once the user customises the MaleData.dat/FemaleData.dat (for example starting from the full phantoms macros),
0243 he/she has also to fix appropriately the scoring mesh in male.in/female.in.
0244
0245 ----------------------------------------------------------------------------------------------------
0246 ------------------------------> Scoring Mesh and the User Score Writer <----------------------------
0247 ----------------------------------------------------------------------------------------------------
0248
0249 The macro primary.mac defines the radiation beam type, energy, direction and geometry. The UI commands of the
0250 General Particle Source should be used to change the radiation field. The macros male.in and female.in contain
0251 the /run/beamOn command and can call upon the radiation beam definition through the UI command
0252 '/control/execute primary.mac'.
0253
0254 Within male.in and female.in, a scoring mesh is defined which records the dose deposition within each individual
0255 phantom voxel. The size of the scoring mesh is defined in line 54 of the male.in/female.in files, and must be defined
0256 to match the constructed phantom dimensions (whole or partial) defined in the according '/ICRPdata/*Data.dat' file.
0257
0258 The mesh dimensions are defined as half-dimensions in x,y,z - meaning a defined scoring mesh x-dimension of 100mm will construct
0259 a scoring mesh spanning from -100mm to +100mm in the geometrical world in which the phantom lies. Furthermore, for the completed
0260 male phantom which has dimensions along x,y,z of 542.798 x 271.399 x 1776 mm, the scoring mesh half-dimensions should be defined
0261 as 271.399 x 135.6995 x 888. mm. The number of bins or divisions to segment the mesh into is then defined in line 51. These
0262 should match the number of phantom voxels in x,y,z which are defined in the MaleData.dat and FemaleData.dat files in the '/ICRPdata'
0263 directory.
0264
0265 If the user edits the MaleData.dat or FemaleData.dat files to change the number of z-slices simulated in a run, they must also edit
0266 the scoring mesh dimensions and number of bins to ensure it correctly scores their defined phantom. To do so, the user will typically
0267 only have to edit lines 54 and 55 of the male.in or female.in macro files.
0268
0269 After completion of a simulation run, the phantom mesh records the deposited dose in each phantom voxel and outputs the data to a text file named
0270 "PhantomMesh_Dose.txt". This text file lists the x,y,z positional number of the voxel in the phantom and the dose recorded within that voxel (in Gy).
0271
0272 The output PhantomMesh_Dose.txt file is created by the User Score Writer class defined in the source code ICRP110UserScoreWriter.cc. In the same class the dose
0273 in the voxels is analysed and associated to organs.
0274
0275 A final output file "ICRP.out" is then created which contains the total dose delivered to each organ.
0276
0277 ----------------------------------------------------------------------------------------------------
0278 ----------------------------------------> Further Info <--------------------------------------------
0279 ----------------------------------------------------------------------------------------------------
0280
0281 -------> ColourMap.dat <--------
0282
0283 This file located in the build directory assigns G4colours to the 53 phantom materials.
0284 The user may edit these as they wish for visualistion purposes.
0285
0286 ----------> Physics <-----------
0287
0288 The QGSP_BIC_HP Physics List is adopted. The user may want to change the
0289 cut of production of secondary particles.
0290
0291 -----> Primary particles <------
0292
0293 The G4 General Particle Source (gps) is used to generate primary radiation field.
0294 Macro primary.mac contains the definition of the primary radiation field.
