Fix the orientation vector model across frame-system pages#5199
Open
btshrewsbury-viam wants to merge 2 commits into
Open
Fix the orientation vector model across frame-system pages#5199btshrewsbury-viam wants to merge 2 commits into
btshrewsbury-viam wants to merge 2 commits into
Conversation
An orientation vector's (x, y, z) is the direction the component's +z
axis points in the parent frame; th spins the component about that
direction. Several pages taught and used it as an axis-angle rotation,
so every 'tilt the camera by rotating about x' config example aimed the
lens horizontally instead. Confirmed against a live viam-server v1.0.0:
ov_degrees {x:1,y:0,z:0,th:180} resolves to pointing along +x with a
180-degree roll, not straight down.
- orientation-vectors.md: fix the field bullets and two Common
orientations table rows that applied the axis-angle reading; scope
the five-format type selection to JSON config (API Pose messages are
always orientation-vector degrees); correct the gimbal-lock claim
(theta is discontinuous at the +/-z poles per the RDK source);
distinguish axis_angles from ov_radians instead of calling them
equivalent.
- arm-fixed-camera.md, arm-gripper-camera.md, mobile-base-arm.md,
mobile-base-sensors.md, quickstarts/frame-system.md: replace every
axis-angle-style camera orientation with a pointing-vector value and
a one-line statement of the rule; state the +z-out-of-the-lens
convention consistently (mobile-base-sensors claimed cameras default
to looking along +y).
- Mobile-base pages: the frame system holds configured relationships
only; it does not track the base as it drives (only arm, gantry, and
gripper feed live inputs). Rewrote the step text, a verification step
that asked readers to drive the base and watch frames move, and a
troubleshooting expand describing a symptom the frame system cannot
produce. Confirmed live: move_straight leaves the base frame's world
pose unchanged.
- quickstarts/frame-system.md: correct the expected print-status
output for the zero-joint ur5e (live-confirmed values); a frame
parented to an arm attaches to the end effector, not the arm origin.
- Consistency: gripper frame origin at the tool center point, lidar
casing, table-surface tree entries annotated.
✅ 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
Style-review pass over the PR's changed pages (viam-doc-review): - orientation-vectors.md: drop the redundant negative clause after the API Pose statement; state the identity orientation positively; split the pole-discontinuity sentence; the Validation section now says 'pointing vector' instead of 'axis' for ov formats, matching the terminology this PR corrects. - arm-fixed-camera.md: put the condition before the instruction in the th guidance (if the image needs to rotate, use th). - mobile-base-arm.md: state the visualizer behavior positively (shows base-parented frames at the configured pose even while the base drives); align the SLAM/movement-sensor sentence with the wording on mobile-base-sensors.md. - arm-gripper-camera.md: replace 'you do not need to add it' with the positive instruction to leave the gripper frame's geometry field empty. - quickstarts/frame-system.md: an arm's printed pose is the pose of its end effector (not 'is its end effector'); split the 44-word sentence. prettier, markdownlint, vale (0 errors), make build-prod all pass.
|
Hey btshrewsbury-viam — CI is green and no reviewer is assigned yet. Could you request one when you have a chance? Auto-comment from overwatch. Will not re-nudge for 7 days. |
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
2 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
Fixes the systemic orientation-vector error found in the motion-planning section review: several pages taught and used
ov_degreesas an axis-angle rotation ("tilt the camera by rotating 30 degrees about x"). In the RDK,(x, y, z)is the direction the component's +z axis points in the parent frame, andthspins the component about that direction (rdk/spatialmath/orientationVector.go, v1.0.0). Every axis-angle-style example aimed the camera somewhere else entirely.Live-confirmed on a viam-server v1.0.0 with fake components:
{x:1,y:0,z:0,th:180}(the docs' "flip to point down") resolves to pointing along +x with a 180° roll;{x:0,y:0,z:-1,th:0}resolves to exactly straight down.Also fixes two related wrong mental models on the same pages:
move_straight(500mm)leaves the base frame's world pose unchanged). Both mobile-base pages claimed it does, including a verification step that could never pass.print-statusoutput showed the zero-joint ur5e atX:0 Y:0 Z:0; the real output (live-confirmed) isX: -817.20 Y: -232.90 Z: 62.80, and the page now explains why.Files
reference/orientation-vectors.md: field bullets and two Common-orientations table rows applied the axis-angle reading; the five-formattypechoice exists only in JSON config (APIPosemessages are always OV degrees); the gimbal-lock section claimed OV is singularity-free (RDK source:this discontinuous at the ±z poles);axis_angleswas described as equivalent toov_radians.frame-system/arm-fixed-camera.md,arm-gripper-camera.md,mobile-base-arm.md,mobile-base-sensors.md: every camera orientation value replaced with a pointing vector plus a one-line statement of the rule; +z-out-of-the-lens convention stated consistently (mobile-base-sensors claimed cameras default to looking along +y); base-tracking passages rewritten; gripper origin unified on the tool center point; lidar casing.quickstarts/frame-system.md: corrected camera orientation, expected CLI output, and the step-6 claims about which frames move.Full review + live-confirmation log:
~/viam/motion-planning-section-review-2026-07-14.md(internal).Heads-up for #5099:
frame-system/overview.md(moved by that PR, untouched here) teaches the same axis-angle model at ~L130 and needs the same fix.Verification
prettier, markdownlint, vale (0 errors),
make build-prodall pass. Orientation semantics, base behavior, and CLI output confirmed against a live viam-server v1.0.0 (machinedocs-review-confirm) with Python SDK 0.79.1.🤖 Generated with Claude Code