[Shannon Bradshaw (shannonbradshaw)]

The pose clouds page says tolerances are measured in the target's (parent) frame, but PoseInCloud measures every leeway in the goal pose's own frame. The cup example's leeways therefore didn't allow what its comments said. This corrects the frame explanation, the OZ semantics, and the example.

Source changes

• Measure PoseCloud theta as twist about the goal's Z axis rdk#6633 (2242a675e, released in RDK v1.12.0): a pose cloud's Theta now bounds only the twist about the goal's Z axis, so tilting the pointing direction uses none of it. No ticket key on the PR or commit.
• Documents: no ticket key found.

Re-reading referenceframe/pose_cloud.go at v1.12.0 for that change: PoseInCloud computes PoseBetween(goalPose, candidatePose) (the candidate expressed in the goal pose's frame) and checks |X|, |Y|, |Z|, |OX|, |OY|, and |1 - OZ| there. The goal pose includes its orientation (planner_options.go passes goal.Pose()), so the axes follow the goal orientation, not the parent frame.

Docs changes

• docs/motion-planning/move-an-arm/pose-clouds.md:
  • Field table: X, Y, Z are along the goal pose's axes; Theta is the twist about the orientation axis.
  • Orientation leeways: OZ is checked as 1 - OZ, so 1 allows any direction within 90 degrees and 2 any direction. The page said 1 accepts any value for every component.
  • "Tolerances are measured in the target's frame" → "…in the goal pose's frame", with what that frame is, the Theta-as-twist behavior from rdk#6633, and when the inclined-surface example works (tool pointing along the surface normal).
  • Cup example: for the goal OX: 1, OZ: 0, Theta: 180, the goal frame's X axis is the table's +Z, Y is the table's -Y, and Z is the table's +X. The old cloud (X: 75, Y: 75, Z: 0, OX: 1, OY: 1, OZ: 0.1) gave 75 mm of vertical slack, held the position along the table's X, allowed up to about 26 degrees of tilt (tipping the cup), and capped the swing about vertical at about 26 degrees. The new cloud (X: 0, Y: 75, Z: 75, OX: 0.05, OY: 1, OZ: 2) gives what the comments describe: slack across the table, the cup on the surface, under 3 degrees of tilt, and an approach from any side.

Reviewer note: the axis mapping comes from OrientationVector.Quaternion() (ZYZ: Rz(lon) Ry(lat) Rz(theta), here Ry(90°) Rz(180°)), worked by hand. An engineering check from the motion team would be welcome.

How I found these

• upcoming.yaml rdk-posecloud-theta-twist flagged the cup example for re-checking at release; RDK v1.12.0 shipped 2026-10-13.
• Grep for PoseCloud, pose cloud, goal_cloud, Theta in docs/motion-planning/: only this page states the leeway frame.

---

Generated by daily docs change agent

---

Generated by Claude Code

[netlify]

✅ Deploy Preview for viam-docs ready!

Name	Link
🔨 Latest commit	99d8cdf
🔍 Latest deploy log	https://app.netlify.com/projects/viam-docs/deploys/6acfa5b4ee3b719e0eb2288a
😎 Deploy Preview	https://deploy-preview-5416--viam-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 38 (🟢 up 3 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 92 (no change from production) PWA: 60 (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.

[Eliza Farley (elizafarley)]

Docs review: Ready to merge

This PR corrects pose-clouds.md so it says tolerances are measured in the goal pose's own frame (not the parent frame), fixes the OZ semantics (1 - OZ), and rewrites the cup example to match. 36444ca fixes both nits from the previous review. It also rewrites the cup example's OX/Theta comments so they describe what PoseInCloud actually does, which settles the tilt-versus-twist question that was waiting on owner sign-off. Every technical claim now matches rdk origin/main and v1.12.0.

CI: All required checks passing (non-required "Check Markdown files" still running at review time)

Docs health: No regressions (the code-fence change resets the page's age clock, as expected)

FYI, not blocking: the author's open question for Motion Planning is whether the current leeways should be able to express a cloud that allows a full swing about vertical plus a small tilt. That's a question about rdk's design, not about these docs: the page now describes current behavior correctly either way.

Verified against source (9 claims)

• Leeways are checked on PoseBetween(goalPose, candidatePose), which is the candidate in the goal pose's frame (goal⁻¹ · candidate): viamrobotics/rdk referenceframe/pose_cloud.go:86, spatialmath/pose.go:105-109
• The goal pose passed in carries its orientation, and the frame is independent of the parent because both poses are in goal.Parent(): motionplan/armplanning/planner_options.go:185-190
• X/Y/Z are bounded by |between.Point()| per axis, in mm: pose_cloud.go:87-95
• OX/OY are bounded by |OX|/|OY|, and OZ by |1 - OZ|, so 1 allows ≤ 90° and 2 allows any direction: pose_cloud.go:97-106
• Theta bounds only the twist about the goal's Z axis, and tilting with no swing uses none of it: pose_cloud.go:72-75, 108-112. Shipped in v1.12.0 (rdk#6633, 2242a675e).
• OV→quaternion is Rz(lon)·Ry(lat)·Rz(theta) (ZYZ): spatialmath/orientationVector.go:129-161
• For OX: 1, OZ: 0, Theta: 180, R = Ry(90°)·Rz(180°) maps goal X→table +Z, goal Y→table −Y, goal Z→table +X, which matches pose-clouds.md:129-131 (worked by hand from the function above)
• OX: 0.05 ⇒ |sin tilt| ≤ 0.05. A swing φ about vertical gives pointing (0, −sin φ, cos φ) with zero twist, which OY: 1 and OZ: 2 accept for any φ.
• New comment "once the approach swings away from the goal, a tilt also reads as twist, so Theta 0 rejects it too": for Rx(φ)·Ry(ε), twist = 2·atan(tan(φ/2)·tan(ε/2)), which is nonzero for φ, ε ≠ 0 and exceeds the 0.001° epsilon (pose_cloud.go:111-112). The author's figures (1.2° at φ=45°, ε=2.9°; 11° at φ=170°, ε=1°) check out.

Automated review by Claude. Rerunning the review updates this comment.

[Shannon Bradshaw (shannonbradshaw)]

Thanks for checking the axis mapping. In 36444ca (pushing now):

• Alt text: "the target frame" is now "the goal frame". The SVG filename is unchanged.
• Tilt and Theta: I checked the twist term numerically, and you're right. It is 2·atan2(qz, qw) of Rx(φ)·Ry(ε). With no swing, any tilt has zero twist. At φ = 45° a 2.9° tilt reads as 1.2° of twist, at 90° as 2.9°, and at 170° a 1° tilt reads as 11°. So Theta: 0 rejects tilt once the approach has swung. The example is stricter than its comment said, and that is what the cup example wants (the cup stays upright). I reworded the comments instead of loosening the cloud:
  • OX: 0.05 now says "keep the tool level".
  • The Theta comment adds: "Once the approach swings away from the goal, a tilt also reads as twist, so Theta 0 rejects it too."

I didn't add a small Theta to allow tilt at every swing angle. Near φ = 180° even a 1° tilt needs about 11° of twist, so no small value works across all swings. The sign-off question for the motion team still stands: should a goal cloud that allows a full swing about vertical plus a small tilt be expressible at all with these leeways?

---

Generated by Claude Code

[github-actions]

🔎💬 Inkeep AI search and chat service is syncing content for source 'Viam Docs'