KAHIBARO
43.2. Geometry Problems
Table of Contents
Missing volumes
In GATE, geometry is entirely defined by your Python code. When a volume is missing, you usually see one of three symptoms. First, interactive or batch visualization shows only the world or a subset of the geometry. Second, actors that should record in that volume produce empty or incomplete output. Third, Geant4 reports that a particle is in an unexpected logical volume, often the world or its parent instead of the intended child.
The most common cause is that a volume was never actually created or was created in a separate function but not attached to the correct parent. In OpenGATE, every volume must have a parent that either is the world or another already existing volume. If you accidentally give a wrong parent name, GATE silently attaches it to a different volume or fails to place it as intended. Carefully check that the parent volume name in your code matches exactly the name you used when defining that parent. Pay attention to typos and case sensitivity. Also verify that the parent is created before the child, for instance by checking the order of your geometry functions.
Another frequent problem is a volume with zero or nonsensical dimensions. If you accidentally set one dimension to zero or a negative value, the solid collapses and you will not see it in visualization. Similarly, units are crucial. A box defined with side length 10 instead of $10 * \mathrm{mm}$ will be interpreted as 10 meters, which may fill or exceed the world volume and hide other geometry. Always confirm that every length, angle, and position has an explicit unit, and that the world size is larger than all its children.
Sometimes the volume exists but appears to be missing because of visualization settings. If a volume is fully transparent or its visibility is turned off for the chosen visualization driver, it will not appear even though it is present in the simulation. Use the geometry visualization tools to enable visibility of all volumes and adjust colors and transparency to something clearly visible. Rotate and zoom the view to ensure that the volume is not hidden behind other structures.
If actors or digitizers seem to ignore a volume, confirm that the name of the volume in the actor configuration matches the one used in the geometry. For example, if you attach a dose actor to "phantom" but the actual volume is named "water_phantom," the actor will not record in that region. A reliable way to verify existence is to list all volumes from the simulation object or inspect the printed geometry summary. This often reveals missing or misnamed components.
Whenever you suspect missing volumes, a systematic check helps. Inspect the world size, verify that all child volumes have positive dimensions with correct units, ensure that parent-child relationships and naming are consistent, and use visualization to confirm what the particle transport sees, not what you expect to see.
Incorrect positions
Incorrect positions do not usually stop the simulation, but they can completely invalidate your results. Typical symptoms include detectors that appear to be behind the source instead of in front, patient or phantom volumes that intersect with the detector unexpectedly, or phase-space or dose actors that record in the wrong region. In more subtle cases, your images or dose distributions look shifted or mirrored compared to reference data.
The root of most position problems is confusion between coordinate systems. GATE uses a global Cartesian coordinate system with X, Y, and Z axes. Volumes are placed relative to their parent volume, not necessarily the world. That means the position is defined in the parent coordinate system. If you assume global coordinates while you are actually inside a nested hierarchy, the volume will end up displaced. Always verify whether the position you pass is relative to the world or to an intermediate parent.
Another frequent source of error is the confusion of axis ordering. It is easy to accidentally swap Y and Z, especially when translating from documentation or images that use a different convention. For example, if your design places detectors along the axial direction but you mistakenly change the Y coordinate instead of Z, the whole ring or array can be rotated by 90 degrees compared to what you intended. When placing arrays or rings, check a few known points: one detector at zero angle, one at 90 degrees, and confirm their coordinates match the intended geometry.
Unit mistakes also appear as position errors. A translation of 10, interpreted as 10 meters instead of 10 millimeters, moves a volume far out of the expected field of view. The volume still exists but appears to be missing or extremely far away in visualization. To avoid this, treat every positional value with units just like dimensions. For example, use $10 \mathrm{mm}$ or $5 \mathrm{cm}$ explicitly and never rely on bare numbers.
Coordinate conversions from images or patient data are particularly error prone. When working with voxelized geometry or DICOM data, the image origin, spacing, and orientation often differ from the GATE world coordinates. If you map the image indices directly to X, Y, Z without converting using the image header information, the patient or phantom can appear translated or mirrored. Ensure that you correctly interpret the image coordinate system and apply the necessary transforms so that, for example, the patient head is at positive Z if that is what your simulation expects.
Visualization is the fastest way to reveal incorrect positions. Enable the display of critical volumes like sources, detectors, and phantoms, and explore the scene with rotation and zoom. Check distances numerically by printing the positions you used in code and compare them with what visualization shows. If you find systematic shifts, isolate the transformation that produces the error, such as a sign error or missing offset.
Always specify positions with explicit units, verify whether coordinates are in the parent or world reference frame, and carefully check axis ordering to avoid incorrect placements that silently corrupt your simulation.
Overlaps
Geometry overlaps happen when two or more volumes occupy the same space in a way that violates the Geant4 placement rules. An overlap can cause particles to start or propagate inside ambiguous regions, which leads to unphysical results and difficult to interpret bugs. GATE helps you detect these problems, but you need to understand what overlap messages mean and how to respond.
You typically encounter overlaps through warnings printed by Geant4 when the geometry is initialized. These warnings may mention overlapping or touching volumes and sometimes give the names of the volumes involved, together with an estimated overlap size. In some cases, overlaps do not produce clear warnings but instead lead to unpredictable transport behavior, such as particles occasionally skipping a boundary or depositing energy in the wrong volume.
The primary cause of overlaps is incorrect positioning relative to parent and sibling volumes. If two children of the same parent are placed so that their boundaries intersect, Geant4 cannot uniquely assign points at the intersection to one or the other. Small mistakes in distance calculations, especially when using manual loops or custom formulas for detector arrays, are common. For example, if you pack crystals into a block using a pitch equal to the crystal size but forget to account for a small gap, the last crystal may extend beyond the intended boundary and overlap its neighbor or the block envelope.
Another cause is too small parent volumes. If you define a child volume inside a parent but give it dimensions larger than the parent, the child extends outside and may overlap other structures that happen to be near the boundary. Always ensure that each child fits fully inside its parent, with some margin if you plan to add multiple children. It can help to compute parent dimensions from the number and size of children, rather than hard coding both.
Rotations also play a role. When you rotate a volume, its bounding box relative to the parent changes. If you place multiple rotated copies using placements that assume no rotation, the corners may overlap. This is especially relevant for ring or polygon arrangements and for slanted components like certain collimators. Visualizing the rotated geometry is very useful here. When debugging, simplify the setup by placing only a few copies at representative angles and check for overlaps before you generate the full array.
Geant4 provides an overlap check that shoots random points inside volumes to see if they intrude into siblings or parents. In GATE, enable geometry checks so that overlaps are reported during initialization. If you receive messages, read them carefully to identify which volumes are affected and by how much. Very tiny overlap distances can be numerical artifacts, but consistent or large overlaps nearly always signal a real geometry problem that must be fixed.
Units and rounding errors can also create overlaps. For example, if you compute a pitch as the sum of two floating point lengths and then repeat it many times, accumulated rounding can make the last element slightly intrude past the intended boundary. Using exact arithmetic when possible, or adding a tiny safety gap between volumes, often resolves that. However, do not rely on gaps that are so small that Geant4 cannot robustly distinguish surfaces.
A systematic strategy for overlap debugging is to reduce complexity. Temporarily remove most volumes and keep only the suspect region. Visualize it and run the overlap check. Adjust dimensions and positions until all warnings disappear. Then gradually reintroduce other parts of the geometry, checking at every step. This modular approach prevents you from getting lost in a large number of simultaneous overlap messages.
A valid GATE geometry must have no significant overlaps. Always run geometry overlap checks after changes, ensure children fit entirely inside their parents, and verify that repeated and rotated volumes do not intersect.
Views: 10