Reference Frame Configuration

Imagine a robotic arm is attached to a table.

Consider one corner of the table the arm is attached to to be the origin of the world, (0, 0, 0). Measure from that point to the base of the arm to get the translation coordinates.

  • Suppose the arm is offset from the corner by 100mm in the positive X direction, and 250mm in the negative Y direction.
  • Supply this translation when configuring the arm component’s frame information.
  • Leave parent and orientation at their default values.

To complete the frame configuration for your machine following this example, navigate to the Config tab on your machine’s page in the Viam app, select the Builder mode, scroll to myArm’s card, and click Add Frame:

frame card example for this configuration

Select the parent frame as world and fill in the coordinates for translation (mm) and orientation (deg) according to the position and orientation of the arm in relation to the world frame’s origin.

  "components": [
      "depends_on": [],
      "name": "myArm",
      "model": "ur5e",
      "type": "arm",
      "namespace": "rdk",
      "attributes": {
        "host": ""
      "frame": {
        "parent": "world",
        "translation": {
          "x": 100,
          "y": -250,
          "z": 0
        "orientation": {
          "type": "ov_degrees",
          "value": {
            "x": 0,
            "y": 0,
            "z": 1,
            "th": 0
ParentRequiredDefault: world. The name of the reference frame you want to act as the parent of this frame.
TranslationRequiredDefault: (0, 0, 0). The coordinates that the origin of this component’s reference frame has within its parent reference frame.
Units: mm.
OrientationRequiredDefault: (0, 0, 1), 0. The orientation vector that yields the axes of the component’s reference frame when applied as a rotation to the axes of the parent reference frame.
Types: Orientation Vector Degrees, Orientation Vector Radians, and Quaternion.
GeometryOptionalDefault: none. Collision geometries for defining bounds in the environment of the machine.
Types: Sphere, Box, and Capsule.

Have questions, or want to meet other people working on robots? Join our Community Discord.

If you notice any issues with the documentation, feel free to file an issue or edit this file.