KAHIBARO
9.6. Debugging with Visualization
Table of Contents
Missing volumes
Visualization is one of your most effective tools for catching geometric mistakes early. When a volume does not appear in the viewer, always assume a geometry problem first, not a physics or source problem. The key idea is to compare what you see with what you think you created from the Python script.
A missing volume is typically caused by one of a few issues: the volume was never added to the simulation, it has zero or negative dimensions, its parent volume is missing or too small, its material is invalid, or it is outside the visible region.
Start by confirming that the volume is actually defined and inserted into the simulation object. In GATE with Python, you usually create a volume with a call that returns a volume handle, then you set its properties. If you reuse a variable name or forget to assign the returned object, the volume might never be registered. Make sure each key detector or phantom volume has a unique and recognizable name. Then, in visualization, check the logical tree or list of volumes if available. If the viewer shows the world but not your detector, the problem is almost always in the way you created or attached that volume.
Next, look at the size of the parent volume, often the world. If the world is too small, child volumes may either be clipped visually or may cause the simulation to abort at initialization. Set the world dimensions so that all subvolumes comfortably fit inside, then regenerate and visualize. If the world is correctly defined but a child volume still does not appear, examine that child’s dimensions. If any dimension is zero or negative, the volume is invalid and will not be created. This can happen when you use computed parameters, such as subtracting margins, and the result becomes nonphysical.
Material assignment can also make a volume appear missing. If a material name is incorrect or not known to Geant4, the volume definition can fail. Check that you use valid material names and that any custom materials are defined before the volume that uses them. In some viewers, a volume whose material is not set might default to the same color as the surrounding medium and be visually indistinguishable. To avoid this, assign distinct colors to key volumes for debugging and temporarily increase opacity so they stand out.
Camera settings and clipping planes can hide volumes as well. If the camera is zoomed very close to the origin, far volumes might be out of the view. Use rotation and zoom to explore the scene systematically. Try zooming out until you see the world boundary, then slowly zoom in to search for your detectors or phantoms. Also, if the viewer supports it, enable drawing of coordinate axes to orient yourself relative to your intended positions.
If the volume is generated programmatically, for example inside a loop that creates arrays of detectors, it might fail only for particular indices because of a miscalculated position or size. In that case, temporarily limit the loop to a single instance, visualize, and incrementally increase the number. Each new visualization step lets you confirm the appearance of additional modules. This progressive approach isolates the first index at which something goes wrong.
Finally, if all else fails, simplify the geometry. Temporarily comment out most volumes, keep only the world and the problematic volume, and visualize. If it appears in this minimal setup, the problem is likely an interaction with other geometry or with the world definition. If it still does not appear, the error lies in its own definition, dimensions, parenting, or material.
A volume that is not clearly visible is effectively not part of your simulation. Always ensure every important detector, phantom, or shield is visible, has a sensible size, lies inside its parent, and has a valid material.
Incorrect placement
Even when all volumes appear, they may not be where you expect. Incorrect placement can completely change the physics outcome, for example placing a source behind shielding instead of in front, or misaligning a detector ring. Visualization makes such problems obvious once you know what to look for.
First, use visualization to check spatial relations instead of focusing only on absolute coordinates. Ask whether the source is inside the phantom, whether the detector fully covers the region of interest, and whether collimators or shields sit in the correct order along the particle path. Rotate the camera around different axes and inspect your setup from multiple views, especially along the main axes (x, y, z). A placement that looks correct from one angle can be clearly wrong from another.
Coordinate sign errors are common. For example, you may intend to place a detector at positive $z$ but mistakenly use a negative value. A quick way to diagnose this is to turn on coordinate axes in the viewer or place a tiny marker volume at the origin with a bright color. Then compare the relative direction of your components to the axes. If the detector appears mirrored or inverted, check your position definitions and any sign conventions in the script.
Another frequent issue is mixing units or forgetting them. In GATE, positions and sizes are unit aware, so you must multiply by the appropriate unit, such as 10 cm or 50 mm. If you accidentally write a bare number without units, it may be interpreted in default internal units and become extremely small or large. In visualization, this shows up as volumes tightly packed at the origin or far away from the world. Carefully review each position and size and verify that it uses a unit consistent with the rest of the geometry.
Misinterpretation of rotation and orientation can also lead to incorrect placement. When you use rotation matrices or Euler angles, it is easy to swap axes or apply rotations in the wrong order. In visualization, your detector might be rotated by 90 degrees or around the wrong axis. To debug this, start with no rotation, confirm that the volume appears in the correct basic position, then add rotation step by step. Each visualization update lets you see the effect of a single transformation. If your geometry uses repeated modules around a ring, verify that the first module is correctly placed before duplicating it around the circle.
If you are using relative placements, where a child volume is placed inside a parent using coordinates relative to the parent center, incorrect assumptions about the parent origin can cause offsets. Visualization helps here, since you can look at the parent and child together. If the child is shifted relative to the intended region inside its parent, recheck the parent’s origin and size. Sometimes the parent is not centered at the world origin, which you may overlook when computing child positions.
When building repeated structures such as arrays of crystals or detectors, an off by one error in indices or spacing can result in overlaps or gaps. In the viewer, count the number of repeated elements along each axis and compare with your loop parameters. If you see a gap at one edge or an extra element overlapping the parent boundary, adjust the step size or number of elements. Temporarily increase the spacing for debugging so that each volume is clearly separated and easier to inspect.
Finally, verify that all placements use the same coordinate system convention. When importing geometry from images or external data, axes may be swapped or inverted compared to your mental model. Visualizing a simple reference object, such as a box that represents a patient table or a phantom support, can help you see if your imported volume aligns with your existing geometry or if it is flipped or shifted.
Incorrect placement can silently invalidate a simulation result. Always use visualization to confirm not only that volumes exist, but also that they occupy the correct positions and orientations relative to sources, detectors, and phantoms.
Geometry overlap
Geometry overlaps occur when two or more volumes occupy the same physical space in a way that violates the requirement that daughter volumes in a given mother volume must not intersect. Overlaps can cause undefined particle transport, strange energy deposition patterns, and even simulation crashes. Visualization is essential for detecting and correcting these issues.
In the viewer, overlaps often appear as volumes that seem to interpenetrate, for example one detector crystal partly inside another, or a shield cutting through a phantom. To make overlaps easier to spot, assign contrasting colors to neighboring volumes and use semi-transparent rendering for at least one of them. Then, slowly rotate around the suspected region and zoom in to examine boundaries. If you see surfaces crossing inside one another, there is an overlap.
Most visualization tools based on Geant4 can also highlight overlaps using a dedicated geometry check. Typically, this function samples points on the surfaces of volumes and tests if they lie inside neighboring solids. You can use it to automatically detect which pairs of volumes are in conflict. The resulting messages often reference the names of the problematic volumes and the estimated overlap distance. Once you know the volume names, you can return to your GATE script and inspect their dimensions and placement.
Several typical design patterns lead to overlaps. One is incorrect spacing in regular arrays. If the distance between centers of repeated volumes is smaller than the sum of their half sizes, they will overlap. In visualization, this appears as crystals or pixels that intersect at their faces or corners. To fix this, compute the spacing from the volume dimensions plus an optional gap, and verify it numerically. For instance, if each crystal has a width $w$ and you want no gap, the center to center distance should be exactly $w$.
Another frequent source of overlaps is using exact border placements without accounting for finite precision. If you place two boxes in direct contact by setting one edge to be exactly equal to another, numerical rounding in floating point arithmetic can create tiny negative or positive overlaps. In practice, it is safer to leave a very small gap, such as $1 \,\mu\text{m}$, between neighboring volumes. In visualization, such a small gap is invisible but is enough to avoid overlap warnings.
Parent and child dimensions must also be consistent. A child volume that is larger than its parent will overlap the parent’s boundaries. For instance, a detector block might extend outside its housing or a phantom might stick out of the world volume. In the viewer, you can often see parts of a child volume emerging from the parent. Compare the parent’s size with the maximum extent of its children and adjust either the parent dimensions or the child positions. Always ensure that each child fits entirely within its mother volume.
Complex or boolean solids increase the risk of overlaps because their effective shapes are less intuitive. When you use union, intersection, or subtraction to build shapes, visually inspect the result alone before integrating it into the full geometry. If a boolean solid is then placed close to another solid, ensure that the combined shapes do not overlap unintentionally. Visualization with high contrast colors and semi-transparency is very helpful here, especially when examining cutouts, holes, and supports.
Be aware that some overlap problems only become obvious when you enable tracks visualization. For example, if particles repeatedly change material over a very short distance or show abnormal scattering in a narrow region, that region might contain overlapping volumes. Drawing a subset of particle tracks, especially for a simple source, can reveal suspicious zigzags or sudden direction changes at boundaries. Once you suspect a problematic region, zoom in on that area and look for volumes that intersect.
After you correct a suspected overlap in the script, always rerun the geometry check and revisualize. Small shifts or size changes can create new overlaps elsewhere, especially in tightly packed detectors or complex assemblies. Take a systematic approach: fix one family of volumes at a time, then verify again.
Valid geometry requires that daughter volumes in a given mother volume do not overlap. Use visualization, automatic overlap checks, and careful inspection of dimensions and spacing to eliminate all overlaps before trusting your simulation results.
Views: 9