Motion planning · repose-motion-planning

Requests & results

Planners are interchangeable because they share one request and one result payload. Both are fixed-size, so a plan can be logged and replayed like any other message.

Request: CuJointPlanRequest<N>

sceneCuPlanningScene<16, 8>: up to 16 obstacles and 8 attached shapes. See Planning scenes.
exclusionsCuSceneExclusions<16>: intended contacts for attached shapes.
start[CuJointPosition; N], normally the measured state.
goal[CuJointPosition; N]. Goals are joint configurations. For a Cartesian goal, solve IK first.

The scene is copied into the planner when the job starts. Later changes to your scene don't affect the running job; send a new request to replan.

Result: CuJointPlanPath<N>

waypoints, lenUp to MAX_WAYPOINTS (32) configurations; waypoints() returns the valid ones. Start and goal included. Empty unless the status has a path.
costPath length in normalised joint units (L2 under the planner's CuJointMetric). With the default metric on an all-revolute arm: total radians.
effortWork spent: samples, expansions or iterations.
statusCuPlanStatus, below.
scene_revisionRevision of the scene the path was checked against.
exclusionsThe exclusions the path was allowed to use.

Segments between waypoints are straight lines in joint space, each checked at the planner's collision_check_step. Planners shortcut their raw output by line of sight, so paths are usually a handful of waypoints.

Status: CuPlanStatus

SearchingRunning, no path yet.
ImprovingA collision-free path exists; more work may shorten it.
ConvergedA path exists and more work can't improve it.
ExhaustedGave up without a path: budget or capacity spent, optimizer stuck in collision, or no free direct line.
InvalidRequestParameters, scene, attached shapes or exclusions are invalid.
InvalidStartStart is out of limits or in collision.
InvalidGoalGoal is out of limits or in collision.
CapacityExceededA path exists but doesn't fit in 32 waypoints even after shortcutting.

status.has_path() is true for Improving and Converged. status.is_final() is true when no further step can change the outcome.

Reading a result

rust
match path.status {
    s if s.has_path() => execute(path.waypoints()),
    CuPlanStatus::InvalidStart => { /* robot is already in collision or out of limits: fix the scene or recover manually */ }
    CuPlanStatus::InvalidGoal  => { /* goal unreachable as given: check it with check_configuration */ }
    CuPlanStatus::Exhausted    => { /* raise the budget, change planner, or simplify the scene */ }
    other => log(other),
}

API reference