uLib/docs/geant_integration.md

Geant integration

Geant4 integration in uLib is done through the HEP/Geant module. The module represets a set of wrapper for geant objects that are also deriving from uLib::Object so they can be used in the uLib::Object tree and visualized with the uLib::Vtk module and driven py properties.

Geant Solid Integration

Geant4 solids in uLib are encapsulated within the uLib::Geant::Solid hierarchy, with primary implementations such as BoxSolid and TessellatedSolid. These classes act as reactive wrappers around native Geant4 G4VSolid objects, bridging the gap between Geant4's static geometry and uLib's dynamic property system.

Property Mapping and Synchronization

The integration relies on a mapping between uLib properties and Geant4 parameters. This allows geometry to be driven by Qt-based property panels or interactive VTK handles. When a property is modified, the library handles the update through the following mechanism:

• Parameter Application: If the underlying Geant4 object supports dynamic updates (e.g., changing box dimensions via SetXHalfLength), uLib applies the change directly to the existing object.
• Solid Re-instantiation: In cases where Geant4 does not support on-the-fly parameter changes, the library transparently recreates the underlying G4VSolid. This ensures that the simulation model always reflects the current state of the design environment.
• Global Signaling: Once the underlying Geant4 state is synchronized, the uLib::Geant::Solid emits an updated() signal. This triggers cascading updates across all dependent observers, such as the VTK rendering pipeline and the Geant4 scene manager, ensuring visual and logical consistency.

VTK Visualization Layer

The visualization of Geant4 solids in VTK is managed by the uLib::Vtk::GeantSolid class and its specializations (e.g., vtkBoxSolid). This class serves as a bridge between the domain model (uLib::Geant::Solid) and the VTK rendering pipeline, inheriting from uLib::Vtk::Prop3D to leverage the framework's standard transformation and property management features.

Geometry Extraction and Rendering

Since Geant4 solids are defined by analytical or tessellated boundary representations, GeantSolid converts them into a format suitable for VTK:

1. Faceted Representation: It retrieves the G4Polyhedron tessellation from the underlying G4VSolid.
2. PolyData Mapping: The vertices and facets of the polyhedron are extracted and mapped to a vtkPolyData object.
3. Actor Configuration: This geometry is assigned to a vtkActor, which is then added to the Prop3D. Default visual properties—such as semi-transparent surfaces and edge visibility—are applied to aid in debugging and design.

Transform Synchronization

The spatial state (Translation, Rotation, and Scale) is synchronized between the Geant4 geometry tree and the VTK viewer ensuring a consistent representation across both domains.

• Geant4 to VTK (Forward): When a solid's placement is updated in Geant4, GeantSolid extracts the translation and rotation from the associated G4VPhysicalVolume. These are converted into a vtkTransform and applied to the actor, aligning the visual model with the simulation's coordinate system.
• VTK to Geant4 (Interactive): Interaction in the viewer (e.g., using a transformation handler) triggers the SyncFromVtk() method. This pushes the new transformation matrix back to the uLib::Geant::Solid domain object, which then updates the Geant4 physical volume.
• Feedback Loop Prevention: To avoid infinite recursion during interactive updates, the synchronization logic utilizes temporary signal blocking. This ensures that a transform update originating from VTK does not trigger a redundant re-update of the VTK representation from the domain model.