Frame System

When your robot has multiple components such as: an arm, a camera, a gripper each component reports positions in its own local coordinate system. A camera sees an object at pixel (320, 240), but the arm needs to know the object’s position in three-dimensional space relative to its own base. Without a unified spatial model, you cannot translate between these coordinate systems.

The frame system solves this by storing the position and orientation of every component in a single, consistent coordinate tree. You define where each component sits relative to its parent, and Viam computes the transforms between any two frames automatically. Once the frame system is configured, you can ask questions like “where is this point in my camera frame, expressed in world coordinates?” with a single API call.

Getting the frame system right is a prerequisite for motion planning, obstacle avoidance, and any task where multiple components need to agree on where things are in physical space.

Concepts

The world frame

The world frame is the fixed root reference point for your entire frame system. You choose what physical location it corresponds to, for example: the corner of a table, the center of a work surface, or the base of an arm. You do not explicitly configure the world frame itself. Instead, you define it implicitly by configuring other frames relative to it.

Pick a point that is easy to measure from and that will not move. For a table-mounted arm, the arm base or a table corner are good choices. For a mobile robot, the center of the base is typical.

Parent-child hierarchy

Each component’s frame has a parent frame. The parent defaults to the world frame if you do not specify one. When you attach a camera to an arm, you set the camera’s frame parent to the arm. This means the camera’s position is defined relative to the arm’s end, and when the arm moves, the camera frame moves with it automatically.

The hierarchy forms a tree rooted at the world frame:

world
├── my-arm
│   ├── my-gripper (attached to arm)
│   └── my-camera (mounted on arm)
├── my-sensor (mounted on table)
└── table-surface

Parent to an intermediate arm link

If you mount a component on an intermediate link of an arm rather than on the end effector, set the parent to <arm-name>:<link-name>. The link name is the id of a link in the arm’s kinematic model. For example, if you have an arm named my-arm with a UR5e kinematic model and you strap a camera to the forearm, set the camera’s parent to my-arm:forearm_link.

{
  "parent": "my-arm:forearm_link",
  "translation": { "x": 0, "y": 0, "z": 30 },
  "orientation": {
    "type": "ov_degrees",
    "value": { "x": 0, "y": 0, "z": 1, "th": 0 }
  }
}

The motion service plans around components attached to intermediate links the same way it plans for components attached to the arm’s end effector. To find the link names for an arm, inspect its kinematic model file or run viam machines part motion print-config and look for frames under the arm’s name.

Translation

Translation is the offset in millimeters from the parent frame’s origin to the component’s origin. It is specified as an (x, y, z) vector:

• x: right/left offset
• y: forward/backward offset
• z: up/down offset

The exact meaning of each axis depends on the parent frame’s orientation. If the parent is the world frame with the standard orientation, +z points up.

Orientation

Orientation describes how a component’s axes are rotated relative to its parent frame. Viam supports several orientation formats:

The default orientation is ov_degrees with values (0, 0, 1), 0, which means the component’s axes are aligned with its parent frame. The orientation vector (x, y, z) defines the axis of rotation, and th defines the rotation angle around that axis. The axis must be a non-zero vector (the code normalizes it internally).

For a detailed reference on orientation vectors, see Orientation Vectors.

Geometry

Each frame can optionally include collision geometry. This is a simple shape that approximates the component’s physical footprint. The motion planner uses these shapes to avoid collisions. Supported types:

• box: defined by x, y, z dimensions in mm
• sphere: defined by a radius in mm
• capsule: defined by a radius and length in mm

Geometry is centered on the frame’s origin by default. You can add a translation offset and orientation offset within the geometry config to shift it relative to the frame.

For detailed information about obstacle geometry, see Define Obstacles.

TransformPose

TransformPose is a method on the machine client that converts a pose from one reference frame to another. You provide a source pose with its reference frame, a destination frame name, and the frame system computes the transform using the configured hierarchy and current joint positions.

For example, to find where a camera’s origin is in the world frame:

from viam.proto.common import PoseInFrame, Pose

# Express the camera's origin (0,0,0) in its own frame
camera_origin = PoseInFrame(
    reference_frame="my-camera",
    pose=Pose(x=0, y=0, z=0, o_x=0, o_y=0, o_z=1, theta=0)
)

# Transform to the world frame
world_pose = await machine.transform_pose(camera_origin, "world")
print(f"Camera in world: x={world_pose.pose.x}, y={world_pose.pose.y}, z={world_pose.pose.z}")

baseOrigin := referenceframe.NewPoseInFrame("my-camera", spatialmath.NewZeroPose())
worldPose, err := machine.TransformPose(context.Background(), baseOrigin, "world", nil)

The optional supplemental_transforms parameter lets you include additional frame relationships that are not part of the stored configuration. This is useful for dynamic frames, such as an object detected by a camera whose position is known relative to the camera but not configured in the frame system.

Common uses:

• Verify frame configuration: transform a component’s origin to the world frame and check that the result matches its physical position.
• Convert detections: transform a point detected in a camera frame to world coordinates so an arm can reach it.
• Compare across frames: when two components report positions in different frames, transform both to a common frame before comparing.

Verify with the CLI

You can inspect your frame system from the command line without writing code:

# Print the frame system configuration
viam machines part motion print-config --part "my-machine-main"

# Print the current pose of every component relative to world
viam machines part motion print-status --part "my-machine-main"

If a component’s pose looks wrong, check the translation and orientation values in its frame configuration. For details on all CLI motion commands, see Motion Service Configuration.

What’s next

Configure the frame system for your hardware setup: