KAHIBARO
Reusable Components
Table of Contents
Detector models
Reusable detector models let you describe a scanner or sensor once, then apply it in many simulations without rewriting geometry or digitizer code. In GATE with Python, a detector model is usually a Python function or class that, given a simulation object and some parameters, creates all needed volumes, assigns materials, adds IDs, and optionally attaches actors or digitizers.
The key idea is to separate the definition of a detector from the particular simulation that uses it. Instead of filling your main script with low level world, box, repetition, and material calls, you keep those details inside a detector function. Your main script then calls something like build_pet_ring(sim, config) or add_gamma_camera(sim, position).
When you design a reusable detector model, start by listing what should be fixed and what should be configurable. Fixed elements might be the material type, the logical hierarchy of crystals inside modules inside rings, or the presence of a collimator in a gamma camera. Configurable elements are typically sizes, counts, and performance parameters. Examples of configurable parameters include ring radius, number of crystals, crystal pitch, collimator length, hole diameter, and shielding thickness.
A good detector model exposes these parameters through a single configuration object such as a dictionary or a small class. This keeps the function signature short and makes it simple to modify the detector without touching the implementation. For instance, a PET block detector model could accept a configuration with entries for crystal size, number of crystals in axial and transaxial directions, crystal material, and whether to add optical properties or not.
Reusable detector functions should also standardize how detector identifiers are assigned. An important goal is that different simulations that use the same detector model produce hits and singles that encode detector IDs in the same way. For example, you might always use ring_id, module_id, and crystal_id fields, or always map these to a single packed integer. Keeping this consistent means analysis scripts and performance metrics do not need to be adapted for each new simulation.
Digitizer configuration can also be folded into detector models, but you must keep the interface clean. One approach is to have the detector function return both geometry information and the list of readout channels or volumes. The calling script can then configure the digitizer on top of that. Another approach is to allow an optional flag in the detector model configuration that tells the function to also define the digitizer chain with a standard energy and timing resolution. Whichever you choose, consistency across models is more important than the exact choice.
Visualization is a useful part of detector models. During development, it is helpful if the model provides optional debug visualization options such as colored subvolumes, axis markers, or volume name patterns. The model can, for instance, accept a debug_visualization flag that sets distinctive colors and transparencies for different detector components, which helps you see how crystals, modules, and shielding fit together.
When you reuse detector models for various applications, you often need to place multiple instances of the same detector in different positions or orientations. Make sure your model allows specifying the parent volume and a base position and rotation. The function should then create all internal children relative to that parent and transform. For example, you might place several identical gamma detector heads around a phantom at varying angles, all created by the same detector model function.
Finally, treat detector models as real software components. Give them descriptive names, add clear docstrings, and keep them in a dedicated Python module or package for detectors. This makes it easier to share them across projects, to version them, and to verify that different simulations really use the same implementation. Over time, you can build a small library of standard models, for instance "generic PET ring", "block-based PET module", "SPECT gamma camera head", or "simple scintillation spectrometer", and use them as building blocks in more complex studies.
Phantom models
Phantom models serve a similar purpose for objects that represent patients, test objects, or dose scoring volumes. A reusable phantom model is a function or class that creates realistic or standardized phantoms with configurable dimensions, material composition, and sometimes voxel structure, while hiding the low level volume and material definitions.
Analytical phantoms are the simplest case. These are built from basic shapes such as boxes, cylinders, and spheres. For reusable analytical phantom models, define functions that create commonly used test objects with parameters for size and material. Examples include water boxes for broad beam dose studies, cylindrical water phantoms for depth dose measurement, or multi layer slabs where each layer is a different material used for attenuation tests. The model function should take a parent volume, an origin, and a configuration that describes layer thicknesses, radii, and materials, and it should return references to the created volumes so you can later attach actors such as dose grids or energy deposition maps.
More advanced phantom models represent anthropomorphic shapes or image based phantoms. In these cases, the model is responsible for loading voxel data, mapping it to materials, and creating the voxelized geometry. A reusable voxel phantom model should hide details such as file formats, CT to material conversion, and region identification from the main script. You can, for example, write a function that takes a path to a CT file, a configuration describing Hounsfield unit to material mapping, and options for cropping or downsampling, and then returns a voxel volume ready to be used as the patient geometry.
To make image based phantom models truly reusable, separate the tasks of loading data, mapping to materials, and constructing the geometry. The phantom model can internally call helper functions such as "load image", "create material map", and "build voxel volume", but from the user perspective there is a single entry point. This approach lets you reuse the same mapping and geometry construction code for different data sets or projects, which increases reproducibility between simulations.
Standardized phantoms, like water equivalent cubes, IEC body phantoms, or head phantoms, are frequently used to compare simulations with experiments or other codes. When you model such phantoms, incorporate the official dimensions and known material settings into the phantom model itself. Keep the configuration parameters limited to things that are expected to vary, such as overall scale or rotation, and leave the reference values fixed. This helps ensure that when you use that phantom model in different studies, you are really simulating the same object.
Phantom models should be designed to integrate naturally with actors. A good pattern is that the phantom function returns both the top volume of the phantom and some metadata about regions of interest, such as a list of organ volume names or IDs. The caller can then attach dose or energy deposition actors to those regions automatically. This avoids hard coding volume names across scripts and keeps the link between geometry and scoring consistent.
As with detector models, clear documentation is essential. Each phantom model should state what it represents, what physical assumptions it uses, and which parameters are user adjustable. For voxel phantoms, document the expected input image orientation and coordinate conventions so that positioning relative to sources and detectors remains correct in every simulation that uses the model.
If you use the same phantom across multiple projects, store the phantom model and its CT to material mapping configuration in a shared, version controlled module. When you later update the mapping or correct a geometry bug, all simulations that rely on that phantom model can be updated in a controlled way by changing a single component, which supports reproducible and traceable simulation studies.
Views: 9