Parent-Child Bodies¶
Parent-child relationships let you track assemblies where multiple rigid parts are connected. The child body's pose is expressed relative to its parent, and motion constraints limit which degrees of freedom the child can move.
What Are Parent-Child Relationships?¶
In many real-world scenarios, tracked objects are not independent. A lid sits on a box, a tool is inserted into a holder, or parts of a mechanism move relative to each other. Parent-child relationships model these connections:
- The parent body is tracked independently in world space
- The child body's pose is defined relative to the parent
- Tracked Motion flags limit which degrees of freedom the child body tracks
Use Cases¶
| Scenario | Parent | Child |
|---|---|---|
| Product with lid | Box | Lid |
| Tool in holder | Holder | Tool |
| Articulated mechanism | Base | Moving part |
| Multi-part assembly | Main body | Sub-component |
Setting Up Parent-Child in Unity¶
1. Create the TrackedBodies¶
Add a TrackedBody component for each rigid part. Each body needs its own mesh (and a tracking model if using silhouette tracking).
2. Hierarchy¶
Make the child TrackedBody's GameObject a child of the parent TrackedBody's GameObject in the Unity hierarchy. The parent reference is established through the hierarchy.
3. Configure Tracked Motion¶
The Tracked Motion setting on the child body controls which degrees of freedom are active relative to the parent. It uses a flags enum:
| Flag | Description |
|---|---|
| None | Rigidly attached to parent (0 DoF) |
| Rotation X | Can rotate around the local X axis |
| Rotation Y | Can rotate around the local Y axis |
| Rotation Z | Can rotate around the local Z axis |
| Translation X | Can translate along the local X axis |
| Translation Y | Can translate along the local Y axis |
| Translation Z | Can translate along the local Z axis |
Combine flags for multi-DoF joints. For example, a hinge allows Rotation Z only. A slider allows Translation X only.
Note
When Tracked Motion is set to None, the child is rigidly fixed to the parent — both bodies move as a single unit. This is useful when you want separate tracking models for different parts of a complex object but they don't move relative to each other.
4. Occlude Parent¶
Enable Occlude Parent on the child body if the child frequently blocks part of the parent in the camera view. This tells the tracker to account for the child's geometry when tracking the parent.
How It Works¶
- The parent body is tracked normally against the camera image
- The child body is also tracked against the image, but only the enabled degrees of freedom are optimized
- The constrained axes are held relative to the parent's pose
Example: Box with Lid¶
Scene Hierarchy:
├── XRTrackerManager
├── Box (TrackedBody)
│ └── Lid (TrackedBody, TrackedMotion = RotationZ)
The lid's TrackedBody has Rotation Z enabled — it can only rotate open and closed relative to the box along one axis.
Existence Check (Is the Child Present?)¶
A child body's Tracking Quality tells you whether the child is actually where it's expected to be. This acts as a presence or existence check:
- High quality — the child's mesh matches the image at its expected position relative to the parent. The part is present.
- Low quality — the image doesn't match what the tracker expects. The part is likely missing, removed, or displaced.
For example, if a lid is expected on a box but has been removed, the lid's tracking quality will drop because the tracker can't find a visual match at that position. Your application can read TrackingQuality on the child body and react accordingly — show a warning, trigger an event, or update UI.
This is especially useful with Tracked Motion = None (rigidly attached children). The child's position is fully determined by the parent, so tracking quality purely reflects whether the part is visually present at that location.
Tips¶
- Start with independent tracking before adding parent-child — verify each body tracks well on its own
- None motion is useful for complex objects that benefit from separate tracking models for different visual features
- The parent must be tracked successfully for the child's constraint to be meaningful — if the parent is lost, the child's world pose will be unreliable
- Enable Occlude Parent when the child body frequently overlaps the parent in the camera view