# 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.