Mobile base with sensors

A mobile base’s sense of its own position comes from its sensors, nothing else. Lidar sweeps tell the base what is around it; front and rear cameras feed detection and SLAM. Every sensor reading is in the sensor’s own reference frame: a lidar point at (2.0 m, 0, 0) is two meters in front of the lidar, not in front of the base. The frame system converts sensor frames to the base frame and on to the world frame, so the navigation stack sees consistent positions. Configuring it is a one-time setup; this guide walks through it.

Frame hierarchy

world
└── my-base
    ├── my-lidar (mounted on top)
    ├── front-camera (front-facing)
    └── rear-camera (rear-facing)

The base is a child of the world frame. All sensors are children of the base, so the entire sensor subtree moves with the base.

Steps

1. Choose your world frame origin

For a mobile base, the world frame origin is the base center at machine start: not a fixed point in the room, but wherever the base was when it came online. Sensor positions are measured relative to the base center, so you do not need to mark anything physically. The frame system tracks the base’s motion from that initial origin.

2. Add a frame to the base

In the CONFIGURE tab, click the base component’s card and then click Frame. (For details on the Frame editor, see Edit a frame in the Viam app.) Edit the JSON for each component below as you go.

Since the world frame origin is at the base center, the translation is zero:

{
  "parent": "world",
  "translation": { "x": 0, "y": 0, "z": 0 },
  "orientation": {
    "type": "ov_degrees",
    "value": { "x": 0, "y": 0, "z": 1, "th": 0 }
  }
}

Click Save in the top-right of the page (or press ⌘/Ctrl+S).

3. Add a frame to the LIDAR

In the sidebar, click your LIDAR component to open its card. On the card, click Frame. Measure the offset from the center of the base to the LIDAR’s sensor origin.

For a LIDAR mounted on top of the base, centered horizontally and 150 mm above the base center:

{
  "parent": "my-base",
  "translation": { "x": 0, "y": 0, "z": 150 },
  "orientation": {
    "type": "ov_degrees",
    "value": { "x": 0, "y": 0, "z": 1, "th": 0 }
  }
}

If the LIDAR is offset forward or to one side, include x and y values. For example, a LIDAR mounted 50 mm forward of center and 150 mm above:

{
  "parent": "my-base",
  "translation": { "x": 0, "y": 50, "z": 150 },
  "orientation": {
    "type": "ov_degrees",
    "value": { "x": 0, "y": 0, "z": 1, "th": 0 }
  }
}

Click Save.

4. Add frames to the cameras

For each camera, click the component in the sidebar to open its card, then click Frame. Measure the offset from the base center to each camera’s mounting position.

Front-facing camera: For a camera mounted at the front of the base, 200 mm forward and 120 mm above the base center:

{
  "parent": "my-base",
  "translation": { "x": 0, "y": 200, "z": 120 },
  "orientation": {
    "type": "ov_degrees",
    "value": { "x": 0, "y": 0, "z": 1, "th": 0 }
  }
}

The default orientation has the camera looking along the +y axis (forward). If your camera is mounted rotated, set value.th to the rotation angle in degrees.

Rear-facing camera:

The rear camera’s configuration mirrors the front camera’s, with two changes: a negative y translation (it is behind the base center) and a 180-degree rotation around z (so it faces backward).

For a camera mounted at the back of the base, 200 mm backward and 120 mm above the base center, facing backward:

{
  "parent": "my-base",
  "translation": { "x": 0, "y": -200, "z": 120 },
  "orientation": {
    "type": "ov_degrees",
    "value": { "x": 0, "y": 0, "z": 1, "th": 180 }
  }
}

The 180-degree rotation around the z axis points the camera backward (along -y).

Click Save after adding each camera frame.

5. Visualize and verify

1. Navigate to the 3D SCENE tab in the Viam app.
2. Verify that all sensor frames appear as children of the base.
3. Check that sensor positions match their physical mounting locations relative to the base center.
4. Confirm that camera orientations point in the correct directions (forward for the front camera, backward for the rear camera).

If any frame appears in the wrong position or orientation, return to the CONFIGURE tab and adjust the values.

6. Verify with TransformPose

Use TransformPose to confirm the relationships between sensor frames and the base frame. For example, transform the front camera’s origin (0, 0, 0) from the camera frame to the base frame. The result should match the camera’s measured offset from the base center.

For details on the TransformPose API, see Frame system: TransformPose.

Troubleshooting

What’s next