Skip to content

Add Visualization section and reframe Debug a motion plan#5099

Draft
btshrewsbury-viam wants to merge 19 commits into
docs/motion-planning-pagesfrom
docs/visualization-section
Draft

Add Visualization section and reframe Debug a motion plan#5099
btshrewsbury-viam wants to merge 19 commits into
docs/motion-planning-pagesfrom
docs/visualization-section

Conversation

@btshrewsbury-viam

@btshrewsbury-viam btshrewsbury-viam commented Jun 18, 2026

Copy link
Copy Markdown
Collaborator

What

Adds a new top-level Visualization section and reframes the motion planning Debug a motion plan page around publishing a plan as custom visuals. No files are moved out of Motion Planning; the 3D scene tab pages stay where they are.

New section: docs/visualization/

  • Visualizing with the 3D scene (_index) — what the 3D scene renders (frames, geometries, point clouds, custom visuals), an improved frame system description (per Michael and Dan), and built-in config content vs custom visuals published in code.
  • Visuals and collisions — transform anatomy (reference frame, pose, geometry, metadata, UUID), stable identity via UUID, geometry types, metadata as visualization attributes, 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).
  • Publish visuals from a module — implement the world state store service (ListUUIDs/GetTransform/StreamTransformChanges), build transforms with the draw library, drive a poll-and-update loop emitting TransformChange events, and visualize a non-WSS resource by depending on it and pulling its API.
  • The drawing library and Viam visualization — the standalone Viam Visualization app vs the in-app 3D scene tab, the draw primitives/styling, and running the app + pushing from a Go client.

Updated in place (stays in Motion Planning)

  • 3D scene tab > Debug a motion plan — reframed to publish a plan's trajectory and goals as transforms (FrameSystemInputs.ComputePoses + draw), serve them through a world state store service, and diagnose failures against obstacle geometry and reach.

Deferred to a later reorg PR

The layout's file moves and unscoped subsections (3D Scene Tools, Perception, Reference > World State Store Service / World State) are not included here, per the "do not move files" note. The world state store API reference already exists at reference/apis/services/world-state-store.md.

Notes for reviewers

  • Code is grounded in the RDK source and the viam-labs/motion-tools / Viam Visualization guides. The rdk core calls (ComputePoses, NewBox, NewSphere) are verified against source; the draw and client/api snippets follow the published guide and are illustrative, not compiled end-to-end.
  • Pre-PR checks pass: prettier, markdownlint, vale (0 findings), and make build-prod.

🤖 Generated with Claude Code

@btshrewsbury-viam @claude
Add Visualization section and reframe Debug a motion plan
e56850f 
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) <noreply@anthropic.com>
@netlify

netlify Bot commented Jun 18, 2026 •
edited
Loading

Copy link
Copy Markdown

✅ Deploy Preview for viam-docs ready!

