Framework Integration & Connected Proxy Representations

Overview

The uprops library serves as the core foundation for property management, transform synchronization, 3D visualization, and Python bindings across the entire framework.

uprops (Zero-Dependency Engine)
  │
  ├── mutomCore (uLib::Object derives from uprops::PropertyContainer)
  │     │
  │     ├── mutomMath (TRS Transform System: ContainerBox, Cylinder)
  │     │     │
  │     │     ├── mutomDetectors (Detector Geometry & Positioning)
  │     │     │
  │     │     ├── mutomGeant (Geant4 Solids & Physical Volumes)
  │     │     │
  │     │     └── mutomVtk (Prop3D, Viewport, Gizmos, Selection)
  │     │           │
  │     │           └── app/gcompose (Qt GUI Property Widgets)
  │     │
  │     └── uLib_python (Pybind11 Wrappers for Python Proxy Clients)

---

uLib::Object & uLib::Property<T>

uLib::Object derives from uprops::PropertyContainer.

uLib::Property<T> multiple-inherits from uLib::Object and uprops::Property<T>:

namespace uLib {

template <typename T>
class Property : public Object, public uprops::Property<T> {
public:
    Property(Object* owner, const std::string& name, T* valuePtr, 
             const std::string& units = "", const std::string& group = "")
        : uprops::Property<T>(owner, name, valuePtr, units, group), m_owner_obj(owner) {}

    virtual void PropertyUpdated() override {
        uprops::Property<T>::PropertyUpdated(); // Publish to LocalSignalBackend
        this->Object::Updated();                 // Emit uLib::Object::Updated signal
    }
};

} // namespace uLib

---

TRS (Transform) Real-Time Synchronization Pipeline

The TRS class (src/Math/Transform.h) encapsulates Translation (Position), Rotation (Rotation), and Scale (Scale) using FunctionalProperty<Vector3f>.

Real-Time Bidirectional Flow

graph TD
    subgraph Viewport ["3D Viewport Interaction"]
        Gizmo["vtkHandlerWidget (3D Gizmo)"]
        Prop3D["uLib::Prop3D / vtkContainerBox / vtkCylinder"]
    end

    subgraph Domain ["Domain C++ Model"]
        Model["ContainerBox / Cylinder / BoxSolid (TRS)"]
        Pos["Position Property (FunctionalProperty<Vector3f>)"]
        Rot["Rotation Property (FunctionalProperty<Vector3f>)"]
        Scl["Scale Property (FunctionalProperty<Vector3f>)"]
    end

    subgraph UI ["Qt GUI (gcompose)"]
        Panel["PropertyEditor / PropertyWidgets"]
        Widgets["VectorPropertyWidget (X, Y, Z LineEdits)"]
    end

    Gizmo -- Drag Handle --> Prop3D
    Prop3D -- SyncFromVtk() --> Model
    Model -- FromMatrix() -> Update() --> Pos & Rot & Scl
    Pos & Rot & Scl -- LocalSignalBackend::PublishChange() --> Widgets
    Widgets -- refresh UI --> Panel

    Panel -- Type New Value --> Widgets
    Widgets -- prop->Set(val) --> Pos & Rot & Scl
    Pos & Rot & Scl -- SetPosition() -> Update() --> Model
    Model -- Object::Updated --> Prop3D
    Prop3D -- ApplyTransform() --> Gizmo

---

Python Proxy Client Integration

Through uLib_python (built using pybind11), Python clients can inspect, manipulate, or create proxy representations for connected uprops objects:

import uLib_python as ulib

# Instantiate a ContainerBox
box = ulib.ContainerBox(ulib.Vector3f(1.0, 2.0, 3.0))

# Inspect properties via uprops container
props = box.GetProperties()
for p in props:
    print(f"Property: {p.GetName()}, Group: {p.GetGroup()}, Value: {p.GetValueAsString()}")

# Set Position property (triggers real-time update across connected C++ GUI and VTK viewports)
box.Position = ulib.Vector3f(10.0, 0.0, 5.0)