refactor: improve Geant4 solid synchronization and update documentation for VTK integration

docs/geant_integration.md

@@ -3,9 +3,32 @@
 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
+# 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.
 
-Geant solid in uLib is represented by the `uLib::Geant::Solid` class and mainly BoxSolid and TessellatedSolid. The solids in Geant does not have the possibility to set properties on the fly so we need to create a new solid every time we want to change the properties of a solid. This is done by creating a new `uLib::Geant::Solid` object and setting the properties of the new solid. The new solid is then added to the `uLib::Geant::Solid` object as a child. The old solid is then removed from the `uLib::Geant::Solid` object as a child. The old solid is then deleted. However id some of the properties can be set then the library will drive the change in the solid update.
 
-The idea is to have a mapping of solid properties that can be used in uLib for Qt representation or vtk representation. then when the property is changed the signaling will update the property in uLib and then the solid will be updated. If the Geant property can be applied to the G4 object underneath then the update will apply the change, in case it is not possible to apply the change to the G4 object underneath then the G4 element will be recreated. 
-In any case a updated singal is emitted and the related element that use that solid is updated ( for instance the scene ).

src/HEP/Geant/Solid.cpp

@@ -107,6 +107,8 @@ void Solid::SetTransform(Matrix4f transform) {
     }
 
     std::cout << "Solid " << GetName() << " position: " << pos << " rotation: " << m << std::endl;
+
+    this->Updated();
 }
 
 void Solid::SetParent(Solid *parent) {
@@ -181,11 +183,14 @@ void TessellatedSolid::Update() {
 BoxSolid::BoxSolid(const char *name) : 
     BaseClass(name), 
     m_ContainerBox(new ContainerBox()), 
-    m_Solid(new G4Box(name, 1, 1, 1))
-  {}
+    m_Solid(new G4Box(name, 0.5, 0.5, 0.5))
+  {
+    Object::connect(m_ContainerBox, &ContainerBox::Updated, this, &BoxSolid::Update);
+    Update();
+  }
 
 BoxSolid::BoxSolid(const char *name, ContainerBox *box) : BaseClass(name) {
-  m_Solid = new G4Box(name, 1, 1, 1);
+  m_Solid = new G4Box(name, 0.5, 0.5, 0.5);
   m_ContainerBox = box;
   Object::connect(box, &ContainerBox::Updated, this, &BoxSolid::Update);
   if (m_Logical) {

src/HEP/Geant/Solid.h

@@ -53,6 +53,7 @@ public:
   void SetMaterial(G4Material *material);
   
   void SetSizeUnit(const char *unit);
+  
   // Implementiamo SetParent qui, per tutti.
   virtual void SetParent(Solid *parent); 
 
@@ -71,11 +72,8 @@ public:
 
   template < typename Ar >
   void serialize(Ar &ar, const unsigned int version) {
-    ar & m_Name;
+    ar & boost::serialization::make_nvp("Name", m_Name);
   }
-    
-    
-
 
 protected:
 
@@ -123,6 +121,7 @@ public:
 
   BoxSolid(const char *name = "");
   BoxSolid(const char *name, ContainerBox *box);
+
   virtual G4VSolid* GetG4Solid() const override { return (G4VSolid*)m_Solid; }
   
   ContainerBox* GetObject() const { return m_ContainerBox; }

src/HEP/Geant/testing/SolidTest.cpp

@@ -25,6 +25,32 @@ int main() {
         TEST1(solid.GetMaterial()->GetName() == "G4_AIR");
     }
 
+    // Test BoxSolid //
+    {
+        Geant::BoxSolid boxsolid("test_boxsolid");
+        boxsolid.SetNistMaterial("G4_AIR");
+        TEST1(boxsolid.GetLogical() != nullptr);
+        // TEST1(boxsolid.GetSolid() != nullptr);
+    }
+
+    // Test BoxSolid with a container box //
+    {
+        ContainerBox box;
+        
+        // box.SetPosition(Vector3f(1,1,1));
+        // box.SetRotation(Rotation(Vector3f(0,1,0), 45_deg));
+        
+        Geant::BoxSolid boxsolid("test_boxsolid", &box);
+        boxsolid.SetNistMaterial("G4_AIR");
+        TEST1(boxsolid.GetLogical() != nullptr);
+        // TEST1(boxsolid.GetSolid() != nullptr);
+        // TEST1(boxsolid.GetSolid()->GetXHalfLength() == 0.5);
+        // TEST1(boxsolid.GetSolid()->GetYHalfLength() == 0.5);
+        // TEST1(boxsolid.GetSolid()->GetZHalfLength() == 0.5);
+
+        
+    }
+
     // Test TessellatedSolid with a simple mesh //
     {
         Geant::TessellatedSolid tsolid("test_tessellated");

src/Vtk/HEP/Geant/vtkBoxSolid.cpp

@@ -40,13 +40,15 @@ BoxSolid::~BoxSolid() {
 
 void BoxSolid::Update() {
   ConnectionBlock blocker(m_UpdateConnection);
-  this->UpdateGeometry();
-  // Ensure base Prop3D properties (color, opacity, etc) and transform are applied
+  // Ensure base GeantSolid logic (G4Polyhedron and Transform) runs
+  this->GeantSolid::Update();
+  // Ensure base Prop3D properties (color, opacity, etc) are applied
   this->Prop3D::Update();
 }
 
 void BoxSolid::SyncFromVtk() {
   this->Prop3D::SyncFromVtk();
+  
   if (auto* proxy = vtkProp3D::SafeDownCast(this->GetProxyProp())) {
       if (vtkMatrix4x4* mat = proxy->GetUserMatrix()) {
           m_BoxContent->SetTransform(VtkToMatrix4f(mat));
@@ -54,16 +56,6 @@ void BoxSolid::SyncFromVtk() {
   }
 }
 
-void BoxSolid::UpdateGeometry() {
-  // Sync geometry from G4VSolid provided by GeantSolid (tessellation)
-  GeantSolid::UpdateGeometry();
-}
-
-void BoxSolid::UpdateTransform() {
-  // Take transform from Prop3D base (which uses GetContent() -> ContainerBox TRS)
-  this->Prop3D::Update();
-}
-
 void BoxSolid::serialize_display(uLib::Archive::display_properties_archive &ar,
                                     const unsigned int version) {
   // Expose Geant solid properties and underlying Box/TRS properties

src/Vtk/HEP/Geant/vtkBoxSolid.h

@@ -49,8 +49,6 @@ public:
   virtual ~BoxSolid();
 
   virtual void Update() override;
-  virtual void UpdateGeometry() override;
-  virtual void UpdateTransform() override;
   virtual void SyncFromVtk() override;
 
   virtual uLib::Object *GetContent() const override {