Configure motion constraints | Move an arm
Configure motion constraints
By default, the motion planner returns any collision-free path to the target pose. The path may curve, twist, or take the end effector through any orientation along the way. For many tasks this is fine, but some tasks require the arm to move in a specific way:
- Carrying a cup of water requires the end effector to stay level.
- Welding a seam requires the tool to follow a straight line.
- Picking an object requires the gripper to contact the object without the planner rejecting the path.
Constraints let you specify these rules, and the motion planner only returns paths that satisfy all of them.
Constraint types
Viam supports four constraint types. You can combine multiple constraints in a single motion request.
LinearConstraint
Forces the end effector to stay close to a straight line between the start and goal poses. Use this for straight-line tool paths.
| Parameter | Type | Description |
|---|---|---|
line_tolerance_mm |
float (optional) | Maximum deviation from the straight line, in millimeters. Only checked when greater than 0. |
orientation_tolerance_degs |
float (optional) | Maximum orientation deviation during motion, in degrees. Only checked when greater than 0. |
When line_tolerance_mm is set, the planner keeps the end effector within that distance of the line segment between start and goal. When orientation_tolerance_degs is set, the planner keeps the end effector orientation within that angular distance of whichever is closer: the start orientation or the goal orientation.
OrientationConstraint
Forces the end effector to maintain a consistent orientation throughout the motion. Use this when the end effector must stay level or keep a fixed orientation (for example, carrying a liquid).
| Parameter | Type | Description |
|---|---|---|
orientation_tolerance_degs |
float (required) | Maximum orientation deviation, in degrees, for orientations that fall outside the start-to-goal box. A value of 0 rejects any deviation outside that box. |
The planner checks each orientation vector component (OX, OY, OZ, Theta) against the start and goal independently. If every component of the current orientation falls between the corresponding start and goal values, the constraint is satisfied with zero error.
Otherwise, the planner measures the angular distance to whichever endpoint is closer (start or goal) and rejects the path if that distance exceeds orientation_tolerance_degs. The per-component box check allows smooth transitions when start and goal have different orientations; the tolerance gives a cushion on either side.
PseudolinearConstraint
Like LinearConstraint but uses proportional tolerances instead of fixed values. The actual tolerance scales with the distance between start and goal.
| Parameter | Type | Description |
|---|---|---|
line_tolerance_factor |
float (optional) | Proportional factor. Actual tolerance = factor x distance(start, goal). |
orientation_tolerance_factor |
float (optional) | Proportional factor for orientation. Actual tolerance = factor x orientation_distance(start, goal). |
Use this when you want the constraint to adapt to the length of the motion. A short move gets a tight tolerance; a long move gets a proportionally larger one.
CollisionSpecification
Allows specific pairs of frames to collide during planning. By default, the planner rejects any path where any two frames collide. CollisionSpecification lets you whitelist specific pairs.
| Parameter | Type | Description |
|---|---|---|
allows |
list of frame pairs | Each entry has frame1 and frame2 (string names). |
Allow a collision when:
- A gripper is expected to contact the object it is picking up.
- Two components are physically close and their simplified collision geometries overlap, while the real components stay clear of each other.
Frame names support hierarchical matching: specifying "my-arm" matches all sub-geometries of the arm (such as my-arm:upper_arm_link, my-arm:forearm_link). For hierarchical matching details, self-collision patterns, and worked examples (arm detecting itself through a vision service, gripper holding an object), see Allow frame collisions.
Pass constraints to Move
Build a Constraints object containing one or more constraint entries and pass it on the Move request’s Constraints field. For worked examples (straight-line tool path, level end effector, combined constraints), see Move with constraints. For CollisionSpecification (allow specific frame pairs to collide), see Allow frame collisions.
Relax the goal with a pose cloud
Constraints restrict the path between poses. The complementary tool is to relax the goal itself. When close enough is acceptable, give the planner a region of acceptable poses instead of a single one, which enlarges the solution set and makes planning faster. This is a pose cloud, and it is often the right move when a goal is failing or planning slowly. See Pose clouds.
Performance considerations
Every constraint adds a check to every candidate path segment, and tight tolerances shrink the set of valid paths. Both raise planning time and the failure rate.
- Tight tolerances (small
line_tolerance_mmororientation_tolerance_degs) increase planning time and may cause the planner to fail if no path exists within the tolerance. - Start with larger tolerances and tighten only as needed. A 10 mm linear tolerance is easier to satisfy than a 1 mm tolerance.
- Combining constraints multiplies the difficulty. Use the minimum set of constraints required for your task.
What’s next
- Move an arm with constraints: practical examples of constrained motion.
- How motion planning works: how the planner searches for constrained paths.
- Define obstacles: define the geometry the planner uses for collision checking.