Update obstacle docs for the built-in obstacle model and 3D scene obstacle types

[Shannon Bradshaw (shannonbradshaw)]

Source changes

• visualization#1107 (2.9.0): Add object > Obstacle now offers Simple, Bounds and Complex types and creates a generic component with the built-in rdk:builtin:obstacle model, with its shapes in attributes.geometries. Before, it created a generic/fake component with a 100 mm frame geometry. The same release saves Appearance tab edits to the component's visualizer config in Build mode.
• app#13981: the app's 3D scene tab now pins @viamrobotics/visualization 2.9.0, so these changes are live.
• rdk#6605: the rdk:builtin:obstacle model shipped in RDK v1.12.0.

Docs changes

• docs/visualization/3d-scene/editing-frames-visually.md: rewrote "Add an obstacle" for the three types and the obstacle model, and added the viam-server v1.12.0 requirement.
• docs/visualization/3d-scene/build-mode.md: the obstacle paragraph now names the obstacle model and its types instead of a fake generic component. Added that Appearance changes are saved in Build mode, and that obstacles carry a list of shapes.
• docs/visualization/3d-scene/controls-and-settings.md: the Appearance row said these settings change rendering only. They're now saved to visualizer in Build mode and not saved in other modes.
• docs/motion-planning/obstacles/configure-workspace-obstacles.md: added rdk:builtin:obstacle to the pattern table and gave it a section (config, label rules, <component>:<label> frame names, frame required, frame geometry ignored), taken from components/generic/obstacle/obstacle.go at v1.12.0. The generic/fake single-primitive section is now framed as the option for viam-server versions before v1.12.0. Which pattern should be the default is left for a follow-up.
• docs/motion-planning/obstacles/overview.md: added a note to the WorldState section. Obstacles passed in a WorldState are resolved to world coordinates once, when planning starts, even if expressed in a moving frame such as the gripper's. Objects that move with a component, such as a carried box, belong in WorldState.transforms, parented to that component. Verified with a palletizing script: modeling the held box as a gripper-frame obstacle let plans drag it through placed boxes, and switching it to a transform parented to the gripper fixed it (42 plans, 0 failures). Matches ObstaclesInWorldFrame in RDK motionplan.

Open docs#5283 (cylinder geometry) touches the obstacle pages too. It doesn't overlap these hunks.

Checks

prettier 3.2.5, markdownlint, vale 3.12.0, frontmatter_rules.py, and make build-prod pass.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for viam-docs ready!

Name	Link
🔨 Latest commit	6f91eef
🔍 Latest deploy log	https://app.netlify.com/projects/viam-docs/deploys/6ad155742390f69937f6062e
😎 Deploy Preview	https://deploy-preview-5423--viam-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 35 (🔴 down 9 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: Blocking issues

Documents the rdk:builtin:obstacle model (RDK v1.12.0) and the 3D scene's Simple, Bounds, and Complex obstacle types and saved Appearance settings (visualization 2.9.0, which the app pins). Almost every claim checks out against source. The verdict comes from one contradicted claim: the Appearance table says Reset appearance removes the visualizer field, but the code clears only the appearance keys. Changing one phrase fixes it.

CI: All required checks passing

Docs health: No regressions

Blocking

• docs/visualization/3d-scene/controls-and-settings.md:45: "Reset appearance removes it" is contradicted by viamrobotics/visualization src/lib/resourceAppearance.ts:153-163. withoutResourceAppearance sets only color, opacity, invisible, and show_axes_helper to undefined, and the code comment says everything else, such as an obstacle's editor hint, is kept. That matters for obstacles: their visualizer also holds the Simple/Bounds/Complex type (src/lib/obstacle.ts:41,74,101), and a reader could think a reset wipes it. A shape inside an obstacle also gets Reset to <component> rather than Reset appearance (ConfigAppearanceDetails.svelte:90). Fix: For example, "Reset appearance clears these values from it."

Nits

• docs/motion-planning/obstacles/configure-workspace-obstacles.md:17-22: The table still leads with erh:vmodutils:obstacle as the default pattern, while the 3D scene now creates rdk:builtin:obstacle. The PR description defers this to the docs team. Consider a follow-up that decides which one is the default, so the two pages don't point readers at different defaults.

Verified against source (17 claims)

• rdk:builtin:obstacle is a generic component model whose config takes geometries: viamrobotics/rdk components/generic/obstacle/obstacle.go:22,25-27,74-76
• First shipped in v1.12.0: obstacle poc (#6605) commit 2176b91d4, earliest tag v1.12.0 (v1.12.0-rc0 before it)
• geometries is required (empty list rejected): obstacle.go:31-33
• Labels must be unique, can't contain :, and can't be world: obstacle.go:42-51
• Unlabeled geometries are named geometry_<n> from 0: obstacle.go:66-68, referenceframe/model.go:188-190
• Geometries are named <component>:<label> in the frame system: obstacle.go:17-21 (model doc comment), referenceframe/model.go:180-205
• Without a frame it isn't in the frame system; a frame geometry is ignored in favor of geometries: obstacle.go:101-107
• JSON example fields (type, x, y, z, label, translation, orientation): spatialmath/geometry.go:104-132
• Add menu offers Simple, Bounds, Complex with the documented descriptions: viamrobotics/visualization src/lib/plugins/WorldTree/obstacleTypeOptions.ts:22-47
• Dialog titles "New simple/bounds/complex obstacle": NewObstacleDialog.svelte:92
• Default names obstacle-N (simple, complex) and bounds-N: obstacleTypeOptions.ts:25,32,39, src/lib/obstacle.ts:105-113
• Simple and Complex start as one 100 mm box at the origin: src/lib/obstacle.ts:13,22-42,82-102
• Bounds starts as a 1000 mm interior with 10 mm walls, raised by half its height so the floor sits on the ground plane: src/lib/obstacle.ts:45-76
• Bounds editor sets interior size, wall thickness, and per-wall toggles: BoundsObstacleEditor.svelte:34-35,74-111
• Complex editor has Add shape: ComplexObstacleEditor.svelte:183
• Appearance (color, opacity, visibility, axes helper) saved to visualizer in build mode, child frames follow unless set, session-only in monitor mode: ConfigAppearanceDetails.svelte:46-90, resourceAppearance.ts:27, SessionAppearanceDetails.svelte, CHANGELOG 2.9.0
• The app ships visualization 2.9.0: viamrobotics/app pnpm-workspace.yaml:50

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

[Shannon Bradshaw (shannonbradshaw)]

Thanks, you're right. Fixed in 3453285: the Appearance row now says Reset appearance clears these values from visualizer and keeps its other settings, such as an obstacle's type. This matches withoutResourceAppearance.

On the default pattern: I'm leaving the table's order as it is in this PR. Whether rdk:builtin:obstacle should replace erh:vmodutils:obstacle as the default is a call for the docs team, so it belongs in a follow-up.

---

Generated by Claude Code

[github-actions]

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