How to use GATE 9


This time I will introduce the contents of the sample code.

There are several sample codes available in GATE.

Choose the sample code that most closely resembles what you want to do. The general procedure is to edit it.

If you want to know how to implement the available methods (introduced in the manual) in your code, the best way is to read the sample code.

If you read this article, you can understand the contents of the sample code (doseByRegions)!

GATEの使い方 9
How to use the GATE


This sample code is in the dosimetry directory.


The configuration is as follows.

The purpose of this sample code is to get the “Dose” for each area within input image.

   the contents of a file

Now let’s look at the image used for input. MetaImage consists of two files, header file (.mhd) and raw data (.raw). When reading, specify .mhd that contains the necessary information.

cd /home/gate/GateContrib/dosimetry/doseByRegions
vv data/AF_UINT16_299_137_348.mhd

P.S. If you have vv installed, use vv. If not, install it or open it using another software (Fiji).
The X direction of the image is 299, the Y direction is 137 and the number of slices is 348.

左下のウィンドウを見ると、どうやらピクセルサイズは1.775 × 1.775 × 4.84 mmのようです。
As you can see in the lower left window above image, the pixel size seems to be 1.775 x 1.775 x 4.84 mm.

Each area has an integer value (0 to 141).
For example, the liver value is “95”.

data/AF_LabelsToMaterials.txt です。
3列で構成され、「画素値(以上) 画素値(未満) 物質名」 です。
It is “data / AF_LabelsToMaterials.txt” that associates the number assigned to the region with the name of the organ.
It consists of 3 columns and is “Pixel value (greater than or equal to) Pixel value (less than) substance name”.

それは data/AF_GateMaterials.db に記載されています。
Assign substances to organs.
It is listed in data/AF_GateMaterials.db.

This sample code distributes the radiation source to the liver. Calculate the absorbed dose of radiation emitted from the liver for each region.
The following two lines are written in the file (ActivityRange95.dat) used to specify the source distribution.

The first 1 means the number of lines below that.
The radiation source is distributed in the area where the pixel value is 95 or more and less than 95 (inconsistent, but in this case only the pixel value 95). The ratio is 1.0 (100%).

   main code

このコードはmac, data, outputディレクトリの一つ上の階層で実行することを想定して書かれています。
Let’s read the contents of the main code!
This code is written to run one level above the mac, data, and output directories.

See here for the original code.

Let’s look at the main code in order from the beginning.


/gate/geometry/setMaterialDatabase           data/AF_GateMaterials.db

# world
/gate/world/setMaterial           Air_outside_body
/gate/world/geometry/setXLength          1000 mm
/gate/world/geometry/setYLength          1000 mm
/gate/world/geometry/setZLength          2000 mm

# Voxel phantom
/gate/world/daughters/name          patient
/gate/world/daughters/insert         ImageNestedParametrisedVolume
/gate/patient/geometry/setHUToMaterialFile     data/AF_LabelsToMaterials.txt
/gate/patient/geometry/setImage       data/AF_UINT16_299_137_348.mhd

First, load the database that contains information on the substances used.
Previously, I used a template like “../../misc/GateMaterials.db”, but this sample code specifies a file stored in the data directory.

The size of World is 1000 × 1000 × 2000mm. World is made up of air.

Next is “How to make a voxel phantom” which has not been explained on this site yet.
There are three ways to create a voxel phantom.

The above three methods can be used, but it is OK if you use ImageNestedParametrisedVolume.

The name of volume can be anything. It is named “patient” in the sample code.

The “setHUToMaterialFile” command tells the GATE the location of AF_LabelsToMaterials.txt that describes the relationship between pixel values ​​and area (organ) names.

“SetImage” describes the location of the image to use. Specify the .mhd file.

It’s easy. Let’s move on.


/gate/physics/addPhysicsList          emlivermore

/gate/physics/Gamma/SetCutInRegion         world 10.0 mm
/gate/physics/Electron/SetCutInRegion         world 10.0 mm
/gate/physics/Positron/SetCutInRegion         world 10.0 mm

/gate/physics/Gamma/SetCutInRegion         patient 0.1 mm
/gate/physics/Electron/SetCutInRegion         patient 0.1 mm
/gate/physics/Positron/SetCutInRegion         patient 0.1 mm

physicsリスト(physicsの詰め合わせ)はemlivemoreを使用しています。これは比較的、低エネルギーのシミュレーションをする場合に使います。低エネルギー用としては、その他にもemstandard_opt3(または opt4)などがあります。
The physics list (pack of physics packs) uses emlivemore. This is used for relatively low energy simulations. Others such as emstandard_opt3 (or opt4) are also used for low energy radiation simulation.
P.S. Although the accuracy will be higher, the calculation time will be longer, so it is necessary to balance with the time.

If you follow the behavior of particles (photons) with too low energy, the calculation time will be long. Use Cut to avoid that. Cut can specify different values ​​for each area. In the above case, secondary particles with a range of 10 mm or less in the world and 0.1 mm or less in the patient will not be emitted.