Name Link
🔨 Latest commit 8c6bf4d
🔍 Latest deploy log https://app.netlify.com/projects/viam-docs/deploys/6a467e7e6f12e10008850d48
😎 Deploy Preview https://deploy-preview-5099--viam-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse		 1 paths audited
Performance: 43 (🟢 up 7 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.

@viambot viambot added the safe to build This pull request is marked safe to build from a trusted zone label Jun 18, 2026
@viamrobotics-overwatch

viamrobotics-overwatch Bot commented Jun 23, 2026

Copy link
Copy Markdown

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.

btshrewsbury-viam and others added 3 commits June 23, 2026 15:59
@btshrewsbury-viam @claude
Visualization: positive prose, overview hub, code accuracy
5f2830c 
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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GdVfSBN5zBzSHStG1HoPDK
@btshrewsbury-viam @claude
Visualization: redirect the section index to the overview
6b20f3a 
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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GdVfSBN5zBzSHStG1HoPDK
@btshrewsbury-viam @claude
Restructure visualization overview and add geometry code examples
0d5f356 
- 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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GdVfSBN5zBzSHStG1HoPDK
@btshrewsbury-viam btshrewsbury-viam mentioned this pull request Jun 25, 2026
Merged
@btshrewsbury-viam btshrewsbury-viam marked this pull request as draft June 29, 2026 15:40
@btshrewsbury-viam
Refine visualization pages: accuracy fixes, LO-driven ordering, clear…
4be9f8c 
…er WorldState vs world state store
@btshrewsbury-viam
Fix marker pose double-application; close LO gaps in visualization ho…
dbdc58c 
…w-tos

- Build geometries at NewZeroPose() and place via WithPose (was applying the
  pose twice: geometry center + transform pose)
- publish-visuals: add GetTransform, StreamTransformChanges, and emit fan-out
- debug-motion-plan: add goalMarker and clarify goal-pose source
- drawing-library: restore the draw-service add/update/remove fan-out passage
@btshrewsbury-viam
Close remaining visualization LO gaps
fa4d646 
- visuals-and-collisions: add a worked full-Transform assembly example (reference
  frame, pose, geometry, metadata, UUID) covering LO1 and metadata-in-code
- drawing-library: add the make setup / make up local-run command (LO6)
- debug-motion-plan: name the service methods that serve the plan markers (LO4)
@btshrewsbury-viam
Add new visualization pages: 3D-scene explainer, point clouds, World …
9c32cbb 
…State reference

- Visualizing with the 3D scene: the section's 3D-scene explainer, owning the
  four 3D-scene learning objectives (identify elements, sources/trace-to-origin,
  built-in-vs-custom, streamed updates)
- Perception > Point Clouds: how depth-camera point clouds render, display, and compare
- Reference > World State: what a per-request WorldState is, vs the world state store service
- Moves/renames of existing pages are deferred to the later reorg
@btshrewsbury-viam
Add 3D Scene Widgets and Cameras pages, sourced from the live 3D scene
5af83a7 
- 3D Scene Tools > 3D Scene Widgets: the widget overlays (Arm positions joint
  table, Camera widgets), enabled from Settings > Widgets
- Perception > Cameras: a camera's live feed widget (resolution, fps), its point
  cloud, and its frame
Content verified against the running app's 3D SCENE tab (viam-server 0.132.0).
@btshrewsbury-viam
Reword Debug a motion plan intro; drop 'static inspector'
a0a1d98
@btshrewsbury-viam
Revert build-apps _index (out of scope); make visualization nav consi…
94f6166 
…stent

- Restore build-apps/_index.md to main: the empty_node/layout:empty change
  belongs in the later reorg PR, not here
- visualization/_index.md: drop empty_node/layout:empty, use layout:docs +
  manualLink to /visualization/overview/ so the section renders as a normal nav
  link like every other section instead of a non-clickable header
@btshrewsbury-viam
Split Debug a motion plan: restore no-code checks, move viz to its ow…
477106d 
…n page

The PR reframe replaced the original visual-inspection guide with a code-heavy
publish-as-custom-visuals technique. Restore the practical no-code checks (frame
positions, obstacle geometry, reach, self-collision, common-causes table) as
'Debug a motion plan', and move the visualization technique to a new
'Visualize a motion plan' page. Each links to the other; Debug is the start,
Visualize is the deeper step. Repoint cards accordingly.
@btshrewsbury-viam
Standardize visualization surface naming
6b46fe2 
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.
@btshrewsbury-viam
Merge remote-tracking branch 'origin/main' into docs/visualization-se…
751c5a0 
…ction
@btshrewsbury-viam
Merge remote-tracking branch 'origin/docs/motion-planning-pages' into…
8c6bf4d 
… docs/visualization-section
@btshrewsbury-viam btshrewsbury-viam changed the base branch from main to docs/motion-planning-pages July 2, 2026 15:07
@btshrewsbury-viam
Rearrange 3D-scene pages into the visualization section per target IA
65c02c4 
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.
@btshrewsbury-viam
Move Verify obstacles into the Obstacles section
51e398d 
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.
@btshrewsbury-viam
Reorganize the plan-troubleshooting pages
c528e9d 
- 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
@btshrewsbury-viam
Create a 3D scene section in Visualization
504fe02 
- 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

safe to build This pull request is marked safe to build from a trusted zone

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@btshrewsbury-viam @viambot