Main Project Page | Alphabetical List | Class List | File List | Class Members | File Members

GEANT4 DICOM Documentation

The DICOM application has been developed by the following Geant4 user collaboration:

Vincent Hubert-Tremblay¹²,
Louis Archambault¹²,
Christina Jarlskog³,
Luc Beaulieu¹².

¹Centre Hospitalier Universitaire de Quebec (CHUQ),
Hotel-Dieu de Quebec, departement de Radio-oncologie
11 cote du palais. Quebec, QC, Canada, G1R 2J6
tel (418) 525-4444 #6720
fax (418) 691 5268
web :

²Université Laval,
Ste-Foy (QC) Canada

³Experimental High-Energy Physics Division,
Physics Department, Lund University.
web :

This example illustrates a preliminary version of a Geant4 interface to the DICOM image format. The example consists in creating an image from CT data in DICOM files. The example is available from the Geant4 source in the example/extended/medical folder.


1. Introduction

2. Installation

3. Run the example

4. Some detail

5. Structure of "Data.dat"

6. Structure of "CT2Density.dat"

7. Strucutre of ".g4" file

8. Exporting the DICOM module


10. Contacts

1) Introduction

G4 routine to build a geometry based on CT data from DICOM images for medical purpose.  Densities are extracted from CT (Hounsfield) numbers and associated with materials using ICRU report 46.

The .dcm files currently available with the example are of a CT calibration phantom. You can find the original phantom reproduced in the image PhantomCT.jpg.
WARNING : this version of the code is slow :  1 minute for 100 photons with the parameterisation geometry. Use a normal (G4Box) geometry to get faster simulation (beware of memory usage!) instead of the parameterisation.

Steps in the progam:
  1. Read Data.dat to get list of DICOM images   [DicomHandler]
  2. Read CT2Density.txt file to make the Hounsfield <-> density conversion   [DicomHandler]
  3. Read each DICOM images   [DicomHandler]
  4. Create geometry with DICOM images   [DicomGeometry]

2) Installation:

 -Example enviroment with the compiler 3.2                             
 -Standard Geant4 example GNUmakefile is provided           

Setup tested on Linux with:

The following environment variables need to be set:           

G4LEDATA: points to low energy data base - G4EMLOW2.2     
Visualisation package: OpenGL

3) Run the example:

- Batch mode:
  - dicom vis.mac :the geometry is visualised with OPENGL
  - dicom run.mac :no geometry visualisation

- Interactive mode:
   the file default.mac is read in order to visualise the phantom.

Make sure you have downloaded the latest DicomHandler patch of the software at the end of this page. It is always better to erase the *.g4 files before running the program with a new set of images.

4) Some details :

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 and is included in the file CT2Density.  The material associations used in this program are represented in the table below.

           #     Density Range                   Materials  
           #       g/cm3                            -        
           #  [ 0.100 , 0.351 ]                 Lungs (inhale)
           #  [ 0.351 , 0.800 ]                 Lungs (exhale)
           #  [ 0.919 , 0.979 ]                 Adipose       
           #  ] 0.979 , 1.004 ]                 Breast        
           #  ] 1.004 , 1.043 ]                 Phantom       
           #  ] 1.043 , 1.109 ]                 Liver         
           #  ] 1.109 , 1.113 ]                 Muscle        
           #  ] 1.113 , 1.400 ]                 Trabecular Bone
           #  [ 1.496 , 1.654 ]                 Dense Bone    
The International Commission on Radiation Units and measurements (ICRU) report 46 was used to build the materials (lung, liver, breast, bones, ...).  Remember that the density range is just a very rough approximation and is applicable to this phantom only.

5) Structure of "Data.dat"

The file named Data.dat contains the list of DICOM images to be included in the geometry.  The structure looks like this :

1st line : Compression Lvl
2nd line : Number of DICOM images
3rd and subsequent lines : Image's names (without the .dcm extension and one per line)

Example of Data.dat :


This example means that there is only one image (14196004.dcm) which is in a folder called PhantomCT and that we need to use a lvl 2 compression when creating the .g4.  The compression lvl will transform this 512x512 pixels image into a 256x256 pixels image and extract density from it.

