Nested Reference Frame Configuration

Imagine a robotic arm is attached to the actuator (moving part) of a gantry.

Consider the point that the gantry itself is fixed to as the center of the world, making the gantry’s origin the same as the world origin: (0, 0, 0).

Measure from that point to the base of the arm to get the translation of the arm.

  • Suppose the base of the arm is mounted to the gantry 0.1 meters above the gantry’s origin.
  • Supply this translation and specify the arm’s parent reference frame as myGantry.
  • Leave all other frames’ orientation and translation at their default values.

Now, as the gantry moves its actuator, the Frame System will translate both the gantry and the arm’s location according to that motion.

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 gantry, then configure your arm. If you don’t have a physical gantry or arm, you can use their fake models.

  • Select the Frame mode.

  • From the left-hand menu, select your gantry.

  • 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 gantry in relation to the world frame’s origin. For example, considering the point that the gantry itself is fixed to as the center of the world you would leave the gantry’s frame at the default configuration:

    Gantry frame card example for this configuration

  • Next, select your arm from the left hand menu.

  • Select the Parent frame as the gantry, and fill in the coordinates for Translation (m) of the arm in relation to the gantry’s origin:

    Arm frame card example for this configuration
{
  "components": [
    {
      "name": "myGantry",
      "model": "single-axis",
      "type": "gantry",
      "namespace": "rdk",
      "attributes": {},
      "depends_on": [],
      "frame": {
        "parent": "world",
        "translation": {
          "y": 0,
          "z": 0,
          "x": 0
        },
        "orientation": {
          "type": "ov_degrees",
          "value": {
            "x": 0,
            "y": 0,
            "z": 1,
            "th": 0
          }
        }
      }
    },
    {
      "depends_on": [],
      "name": "myArm",
      "model": "ur5e",
      "type": "arm",
      "namespace": "rdk",
      "attributes": {
        "host": "127.0.0.1"
      },
      "frame": {
        "parent": "myGantry",
        "translation": {
          "x": 0,
          "y": 0,
          "z": 100
        },
        "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.