Reference Frame Configuration

Imagine a robotic arm is attached to a table.

Consider one corner of the table the arm is attached 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 0.1 m in the positive X direction, and 0.25 m 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 configure your machine following this example:

  • Navigate to the CONFIGURE tab of your machine’s page in the Viam app.

  • Select Builder mode and configure your arm. If you don’t have a physical arm, you can use a fake model.

  • Select the Frame mode.

  • From the left-hand menu, select your arm:

    Frame card for an arm with the default reference frame settings

  • Keep the Parent frame as world and fill in the coordinates for Translation (m) and Orientation (deg) according to the position and orientation of the arm in relation to the world frame’s origin:

    Frame card for an arm with a translation of 0.1 meters and -0.25 meters configured
{
  "components": [
    {
      "depends_on": [],
      "name": "myArm",
      "model": "ur5e",
      "type": "arm",
      "namespace": "rdk",
      "attributes": {
        "host": "127.0.0.1"
      },
      "frame": {
        "parent": "world",
        "translation": {
          "x": 100,
          "y": -250,
          "z": 0
        },
        "orientation": {
          "type": "ov_degrees",
          "value": {
            "x": 0,
            "y": 0,
            "z": 1,
            "th": 0
          }
        }
      }
    }
  ]
}
ParameterRequired?Required
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: m in Frame Editor, mm in JSON.
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 (ov_degrees), Orientation Vector Radians (ov_radians), Euler Angles (euler_angles), and Quaternion (quaternion).
geometryOptionalDefault: none. Collision geometries for defining bounds in the environment of the machine.
Units: m in Frame Editor, mm in JSON.
Types: Sphere (sphere), Box (box), and Capsule (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.