/gate/actor/addActor         DoseActor  dose3D
/gate/actor/dose3D/attachTo        patient
/gate/actor/dose3D/stepHitType         random
/gate/actor/dose3D/setResolution          299 137 348
/gate/actor/dose3D/enableDose        true
/gate/actor/dose3D/save        output/output.mhd
/gate/actor/dose3D/inputDoseByRegions                             data/AF_UINT16_299_137_348.mhd
/gate/actor/dose3D/outputDoseByRegions                            output/DoseByRegions.txt
/gate/actor/dose3D/addRegion        1000: 89, 90, 91
/gate/actor/dose3D/addRegion        1001: 92, 93, 94 

This section is about data collection.
I wrote an article about Output before, but this time it’s a different way. This will be the method called Actor. Unlike ROOT, it does not collect data in multiple dimensions, so it cannot be processed later, but it is convenient if the information and the format (size, matrix, etc.) you want to obtain are predetermined.

I will write about Actor in an other article, so I will not describe it in detail here.

This sample code uses an Actor called DoseActor. Outputs the distribution of absorbed dose as a three-dimensional image.

The name of the actor is “dose3D”, but this can be changed arbitrarily. Since we are attaching to “patient” (attachTo), I get information from Hits in “patient”.

Although “random” is specified for “stepHitType”, there are other things such as “pre” and “post”. step consists of pre-step-point and post-step-point. The manual recommends using “random”.

Next is “setResolution”. Get Dose information as a 3D image. It is necessary to decide the number of divisions of the 3D image. This time, it is 299x137x348 with the same number of divisions as the image used for input. There is a way to specify the voxel size, but I think it’s easier to use setResolution.

In “enableDose”, other information can be output by the following description.

/gate/actor/dose3D/enableEdep true
/gate/actor/dose3D/enableUncertaintyEdep true
/gate/actor/dose3D/enableSquaredEdep true
/gate/actor/dose3D/enableDose true
/gate/actor/dose3D/enableUncertaintyDose true
/gate/actor/dose3D/enableSquaredDose true
/gate/actor/dose3D/enableNumberOfHits true

The result is saved in the “output” directory as “output.mhd”. The image format is MetaImage format.

The input image is a numerical phantom simulating the human body. If you want to know the absorbed dose of a particular organ, you need to tell Gate how to separate the collected data. In this case, you can use the input image as is.Therefore, for inputDoseByRegions, specify AF_UINT16_299_137_348.mhd.

Then, the result of each region is written and output to a file called DoseByRegions.txt. If you look at the contents of DoseByRegions.txt after the calculation, you can confirm that the contents are as follows.

Use addRegion when you want to combine multiple areas (pixel values) in the image and treat them as one area (to obtain the absorbed dose). In the example above, the pixel value 89,90,91 are region: 1000, 92,93,94 are region: 1001.

run initialize

Then initialize it.
The same result can be obtained every time when the seed of random numbers is set, so it is useful if you want to consider the same conditions.

/gate/random/setEngineSeed                                        1337


Next is the section on radiation sources.
Must be written after initialize.

# Source from ICRP voxel model
/gate/source/addSource     ActivityImage voxel
/gate/source/ActivityImage/reader/insert      image
/gate/source/ActivityImage/imageReader/translator/insert     range
/gate/source/ActivityImage/imageReader/rangeTranslator/readTable  data/ActivityRange95.dat
/gate/source/ActivityImage/imageReader/readFile        data/AF_UINT16_299_137_348.mhd
/gate/source/ActivityImage/setPosition        -265.3625 -121.5875 -842.16 mm

/gate/source/ActivityImage/gps/particle        gamma
/gate/source/ActivityImage/gps/energytype       Mono
/gate/source/ActivityImage/gps/monoenergy       1 MeV
/gate/source/ActivityImage/gps/angtype        iso

画像の画素値をもとに線源を配置しています(Voxelized source)。
The source is arranged based on the pixel value of the image (Voxelized source).
As mentioned above, the relationship between the pixel value and the radiation source distribution ratio is described in ActivityRange95.dat. There are many commands to write, but it’s OK if you copy and paste this sample.

stack画像の中心座標からx方向に-265.3625 mm、y方向に-121,5875 mm、z方向に-842.16 mm移動させた点が開始位置です。
One thing to keep in mind is that the source position must specify the starting point in the x, y, z directions.
The starting position is the point moved by -265.3625 mm in the x direction, -121,5875 mm in the y direction, and -842.16 mm in the z direction from the center coordinates of the stack image.

The image matrix is 299 x 137 x 348, and the pixel size is 1.775 x 1.775 x 4.84 mm, so the image size is 530.725 x 243.175 x 1684.32 mm. The half values are 265.3625, 121.5875, and 842.16 mm, respectively.

The types of particles are gamma rays, and the energy is a mono spectrum (1 MeV) and is emitted in the 4π direction.

Number of primaries

Finally, specify the number of particles to generate.

/gate/application/setTotalNumberOfPrimaries         1e5

So far, it was a method to specify the imaging time (as below), but you can specify the number of particles to generate using setTotalNumberOfPrimaries. The calculation is executed with the “start” command.

The execution start command (startDAQ) introduced so far is as follows.

#SPECT PET example
/gate/application/setTimeSlice      1  s
/gate/application/setTimeStart      0.    s
/gate/application/setTimeStop      2.  s


The figure below shows the result of calculation with 1e5 (100000) times in this sample code.

Since 1 MeV gamma ray is emitted from the liver, it can be seen that the absorbed dose in the liver is the largest.


This human body phantom can be used for various purposes.