# 2. Defining a geometry¶

The definition of a geometry is a key step in designing a simulation because it is through the geometry definition that the imaging device and object to be scanned are described. Particles are then tracked through the components of the geometry. This section explains how to define the different components of the geometry.

## 2.1. The world¶

### 2.1.1. Definition¶

The world is the only volume already defined in GATE when starting a macro. All volumes are defined as daughters or grand-daughters of the world. The world volume is a typical example of a GATE volume and has predefined properties. The world volume is a box centered at the origin. For any particle, tracking stops when it escapes from the world volume. The world volume can be of any size and has to be large enough to include all volumes involved in the simulation.

### 2.1.2. Use¶

The first volume that can be created must be the daughter of the world volume. Any volume must be included in the world volume. The geometry is built from the world volume.

### 2.1.3. Description and modification¶

The world volume has default parameters: shape, dimensions, material, visibility attributes and number of children. These parameters can be edited using the following GATE command:

/gate/world/describe


The output of this command is shown in Fig. 2.1. The parameters associated with the world volume can be modified to be adapted to a specific simulation configuration. Only the shape of the world volume, which is a box, cannot be changed. For instance, the X length can be changed from 50 cm to 2 m using:

/gate/world/geometry/setXLength 2. m


The other commands needed to modify the world volume attributes will be given in the next sections.

## 2.2. Creating a volume¶

### 2.2.1. Generality - Tree creation¶

When a volume is created with GATE, it automatically appears in the GATE tree. All commands applicable to the new volume are then available from this GATE tree. For instance, if the name of the created volume is Volume_Name, all commands applicable to this volume start with:

/gate/Volume_Name/


The tree includes the following commands:

• setMaterial: To assign a material to the volume

• attachCrystalSD: To attach a crystal-SensitiveDetector to the volume

• attachPhantomSD: To attach a phantom-SensitiveDetector to the volume

• enable: To enable the volume

• disable: To disable the volume

• describe: To describe the volume

The tree includes sub-trees that relate to different attributes of the volume Volume_Name. The available sub-trees are:

• daughters: To insert a new ‘daughter’ in the volume

• geometry: To control the geometry of the volume

• vis: To control the display attributes of the volume

• repeaters: To apply a new ‘repeater’ to the volume

• moves: To ‘move’ the volume

• placement: To control the placement of the volume

The commands available in each sub-tree will be described in Building a volume, Repeating a volume, Placing a volume, Moving a volume.

### 2.2.2. Units¶

Different units are predefined in GATE (see Table 2.1) and shall be referred to using the corresponding abbreviation. Inside the GATE environment, the list of units available in GATE can be edited using:

/units/list


### 2.2.3. Axes¶

Any position in the world is defined with respect to a three-axis system: X, Y and Z. These three axes can be seen in the display window using:

/vis/scene/add/axes

Table 2.1 List of units available in GATE and corresponding abbreviations

LENGTH

SURFACE

VOLUME

ANGLE

parsec pc

kilometer km

kilometer2 km2

kilometer3 km3

meter m

meter2 m2

meter33 m3

centimeter cm

centimeter2 cm2

centimeter3 cm3

degre deg

micrometer mum

millimeter2 mm2

millimeter3 mm3

nanometer nm

angstrom Ang

TIME

SPEED

ANGULAR SPEED

ENERGY

second s

meter/s m/s

electronvolt eV

millisecond ms

centimeter/s cm/s

degree/s deg/s

kiloelectronvolt KeV

microsecond mus

millimeter/s mm/s

rotation/s rot/s

megaelectronvolt MeV

nanosecond ns

meter/min m/min

gigaelectronvolt GeV

picosecond ps

centimeter/min cm/min

degree/min deg/min

teraelectronvolt TeV

millimeter/min m/min

rotation/min rot/min

petaelectronvolt PeV

meter/h m/h

joule j

centimer/h cm/h

degree/h deg/h

millimeter/h mm/h

rotation/h rot/h

ACTIVITY DOSE

AMOUNT OF SUBSTANCE

MASS

VOLUMIC MASS

becquerel Bq

mole mol

milligram mg

g/cm3 g/cm3

curie Ci

mg/cm3 mg/cm3

gray Gy

kilogram kg

kg/m3 kg/m3

ELECTRIC CHARGE

ELECTRIC CURRENT

ELECTRIC POTENTIAL

MAGNETIC FLUX - MAGNETIC FLUX DENSITY

eplus e+

ampere A

volt V

weber Wb

coulomb C

milliamper mA

kilovolt kV

tesla T

microampere muA

megavolt MV

gauss G

nanoampere nA

kilogauss kG

TEMPERATURE

FORCE - PRESSURE

POWER

FREQUENCY

kelvin K

newton N

watt W

hertz Hz

pascal Pa

kilohertz kHz

bar bar

megaherz MHz

atmosphere atm

### 2.2.4. Building a volume¶

Any new volume must be created as the daughter of another volume (i.e., World volume or another volume previously created).

Three rules must be respected when creating a new volume:

• A volume which is located inside another must be its daughter

• A daughter must be fully included in its mother

• Volumes must not overlap

Errors in building the geometry yield wrong particle transportation, hence misleading results!

Creating a new volume

To create a new volume, the first step is to give it a name and a mother using:

/gate/mother_Volume_Name/daughters/name Volume_Name


This command prepares the creation of a new volume named Volume_Name which is the daughter of mother_Volume_Name.

Some names should not be used as they have precise meanings in gate. These names are the names of the GATE systems (see Defining a system) currently defined in GATE: scanner, PETscanner, cylindricalPET, SPECTHead, ecat, CPET, OPET and OpticalSystem.

