Motion planning docs: direct joint-space path first, cBiRRT as fallback#5197
Merged
Conversation
The code example on the pose-clouds page kept the cup upright with an OrientationConstraint, which only bounds the pointing direction at the goal. The canonical pouring demo (viam-pouring-demo, PR #54) uses a LinearConstraint with both LineToleranceMm and OrientationToleranceDegs, moving the cup along a straight, level path so it does not spill. This matches dgottlieb's review note on #5098 that the orientation-only approach may not reliably prevent spills. Switch the example and its surrounding prose to the linear constraint. The place-a-cup-on-the-table scenario, pose cloud, and figures are unchanged.
The figure shows the gripper holding the cup from the side, with the tool pointing horizontally, but the code used OZ:-1 (a top-down grasp). Set the goal orientation to OX:1 so the code matches the figure. With a horizontal grasp, Theta:180 would roll the cup about a horizontal axis and tip it. Relax OX and OY instead, so the planner can approach from any side (the cup may rest at any rotation about vertical), with a small OZ leeway to keep the approach horizontal and the cup upright. This matches the pouring demo and exercises the OX/OY/OZ rows of the tolerance table.
The motion planning pages presented cBiRRT as the primary algorithm. In the RDK (verified at v1.0.0), cBiRRT is the fallback: the planner first generates IK solutions, ranks them by joint travel, and returns the straight-line joint-space path to a low-cost solution when that path passes collision and constraint checks. cBiRRT runs only when no reasonable solution is directly reachable. - how-planning-works.md: lead with the direct-path stage, frame cBiRRT as the fallback, and document how linear constraints keep planning in the direct stage (tolerances below 10 mm/deg disable the fallback). - motion-planning/reference/algorithms.md: describe the two-stage strategy; absorb the aliases of the deleted legacy page. - Delete reference/services/motion/algorithms.md: it described an RRT*-Connect/CBiRRT hybrid and TP-space base planning that no longer exist in the RDK; its URL now redirects to the current algorithms page. - first-arm.md: the obstacle-free quickstart motion takes the direct path, not cBiRRT. - motion-service.md: scope the smoothing default to cBiRRT fallback paths.
✅ Deploy Preview for viam-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
viambot
added
the
safe to build
The PR htmltest job builds with config_local.toml, which sets disableAliases = true, so the alias left behind for the deleted /reference/services/motion/algorithms/ page emits no file in that build and the generated MoveOnGlobe note's link dangled. Point the link at the real page, /motion-planning/reference/algorithms/, in both the generated include and its override source so regeneration preserves it.
btshrewsbury-viam
requested review from
Dan Gottlieb (dgottlieb) and
oliviamiller
July 14, 2026 17:52
Dan Gottlieb (dgottlieb)
approved these changes
Jul 14, 2026
oliviamiller
approved these changes
Jul 14, 2026
|
🔎💬 Inkeep AI search and chat service is syncing content for source 'Viam Docs' |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Corrects the motion planning docs to describe the actual happy path: the planner tries a straight line through joint space to an IK solution first, and runs cBiRRT only as a fallback. Olivia Miller flagged that How planning works and /reference/services/motion/algorithms/ both presented cBiRRT as the primary algorithm.
Verified against the RDK at the v1.0.0 release tag (
motionplan/armplanning/):planSingleGoal→initRRTSolutions→getSolutions: IK generates up to 100 solutions, scored by joint-space travel (plus a mid-range joint bias). Each solution gets a straight-line joint-spaceCheckPath. The cheapest solution within 3× (defaultOptimalityMultiple) of the best cost that passes is returned immediately; cBiRRT runs only when none does, seeded with the surviving solutions.planToDirectJoints: explicit joint goals get the same straight-line check first.generateWaypoints: aLinearConstraintsubdivides the motion into Cartesian steps; tolerances below 10 mm/deg disable cBiRRT entirely.Changes
docs/motion-planning/how-planning-works.md— restructured: "First attempt: a straight line in joint space" now leads, cBiRRT is framed as the fallback, and a paragraph covers how linear constraints keep planning in the direct stage.docs/motion-planning/reference/algorithms.md— describes the two-stage strategy (stage table, cBiRRT role marked as fallback, direct-path cost gate added to defaults); absorbs the deleted legacy page's aliases.docs/reference/services/motion/algorithms.md— deleted. It described an RRT*-Connect/CBiRRT hybrid and TP-space base planning, neither of which exists at RDK v1.0.0 (git grepfinds no RRT* or tpspace source; the builtin service returns "not supported" forMoveOnMap/MoveOnGlobe). Its URL and/operate/alias now redirect to the current algorithms page (verified in the builtpublic/output). This also resolves the pre-existing alias collision: the new page already claimed/reference/services/motion/algorithms/as an alias while the legacy file occupied it.docs/motion-planning/quickstarts/first-arm.md— the obstacle-free quickstart motion takes the direct path, so the "What happened" list no longer claims cBiRRT ran.docs/motion-planning/reference/motion-service.md— smoothing default scoped to cBiRRT fallback paths.docs/reference/services/motion/_index.md— algorithms link retargeted to/motion-planning/reference/algorithms/.Absorbs #5149
The first two commits are the pose-clouds linear-constraint fixes from #5149, which is closed in favor of this PR.
Known artifact
The generated
MoveOnGlobeAPI note still links to/reference/services/motion/algorithms/for base-planning latency; that link now redirects to the arm algorithms page. The note comes from generated content and is stale regardless (builtin no longer implementsMoveOnGlobe); fixing it belongs in the upstream generator.Verification
rdktag v1.0.0 (plan_manager.go,node.go,planner_options.go,smooth.go); independently confirmed by a second review pass over the same tag.vale(0 errors), andmake build-prodall pass; alias redirects for both legacy URLs confirmed in build output.🤖 Generated with Claude Code