uLib/.agents/skills/object_context.md

Skill: Object Context & Scene Management

Guidelines for managing the uLib object hierarchy, Geant4 volume instantiation, and Gcompose scene interaction.

1. Object Creation & Context

• Factory Pattern: Always use ObjectFactory to instantiate objects from the registry. Avoid direct new calls for domain objects to ensure proper metadata and property initialization.
• Context Ownership: The Context is the source of truth. Every persistent object must be registered within the Context to participate in the tree hierarchy, property system, and serialization.

2. Geant4: Logical vs. Physical Volumes

In the Geant4/HEP domain, visibility and placement follow a strict two-tier hierarchy:

• LogicalVolume: Defines what the object is (Solid/Shape, Material, and daughter volumes). It is a template and does not have a spatial position.
• PhysicalVolume: Defines where and how an instance exists. It references a LogicalVolume and holds the TRS (Translation, Rotation Matrix/Scale).
• CRITICAL: Adding a Solid or LogicalVolume to the scene is insufficient for visualization. To display an object in the VTK viewport, you must:
  1. Define the LogicalVolume.
  2. Instantiate a PhysicalVolume from that LogicalVolume.
  3. Add the PhysicalVolume to the scene context and apply TRS transformations to it.

3. Gcompose: Tree Hierarchy & Visualization

• 3D Representations: Objects with 3D actors are automatically wrapped in VTK representations (e.g., vtkContainerBox). Non-3D objects remain in the tree but have no viewport presence.
• Reference Handling:
  • Internal object references (raw pointers or SmartPointer) are rendered as "virtual children" in the tree.
  • Instance Re-use: One object can appear as a child under multiple parents if referenced multiple times; these are placeholders for the same underlying instance.
• Setting References:
  • Property Selector: Filter and select compatible types from the global context within the property editor.
  • Drag & Drop: Drag an object from the tree and drop it onto a property field. The system automatically validates types and performs the necessary casting/assignment.

4. Best Practices & Checks

• TRS Logic: Always apply transformations to the PhysicalVolume. Changes to a LogicalVolume will affect all its instances but will not move them.
• Dependency Tracking: Use the tree structure to identify shared references. Changing a property on a shared object affects all parent nodes that reference it.