Motion planning

Your robot arm needs to move from one position to another without colliding with the table, the walls, or itself. Computing a collision-free path through 3D space means reasoning about the arm’s kinematic model, the workspace geometry, and any constraints on how the arm should move.

Viam’s motion service handles this for you. You describe the spatial layout of your workspace (the frame system) and any obstacles, then tell the arm where to go. The planner finds a safe path and executes it.

This section covers motion planning for arms, gantries, and other kinematic chains. For GPS-based autonomous navigation with mobile bases, see Navigation.

Start here

New to Viam’s motion service? Work through a short quickstart that uses fake components so you can run it on any machine:

Move your first arm

From zero to an arm moving under motion service control, using a fake arm that runs on any machine.

Configure a frame system

Set up a table-mounted arm with a gripper and a wrist camera, and verify the frame configuration with TransformPose.

How it works

Motion planning in Viam connects several pieces:

  1. Frame system: a coordinate tree that tracks where every component is in space. The frame system lets you specify target positions in any frame and translates between them automatically.

  2. Kinematic model: a description of the arm’s joints and links that tells the planner what configurations are physically possible.

  3. Obstacles: geometry (boxes, spheres, capsules) that define regions the arm must avoid.

  4. Constraints: rules about how the arm should move between poses, such as keeping the end effector on a straight line or maintaining its orientation.

  5. Motion service: takes the frame system, kinematic model, obstacles, and constraints and computes a collision-free path from the current pose to the target.

Topic subsections

Frame system

Build a unified coordinate tree so all components agree on where things are in physical space.

Move an arm

Command an arm to a target pose, along a constrained path, or directly in joint space.

Obstacles

Define collision geometry so the motion planner computes safe, collision-free paths.

Pick and place

End-to-end manipulation: detect, grasp, move, and release an object.

3D scene

Visualize your machine's frame system, geometries, and point clouds in an interactive 3D view.

Other how-tos

Move a gantry

Control gantry axes directly or plan complex gantry motion.

Monitor a running plan

Start a non-blocking motion plan and react to progress, completion, and failure.

Debug motion with the CLI

Diagnose frame configuration and motion issues from the command line using the Viam CLI motion commands.

Concept pages

How planning works

The algorithm Viam uses to plan robot arm motion, why it works for arms, and what to try when planning fails.

Replanning

Which motion service methods replan during execution, when, and why. The single most common mental-model mismatch for new users.

Reference

Reference

Configuration, API, and technical reference for the motion service.