Version:
[ ReleaseNotes ] [ 1.0 ] [ 1.1 ] [ 2.0 ] [ 3.0 ] [ 3.1 ] [ 3.2 ] [ 4.0 ] [ 4.0.p1 ] [ 4.0.p2 ] [ 4.1 ] [ 4.1.p1 ] [ 5.0 ] [ 5.0.p1 ] [ 5.1 ] [ 5.1.p1 ] [ 5.2 ] [ 5.2.p1 ] [ 5.2.p2 ] [ 6.0 ] [ 6.0.p1 ] [ 6.1 ] [ 6.2 ] [ 6.2.p1 ] [ 6.2.p2 ] [ 7.0 ] [ 7.0.p1 ] [ 7.1 ] [ 7.1.p1 ] [ 8.0 ] [ 8.0.p1 ] [ 8.1 ] [ 8.1.p1 ] [ 8.1.p2 ] [ 8.2 ] [ 8.2.p1 ] [ 8.3 ] [ 8.3.p1 ] [ 8.3.p2 ] [ 9.0 ] [ 9.0.p1 ] [ 9.0.p2 ] [ 9.1 ] [ 9.1.p1 ] [ 9.1.p2 ] [ 9.1.p3 ] [ 9.2 ] [ 9.2.p1 ] [ 9.2.p2 ] [ 9.2.p3 ] [ 9.2.p4 ] [ 9.3 ] [ 9.3.p1 ] [ 9.3.p2 ] [ 9.4 ] [ 9.4.p1 ] [ 9.4.p2 ] [ 9.4.p3 ] [ 9.4.p4 ] [ 9.5 ] [ 9.5.p1 ] [ 9.5.p2 ] [ 9.6 ] [ 9.6.p1 ] [ 9.6.p2 ] [ 9.6.p3 ] [ 9.6.p4 ] [ 10.0 ] [ 10.0.p1 ] [ 10.0.p2 ] [ 10.0.p3 ] [ 10.0.p4 ] [ 10.1 ] [ 10.1.p1 ] [ 10.1.p2 ] [ 10.1.p3 ] [ 10.2 ] [ 10.2.p1 ] [ 10.2.p2 ] [ 10.2.p3 ] [ 10.3 ] [ 10.3.p1 ] [ 10.3.p2 ] [ 10.3.p3 ] [ 10.4 ] [ 10.4.p1 ] [ 10.4.p2 ] [ 10.4.p3 ] [ 10.5 ] [ 10.5.p1 ] [ 10.6 ] [ 10.6.p1 ] [ 10.6.p2 ] [ 10.6.p3 ] [ 10.7 ] [ 10.7.p1 ] [ 10.7.p2 ] [ 10.7.p3 ] [ 10.7.p4 ] [ 11.0 ] [ 11.0.p1 ] [ 11.0.p2 ] [ 11.0.p3, ] [ 11.0.p4 ] [ 11.1 ] [ 11.1.1 ] [ 11.1.2 ] [ 11.1.3 ] [ 11.2 ] [ 11.2.1 ] [ 11.2.2 ] [ 11.3.0 ]
1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
2 | DicomG4 |
3 + +
4 | README |
5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
6
7 The DICOM application has been originally developed by the Geant4 users:
8 Louis Archambault,+Luc Beaulieu, ++Vincent Hubert-Tremblay.
9
10 + Centre Hospitalier Universitaire de Quebec (CHUQ),
11 Hotel-Dieu de Quebec, departement de Radio-oncologie
12 11 cote du palais. Quebec, QC, Canada, G1R 2J6
13 tel (418) 525-4444 #6720
14 fax (418) 691 5268
15 web : thomson.phy.ulaval.ca/phys_med
16
17 ++ Université Laval, Québec (QC) Canada
18
19
20 And it has been deeply reviewed by Pedro Arce in December 2007.
21 Very small changes by Stephane Chauvie in January 2008.
22 Stephane Chauvie, Oct 2009: changed Physics list; changes in DICOM read.
23 Stephane Chauvie and Andrea Armando; June 2010 adapted for reading whatever DICOM file
24 Jonathan Madsen, Nov 2013: updated DICOM to utilize multithreading now available in Geant4.10
25 Alexander Howard, Dec 2023: updated scorer to give correct voxel index for both regular and nested geometries
26
27 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
28 @@@ @@@
29 @@@ NEW DICOM READER BASED ON DCMTK @@@
30 @@@ @@@
31 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
32 A new way to read DICOM files has been implemented since release 10.3, to avoid the often problems found by users when reading DICOM files.
33 It can also read RT structures in DICOM format as well as RT plans.
34 This utility uses the DCMTK (http://dicom.offis.de/dcmtk.php.en).
35
36
37 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
38 @@@ @@@
39 @@@ NEW DICOM HEAD PROJECT @@@
40 @@@ @@@
41 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
42
43 A new DICOM Digital Head included by S. Guatelli (susanna@uow.edu.au) and V. Giacometti. Available since Geant4 10.4.
44 The Digital model is documented in: Giacometti, V., Guatelli, S., Bazalova-Carter, M., Rosenfeld, A.B., Schulte, R.W.,
45 "Development of a high resolution voxelised head phantom for medical physics applications", (2017) Physica Medica, 33, pp. 182-188.
46
47 --->1) Introduction
48
49 This example serves first to convert a DICOM file to a simple ASCII file, where the Hounsfield numbers are converted to materials and densities so that it can be used by GEANT4. It serves also to create a GEANT4 geometry based on the DICOM file information using the G4PhantomParameterisation.
50
51 You can find the phantom reproduced in the image PhantomCT.jpg.
52 In the application the phantom is placed on a table.
53
54 ---> 2a) Installation, OLD version:
55
56 - A standard Geant4 example CMakeLists.txt is provided
57 - Configure via cmake with 'cmake -DGeant4_DIR=/path_to_geant4_install/lib/Geant4-x.x.x /path/to/DICOM/source' then make
58
59 ---> 2b) Installation, NEW version (based on DCMTK):
60
61 You have to download and install DCMTK, see http://dicom.offis.de/dcmtk.php.en . At least you need version 3.6.1 or newer; the important thing is that you make sure it contains the dcmrt package.
62 Then define the enviromental variable DCMTK_BASE_DIR to point to the directory where you have installed it.
63 And to run it, you have to add to the enviromental variable LD_LIBRARY_PATH the path ${DCMTK_BASE_DIR}/lib (i.e. export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${DCMTK_BASE_DIR}/lib )
64
65 Then you have to set the enviromental variable DICOM_USE_DCMTK to 1.
66 - A standard Geant4 example GNUmakefile is provided, but have to uncomment the line
67 #DICOM_USE_DCMTK := true
68 - Compile it with 'make'/'gmake'
69
70 - A standard Geant4 example CMakeLists.txt is provided
71 - Configure via cmake with
72 'cmake -DGeant4_DIR=/path_to_geant4_install/lib/Geant4-x.x.x \
73 -DDCMTK_DIR=/path_to_dcmtk_install /path/to/DICOM/source'
74 then make
75
76 ---> 2c) CMake installation and inheriting from DICOM:
77
78 - Set the CMAKE_INSTALL_PREFIX (typically use the same install prefix as the Geant4 distribution)
79 - Install the project
80 - Installation will install libraries + DICOMConfig.cmake + other config files
81 - if DCMTK is enabled, will also install dicomReader library + icomReaderConfig.cmake and it's other config files
82 - In the new Geant4 application, add "find_package(DICOM REQUIRED)" to CMakeLists.txt
83 - (optionally) add "set(DICOM_DIR ${Geant4_DIR} CACHE PATH "Path to DICOM installation config files") to CMakeLists.txt
84 - add "include_directories(${DICOM_INCLUDE_DIRS}) and link target to ${DICOM_LIBRARIES}
85 - if DCMTK is enabled, DICOMConfig.cmake will include the DCMTK and dicomReader installations, i.e. there is not need for "find_package(dicomReader)" or "find_package(DCMTK)"
86
87
88 ---> 3) Run the example:
89
90 - To run, the environment variable G4LEDATA needs to be set, pointing to the low energy data base, and the G4LEVELGAMMADATA pointing to the PhotonEvaporation data base
91
92 - batch mode:
93 - DICOM run.mac
94
95 - interactive mode:
96 - DICOM
97 the file vis.mac is read in order to visualise the phantom with OpenGL, DAWN or VRML
98
99 - Environment variables:
100 - DICOM_CHANGE_MATERIAL_DENSITY
101 - set to the minimum density difference before making a separate material
102 - e.g. if DenseBone is from > 1.496 to <= 1.654 and DICOM_CHANGE_MATERIAL_DENSITY=0.079
103 then DenseBone would be separated into DenseBone > 1.496 to <= 1.575 and DenseBone > 1.575 to <= 1.654
104 - DICOM_PARTIAL_PARAM
105 - set to 1 to build the partial build instead of regular or nested construction (see section 9)
106 - DICOM_NESTED_PARAM
107 - set to 1 to build the nested construction (see section 9; overridden by DICOM_PARTIAL_PARAM)
108 - DICOM_NTHREADS
109 - To set the number of threads (when G4MULTITHREADED is defined via GEANT4_BUILD_MULTITHREADED=ON during Geant4 source build)
110 - Needs to be set to the number of desired threads, e.g. DICOM_NTHREADS=8 (default is 4 threads)
111 - DICOM_USE_HEAD
112 - set to 1 (export DICOM_USE_HEAD=1) to use the digital head phantom documented in Giacometti, V., Guatelli, S., Bazalova-Carter, M., Rosenfeld, A.B., Schulte, R.W.,
113 "Development of a high resolution voxelised head phantom for medical physics applications", (2017) Physica Medica, 33, pp. 182-188.
114 To use this option, the DICOM library needs to be downloaded. This is distributed with the other Geant4 data files on the Geant4 Download site.
115 For convenience of use, it is suggested to have the DICOM library directory in the DICOM Geant4 extended example or in the directory containing the DICOM executable.
116 When using this option,
117 1) export DICOM_USE_HEAD=1
118 2) export DICOM_PATH=path/to/DICOM1.1/DICOM_HEAD - to use the full DICOM HEAD project
119 or
120 export DICOM_PATH=path/to/DICOM1.1/DICOM_HEAD_TEST - to use 4 DICOM files of the DICOM HEAD project. This option is useful for testing purposes.
121 3) THE DICOM_HEAD uses the OLD version of the Metadata files (see point 4a)
122 Note 1: The Conversion of Hounsfield numbers to materials (point 5) is not used. The material is associated to the voxel in the Detector Construction
123 without using the calibration curve.This happens because the DICOM project has already been segmented and cleaned from artefacts (see publication).
124
125 ---> 4) Metadata file:
126
127 The old version of "Data.dat" is found in "Data.dat.old", when the project is configured with DICOM_USE_DCMTK=OFF,
128 "Data.dat.old" is copied into the binary directory at "Data.dat".
129 - i.e. cp ${PROJECT_SOURCE_DIR}/Data.dat.old ${PROJECT_BINARY_DIR}/Data.dat
130
131 The new version of "Data.dat" is found in "Data.dat.new", when the project is configured with DICOM_USE_DCMTK=ON,
132 "Data.dat.new" is copied into the binary directory as "Data.dat".
133 - i.e. cp ${PROJECT_SOURCE_DIR}/Data.dat.new ${PROJECT_BINARY_DIR}/Data.dat
134
135 ---> 4a) Metadata file, OLD version:
136
137 The file Data.dat has the following information
138 - A line with the compression value (used only to create the .g4dcm and .g4dcmb, not to read it)
139 - A line with the number of files
140 - A line for each file name (to these names it will be added the suffix .dcm to read the DICOM files in their original format, and the suffix .g4dcm to read the text files that contain the DICOM information where the Hounsfield numbers have been converted to material and densities)
141
142 In case you want to convert DICOM files to text files, it must have the following lines:
143 - The number of materials you want to use
144 - A line for each material describing its name and the upper bound of the density interval. The materials should be described in increasing order of density. The voxels with a density between 0. and the first upper bound will be assigned to the first material, those with a density between the first upper bound and the second upper bound will be assigned to the second material, etc.
145
146 ---> 4b) Metadata file, NEW version (based on DCMTK):
147
148 As for the previous version, a Data.dat file has to be defined to manage the conversion options. The format of this file is though quite different from the previous version. The format of this file is based on tags (similary to the ASCII geometry files).
149 The following tags should be used:
150
151 :COMPRESSION level
152
153 Where "level" is the number of voxels that will be merged into one in the X and Y dimen-
154 sions. The Hounsfield numbers of the voxels merged are averaged to give the
155 resulting value for the new voxel.
156 Example:
157 :COMPRESSION 4 // 4 X 4 voxels will be merged, so that the number of voxels in X and Y dimensions will be reduced by a factor 4
158
159 :FILE file_name
160 These are the list of files (one line per file) in DICOM format that will be treated.
161 They can be of modality CT, RTSTRUCT or RTPLAN (the code will automatically
162 detect its modality and treat it correspondingly).
163 Example:
164 :FILE 1.dcm
165 :FILE 2.dcm
166 :FILE 3.dcm
167
168 :CT2D Hounsfield_number density
169 These sets of value pairs build the calibration curve (linearly interpolating between them). In other words, each Hounsfield number is given a material density using a function that is built interpolating between this list of value pairs.
170 Example:
171 :CT2D -5000 0.
172 :CT2D -1000 0.01
173 :CT2D -400 0.602
174 :CT2D 300 1.145
175 :CT2D 2000 1.856
176
177 :MATE material_name upper_bound_of_material_Hounsfield_number_interval
178 This serves for the Hounsfield number to material name conversion. The voxels with a Hounsfield number between 0. and the first upper bound will be assigned to the first material, those with a Hounsfiled number between the first upper bound and the second upper bound will be assigned to the second material, etc.
179 Example:
180 :MATE G4_AIR -800
181 :MATE G4_LUNG_ICRP -145
182 :MATE G4_ADIPOSE_TISSUE_ICRP -60
183 :MATE G4_WATER 0
184
185 Alternatively to the use of :MATE, you can use the :MATE_DENS
186 :MATE_DENS material_name upper_bound_of_material_density_interval
187 This serves for the material density to material name conversion. The voxels with a density between 0. and the first upper bound will be assigned to the first material, those with a density between the first upper bound and the second upper bound will be assigned to the second material, etc.
188 Example:
189 :MATE_DENS G4_AIR 0.207
190 :MATE_DENS G4_LUNG_ICRP 0.919
191 :MATE_DENS G4_ADIPOSE_TISSUE_ICRP 0.979
192 :MATE_DENS G4_WATER 1.01
193
194 We recommend the use of :MATE instead of :MATE_DENS as this is the way is used more often in the literature.
195
196 :FILE_OUT file_name
197 Name of output file containing the DICOM information in ASCII format
198
199
200 --->5) Conversion of Hounsfield numbers to materials:
201
202 After reading the name of files from Data.dat, if a file .dcm is found, then it looks for the corresponding .g4dcm file and if not found creates it.
203 Each file corresponds to a Z slice. The Z slices will be merged at runtime to form a unique patient volume; therefore the different slices have to be contiguous in Z.
204
205 The DICOM images pixel values represent CT (Hounsfield) numbers and they should be converted, first, to a given density and then to a material type. The relation between CT number and density is more or less linear.
206 The file CT2Density.dat contains the calibration curve to convert CT (Hounsfield) number to physical density
207 The assignment of material densities to materials is done following the information from the file Data.dat (see below). In this case we have used:
208
209 #####################################################
210 # Density Range Material #
211 #---------------------------------------------------#
212 # mg/cm3 - #
213 #---------------------------------------------------#
214 # [ 0. , 0.207 ) Air #
215 # [ 0.207 , 0.481 ) Lungs (inhale) #
216 # [ 0.481 , 0.919 ) Lungs (exhale) #
217 # [ 0.919 , 0.979 ) Adipose #
218 # [ 0.979 , 1.004 ) Breast #
219 # [ 1.004 , 1.043 ) Phantom #
220 # [ 1.043 , 1.109 ) Liver #
221 # [ 1.109 , 1.113 ) Muscle #
222 # [ 1.113 , 1.496 ) Trabecular Bone#
223 # [ 1.496 , 1.654 ] Dense Bone #
224 #####################################################
225
226 Data taken from the International Commission on Radiation Units and measurements (ICRU) report 46 was used to build the materials (lung, liver, breast, bones, ...).
227
228 When using the Digital Head Phantom, the CT2Density.dat is not used. The conversion is performed directly in the Dicom Handler.cc
229
230 --->6) Splitting materials in density intervals:
231
232 In the class DicomDetectorConstruction, it is defined a density interval
233
234 G4double densityDiff = 0.1;
235
236 This means that the voxels of each material will be grouped in density intervals of 0.1 g/cm3 and a new material will be created for each group of voxels.
237
238 --->7) Voxel colouring:
239
240 The file Colormap.dat defines the colour that will be assigned to the voxels of each material.
241
242 --->8) DICOM file formats:
243
244 The DICOM files are converted to a simple text format. You may create your own file with the following format (see e.g. 14196616.g4dcm):
245
246 - A line with the number of materials
247 - A line for each material with its index and name (the same name of materials that you construct as G4Material's)
248 - A line with the number of voxels in X, Y and Z
249 - A line with the minimum and maximum extension in X (mm)
250 - A line with the minimum and maximum extension in Y (mm)
251 - A line with the minimum and maximum extension in Z (mm)
252 - A number of lines containing the nVoxelX*nVoxelY*nVoxelZ material indices (one per voxel)
253 - A number of lines containing the nVoxelX*nVoxelY*nVoxelZ material densities (one per voxel)
254
255 As commented before the DICOM files (.dcm) are assumed to describe one Z slice per file, and therefore the GEANT4 text files (.g4dcm) created from them have also one unique Z slice per file. Nevertheless if you create your own .g4dcm file you may include as many Z slices as desired. In any case you have to respect the rule that the Z slices must be contiguous.
256
257 The same information is also used to fill a file in binary format, that contains the same information as the text format. Its name ends in .g4dcmb, instead of .g4dcm .
258
259 --->9) Choosing different parameterisation/navigation options:
260
261 There are four possible ways in GEANT4 to treat the navigation in regular voxelised volumes:
262
263 - The 3D optimisation with G4SmartVoxel: a 3D grid is built, so that the location of voxels is fast, but it requires a lot of memory
264 - Using G4NestedParameterisation. The search is done hierarchically in X, Y and Z. It is fast and does not require big memory
265 - Using G4PhantomParameterisation/G4RegularNavigation: an special algorithm to navigate in regular voxelised geometries (see GEANT4 doc). This is the fastest way without any extra memory requirement (and it is the default in this example). It includes an option (default) to skip frontiers between voxels when they have the same material. When using this option at each step the energy is all deposited in the last voxel; for properly distribution of the dose (=energy/volume) the G4PSDoseDeposit scorer can be used for regular (see (10) below) and G4PSDoseDeposit3D for nested parameterisation (see (11) below).
266
267 Obsolete option:
268 - Use 1D optimisation in replica. It will be very slow because each time a track exits a voxel it has to loop to all other voxels in a 2D slide in order to locate which one it will enter.
269
270 You can select amongst the four options in the following way:
271
272 - By default the example will run with G4RegularNavigation
273
274 - To use the first option at RegularDicomDetectorConstruction.cc you must set
275
276 patient_phys->SetRegularStructureId(0);
277
278 - To use the second option (Nested Parameterisation) you must set the enviromental variable DICOM_NESTED_PARAM to 1
279
280 - To use the final, obsolete 1D-option, apart from the change above at RegularDicomDetectorConstruction.cc you need to replace (i.e. use kUndefined)
281
282 G4PVParameterised * patient_phys = new G4PVParameterised("Patient",voxel_logic,container_logic,
283 kUndefined, nVoxelX*nVoxelY*nVoxelZ, param);
284 by
285 G4PVParameterised * patient_phys = new G4PVParameterised("Patient",voxel_logic,container_logic,
286 kXAxis, nVoxelX*nVoxelY*nVoxelZ, param);
287
288 Note also you must *not* set the enviromental variable DICOM_NESTED_PARAM.
289
290
291 --->10) Calculating dose in phantom voxels for regular navigation
292
293 As mentioned above the regular navigation has the option to keip voxel frontiers when two voxels share the same material, what can make the CPU time several times smaller. But this option makes that all energy deposited is computed in the last voxel, instead of distributing it along the voxels traversed. To properly calculate the dose in each voxel the G4PSDoseDeposit scorer can be used.
294
295 It takes into account the fact that, when the particle travels through the voxels it looses energy and therefore the energy lost per length (dEdx) is bigger and also the effect of the multiple scattering is bigger.
296 The algorithm to make this correction is an iterative one, as the step length increase due multiple scattering (that converts the geometrical step length in what we will call the true step length) and the energy loss are correlated.
297 It works in the folloing way: first the total true step length is distributed among the voxels proportionally to their geometrical step length; with these values it is calculated one voxel after another the value of dEdx and then the value of the kinetic energy at the entrance of each voxel; with these values it is calculated the geometrical to true step corrections due to multiple scattering for each voxel; finally these new values are used to recalculate the energy lost in each voxel. It has been demonstrated for dose in a water phantom and in a real phantom that the two-step iteration described is enough to reproduce the dose calcualted when no skipping of voxel frontiers is done.
298
299 This scorer is implemented in this examples if the regular navigation option is
300 chosen. It is triggered at the method RegularDicomDetectorConstruction::ConstructPhantom() by the call
301
302 SetScorer(voxel_logic);
303
304 --->11) Calculating dose in phantom voxels for nested parameterisation
305
306 For the nested parameterisation the geometry comprises replicas in X and Y which are then parameterised in Z. This means that to get the correct voxel idendification the replica depth has to be taken into account. The G4PSDoseDeposit3D scorers uses a fixed algorithm to calculate the voxel ID, according to the number
307 of voxels in each axes and the associated replica depth. G4PSDoseDeposit3D("DoseDeposit", fNoVoxelsZ, fNoVoxelsY, fNoVoxelsX, 0, 2, 1) contains the number of voxels at the top level (0) and then two daughter levels down for the Y-voxels and one depth down for X.
308
309 --->12) Output
310 dicom.out is produced running the macro file run.mac. It has 2 columns: the first is the number of
311 voxel (ordered in x,y,z) and the second the dose there deposited (in Gy)
312 It is produced, as an example, with a compression value of 32
313
314
315 --->13) Partial phantom
316 It is possible to create a partial phantom, that is the intersection of a phantom with a volume. You may define the volume with the command
317
318 /dicom/intersectWithUserVolume 0. 0. 0. 45.*deg 0. 0. TUBE 0. 150. 100.
319
320 where the first three arguments are its position, its second three arguments are the rotation around the global X, Y and Z axis and the rest of the parameters are the same that you use to build a solid using the ASCII geometry format
321
322 Alternatively you can intersect the phantom with an existing Geant4 volume with the command
323
324 /dicom/intersectWithG4Volume VOLUME_NAME
325
326 The job will create an ASCII file names "phantom.g4pdcm" containing the partial phantom. To read this file all what is needed is to set the enviromental variable DICOM_PARTIAL_PARAM to 1
327
328 --->14) Visualisation
329
330 The Geant4 drivers are not meant for visualizing millions of voxel and visualising the DICOM geometries can be very computationally demanding.
331 The users may want to visualise each DICOM slice separately or use higher compression values when visualising a part of DICOM project.
332
333
334