The compression lvl simply tells the program to get the mean value from a square of {compression lvl} by {compression lvl} pixels (in this example: square of 2x2) starting from the top left corner. You must use multiple of 512 to get a nice results. If you use  something else and your image is 512x512, some of the pixels are going to be choped off at the bottom of the image!

6) Structure of "CT2Density.dat"

The file named CT2Density.dat contains the table of the corresponding density in function of the pixel value (which is supposed to be the Hounsfield number).  A very simple linear interpolation is used to get other values.  The structure looks like this :

1st line : Total number of line in table
2nd and other lines :
    - 1st column : Pixel value
    - 2nd column : Density value in g/cm3

Example of CT2Density :

The calibration of the program (conversion of HU to density) depends on the type of the scanner and on the kV used in the examination. The calibration curve can be experimentally obtained using a CT reference phantom. The above plot shows examples of curves obtained in this way for two different models of CT scanners operating at different potentials.

Figure 1 - Example of CT calibration curves (courtesy of Christina Jarlskog).


7) Structure of the ".g4" files

When processing an image, a .g4 file is created by the class DicomHandler. The geometry is built by reading this file and not the .dcm image. The structure looks like this :

1st line :
    -1st column : Number of rows (#pixel)
    -2nd column : Number of columns (#pixel)
2nd line :
    -1st column : Pixel spacing in X (mm)
    -2nd column : Pixel spacing in Y  (mm)
3rd line : Slice thickness (mm)
4rd line : Slice locations (mm)
rest of the lines : Density value for each pixel value (g/cm3)
(each line correspond to a pixel row starting from the first to the last, the same thing is true for the columns)

Example :
4        4
0.987   0.987
0.000000 0.000000 0.000000
0.000000 1.073585
0.000000 1.073585
0.000000 0.000000 0.000000 0.000000

The very first value of density correspond to the pixel in the upper left corner of the image. The second one in the same row is the next at its right and so on until all of the 4 columns are done.

8) Exporting the DICOM module

The DICOM module is easly exportable. To read images in your own program, you need the class DicomHandler (files :, DicomHandler.hh) and the configuration files Data.dat, CT2Density.dat. This class must be called before the Geant4 initiallisation in your main function. A public function named checkFileFormat() has been created to make things a lot easier to use.

Example of main.c :

#include ""

int main(int argc,char** argv)
    // Treatment of DICOM images before creating the G4runManager

    DicomHandler *dcmHandler = new DicomHandler;
    delete dcmHandler;

    //                GEANT4 INITIALIZATION

Those three line  should be able to load all the images described in the file Data.dat and create *.g4 file containing the size and density informations needed to construct the geometry.
To create the DICOM geometry, this example use a parameterisation class called PatientParameterisation. It simply puts one G4Box for each density at the good pixel position. The material are set using the table shown above (4. Some details). The parameterisation function is called from If you wish to use this basic geometry construction you will need to add the files,, and Be aware that this geometry is very heavy (it creates a LOT! of parameterise G4Box), so big simulation are not yet possible. The class DicomGeometry is simply the Geant4 class UserDetectorConstructor.

Short review for the export :

- To read .dcm image you need :
    - Data.dat
    - CT2Density.dat

- To create geometry with .g4 you need :
    -  (this is supposed to be the UserDetectorConstructor)

9) Downloads

To get a copy of the example, download the latest Geant4 version. It should be in the examples/extended/medical/DICOM directory. The version is however more then 1 year old. Several correction were added to the DicomHandler class. Use these files to update your example :

This is a small bash script to help you configure Data.dat :
(check the comments)

10) Contacts

If you have any questions or wish to notify of updates and/or modifications please contact one of us :

¹Centre Hospitalier Universitaire de Quebec (CHUQ),
Hotel-Dieu de Quebec, departement de Radio-oncologie
11 cote du palais. Quebec, QC, Canada, G1R 2J6
tel (418) 525-4444 #6720
fax (418) 691 5268
web :

²Université Laval,
Ste-Foy (QC) Canada

³Experimental High-Energy Physics Division,
Physics Department, Lund University.