Add motion planning pages: end effector frames, waypoints, pose clouds, plan verification

[btshrewsbury-viam]

What

Adds four new pages under Motion Planning and wires them into the section navigation.

New pages

• Frame System › End effector frames — Explains that Move targets a named frame, not a component: how component_name selects the end effector frame, how the frame attribute defines a static frame, how WorldState transforms extend the frame system for a single request, and how WorldState differs from the world state store service.
• Move an arm › Moving through multiple waypoints — Routing one plan through ordered goals with armplanning.PlanMotion: how PlanRequest.Goals chains PlanStates into a single continuous trajectory, mixing poses / joint configurations / pose clouds per waypoint, and using return_partial_plan to isolate an infeasible waypoint.
• Move an arm › Pose clouds — Relaxing an over-constrained goal into a region of acceptable poses with NewPoseInFrameWithGoalCloud: the translational/rotational leeways, why tolerances are measured in the target frame, and when a goal region beats an exact pose. Briefly noted and linked from the Configure constraints page.
• Verifying a Motion Plan — Planning without executing: armplanning.PlanMotion vs motionService.Move, assembling a PlanRequest, reading the returned Plan/Trajectory, and reproducing the same plan over the motion service with the plan DoCommand verb (and its trade-offs).

Navigation / edits

• Cards added to the Motion Planning index, Frame System overview, and Move an arm overview.
• Configure constraints page gains a short "relax the goal with a pose cloud" pointer + link.

Notes for reviewers

• Page structure, prose style, and front matter follow the existing Motion Planning pages.
• API usage is grounded in the RDK source, but the Go snippets have not been compiled end-to-end, worth a check during review.
• Pre-PR checks pass: prettier, markdownlint, vale (0 findings), and make build-prod.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for viam-docs ready!

Name	Link
🔨 Latest commit	19cdacf
🔍 Latest deploy log	https://app.netlify.com/projects/viam-docs/deploys/6a467e4980419400086f4407
😎 Deploy Preview	https://deploy-preview-5098--viam-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 45 (🟢 up 9 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 92 (no change from production) PWA: 70 (no change from production) View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Shannon Bradshaw (shannonbradshaw)]

Keeping a few general questions here as I review this:

• What can we expect readers to already be familiar with when they read this page?
• Do we need to summarize what a pose is? Should there be a reference section, perhaps in the overview that we link readers to for more details?
• Same question for world state.

[Shannon Bradshaw (shannonbradshaw)]

Yeah, I think we need to define pose and frame clearly in a place that we can reference elsewhere. Currently thinking the overview page might be the best place for that, but I'll continue to assess as I review.

[Dan Gottlieb (dgottlieb)]

This all looks great. Biggest question is the orientation axis on the images.

[Dan Gottlieb (dgottlieb)]

This is more of a question for me -- Before an object (sitting on a table for example) is grasped, a natural orientation vector would be +Z going "up". But when re-parenting the object to a gripper (where positive Z is "down"), that would flip it's orientation vector? That can't be right?

It seems that re-parenting for complex object where that "child" orientation vector matters isn't as simple as just changing the parent.

[btshrewsbury-viam]

I am thinking if the object we picked up had built in frames, it would be relative to some parent. that transform to parent would need to change on pickup. for something like a drill, it could have a grip frame and a drill bit frame, we would need to define a transform from the TCP to the grip frame on pickup so we don't loose the drill bit, and if it wasn't using DH the orientation would probably change axis.

[Dan Gottlieb (dgottlieb)]

I think the goal is to populate motion service requests with items defined in the world state store service. Not sure if that task without a completion date warrants changing the narrative here. But just wanted to be transparent that the two ought to be more similar than they currently are.

The documentation though is accurate w.r.t how things behave today.

[btshrewsbury-viam]

Once that goes through I will need to update a bunch then, have similar distinctions in the new Visualization Section

[Dan Gottlieb (dgottlieb)]

I'm not sure if there needs to be a documentation change here, just being transparent about the intention of armplanning.PlanMotion.

Calling PlanMotion directly is regarded as accessing a "private" API. It's (long term) goal is to only be consumed by the motion service. That said, there are enough limitations (e.g: passing around large meshes may not be feasible) with using the motion service such that using this more directly is helpful/neccessary.

Being considered "private", we do break this API. So there's some risk in adopting this heavily into application code.

The remote section here about using the motion service with the "plan" command is the recommended path. Hopefully we can make it more ergonomic in the future and allow users to make that call without having to proto serialize the MoveReq by hand. Which motivated me to file a ticket for that: https://viam.atlassian.net/browse/RSDK-14155

[btshrewsbury-viam]

Making plan easier to use from the Motion Service's perspective would be amazing. I can switch this to only show the DoCommand verb if that feels more correct. I ended up making a bunch of helpers to make marshalling a bit easier: https://github.com/viam-labs/viamkit/blob/main/verify/plan.go. The plan verb was extremely important in moving the pallet around

[Dan Gottlieb (dgottlieb)]

Thanks for sharing that code link -- I've added it to the ticket to give more concrete motivation of what users shouldn't need to write.

I can switch this to only show the DoCommand verb if that feels more correct.

Again, not sure if I'm the right decision maker here. But given the plan verb can do everything (in the context of verifying -- not in the context of multiple waypoints), opting to get rid of the direct armplanning.PlanMotion example makes sense to me.

[Dan Gottlieb (dgottlieb)]

I know you asked to especially look at this, so leaving a note.

This all looks good to me! I think this does a much better job explaining the "follow the tilt" motivation/ease than my code comment did.

The code example at the bottom re: not spilling is definitely what we're striving for what a user should write. I'm skeptical that system reliably achieves that! But see nothing that needs to change there.

If there's anything worth detailing, it's about the sharp edge regarding orientation vector normalization. I'm not sure if the wine pouring example/documentation is the most straightforward example. But there's definitely a game where setting a goal pose with OZ: 0 (and leaving OX/OY untouched because of an unconstrained pose cloud) is a bit undefined. Because the goal orientation of OX: 0, OY: 0, OZ: 0 would get normalized back to OX: 0, OY: 0, OZ: 1. And from there having a pose cloud of OX: 1, OY: 1, OZ: no longer does the right thing.

Maybe this goes into the "what is a pose" documentation Shannon was referring to above. Or we just wait on this more esoteric documentation in case we come up with a better idea for resolving that ambiguity most likely preserves user intent.

[Dan Gottlieb (dgottlieb)]

lgtm % updated svgs

[Dan Gottlieb (dgottlieb)]

Thanks for sharing that code link -- I've added it to the ticket to give more concrete motivation of what users shouldn't need to write.

I can switch this to only show the DoCommand verb if that feels more correct.

Again, not sure if I'm the right decision maker here. But given the plan verb can do everything (in the context of verifying -- not in the context of multiple waypoints), opting to get rid of the direct armplanning.PlanMotion example makes sense to me.

[Shannon Bradshaw (shannonbradshaw)]

Thanks for this PR. It fills a massive gap. Many changes requested in comments throughout.