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 100mm 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 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 myGantry’s card, and click Add Frame:

gantry 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 gantry in relation to the world frame’s origin.

Navigate to myArm’s card and click Add Frame:

arm frame card example for this configuration

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

{
  "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
          }
        }
      }
    }
  ]
}
ParameterInclusionRequired
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.