Add Visualization section and reframe Debug a motion plan#5099
Open
btshrewsbury-viam wants to merge 52 commits into
Open
Add Visualization section and reframe Debug a motion plan#5099btshrewsbury-viam wants to merge 52 commits into
btshrewsbury-viam wants to merge 52 commits into
Conversation
…s, plan verification Add four new pages under Motion Planning and wire them into navigation: - Frame System > End effector frames: how Move targets a named frame, the frame attribute, WorldState transforms, and WorldState vs the world state store service. - Move an arm > Moving through multiple waypoints: multi-goal PlanRequest with armplanning.PlanMotion, continuous trajectory, return_partial_plan. - Move an arm > Pose clouds: relax a goal into a region with NewPoseInFrameWithGoalCloud; briefly noted and linked from the constraints page. - Verifying a Motion Plan: armplanning.PlanMotion vs Move, assembling a PlanRequest, reading the Plan, and the motion service plan DoCommand verb. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Add a new top-level Visualization section covering the 3D scene and the world state store service, and reframe the motion planning debug page around publishing a plan as custom visuals. - visualization/_index.md: what the 3D scene renders, an improved frame system description, and built-in vs custom visuals. - visualization/visuals-and-collisions.md: transform anatomy, UUIDs, geometry types, and why a visual is not an obstacle the planner avoids. - visualization/publish-visuals-from-a-module.md: implement a world state store service, build transforms with the draw library, poll-and-update loop, and visualizing a non-WSS resource by depending on it. - visualization/drawing-library.md: the draw library and the standalone Viam Visualization app. - motion-planning/3d-scene/debug-motion-plan.md: publish a plan's trajectory and goals as transforms (ComputePoses + draw), then diagnose against obstacles and reach. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
✅ 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
Apply house-style fixes from the doc review: remove the negation-based opening and the "Understanding..." learning-objective leak, replace the vague "targets frames" wording with what Move actually does, convert "is not treated as hardware" to the positive "resolves to a frame", reframe the world state store contrast positively (noun-plus-job), and trim the description under the Hugo length limit. Co-Authored-By: Claude Opus 4.8 <[email protected]> Claude-Session: https://claude.ai/code/session_01GdVfSBN5zBzSHStG1HoPDK
|
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. |
Apply house-style and accuracy fixes across the move-an-arm motion pages, and add diagrams for the concepts that read better visually. - Pose clouds: rework the example around a grasped cup with a target frame and an orientation constraint, add a units/default table and a PoseCloud snippet, and add two diagrams (the cup pose cloud and the tilted-surface target frame with the orientation-vector tolerance). - Multiple waypoints: answer the start-state and frame-system questions against source, and add a single-Move-vs-multi-goal contrast diagram. - Verify a plan and constraints: convert negations to positive statements, replace jargon, and fix a banned idiom in a heading. All code is verified against the RDK source (NewPoseInFrameWithGoalCloud, PoseCloud, OrientationConstraint, armplanning.PlanMotion, PlanRequest). Co-Authored-By: Claude Opus 4.8 <[email protected]> Claude-Session: https://claude.ai/code/session_01GdVfSBN5zBzSHStG1HoPDK
Use arm.JointPositions to seed the start state from the arm's current position (with arm.FromRobot), and explain the extra/nil parameter. Correct the PlanRequest description (the world state is optional, not required), and fix grammar and code-comment typos. Co-Authored-By: Claude Opus 4.8 <[email protected]> Claude-Session: https://claude.ai/code/session_01GdVfSBN5zBzSHStG1HoPDK
Convert negation-heavy framing to noun-plus-job across the visualization pages (a visual and its collision geometry each get a positive role), and fix soft negatives vale does not flag (invisible, nothing, cannot). Move the section index into an overview page (thin _index + manualLink, matching the frame-system convention) and restructure it as a hub with a short section per visualization approach: the 3D scene, Viam Visualization, component data in apps, and time-series dashboards. Fix code against source: api.DrawGeometry takes a DrawGeometryOptions struct, and add the draw service's add/update/remove fan-out to the browser. Improve the frame system description to lead concrete. Co-Authored-By: Claude Opus 4.8 <[email protected]> Claude-Session: https://claude.ai/code/session_01GdVfSBN5zBzSHStG1HoPDK
Make /visualization/ forward to /visualization/overview/ with the empty-node layout and a canonical link, matching how other section indexes (reference/apis/services, tutorials/control) redirect. Co-Authored-By: Claude Opus 4.8 <[email protected]> Claude-Session: https://claude.ai/code/session_01GdVfSBN5zBzSHStG1HoPDK
- Overview: add per-approach when/why bullets, name the Viam web app and the apps you build with an SDK, and link the build-apps tutorials. - Redirect /build-apps/ to its overview page (empty_node + canonical). - Visuals and collisions: add JSON/Python/Go examples for each geometry type, building the Geometry proto directly (no helper library), per the example-visualizations-go and example-visualizations-python modules. Co-Authored-By: Claude Opus 4.8 <[email protected]> Claude-Session: https://claude.ai/code/session_01GdVfSBN5zBzSHStG1HoPDK
- Flip arm/tool/object frames to Z-down (DH convention) while keeping the world frame Z-up, per Dan's orientation-axis comment. - Use a right-handed Z-down triad with green Y on the world frame's lower-left side (X-left, Y-down-left), so all green axes sit on one side; give Y a longer line so it reads clearly. - Label one triad per image (the rest are color-coded), draw red X over green Y, and remove the per-axis labels that collided. - Trim the end-effector-types caption to drop the ambiguous "world frame at the base" clause; widen the canvas so "drill-tip frame" is not clipped. - Delete the orphaned drill-bit-frame.svg (superseded by arm-vs-gripper-frame). Co-Authored-By: Claude Opus 4.8 <[email protected]> Claude-Session: https://claude.ai/code/session_01GdVfSBN5zBzSHStG1HoPDK
Co-authored-by: Shannon Bradshaw <[email protected]>
Co-authored-by: Shannon Bradshaw <[email protected]>
Per Dan's review: a pose cloud's OX/OY/OZ leeways are checked against a normalized orientation vector, so the three share one unit-sphere budget and do not move independently. Explain that you widen all three together to let the pointing direction vary, and that a wide OX/OY with a tight OZ holds the tool aligned because OZ pins the direction and the unit-sphere constraint then holds OX and OY at 0. Co-Authored-By: Claude Opus 4.8 <[email protected]> Claude-Session: https://claude.ai/code/session_01GdVfSBN5zBzSHStG1HoPDK
btshrewsbury-viam
marked this pull request as draft
June 29, 2026 15:40
Co-authored-by: Shannon Bradshaw <[email protected]>
Co-authored-by: Shannon Bradshaw <[email protected]>
Co-authored-by: Shannon Bradshaw <[email protected]>
Restructure end-effector-frames.md into the arm frame, end effector frames, component-frame definition, moving with the motion service, and code-defined frame sections. Add the arm/joint-frames figure and fix the frame-system diagram triads (right-handed axes, DH joint orientation). Link the world state store service and WorldState references.
Rework pose-clouds.md: when-to-use guidance, the cup running example, the pose-cloud-as-box model, tolerances measured in the target frame, and the orientation-vector tolerance coupling plus the normalization sharp edge. Update the pose-cloud-cup and pose-cloud-target-frame diagrams (right-handed triads, label fixes).
Add brief frame and pose definitions to the frame-system overview so they are referenceable (per review), and repoint the end-effector-frames link to the new anchor.
Differentiate the three confusable 'apps': - the Viam app (app.viam.com, hosts the 3D SCENE tab) — no more 'Viam web app' - Viam Visualization / the standalone Viam visualizer — no more 'Viam Visualization app' - a custom app / custom user interface you build (was 'an app you build') Also capitalize the product name Viam Visualization consistently.
… docs/visualization-section
btshrewsbury-viam
changed the base branch from
main
to
docs/motion-planning-pages
July 2, 2026 15:07
Moves (with aliases from old URLs, cross-links + section cards updated): - calibrate-frame-offsets -> visualization/3d-scene-tools/measuring-between-frames (renamed) - edit-frames -> visualization/3d-scene-tools/editing-frames-visually (renamed) - verify-point-cloud-alignment -> visualization/perception/ Surface the World State Store Service reference under Visualization > Reference. Content split of motion-planning/3d-scene/_index.md is deferred.
Move motion-planning/3d-scene/set-up-obstacle-avoidance.md -> motion-planning/obstacles/verify-obstacles.md (alias from old URL), add it to the obstacles how-to cards, and repoint inbound links.
- Move Debug a motion plan and Visualize a motion plan out of 3d-scene/ to the motion-planning root - Merge 'Debug with the CLI' into 'Debug a motion plan' as a 'With the CLI' section alongside the '3D scene' checks (aliases from both old URLs) - Retitle verify-a-plan linkTitle to 'Verify a plan before running it' - Reweight the cluster in order: how-works(80), verify(82), debug(84), visualize(86) - Repoint inbound links; aliases cover old URLs
- Rename '3D Scene Tools' to a '3D scene' section (visualization/3d-scene/) and move Measuring between frames, Editing frames visually, 3D Scene Widgets into it - Make 'Visualizing with the 3D scene' the section landing (_index) - Move the old motion-planning '3D scene tab' reference in as 'The 3D scene interface', stripping the concept intro now on the landing and dropping its cross-section how-to cards - Aliases from all old URLs (including /motion-planning/3d-scene/); repoint links
…ction # Conflicts: # docs/motion-planning/_index.md # docs/motion-planning/frame-system/end-effector-frames.md # docs/motion-planning/verify-a-plan.md
- Convert em-dash-as-punctuation to colons in the 3D scene interface and editing-frames pages (carried in from the old motion-planning pages) - Reword 'the planner knows about them' to avoid personification - 'lands in the wrong place' -> 'appears in the wrong place'
The Netlify no-more-404 plugin failed the deploy: /visualization/3d-scene-tools/ existed in this branch's earlier deploys (before the section was renamed to '3d-scene') and 404'd with no redirect. Alias it to /visualization/3d-scene/.
btshrewsbury-viam
marked this pull request as ready for review
July 7, 2026 16:37
…ings - Transform's geometry field is physical_object, not Transform.Geometry (verified against go.viam.com/api common.proto and the Python SDK) - Motion.GetPose is deprecated in favor of the frame system service's GetPose, not Robot.GetPose (rdk services/motion/motion.go) - Rewrite negation-heavy openings positively (verify-obstacles, visualize-a-motion-plan), drop personification (arm "thinks"/"expects") - Replace banned words: surface(s) as verb, ships, guarantees - Define stepColor/goalColor and commonpb import in plan snippets; replace placeholder loop body with the stepMarker call - Note commonpb/pb import paths in module snippets - Consistent linkTitle casing; WorldState page heading and tightening - Sphere: name both the JSON r key and proto radius_mm field
Hugo warned on the two new descriptions (171 and 159 chars, limit 158); the perception index opener was one 31-word sentence.
The scene's metadata parser recognizes colors, color_format, opacities, show_axes_helper, invisible, chunks, and relationships, and ignores unknown keys. collision_allowed appears only in a proto comment; neither the draw library writes it nor the scene reads it, so drop it.
- Transform metadata reference: the seven keys the scene reads (colors, color_format, opacities, show_axes_helper, invisible, chunks, relationships) with wire formats, verified against draw/transform.go and the scene's metadata.ts parser - Vision services in the 3D scene: display GetObjectPointClouds output, per-service toggles and polling rate, camera-frame vs detector attribution, tuning loop, empty-layer checks - Troubleshoot the 3D scene: classify symptoms by layer (configuration, module, connection) and read the scene's own signals first - Rename drawing-library.md to viam-visualization.md (alias kept): the page is the standalone-visualizer how-to; adds the snapshot save/load flow with the visualization_snapshot filename prefix - Python note on publish-visuals: viam.services.worldstatestore implements the same three methods; draw helper is Go-only - Cards for the new pages on overview, perception, and reference indexes
- Document the frame POV widget (opens from the Details panel's View from this frame button; verified ungated, WEBLABS_EXPERIMENTS is empty) and move camera-widget mechanics to the widgets page - Map the axis colors to X, Y, Z on the 3D scene index - Link the embedding guide from the overview's custom apps section - Link the geometry types table from visuals-and-collisions - World state store API page: replace the stale VISUALIZE tab name, describe what the API does, and link the implementing how-to
…ction # Conflicts: # docs/visualization/3d-scene/the-3d-scene-interface.md
This was referenced Jul 14, 2026
- draw library reference: placement/identity options, shape constructors, color builders, metadata options, snapshot options, each verified against motion-tools main; pkg.go.dev linked as the current inventory since the library moves faster than the RDK - Publish visuals: show the machine-config services entry (api rdk:service:world_state_store, model, depends_on) so the implemented module actually lands on a machine
- Viam Visualization page: hosted playground (try without installing), the Running locally guide, the generated client API reference, and a new Connect to a live machine section (.env.local credentials + machine picker), which the upstream guide documents and our page previously omitted - Publish visuals: link the upstream Implementing WorldStateStoreService guide and its complete runnable example module - draw reference: link the project's generated API docs alongside pkg.go.dev
Member
|
It looks like the following files may have been renamed. Please ensure you set all needed aliases: |
btshrewsbury-viam
requested review from
Devin T. Currie (DTCurrie) and
Micheal Parks (micheal-parks)
July 14, 2026 17:59
Collaborator
Author
|
Micheal Parks (@micheal-parks) and Devin T. Currie (@DTCurrie) would you mind reviewing please? The new viz section of the docs can be seen here: https://deploy-preview-5099--viam-docs.netlify.app/visualization/overview/ |
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
Adds a new top-level Visualization section, moves the 3D scene tab pages into it, and reframes motion-plan debugging around the 3D scene and publishing a plan as custom visuals.
New section:
docs/visualization/3d-scene/_index) — what the scene renders, where each element comes from, and built-in configuration content vs custom visuals published at runtime.physical_objectfield, metadata, UUID), stable identity via UUID, geometry types with JSON/Python/Go examples, and the key point that a world-state-store visual is not an obstacle the planner avoids (planner geometry comes from the frame system +WorldState).ListUUIDs/GetTransform/StreamTransformChanges), build transforms with thedrawlibrary, drive a poll-and-update loop emittingTransformChangeevents, and visualize a non-WSS resource by depending on it and pulling its API, plus the machine-config services stanza that puts the module on a machine.GetObjectPointCloudsoutput in the scene), and verify point cloud alignment (moved from Motion Planning).WorldStateconcept page, a Transform metadata reference (the seven keys the scene actually reads, with wire formats, verified against the draw library and the scene's parser), a draw library reference (placement/identity options, shape constructors, colors, metadata, snapshot options, linked to the generated API docs and pkg.go.dev), plus a card to the existing world state store API reference.Pages moved into Visualization (aliases added for every old URL)
motion-planning/3d-scene/_index.md→visualization/3d-scene/the-3d-scene-interface.mdmotion-planning/3d-scene/edit-frames.md→visualization/3d-scene/editing-frames-visually.mdmotion-planning/3d-scene/calibrate-frame-offsets.md→visualization/3d-scene/measuring-between-frames.mdmotion-planning/3d-scene/verify-point-cloud-alignment.md→visualization/perception/verify-point-cloud-alignment.md3d-scene-widgets.md(arm positions, camera widgets, frame POV)Motion Planning changes
motion-planning/debug-motion-plan.mdand now covers both the 3D scene checks and the CLI checks; it absorbs and redirects the deleteddebug-motion-with-cli.md.motion-planning/visualize-a-motion-plan.md) — convert a plan's trajectory to poses withFrameSystemInputs.ComputePoses, build step/goal markers withdraw, and serve them through a world state store service.motion-planning/3d-scene/set-up-obstacle-avoidance.md→motion-planning/obstacles/verify-obstacles.md.Notes for reviewers
editing-frames-visually.mdthrough the rename, and the AI Scene Builder toolbar button is documented on the interface page with its link retargeted to the new path.client/apianddrawAPI references, and the browser playground. All URLs verified live.v1.0.0-rc0(world state store service interface,TransformChange,ComputePoses,armplanning.PlanMotion,sensor.FromProvider, capsule length ≥ 2×radius, CLI motion commands),go.viam.com/apiv0.1.566 proto (Transform.physical_object, geometry oneof, metadata conventions), andviam-labs/motion-toolsmain (drawAPI,api.DrawGeometry, Settings panel labels, PLY-only mesh loading).drawandclient/apisnippets follow the published guide and are illustrative, not compiled end-to-end.draw/transform.goandsrc/lib/metadata.ts;collision_allowedappears only in a proto comment and is neither written nor read, so the docs no longer mention it.make build-prod.🤖 Generated with Claude Code