> For the complete documentation index, see [llms.txt](https://doc.ancoraspring.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.ancoraspring.com/asmagic/sensors-and-simulation/astriad/simulation.md).

# Place and Attach Frames

Attach an asTriad component to a robot scene or draw frames in a Python simulation loop.

asTriad renders visual coordinate frames with their origins at the sphere centers.

## Origin and placement

The sphere center is the coordinate origin. `size` sets its diameter in millimeters; position and offset values use meters. A world placement sets that center in world coordinates. An attachment places it in the target body's, geom's or site's local coordinates and follows its motion.

For a robot workflow with tool, world, target and object frames, see [Robot Experiments](https://doc.ancoraspring.com/asmagic/sensors-and-simulation/astriad/examples.md).

## Attach to an existing scene

Export the frame with the desired sphere diameter:

```bash
asTriad export --size 20 --output asTriad_20mm.xml
```

The component is centered at `(0, 0, 0)` in body `asTriad`. It supplies inline assets and a matte material; lighting and simulation settings come from the host scene. Its geoms have zero mass and contact masks set to zero.

Add the model to your scene's `<asset>`:

```xml
<asset>
  <model name="triad" file="asTriad_20mm.xml"/>
</asset>
```

Inside the target robot body, place it at the desired local pose:

```xml
<frame pos="0 0 0.03">
  <attach model="triad" body="asTriad" prefix="tool_"/>
</frame>
```

The imported frame follows the parent body. Use a unique prefix for each instance. [robot\_scene.xml](https://github.com/asMagicApp/asTraid/blob/v0.10.0/examples/robot_scene.xml) combines a fixed world frame and a frame on a hinged arm.

<figure><img src="https://3069436181-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiTOs5tBJUyhQCv2lbX6A%2Fuploads%2Fgit-blob-d7c1940199ccb78c770005ab7cbbec643386769c%2FasTriad-robot-scene.png?alt=media" alt="A fixed world coordinate frame beside a frame on a hinged arm"><figcaption><p>World and robot frames composed from the same XML component, rendered in native MuJoCo.</p></figcaption></figure>

Save the following scene beside `asTriad_20mm.xml`:

{% file src="/files/n3Mu328TVd73PrqrpiFw" %}
Hinged-arm scene with an attached asTriad component.
{% endfile %}

```bash
python -m mujoco.viewer --mjcf asTriad_robot_scene.xml
```

### Attach to a named site with Python

For a robot scene containing `tool_tip`:

```python
import mujoco

scene = mujoco.MjSpec.from_file("robot.xml")
triad = mujoco.MjSpec.from_file("asTriad_20mm.xml")
scene.attach(triad, prefix="tool_", site=scene.site("tool_tip"))
model = scene.compile()
```

The [attach\_xml.py](https://github.com/asMagicApp/asTraid/blob/v0.10.0/examples/attach_xml.py) helper saves the combined scene:

```bash
python examples/attach_xml.py robot.xml --triad asTriad_20mm.xml --site tool_tip
```

## Open in MuJoCo Live

Set **Sphere diameter** in the [online tool](https://ancoraspring.com/astriad/) and choose **Download MJCF**, or use the [20 mm sample](https://doc.ancoraspring.com/asmagic/sensors-and-simulation/astriad.md#open-in-mujoco-live). Use **Display settings** in the online tool to adjust its background and lighting. Drop the XML onto [MuJoCo Live](https://live.mujoco.org/). Rotate and zoom the view to inspect it.

Use **View → Editor** to edit numeric geometry fields and **Compile and Reload** to apply changes. For proportional resizing, export again with a new `--size` value, then load that XML.

In **Options → Visibility Groups**, use the following controls. Choose **Labels → Site** for the axis labels.

| Part          | Visibility control |
| ------------- | ------------------ |
| X arrow       | Geoms 0            |
| Y arrow       | Geoms 1            |
| Z arrow       | Geoms 2            |
| Origin sphere | Sites 0            |

The XML also opens locally in MuJoCo 3.3.7 or 4.0:

```bash
python -m mujoco.viewer --mjcf asTriad_20mm.xml
```

`--size` sets the sphere diameter in millimeters; exported MJCF lengths use meters. See the [official viewer documentation](https://mujoco.readthedocs.io/en/4.0.0/studio/web_viewers.html#mujoco-live) for model loading and controls.

## Included simulation

The package includes a complete gravity-and-contact example with a world frame, a body frame and a site frame:

{% tabs %}
{% tab title="macOS" %}

```bash
mjpython -m asTriad attached
```

{% endtab %}

{% tab title="Linux / Windows" %}

```bash
asTriad attached
```

{% endtab %}
{% endtabs %}

Use `mjpython` for MuJoCo's passive viewer on macOS.

<figure><img src="https://3069436181-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiTOs5tBJUyhQCv2lbX6A%2Fuploads%2Fgit-blob-20c66fbc88edc13db617b33cb7e30d39969431cc%2FasTriad-attachment.png?alt=media" alt="A fixed world coordinate frame beside a simulated box with body and site coordinate frames"><figcaption><p>World, body and site frames in MuJoCo.</p></figcaption></figure>

## Python overlay placement

| Placement         | Pose source                             | Example use                                            |
| ----------------- | --------------------------------------- | ------------------------------------------------------ |
| Fixed world frame | An explicit position and rotation       | A world origin, table reference or inspection location |
| `body` attachment | The body's local origin and orientation | A robot link or moving rigid object                    |
| `geom` attachment | The geom's own origin and orientation   | A visual or collision shape offset within a body       |
| `site` attachment | A named site's pose                     | A tool tip, grasp point or sensor reference            |

The following snippets assume `model` is your existing MuJoCo model.

```python
from asTriad import AsTriad

world = AsTriad(size=10, name="world", position=(0, 0, 0.02))
object_frame = AsTriad(size=10, name="object").attach(
    model, body="object", offset=(0, 0, 0.03)
)
tip_frame = AsTriad(size=6, name="tip").attach(model, site="tool_tip")
```

Use `geom="box"` to bind to a geom. Choose one target per attachment; names and numeric IDs are supported.

### Local offsets and rotation

`offset=(0, 0, 0.03)` places the origin **30 mm along the target's local Z axis** and rotates with the target. `rotation` is a 3×3 matrix mapping the triad's axes into the target's local coordinates.

```
world_position = target_position + target_rotation @ offset
world_rotation = target_rotation @ local_rotation
```

For a fixed frame, `rotation` maps directly into world coordinates. Its columns are the world directions of local X, Y and Z. Position and offset values use **meters**; `size` uses **millimeters**.

## Complete example

For robot models, see [UR5e experiments](https://doc.ancoraspring.com/asmagic/sensors-and-simulation/astriad/examples.md).

Save this as `show_frames.py`:

{% code title="show\_frames.py" lineNumbers="true" %}

```python
import time
import mujoco
import mujoco.viewer
from asTriad import AsTriad, TriadOverlay

model = mujoco.MjModel.from_xml_string("""
<mujoco>
  <option timestep="0.002"/>
  <worldbody>
    <light pos="0 -0.5 1" dir="0 0 -1"/>
    <geom type="plane" size="0.5 0.5 0.01"/>
    <body name="object" pos="0 0 0.10">
      <freejoint/>
      <geom name="box" type="box" size="0.025 0.025 0.025"
            mass="0.15" rgba="0.45 0.52 0.65 1"/>
      <site name="tool_tip" pos="0 0 0.025" size="0.001"/>
    </body>
  </worldbody>
</mujoco>
""")
data = mujoco.MjData(model)
data.qvel[0] = 0.05
data.qvel[5] = 1.5
mujoco.mj_forward(model, data)

world = AsTriad(size=10, name="world", position=(-0.06, 0, 0.01))
tool = AsTriad(size=10, name="tool").attach(model, site="tool_tip")
overlay = TriadOverlay(model, [world, tool])

with mujoco.viewer.launch_passive(model, data) as viewer:
    with viewer.lock():
        viewer.cam.lookat[:] = (0, 0, 0.05)
        viewer.cam.distance = 0.5
        viewer.cam.azimuth = 135
        viewer.cam.elevation = -25
    while viewer.is_running():
        tick = time.perf_counter()
        with viewer.lock():
            for _ in range(5):
                mujoco.mj_step(model, data)
            mujoco.mj_forward(model, data)
        overlay.update(viewer, data)
        viewer.sync()
        time.sleep(max(0, 0.01 - (time.perf_counter() - tick)))
```

{% endcode %}

Run `mjpython show_frames.py` on macOS or `python show_frames.py` on Linux and Windows. The box falls and rotates, its tool frame follows it, and the world frame stays fixed.

[Python API reference](https://github.com/asMagicApp/asTraid/blob/v0.10.0/docs/api.md)
