- How to use the movements and the placements ?
- How to generate and then analyse the GATE root file ?
- What is the world ?
- How to enable Interfile projection sets?
- What is a macro ? How to execute a macro?
- How to create a geometric element (box, cylinder, ...)?
- How to build my first cylindrical1 system ?
- What is written in the ASCII output files?
- Decays, Hits, Pulses, Singles, Coincidences, what is the meaning of these words ?
- How to generate LMF output ?
- How do i use the online plotter ?
One of the GATE specificity is to allow the movement of the objects. You must apply a on a geometric element, during the geometry construction (before initialization), to change the default position of the element (default position is the center of its mother). The allow to make an element move during the simulation itself. Placement and moves are applied on the chosen element (ex. a PET camera) and on all its daughters (ex. crystals of this PET camera).
In your when you create a geometric element, the initial position is the center of its mother (or the world). You can apply two placements:
This is an a example of a scripted creation and translation of an element.
# Sphere translation : set the XYZ position of the center of the sphere
/gate/myBalloon/placement/setTranslation 135 10 0 mm
See also this small and funny macro.
This is an a example of a scripted creation and rotation of an element.
# Box Rotation translation : set the rotation axis and angle
/gate/myBox/placement/setRotationAxis 1 0 0
/gate/myBox/placement/setRotationAngle -20 deg
/gate/myBox/placement/setRotationAxis 0 1 0
/gate/myBox/placement/setRotationAngle 20 deg
See also this small macro
GATE rebuilds the complete geometry after each time slice. Your moves will be ignored if you just have one time slice in your simulation. Moves are performed during the simulation (after the /start command), but are defined before initialization (when you create your geometry).
To enable the translation of an object you have to define the translation speed in all directions (XYZ) with one line.
/gate/myBox/rotation/setSpeed 0. 0. 10. mm/s
See this complete macro
To enable the rotation of an object you have to define the rotation axis and the speed like in this example.
/gate/myBox/rotation/setSpeed 1. deg/s
/gate/myBox/rotation/setAxis 0 1 1
See this complete macro
In GATE, orbiting is defined as a rotation around an axis described by 2 chosen points. Orbiting has an autoRotation option (enabled or not), that allows to change (or not) the object orientation during the rotation. Execute this two complete macros to see the difference :
orbiting without auto rotation
orbiting with auto rotation
The lines to insert an orbiting moves are:
/gate/myBox/orbiting/setSpeed 10. deg/s
/gate/myBox/orbiting/setPoint1 10. 30. 50. mm
/gate/myBox/orbiting/setPoint2 10. -30. -50. mm
- GENERATE THE FILE:
- LOAD THE MACRO EXAMPLE:
If you need to generate the root output file, this can be done by adding the following line in the macro :
which will provide you with a FILE_NAME.root file, containing : 4 histograms and 4 trees (GATE, COINCIDENCES, HITS and SINGLES) in which several variables are stored.
When launching ROOT, you should see:
If needed, and for a matter of file size, you could choose not to generate all trees.
In this case just add the following lines in your macro :
By turning to 1 (or 0) one of this tree flag, you will fill (or not) the given tree.
You can either plot the variables directly from the browser. See the ROOT HOMEPAGE for more details.
Below you may find a very simple example of a root macro ( analysis.C) to analyse the ROOT output file.
To launch the file in ROOT, type :
root  .x analysis.C
In this example, a root file called gate.root is read and several plots are shown as examples.
You may also use the MakeCode class. Example :
root  Coincidences->MakeCode("test.C");
Please consult the ROOT HOMEPAGE for more details.
What is the world ?
The world is the main box where your simulation is performed. Out of the world, the generated particles are not tracked.The world is typically a cube that contains a system, a source and a phantom. It must be big enough to contain all these objects, and not too much big to allows comfortable visualization. This is a perfect world...
- Output Possibilities
- Interfile specifics
- How to enable/disable ?
Several output options exist when performing SPECT oriented simulations. Most commonly the ROOT and ASCII output are chosen but one can also store the simulated data in Interfile format.
The most important characteristic of the Interfile format is detailed below:
When image data relate to multiple windows etc. (e.g. energy windows, time windows, multiple heads) the images shall be nested according to the order in which the corresponding keys are defined. Thus if multiple energy windows are used, all the image data for the first window must be given first, followed by the image data for the second window, etc. This loop structure is defined in the Interfile syntax by the use of the 'for' statement.
This rule is especially applicable for multiheaded systems. The InterFile projection set is written in Gate following the above rule causing the positioning to be realistic, so from 0, 10, 20, 30,....,360 degrees independent of headID.
For instance: /gate/output/projection/pixelSizeX 2. mm /gate/output/projection/pixelSizeY 2. mm /gate/output/projection/pixelNumberX 128 /gate/output/projection/pixelNumberY 128 /gate/output/projection/projectionPlane XY /gate/output/projection/verbose 2 /gate/output/projection/describe for storing your XY-plane projection data in an 128x128 array of 2x2mm pixels. And put /gate/output/projection/disable in your macro to disable this possibility.
- What is a macro ?
- How to execute a macro in interactive mode ?
- How to execute a macro in shell mode ?
One of the interest of GATE is that everything is scriptable. That means that you can use every GATE possibilities with some very easy-to-use scripts called macros. A macro is an ASCII file (with .mac extension) composed of Geant4 and GATE scripted commands and eventually some comments. In a macro, the comments begin by #
Once GATE and all requirements (Geant4, CLHEP, ...) are installed on your system, you normally can start a session in the compilation directory (where your makefile is placed) by:
if your system is Linux.
Then, you should see this prompt:
After that you can type the scripted command. A particular command is
PreInit> /control/execute cyl.mac
that executes all lines of this macro example: cyl.mac.
You can of course include some /control/execute lines in your macro to separate the different parts of you macro. The previous example could be:
You can run GATE macros directly from your shell prompt by:
The shell mode is faster than interactive mode, but it not allows visualization.
Interactive mode should be chosen to write your macro, and shell mode should be chosen to run a finished and validated macro.
GATE allows to build complex geometries with simple elements. The elements can be totally described (name, form, dimensions, material, visualization rendering) with less than 15 scripted commands. The typical declaration of an element is:
- name, mother name and shape
- position and dimensions
A box is the most simple shape: a parallelepiped. Read these following lines with comments to understand how to script it.
# Every element is the son of another one or at least, of the world.
# We define here his name from scripted command allowed by his mother.
# Here we define the shape: box
# By default the objects are placed at the center of their mother.
# This line can change this default position.
/gate/mybox/placement/setTranslation 58. 0 0 mm
# Here we define the XYZ dimensions of the box
/gate/mybox/geometry/setXLength 16. mm
/gate/mybox/geometry/setYLength 18.1 mm
/gate/mybox/geometry/setZLength 74. mm
# ...his material (Material should be known by GATE.
# It must be defined in GateMaterials.db file)
# Then, the color (black blue cyan gray green grey magenta red white yellow)
# and the visualization rendering:
# wire frame :
# or not
# or not
You will find here a macro that create the following boxes.
Cylinders are defined with the same philosophy
It is possible to create more complex elements like polycones. The folowing polycones are created with this macro. The pertinent line is:
/gate/body/geometry/setProfile 11.5 0.0 0 ...
The numbers are zPosition1, Rinner1, Routter1, zPosition2, Rinner2, Routter2, ...
GATE allows to build different tomographic systems. A system is a geometry with a predefined hierarchy describing PET (ecat system, cylindrical1 system), or SPECT (spectHead system). The only sytstem that allows to generate LMF files is cylindrical1.
Once you defined your world, you can add your cylindrical1 system as a daughter of world. World must be defined by a box at the beginning of your macro, just after visualization lines:
/gate/world/geometry/setXLength 40 cm
/gate/world/geometry/setYLength 40. cm
/gate/world/geometry/setZLength 40. cm
Then, cylindrical1 must be defined by these lines, changing of course material and dimensions:
/gate/cylindrical1/geometry/setRmax 68 mm
/gate/cylindrical1/geometry/setRmin 50 mm
/gate/cylindrical1/geometry/setHeight 74. mm
Cylindrical1 is then defined as a five levels geometry (from daughter to mother):
- 1 Layer
- 2 Crystal, box composed of one or several radially arranged layers.
- 3 Submodule box composed of one or several crystals arranged in 2D matrix.
- 4 Module box composed of one or several submodules arranged in 2D matrix.
- 5 Rsector box composed of one or several modules arranged in 2D matrix.
A complete cylindrical1 scanner is performed by a ring repeater applied on rsectors.
The repetition of each level should follow certain rules:
- 1 Layer repetition is not performed by a repeater. You have to define your layers as boxes inside the crystal.
- 2 Crystal repetition, is performed by a cubicarray repeater without X repetion (repeatNumberX = 1)
- 3 Submodule repetition is performed by a cubicarray repeater without X repetion (repeatNumberX = 1).
- 4 Module repetition is performed by a cubicarray repeater without X repetion (repeatNumberX = 1).
- 5 Rsector repetition is performed by a cubicarray repeater without X repetion (repeatNumberX = 1).
IMPORTANT: visualization will help you to build a cylindrical1 with no overlapping, with coherent dimensions, and to avoid geometric error. It is possible to not define one (or several) geometry levels, but the last level must be layer, and the first one must be rsector.
You will find here a complete macro example of a double layer (BGO/LSO) cylindrical1 system, shown on picture. It is recommanded to execute it line by line with visualization enabled to understand the different geometry levels.
The GateToASCII class of GATE allows to obtain the simplest output possible : ASCII files. This is the most readable output, and it allows you to treat your raw data with your own tools. In the other hand, this output is not compressed and the output files are very large. To write on disk is the slowest operation of GATE, so if you do not need ASCII files, it is strongly recommended to disable this output.
- How to enable this output in your macro ?
- What are the different columns in ASCII files ?
All the output commands (/gate/output/...) must always be after the initialization line.
As in most of the output modules of GATE, you can enable ASCII output files for Hits, Singles (at the end of the digitizer chain), Coincidences, but also the Singles after the different steps of the digitizer chain.
In your macro, set to 1 the different flags (resp.):
# enable ascii output for hits
# enable ascii output for Singles (end of digitizer chain)
# enable ascii output for coincidences
# enable ascii output for singles (after a digitizer module)
In all files the units are
- MeV (energy)
- mm (position)
- s (time)
- deg (angle)
A. For the Hits file (gateHits.dat):
Each line is a hit and the colums are :
Column 1 : ID of the run (i.e. time-slice)
Column 2 : ID of the event
Column 3 : ID of the primary particle of whom the descendant generated this hit
Column 4 : ID of the source which emitted the primary particle
Column 5 to 10 : Volume IDs*, depends on the way the system is attached to the geometry. For cylindricalPET it is :
- Column 5 : ID of volume attached to the "base" level of the system
- Column 6 : ID of volume attached to the "rsector" level of the system
- Column 7 : ID of volume attached to the "module" level of the system
- Column 8 : ID of volume attached to the "submodule" level of the system
- Column 9 : ID of volume attached to the "crystal" level of the system
- Column 10 : ID of volume attached to the "layer" level of the system
Column 11 : Time stamp of the hit Column 12 : Energy deposited by the hit Column 13 : Range of particle which has generated the hit Column 14, 15 ,16 : XYZ position of the hit in the world referential Column 17 : Geant4 code of the particle which has generated the hit Column 18 : ID of the particle which has generated the hit Column 19 : ID of the mother of the particle which has generated the hit Column 20 : ID of the photon from whom the particle which has generated the hit come Column 21 : Number of compton interactions in phantoms before reaching the detector Column 22 : Name of the process which has generated the hit Column 23 : Name of the last volume where a Compton effect occurs B. For the Singles files (gateSingles.dat): Each line is a single and the columns are : Column 1 : ID of the run (i.e. time-slice) Column 2 : ID of the event Column 3 : ID of the source Column 4, 5, 6 : XYZ position of the desintegration in world referential Column 7 to 12 : volume IDs*(cf. columns 5-10 of A.) Column 13 : Time stamp of the single Column 14 : Energy deposited by the single Column 15 to 17 : XYZ position of the hit in the world referential Column 18 :Number of Compton interactions in phantoms before reaching the detector Column 19 :Number of Compton interactions in detectors before reaching the detector Column 20 : Name of the phantom where a compton effect occurs C. For the Coincidences files (gateCoincidences.dat): Each line is a coincidence created with two singles and the columns are : Column 1 : ID of the run (i.e. time-slice) (first single) Column 2 : ID of the event (first single) Column 3 : ID of the source (first single) Column 4 to 6 : XYZ position of the desintegration in world referential (first single) Column 7 : Time stamp (first single) Column 8 : Energy deposited (first single) Column 9 to 11 : XYZ position in the world referential (first single) Column 12 to 17 : volume IDs* (cf. columns 5-10 of A.) (first single) Column 18 : Number of Compton interactions in phantoms before reaching the detector (first single) Column 19 : Number of Compton interactions in detectors before reaching the detector (first single) Column 20 : Scanner axial position (first single) Column 21 : Scanner angular position (first single) Column 22 : ID of the run (i.e. time-slice) (second single) Column 23 : ID of the event (second single) Column 24 : ID of the source (second single) Column 25 to 27 : XYZ position of the desintegration in world referential (second single) Column 28 : Time stamp (second single) Column 29 : Energy deposited (second single) Column 30 to 32 : XYZ position in the world referential (second single) Column 33 to 38 : volume IDs* (cf. columns 5-10 of A.) (second single) Column 39 : Number of Compton interactions in phantoms before reaching the detector (second single) Column 40 : Number of Compton interactions in detectors before reaching the detector (second single) Column 41 : Scanner axial position (second single) Column 42 : Scanner angular position (second single)
At the end of simulation, you wil find a file named gateRun.dat in your directory. This file is the list of the number of decays for each run (one by line).
When you build a voxelised source, by default, GATE writes the voxel densitiy values in a file (voxels.dat), to allow a cross-check of what you have loaded. In your macro, you can disable this option :
The format of voxels.dat is:
- line 1: Nx Ny Nz : number of voxels in the three directions
- line 2: dx dy dz :size of the voxel in millimeters
- line 3 to the end: voxel density values.
Order of the voxels: increase the index along x, then y, then z: For example for a 2x2x2 matrix the densities are written in the following order:
* : number of different volumeIDs depends on the complexity of the system geometry (6 IDs for cylindricalPET system, 3 for ecat system, ...). Then, the number of column of your ASCII file is not constant, but system-dependant.
- Singles (digis)
In GATE, a decay is the emission from a source of a particle. It can be more or less a reflect of a reality: GATE can generate real decays of a particle emitter (i.e: emission of a Beta+, that will give two photons) but also "artificial decays" with a "particle gun" (i.e: emission of two photons with the back-to-back tool). In this example, the particle gun is faster (from CPU time point of view), but you loose accurate physical effects (positron range, ...).
A hit is the elementary step of a particle tracking. A hit can be a physical interaction (Compton scattering, Photoelectric, ...) with an energy deposition, or a transportation (when a particle is leaving a volume). Hits that occurs in a sensitive detector (crystalSD or phantomSD) are stored and will appear in your output (ROOT, ASCII). The other hits are lost (but not ignored !). Hits are converted in pulses by the GateHitConvertor class.
A pulse is a hit with a non-zero energy deposition. Pulse are collected and treated in a digitizer.
At the end of a decay tracking, pulses are collected, and treated in a digitizer (a processing chain). Generally, the first step of the digitizer is a adder, that collect the pulses that occurs in a detection volume (crystalSD), and add their energies. Depending on how your crystals are read from the acquisition system of the camera, you will organize a group of pulses to form a Single. The module of the digitizer chain which create the Singles is called the readout. Position of the single is found merging positions of its pulses (centroid merge). The single is then send to the other modules of the digitizer (thresholder, dead-time, ...), and can be stored after each step.
To modelize PET cameras, GATE can perform a coincidence sorting. The singles are collected and stored in a queue, and then associated by pair if their time stamp is lower than the coincidence window. A pair of associated singles is a coincidence
- Generate the files
It is recommended to read all documents related to LMF and the P4.mac macro example availables on the OpenGATE main webpage.
You will only find here how to generate and customize LMF files. To treat this files and sort coincidences you have to use LMF library, also available on OpenGATE main webpage.
If you need to generate the LMF output file (List Mode Format is under LGPL Licence), this can be done by adding the following lines in the macro after the creation of a cylinrical1 system and the initialization line (/run/initialize):
which will generate a pair of LMF files: FILE_NAME.ccs (binary file) and FILE_NAME.cch (ASCII file). Default file names are lmf1.ccs and lmf1.cch
disables the LMF output.
- FILE_NAME.cch contains some general information, such as energy step, time step, etc... It is automatically generated.
- FILE_NAME.ccs contains the singles themselves in a compact binary format. The singles are the output of the digitizer chain. You have to check your digitization to know exactly what is stored in LMF.
Typical digitization performs a centroid calculation of hits in a same crystal (adder), and a "first wins sum" in different crystals of a same level of a cylinrical1 PET system.
A single event of a PET simulation stored in LMF can be defined by this real machine data:
- Time Stamp (8 bytes)
- Energy deposited (1 byte)
- Detector ID (2 bytes) contains a unique number for each elementary detection part of the PET scanner
- Scanner axial position (2 bytes)
- Scanner angular position (2 bytes)
and these simulation data:
- Run ID, incremented for each time slice (4 bytes)
- Event ID, incremented for each decay. That allows in particular to know if a coincidence is a random coincidence or not (4 bytes)
- Source ID, if several sources (2 bytes)
- Source XYZ position (6 bytes)
- Single XYZ position. That allows to know real position of the single event in the laboratory (6 bytes)
- Number of Compton of the event (1 byte)
Except Time Stamp, all these fields can be stored or not, playing with the following bools in your macro. Of course, the more you store inforamation, the bigger will be your LMF files.
For example, you needn't to store scanner axial position and scanner angular position if there is no scanner movement... Please add these lines to your macro:
Then you can store detectorID (1) or not (0):
store energy (1) or not (0)
store the axial position if the PET has a translation movement (1) or not (0)
store the angular position if the PET has a rotation movement (1) or not (0)
store simulation data that are not available in a real world (1) or not (0). If 0 the other following lines will be ignored.
store the compton number (1) or not (0)
store the sourceID (1) or not (0)
store the source XYZ position (1) or not (0)
store the real XYZ position (1) or not (0)
store the eventID (1) or not (0)
store the runID (1) or not (0)
The following lines:
will create toto.ccs and toto.cch that will contain for every event of your simulation time stamp, and event ID (12 bytes / event)
A complete example macro with LMF output is downloadable here.
The following example illustrate how to use the online plotter
Macro example :
/gate/output/plotter/addPlot hist Ion_decay_time_s
/gate/output/plotter/addPlot hist Positron_Kinetic_Energy_MeV
/gate/output/plotter/addPlot tree Singles compton
/gate/output/plotter/addPlot tree Coincidences energy1
with the command being :
addPlot hist NAME_of_the_histo
to plot an histogram defined in GATE. and
addPlot tree NAME_of_the_tree NAME_of_the_variable
to plot a variable from one of the GATE trees.