The creation of a new volume is completed only when assigning a shape to the new volume. The tree

/gate/Volume_Name/


is then generated and all commands in the tree and the sub-trees are available for the new volume.

Different volume shapes are available, namely: box, sphere, cylinder, cone, hexagon, general or extruded trapezoid, wedge, elliptical tube, tessellated and TetMeshBox.

The command line for listing the available shapes is:

/gate/world/daughters/info


The command line for assigning a shape to a volume is:

/gate/mother_Volume_Name/daughters/insert Volume_shape


where Volume_shape is the shape of the new volume.

Volume_shape must necessarily be one of the available names:

box for a box - sphere for a sphere - cylinder for a cylinder - ellipsoid for an ellipsoid - cone for a cone - eltub for a tube with an elliptical base - hexagone for an hexagon - polycone for a polygon - trap for a general trapezoid - trpd for an extruded trapezoid - wedge for a wedge - tessellated for a tessellated volume and TetMeshBox for a box which contains a tetrahedral mesh.

The command line assigns the shape to the last volume that has been named.

The following command lists the daughters of a volume:

/gate/Volume_Name/daughters/list

• Example:

/gate/world/daughters/name Phantom
/gate/world/daughters/insert box


The new volume Phantom with a box shape is inserted in the World volume.

Defining a size

After creating a volume with a shape, its dimensions are the default dimensions associated with that shape. These default dimensions can be modified using the sub-tree /geometry/

The commands available in the sub-tree depend on the shape. The different commands for each type of shape are listed in Table 2.2

These commands can be found in the directory:

/gate/Volume_Name/geometry   (Some volumes visualisation are available here: http://gphysics.net/geant4/geant4-gdml-format.html )

Table 2.2 Commands of the sub-tree geometry for different shapes

BOX

TRPD

setXLength: Set the length of the box along the X axis

setX1Length: Set half length along X of the plane at -dz position

setYLength: Set the length of the box along the Y axis

setY1Length: Set half length along Y of the plane at -dz position

setZLength: Set the length of the box along the Z axis

setX2Length: Set half length along X of the plane at +dz position

SPHERE

setY2Length: Set half length along Y of the plane at +dz position

setRmin: Set the internal radius of the sphere (0 for full sphere)

setZLength: Set half length along Z of the trapezoid

setRmax: Set the external radius of the sphere

setXBoxLength: Set half length along X of the extruded box

setPhiStart: Set the start phi angle

setYBoxLength: Set half length along Y of the extruded box

setDeltaPhi: Set the phi angular span (2PI for full sphere)

setZBoxLength: Set half length along Z of the extruded box

setThetaStart: Set the start theta angle

setXBoxPos: Set center position X of the box

setDeltaTheta: Set the theta angular span (2PI for full sphere)

setYBoxPos: Set center position Y of the box

CYLINDER

setZBoxPos: Set center position Z of the box

setRmin: Set the internal radius of the cylinder (0 for full cylinder)

PARALLELEPIPED (… not yet implemented…)

setRmax: Set the external radius of the cylinder

setDx: Set Dx dimension of the parallelepiped

setHeight: Set the height of the cylinder

setDy: Set Dy dimension of the parallelepiped

setPhiStart: Set the start phi angle

setDz: Set Dz dimension of the parallelepiped

setDeltaPhi: Set the phi angular span (2PI for full cylinder)

setAlpha: Set Alpha angle

CONE

setTheta: Set Theta angle

setRmin1: Set the internal radius of one side of the cone (0 for full cone)

setPhi: Set Phi angle

setRmax1: Set the external radius of one side of the cone

POLYCONE (… not yet implemented…)

setRmin2: Set the internal radius of one side of the cone (0 for full cone)

setProfile: Set vectors of z, rInner, rOuter positions

setRmax2: Set the external radius of one side of the cone

setPhiStart: Set the start phi angle

setHeight: Set the height of the cone

setDeltaPhi: Set the phi angular span (2PI for full cone)

setPhiStart: Set the start phi angle

HEXAGONE

setDeltaPhi: Set the phi angular span (2PI for full cone)

ELLIPSOID

setHeight: Set the height of the hexagon

setXLength: Set the half axis length in the X direction

WEDGE

setYLength: Set the half axis length in the Y direction

setNarrowerXLength: Set the length of the shorter side of the wedge in the X direction

setZLength: Set the half axis length in the Z direction

setXLength: Set the length of the wedge in the X direction

setZBottomCut: To cut the ellipsoide along the Z axis

setYLength: Set the length of the wedge in the Y direction

setZTopCut: To cut the ellipsoide along the Z axis

setZLength: Set the length of the wedge in the Z direction

ELLIPTICAL TUBE

TET-MESH BOX

setLong: Set the length of the semimajor axis

reader/setPathToELEFile: Set path to ‘.ele’ input file, which describes a tetrahedral mesh

setShort: Set the length of the semiminor axis

reader/setUnitOfLength: Set unit of length for the values in the ‘.ele’ input file

setHeight: Set the height of the tube

setPathToAttributeMap: Set path to txt-file which defines material and colour of the tetrahedra

TESSELLATED

setPathToVerticesFile: Set the path to vertices text file

For a box volume called Phantom , the X, Y and Z dimensions can be defined by:

/gate/Phantom/geometry/setXLength 20. cm
/gate/Phantom/geometry/setYLength 10. cm
/gate/Phantom/geometry/setZLength 5. cm


The dimensions of the Phantom volume are then 20 cm, 10 cm and 5 cm along the X, Y and Z axes respectively.

Defining a material

A material must be associated with each volume. The default material assigned to a new volume is Vacuum. The list of available materials is defined in the GateMaterials.db file. (see Materials).

The following command fills the volume Volume_Name with a material called Material:

/gate/Volume_Name/setMaterial Material

• Example:

/gate/Phantom/setMaterial Water


The Phantom volume is filled with Water.

Defining a color or an appearance

To make the geometry easy to visualize, some display options can be set using the sub-tree /vis/

The commands available in this sub-tree are: setColor, setVisible, setDaughtersInvisible, setLineStyle, setLineWidth, forceSolid and forceWireframe (see Table 2.3)

Table 2.3 List of commands of the GATE sub-tree geometry

Command

Action

Argument

setColor

Selects the color for the current volume

white, gray, black, red, green, blue, cyan, magenta and yellow

setVisible

Shows or hides the current volume

setDaughtersInvisible

Shows or hides the current volume daughters

setLineStyle

Sets the current volume line-style

dashed, dotted and unbroken

setLineWidth

Sets the current volume line-width

forceSolid

Forces solid display for the current volume

forceWireframe

Forces wireframe display for the current volume

These commands can be found in the tree /gate/Volume_Name/vis.

• Example:

/gate/Phantom/vis/setColor blue
/gate/Phantom/vis/forceWireframe


The Phantom volume will be displayed in blue and will be transparent.

Enabling or disabling a volume

A volume cannot be destroyed. The only possible action is to disable it: this makes the volume disappear from the display window but not from the geometry.

Only the world volume cannot be disabled.

To disable a volume Volume_Name, the command is:

/gate/Volume_Name/disable


The volume Volume_Name can be enabled again using:

/gate/Volume_Name/enable

• Example:

/gate/Phantom/disable


The Phantom volume is disabled.

Describing a volume

The parameters associated with a volume Volume_name can be listed using:

/gate/Volume_Name/describe

• Example:

/gate/Phantom/describe


The parameters associated with the Phantom volume are listed.

#### 2.2.4.1. Examples¶

##### 2.2.4.1.1. How to build a NaI crystal¶

A volume named crystal is created as the daughter of a volume whose shape is defined as a box:

/gate/mother_Volume_Name/daughters/name     crystal
/gate/mother_Volume_Name/daughters/insert   box


The X, Y and Z dimensions of the volume crystal are set to 1 cm, 40 cm, and 54 cm respectively:

/gate/crystal/geometry/setXLength           1. cm
/gate/crystal/geometry/setYLength           40. cm
/gate/crystal/geometry/setZLength           54. cm


The new volume crystal is filled with NaI:

/gate/crystal/setMaterial                   NaI


The new volume crystal is colored in yellow:

/gate/crystal/vis/setColor                  yellow


The next command lists the parameters associated with the crystal volume:

/gate/crystal/describe


The crystal volume is disabled:

/gate/crystal/disable

##### 2.2.4.1.2. How to build a “trpd” volume¶

An alternative way of describing complicated geometries is to use a so-called “boolean” volume in order to describe one piece using a single volume instead of using a mother-children couple. This can make the description easier and more synthetic. The example below describes how the shape shown in Fig. 2.3 can be defined using a trpd shape, based on a “boolean” volume consisting of a trapezoid “minus” a box:

# V I S U A L I S A T I O N
/vis/open OGLSX /vis/viewer/reset
/vis/viewer/viewpointThetaPhi 60 60
/vis/viewer/zoom 1
/vis/viewer/set/style surface
/vis/drawVolume /tracking/storeTrajectory 1
/vis/scene/endOfEventAction accumulate
/vis/viewer/update
/vis/verbose 2
/gate/geometry/enableAutoUpdate
/gate/world/daughters/name                Volume_Name
/gate/world/daughters/insert              box
/gate/Volume_Name/geometry/setXLength     40 cm
/gate/Volume_Name/geometry/setYLength     40 cm
/gate/Volume_Name/geometry/setZLength     40 cm
/gate/Volume_Name/vis/forceWireframe
/gate/Volume_Name/daughters/name          trapeze_name
/gate/Volume_Name/daughters/insert        trpd
/gate/trapeze_name/geometry/setX1Length   23.3 mm
/gate/trapeze_name/geometry/setY1Length   21.4 mm
/gate/trapeze_name/geometry/setX2Length   23.3 mm
/gate/trapeze_name/geometry/setY2Length   23.3 mm
/gate/trapeze_name/geometry/setZLength    6. mm
/gate/trapeze_name/geometry/setXBoxPos    0. mm
/gate/trapeze_name/geometry/setYBoxPos    0. m
/gate/trapeze_name/geometry/setZBoxPos    0.7501 mm
/gate/trapeze_name/geometry/setXBoxLength 20.3 mm
/gate/trapeze_name/geometry/setYBoxLength 20.3 mm
/gate/trapeze_name/geometry/setZBoxLength 4.501 mm


The new volume called trapeze_name, which is the daughter of the Volume_Name volume, is described with 5+6 parameters. The first 5 parameters relate to the trapezoid, whereas the last 6 parameters describe the extruded volume using a box shape.

##### 2.2.4.1.3. How to build a “wedge” volume¶

Gate provides the class GateTrapCreator to create and insert trapezoidal volumes into the geometry. To create a trapezoid, the user needs to specify eleven parameters (besides its name and material), which does not make it easy to use.

To model “slanted” crystals, a new class called GateWedgeCreator (derived from G4Trap) builds right angular wedges. As shown in Fig. 2.4, a wedge is defined by only three parameters that are easily understood:

1. XLength: is the length of the wedge in the X direction.

2. NarrowerXLength: is the length of the shorter side of the wedge in the X direction.

3. YLength: is the length in the Y direction.

4. ZLength: is the length in the Z direction.

For instance, the following macro lines insert a wedge crystal as a daughter of a module:

/gate/module/daughters/name                wedge0
/gate/module/daughters/insert              wedge
/gate/wedge0/geometry/setXLength           10 mm
/gate/wedge0/geometry/setNarrowerXLength   8.921 mm
/gate/wedge0/geometry/setYLength           2.1620 mm
/gate/wedge0/geometry/setZLength           2.1620 mm
/gate/wedge0/setMaterial                   LSO
/gate/wedge0/vis/setColor                  yellow

##### 2.2.4.1.4. How to build a “tessellated” volume¶

In GATE, you have the possibility to create a tessellated volume from an STL file. STL is a common file format that uses triangular facets to define the surface of a three-dimensional object. This allows to simulate a complex geometry imported from a CAD software. The surface described in the STL file is used to create a volume in GATE using the Geant4 G4TessellatedSolid class. It’s important to note that only one material is associated to a tessellated volume. You can use either ASCII or binary STL files.

/!\ STL files are imported in GATE with a unit defined as mm.

Here is an example to create a tessellated volume from an STL file in a GATE macro:

/gate/world/daughters/name                                        kidneyLeft
/gate/world/daughters/insert                                      tessellated
/gate/kidneyLeft/placement/setTranslation                         -265.3625 -121.5875 -842.16 mm
/gate/kidneyLeft/geometry/setPathToSTLFile                        data/Label89.stl
/gate/kidneyLeft/setMaterial                                      Kidney


Label89.stl being the STL file containing the triangular facets.

Declaring other tessellated volumes (including daughters), one can create a complex geometry (for example kidneys) for accurate dosimetry:

The complete code used to generate this figure can be found in the GateContrib GitHub repository under misc/geometry_STL/kidneys.

##### 2.2.4.1.5. How to build a “TetMeshBox” volume¶

The TetMeshBox volume is a box volume which contains a tetrahedral mesh. The tetrahedral mesh can be loaded from an ‘.ele/.node’ file pair, which can be generated by TetGen, an open-source tetrahedral mesh generator. Please refer to the TetGen manual for a comprehensive explanation of the structure of ‘.ele’ and ‘.node’ files. An example usage of the TetMeshBox would look like this:

/gate/world/daughters/name                    meshPhantom
/gate/world/daughters/insert                  TetMeshBox
/gate/meshPhantom/setMaterial                 Air
/gate/meshPhantom/setPathToAttributeMap       data/RegionAttributeTable.dat


Here, GATE would implicitly assume that two files exist, namely ‘data/BodyHasHeart.node’ and ‘data/BodyHasHeart.ele’. The numerical values defined in those files are interpreted according to the ‘setUnitOfLength’ command. GATE assumes that the ‘.ele’ input file defines a region attribute for each tetrahedron – an integer attribute, which logically groups tetrahedra that form a sub-structure of the mesh. The user has to provide an ‘attribute map’, which defines material and colour for each region within the tetrahedral mesh. An attribute map is a txt-file and looks as follows:

# [first region,    last region]    material    visible   r       g       b      alpha
# ------------------------------------------------------------------------------------
1                   1               Heart       true      1.00    0.0     0.0    1.0
2                   3               Adipose     true      1.00    0.89    0.77   1.0


The first two columns refer to the region attributes defined in the ‘.ele’ file.

The size of the bounding box will adapt to the extent of the tetrahedral mesh and the material of the bounding box can be set via the ‘setMaterial’. Here, a visual example of the TetMeshBox volume:

The complete code used to generate this figure can be found in the GateContrib repository on Github under misc/TetrahedralMeshGeometry.

## 2.3. Repeating a volume¶

To create X identical volumes, there is no need to create X different volumes. Only one volume must be created and then repeated. There are four different ways to repeat a volume: the linear repeater, the ring repeater, the cubic array repeater and the quadrant repeater.

To list the repeaters defined for the volume Name_Volume, use:

/gate/Name_Volume/repeaters/info


### 2.3.1. Linear repeater¶

The linear repeater is appropriate to repeat a volume along a direction (X, Y or Z axis). To use the linear repeater, first select this type of repeater using:

/gate/Name_Volume/repeaters/insert linear


Then define the number of times N the volume Name_Volume has to be repeated using:

/gate/Name_Volume/linear/setRepeatNumber N


Finally, define the step and direction of the repetition using:

/gate/Name_Volume/linear/setRepeatVector 0. 0. dZ. mm


A step of dZ mm along the Z direction is defined.

The “autoCenter” command allows the user to set the position of the repeated volumes:

/gate/Name_Volume/linear/autoCenter true or false


The “true” option centers the group of repeated volumes around the position of the initial volume that has been repeated.

The “false” option centers the first copy around the position of the initial volume that has been repeated. The other copies are created by offset. The default option is true.

• Example:

/gate/hole/repeaters/insert          linear
/gate/hole/linear/setRepeatNumber    12
/gate/hole/linear/setRepeatVector    0. 4. 0. cm


The hole volume is repeated 12 times every 4 cm along the Y axis. The application of this linear repeater is illustrated in Fig. 2.6.

### 2.3.2. Ring repeater¶

The ring repeater makes it possible to repeat a volume along a ring. It is useful to build a ring of detectors in PET.

To select the ring repeater, use:

/gate/Name_Volume/repeaters/insert ring


To define the number of times N the volume Name_Volume has to be repeated, use:

/gate/Name_Volume/ring/setRepeatNumber N


Finally, the axis around which the volume Name_Volume will be repeated must be defined by specifying two points using:

/gate/Name_Volume/ring/setPoint1 0. 1. 0. mm
/gate/Name_Volume/ring/setPoint2 0. 0. 0. mm


The default rotation axis is the Z axis. Note that the default ring repetition goes counter clockwise.

These three commands are enough to repeat a volume along a ring over 360°. However, the repeat action can be further customized using one or more of the following commands. To set the rotation angle for the first copy, use:

/gate/Name_Volume/ring/setFirstAngle x deg


The default angle is 0 deg.

To set the rotation angle difference between the first and the last copy, use:

/gate/Name_Volume/ring/setAngularSpan x deg


The default angle is 360 deg.

The AngularSpan, the FirstAngle and the RepeatNumber allow one to define the rotation angle difference between two adjacent copies (AngularPitch).

$$\frac{AngularSpan-FirstAngle}{RepeatNumber-1} = AngularPitch$$

To set the number of objects in the periodic structure, hence the periodicity, use:

/gate/Name_Volume/ring/setModuloNumber M


When the volume auto-rotation option is enabled, the volume itself is rotated so that its axis remains tangential to the ring (see Fig. 2.8). If this option is disabled, all repeated volumes keep the same orientation (see Fig. 2.9). The commands for enabling or disabling the auto-rotation option are:

/gate/Name_Volume/ring/enableAutoRotation
/gate/Name_Volume/ring/disableAutoRotation


A volume can also be shifted along Z periodically. Each element of a sequence is shifted according to its position inside the sequence, defined as “j” below. In a sequence composed of $$M_{ModuloNumber}$$ elements, the shift values are defined as $$Zshift_{i} \quad \equiv \quad Zshift_{j}$$ where :

• i is the position in the full ring

• j =(i % $$M_{ModuloNumber}$$)+1 is the position in a sequence, starting at 1.

To set a shift and the value of this shift, use:

/gate/Name_Volume/ring/setModuloNumber 1
/gate/Name_Volume/ring/setZShift1 Z mm


Up to 8 shifts and different shift values can be defined (setZShift1 to setZShift8).

Remark: This geometry description conforms to the document “List Mode Format Implementation: Scanner geometry description Version 4.1 M.Krieguer et al “ and is fully described in the LMF output, in particular in the ASCII header file entry:

z shift sector j mod $$M_{ModuloNumber}$$ : Zshift_j units

Here j (j starting here at 0) stands for the $$n^{th.}$$ object being shifted each $$M_{ModuloNumber}$$ object. Each shift value introduced in the command line below corresponds to a new line in the .cch file.

The LMF version 22.10.03 supports a geometry with a cylindrical symmetry. As an example, a repeater starting at 0 degree and finishing at 90 degree (a quarter of ring) will not be supported by the LMF output.

• Example 1:

/gate/hole/repeaters/insert          ring
/gate/hole/ring/setRepeatNumber      10
/gate/hole/ring/setPoint1            0. 1. 0. mm
/gate/hole/ring/setPoint2            0. 0. 0. mm


The hole volume is repeated 10 times around the Y axis. The application of this ring repeater is illustrated in Fig. 2.10.

• Example 2:

/gate/rsector/repeaters/insert       ring
/gate/rsector/ring/setRepeatNumber   20
/gate/rsector/ring/setModuloNumber   2
/gate/rsector/ring/setZShift1        -3500 mum
/gate/rsector/ring/setZShift2        +3500 mum
/gate/rsector/ring/enableAutoRotation


The rsector volume is repeated 20 times along a ring. The sequence length is 2, with the first and the second volume shifted by -3500 µ m and 3500 µ m respectively. The rsector volume could also include several volumes itself, each of them being duplicated, which is illustrated in Fig. 2.12.

### 2.3.3. Cubic array repeater¶

The cubic array repeater is appropriate to repeat a volume along one, two or three axes. It is useful to build a collimator for SPECT simulations.

To select the cubic array repeater, use:

/gate/Name_Volume/repeaters/insert cubicArray


To define the number of times Nx, Ny and Nz the volume Name_Volume has to be repeated along the X, Y and Z axes respectively, use:

/gate/hole/cubicArray/setRepeatNumberX Nx
/gate/hole/cubicArray/setRepeatNumberY Ny
/gate/hole/cubicArray/setRepeatNumberZ Nz


To define the step of the repetition X mm, Y mm and Z mm along the X, Y and Z axes respectively, use:

/gate/hole/cubicArray/setRepeatVector X Y Z mm


The autocentering options are available for the cubic array repeater. If a volume is initially at a position P, the set of volumes after the repeater has been applied is centered on P if autoCenter is true (default). If autoCenter is false, the first copy of the group is centered on P.

• Example:

/gate/hole/repeaters/insert               cubicArray
/gate/hole/cubicArray/setRepeatNumberX    1
/gate/hole/cubicArray/setRepeatNumberY    5
/gate/hole/cubicArray/setRepeatNumberZ    2
/gate/hole/cubicArray/setRepeatVector     0. 5. 15. cm


The hole volume is repeated 5 times each 5 cm along the Y axis and twice each 15 cm along the Z axis. The application of this cubic array repeater is illustrated in figure Fig. 2.13.

The quadrant repeater is appropriate to repeat a volume in a triangle-like pattern similar to that of a Derenzo resolution phantom.

To select the quadrant repeater, use:

/gate/Name_Volume/repeaters/insert quadrant


To define the number of repetition lines, use:

/gate/hole/quadrant/setLineNumber X


To define the orientation of the quadrant (the direction of line repetition), use:

/gate/hole/quadrant/setOrientation N deg


To define the distance between adjacent copies, use:

/gate/hole/quadrant/setCopySpacing xx cm


To define the maximum range of the repeater which is the maximum distance between a copy and the original volume, use:

/gate/hole/quadrant/setMaxRange xx cm


This command can be used to remove corner-copies that would fall outside your phantom

• Example:

/gate/hole/repeaters/insert           quadrant


The hole volume is repeated in a triangle-like pattern. The application of this quadrant repeater is illustrated in Fig. 2.6.

Remark: The repeaters that are applied to the Name_Volume volume can be listed using:

/gate/Name_Volume/repeaters/list


### 2.3.5. Sphere repeater¶

The sphere repeater makes it possible to repeat a volume along a spherical ring. It is useful to build rings of detectors for PET scanners having gantry of spherical shape (e.g. SIEMENS Ecat Accel, Hi-Rez, ….)

To select the sphere repeater, use:

/gate/Name_Volume/repeaters/insert sphere


Then, the radius R of the sphere can be set using:

/gate/Name_Volume /sphere/setRadius X cm


To define the number of times N1 and N2 the volume Name_Volume has to repeated in the transaxial plane and the axial plane respectively, use:

/gate/Name_Volume/sphere/setRepeatNumberWithTheta N1
/gate/Name_Volume/sphere/setRepeatNumberWithPhi N2


To set the rotation angle difference between two adjacent copies in the transaxial direction, use:

/gate/Name_Volume/sphere/setThetaAngle x deg


To set the rotation angle difference between two adjacent copies in the axial direction, use:

/gate/Name_Volume/sphere/setPhiAngle y deg


The replicates of the volume Name_Volume will be placed so that its axis remains tangential to the ring.

Example Fig. 2.17:

/gate/block/repeaters/insert                   sphere
/gate/block/sphere/setRepeatNumberWithTheta    10
/gate/block/sphere/setRepeatNumberWithPhi      3
/gate/block/setThetaAngle                      36 deg
/gate/block/setThetaAngle                      20 deg


The block volume is repeated 10 times along the transaxial plane, with a rotation angle between two neighbouring blocks of 36 deg, and is repeated 3 times in the axial direction with a rotation angle between two neighbouring blocks of 20 deg. The sphere defined here has a 25 cm radius.

### 2.3.6. Generic repeater¶

It is also possible to repeat a volume according to a list of transformations (rotation and translation). The time column is ignored by the generic repeater.

The following macros read the transformations into a simple text file:

/gate/myvolume/repeaters/insert                       genericRepeater
/gate/myvolume/genericRepeater/setPlacementsFilename  data/myvolume.placements
/gate/myvolume/genericRepeater/useRelativeTranslation 1


The text file “myvolume.placements” is composed as follows:

###### List of placement (translation and rotation)
###### Column 1      is time in seconds
###### Column 2      is rotationAngle in degree
###### Columns 3,4,5 are rotation axis
###### Columns 6,7,8 are translation in mm
Time     s
Rotation deg
Translation mm
0      0       0 1 0       0 0 10
0      10      0 1 0       0 0 10
0      15      0 1 0       0 0 20

• line with # are ignored

• first word must be Time followed with the units

• next words must be Rotation then Translation followed with the units (deg and mm here)

• Rotation are described with 4 columns, the first for the angle, three others for the rotation axis

• Translation are described with X Y Z.

• using “useRelativeTranslation 1” (default) allows to compose the transformation according to the initial volume translation. If set to 0, the transformation is set as is (in the coordinate system of the mother volume).

See example GateRT

## 2.4. Placing a volume¶

The position of the volume in the geometry is defined using the sub-tree:

/placement/


Three types of placement are available: translation, rotation and alignment.

### 2.4.1. Translation¶

To translate the Name_Volume volume along the X direction by x cm, the command is:

/gate/Name_Volume/placement/setTranslation x. 0. 0. cm


The position is always given with respect to the center of the mother volume.

To set the Phi angle (in XY plane) of the translation vector, use:

/gate/Name_Volume/placement/setPhiOfTranslation N deg


To set the Theta angle (with regard to the Z axis) of the translation vector, use:

/gate/Name_Volume/placement/setThetaOfTranslation N deg


To set the magnitude of the translation vector, use:

/gate/Name_Volume/placement/setMagOfTranslation xx cm

• Example:

/gate/Phantom/placement/setTranslation           1. 0. 0. cm
/gate/Phantom/placement/setMagOfTranslation      10. cm


The Phantom volume is placed at 10 cm, 0 cm and 0 cm from the center of the mother volume (here the world volume). The application of this translation placement is illustrated in Fig. 2.18.

### 2.4.2. Rotation¶

To rotate the Name_Volume volume by N degrees around the X axis, the commands are:

/gate/Name_Volume/placement/setRotationAxis    X 0 0
/gate/Name_Volume/placement/setRotationAngle   N deg
/gate/Name_Volume/placement/setAxis            0 1 0


The default rotation axis is the Z axis.

• Example:

/gate/Phantom/placement/setRotationAxis        0 1 0
/gate/Phantom/placement/setRotationAngle       90 deg


The Phantom volume is rotated by 90 degrees around the Y axis. The application of this rotation placement is illustrated in Fig. 2.20.

### 2.4.3. Alignment¶

Using the alignment command, a volume having an axis of symmetry (cylinder, ellipso, cone and hexagone) can be aligned parallel to one of the three axes of the axis system.

To align the Name_Volume volume along the X axis, use:

/gate/Name_Volume/placement/alignToX


The rotation parameters of the Name_Volume volume are then set to +90 degree around the Y axis.

To align the Name_Volume volume along the Y axis, use:

/gate/Name_Volume/placement/alignToY


The rotation parameters of the Name_Volume volume are then set to -90 degree around the X axis.

To align the Name_Volume volume along the Z axis (default axis of rotation) use:

/gate/Name_Volume/placement/alignToZ


The rotation parameters of the Name_Volume volume are then set to 0 degree.

### 2.4.4. Special example: Wedge volume and OPET scanner¶

The wedge is always created as shown in Fig. 2.4, that is with the slanted plane oriented towards the positive X direction. If one needs to have it oriented differently, one could, for instance, rotate it:

/gate/wedge0/placement/setRotationAxis 0 1 0
/gate/wedge0/placement/setRotationAngle 180 deg


The center of a wedge in the Y and Z directions are simply

$$\frac{setYLength}{2}, \frac{setZLength}{2}$$

respectively. For the X direction, the center is located such that

$$2 \Delta = \frac{setXLength + setNarrowerXLength}{2}$$

where Delta is the length of the wedge across the middle of the Y direction, as shown in Fig. 2.22.

Wedge crystals are used to build the OPET scanner, in which the scanner ring geometry approximates a true circular ring.

By knowing the radius gantry R and the length of the longest crystal, it is possible to arrange a series of 8 crystals with varying the lengths as shown in Fig. 2.23.

It is first necessary to create by-hand the first row of crystals. This is accomplished by first creating a module just big enough to contain one row of wedge crystals:

/gate/rsector/daughters/name        module
/gate/rsector/daughters/insert      box
/gate/module/geometry/setXLength    10 mm
/gate/module/geometry/setYLength    17.765 mm
/gate/module/geometry/setZLength    2.162 mm
/gate/module/setMaterial            Air


Then, a box that will contain the first wedge crystal is located inside the module:

/gate/module/daughters/name                  crystal0
/gate/module/daughters/insert                box
/gate/crystal0/geometry/setXLength           10 mm
/gate/crystal0/geometry/setYLength           2.1620 mm
/gate/crystal0/geometry/setZLength           2.1620 mm
/gate/crystal0/placement/setTranslation      0. -7.8015 0. mm
/gate/crystal0/setMaterial                   Air
/gate/crystal0/vis/setColor                  black
/gate/crystal0/vis/setVisible                false


Finally, the actual crystal is placed inside its box:

/gate/crystal0/daughters/name                LSO0
/gate/crystal0/daughters/insert              wedge
/gate/LSO0/geometry/setXLength               10 mm
/gate/LSO0/geometry/setNarrowerXLength       8.921 mm
/gate/LSO0/geometry/setYLength               2.1620 mm
/gate/LSO0/geometry/setZLength               2.1620 mm
/gate/LSO0/placement/setRotationAxis         0 1 0
/gate/LSO0/placement/setRotationAngle        180 deg
/gate/LSO0/placement/setTranslation          0.2698 0. 0. mm
/gate/LSO0/setMaterial                       BGO


It is necessary to locate each crystal in separate “layers”.

The last two steps are repeated for each crystal inside the module. Then the module is repeated along the Z axis and the block is repeated 6 times around the center of the scanner.

Fig. 2.24 shows the final OPET scanner.

## 2.5. Moving a volume¶

The GEANT geometry architecture requires the geometry to be static during a simulation. However, the typical duration of a single event (e.g. ps for the particle transport, µs for scintillation, or ms for the response of the electronics) is very short when compared to most of the geometrical changes to be modeled (e.g. movements of the phantom or of the detector or bio-kinetics). Therefore, the elements of the geometry are considered to be at rest during each time-step. Between every time-step, the position and the orientation of a subset of daughter volumes can be changed to mimic a movement such as a rotation or a translation. These displacements are parametrized by their velocity. Hence, the amplitude of the volume displacement is deduced from the duration of the time-step multiplied by the velocity of the displacement.

Given the speed of the components of the geometry, it is the responsibility of the user to set the time step duration short enough in order to produce smooth changes.

A volume can be moved during a simulation using five types of motion: rotation, translation, orbiting, wobbling and eccentric rotation, as explained below.

### 2.5.1. Translation¶

To translate a Name_Volume volume during the simulation, the commands are:

/gate/Name_Volume/moves/insert translation
/gate/Name_Volume/translation/setSpeed x 0 0 cm/s


where x is the speed of translation and the translation is performed along the X axis. These commands can be useful to simulate table motion during a scan for instance.

• Example:

/gate/Table/moves/insert           translation
/gate/Table/translation/setSpeed   0 0 1 cm/s


The Table volume is translated along the Z axis with a speed of 1 cm per second.

### 2.5.2. Rotation¶

To rotate a Name_Volume volume around an axis during the simulation, with a speed of N degrees per second, the commands are:

/gate/Name_Volume/moves/insert rotation
/gate/Name_Volume/rotation/setSpeed N deg/s
/gate/Name_Volume/rotation/setAxis 0 y 0

• Example:

/gate/Phantom/moves/insert         rotation
/gate/Phantom/rotation/setSpeed    1 deg/s
/gate/Phantom/rotation/setAxis     0 1 0


The Phantom volume rotates around the Y axis with a speed of 1 degree per second.

### 2.5.3. Orbiting¶

Rotating a volume around any axis during a simulation is possible using the orbiting motion. This motion is needed to model the camera head rotation in SPECT. To rotate the Name_Volume volume around the X axis with a speed of N degrees per second, the commands are:

/gate/SPECThead/moves/insert orbiting


The last two commands define the rotation axis.

It is possible to enable or disable the volume auto-rotation option using:

/gate/Name_Volume/orbiting/enableAutoRotation
/gate/Name_Volume/orbiting/disableAutoRotation


Example:

/gate/camera_head/moves/insert            orbiting


The camera_head volume is rotated around the Z axis during the simulation with a speed of 1 degree per second.

### 2.5.4. Wobbling¶

The wobbling motion enables an oscillating translation movement to the volume.

This motion is needed to mimic the behavior of certain PET scanners that wobble to increase the spatial sampling of the data during the acquisition.

The movement that is modeled is defined by $$dM(t) = A . sin (2.PI.f.t + phi)$$ where dM(t) is the translation vector at time t, A is the maximum displacement vector, f is the movement frequency, phi is the phase at t=0, and t is the time.

To set the parameters of that equation, use:

/gate/Name_Volume/moves/insert osc-trans


To set the amplitude vector of the oscillating translation:

/gate/Name_Volume/osc-trans/setAmplitude x. 0. 0. cm


To set the frequency of the oscillating translation:

/gate/Name_Volume/osc-trans/setFrequency N Hz


To set the period of the oscillating translation:

/gate/Name_Volume/osc-trans/setPeriod N s


To set the phase at t=0 of the oscillating translation:

/gate/Name_Volume/osc-trans/setPhase N deg

• Example:

/gate/crystal/moves/insert               osc-trans
/gate/crystal/osc-trans/setAmplitude     10. 0. 0. cm
/gate/crystal/osc-trans/setFrequency     50 Hz
/gate/crystal/osc-trans/setPeriod        1 s
/gate/crystal/osc-trans/setPhase         90 deg


In this example, the movement that is modeled is defined by $$dM(t) = 10 . sin (100.PI.t + 90)$$

### 2.5.5. Eccentric rotation¶

The eccentric rotation motion enables an eccentric rotation movement of the volume. It is a particular case of the orbiting movement. To set the object in eccentric position (X-Y-Z) and rotate it around the OZ lab frame axis, use:

/gate/Name_Volume/moves/insert eccent-rot


To set the shifts in the X-Y-Z directions:

/gate/Name_Volume/eccent-rot/setShiftXYZ x y z cm


To set the orbiting angular speed:

/gate/Name_Volume/eccent-rot/setSpeed N deg/s


Remark: This particular move is closely related to the LMF definition since the move parameters (shifts in all 3 directions and angular speed) are propagated in the .cch header.

• Example:

/gate/crystal/moves/insert                 eccent-rot
/gate/crystal/eccent-rot/setShiftXYZ       5. 0. 0. cm
/gate/crystal/eccent-rot/setSpeed          10 deg/s


The crystal volume is placed at 10 cm, 0 cm and 0 cm from the center of its mother volume and will rotate around the Z axis during the simulation with a speed of 10 degrees per second.

### 2.5.6. Generic move¶

A volume can be move at given time value thanks to the following macros:

/gate/myvolume/moves/insert                       genericMove
/gate/myvolume/genericMove/setPlacementsFilename  data/myvolume.placements


In the same idea than Generic repeater, the placements file contains the transformations (rotation, translation) and the time value where this transformations is applied:

###### List of placement (translation and rotation) according to time
###### Column 1      is Time in s (second)
###### Column 2      is rotationAngle in degree
###### Columns 3,4,5 are rotation axis
###### Columns 6,7,8 are translation in mm
Time s
Rotation deg
Translation mm
0           0      0 1 0      0  0 100
250.7       3      0 1 0      0 10 100
492.9       4      0 1 0      0 20 100
742.9       8      0 1 0      30 0 100


WARNING. The time values given here do not necessarily correspond to simulation’s run. The real runs are defined with the time slices (see Eighth step: Starting an acquisition for example). At each new run, GATE looks into the time-placements list and chooses the one that corresponds to the starting time of the run. It leads that some placements can be not applied (if one run start before the placement time and the next run start after the next placement time). If run time is after the last placements time in the list, the last placements is applied.

See example GateRT

### 2.5.7. Generic repeater move¶

You can combine generic repeater and generic move to allow different repeated configurations according to time. This is for example useful to describe multi-leaf collimator from a single leaf which is repeated at different positions, and which move according to each beam:

/gate/myvolume/moves/insert                               genericRepeaterMove
/gate/myvolume/genericRepeaterMove/setPlacementsFilename  data/myvolume.placements
/gate/myvolume/genericRepeaterMove/useRelativeTranslation 1

###### List of placement (translation and rotation)
###### Column 1      is rotationAngle in degree
###### Columns 2,3,4 are rotation axis
###### Columns 5,6,7 are translation in mm
Time s
NumberOfPlacements 3
Rotation deg
Translation mm
#Time  # Placement 1             # Placement 2           # Placement 3
0      10  0 1 0  20  0  0       10 0 1 0   80  0  0     10 0 1 0    -60  0  0
1      20  0 1 0  20 10  0       20 0 1 0   80 10  0     20 0 1 0    -60 10  0
2      30  1 1 0  20  0  0       30 1 1 0   80  0  0     30 1 1 0    -60  0  0
4      40  0 1 1  20  0 40       40 0 1 1   80  0 40     40 0 1 1    -60  0 40


The ‘NumberOfPlacements’ is needed to indicate how many different repetition are performed at each motion.

## 2.6. Updating the geometry¶

Updating the geometry is needed to take into account any change in the geometry. It also refreshes the display window. The geometry can be updated with the following command:

/gate/geometry/rebuild