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

docs/motion-planning/obstacles/configure-workspace-obstacles.md

@@ -12,13 +12,14 @@ diataxis: how-to
 Static obstacles are the fixed shapes in your workspace: the table the arm is bolted to, a back wall, a ceiling, a bin the arm reaches into.
 Configure them once through the Viam app and the motion planner includes them on every plan.
 
-Three config patterns cover most cases:
+These config patterns cover most cases:
 
-| Pattern                                                                   | Use when                                                                                               |
-| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| [`erh:vmodutils:obstacle`](#default-obstacle-pattern)                     | Most workspace obstacles: tables, walls, fixtures, bespoke shapes. One component, any geometry.        |
-| [`rdk:builtin:fake` generic component](#configure-a-single-primitive)     | A single box, sphere, capsule, or cylinder when you do not want to add a registry module.              |
-| [`erh:vmodutils:obstacle-open-box`](#containers-and-work-cell-boundaries) | Containers, bins, or rectangular work-cell envelopes. Generates five geometries from outer dimensions. |
+| Pattern                                                                      | Use when                                                                                               |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| [`erh:vmodutils:obstacle`](#default-obstacle-pattern)                        | Most workspace obstacles: tables, walls, fixtures, bespoke shapes. One component, any geometry.        |
+| [`rdk:builtin:obstacle` generic component](#use-the-built-in-obstacle-model) | The same list of geometries with no registry module to add. Requires `viam-server` v1.12.0 or later.   |
+| [`rdk:builtin:fake` generic component](#configure-a-single-primitive)        | A single box, sphere, capsule, or cylinder when you do not want to add a registry module.              |
+| [`erh:vmodutils:obstacle-open-box`](#containers-and-work-cell-boundaries)    | Containers, bins, or rectangular work-cell envelopes. Generates five geometries from outer dimensions. |
 
 For obstacles your code builds at runtime (objects detected by vision, temporary keep-out zones), see [Plan collision-free paths](/motion-planning/obstacles/avoid-obstacles/) instead.
 
@@ -184,11 +185,43 @@ Use one component per logical obstacle (table, ceiling, each wall) when the obst
 Use several geometries under one component when the shapes form a rigid unit: an L-bracket, an enclosure, a tool stand with a base and a post.
 The component's frame positions the whole group.
 
+## Use the built-in obstacle model
+
+`viam-server` v1.12.0 and later include an obstacle model, `rdk:builtin:obstacle`, under the generic component API.
+Like `erh:vmodutils:obstacle`, it takes a `geometries` list, but it needs no registry module.
+The **3D SCENE** tab creates this model when you add an obstacle: see [Add an obstacle](/visualization/3d-scene/editing-frames-visually/#add-an-obstacle).
+
+To configure it in JSON, add a component like this one to your machine's configuration:
+
+```json
+{
+  "name": "table",
+  "api": "rdk:component:generic",
+  "model": "rdk:builtin:obstacle",
+  "attributes": {
+    "geometries": [
+      { "type": "box", "x": 1800, "y": 1100, "z": 40, "label": "top" }
+    ]
+  },
+  "frame": {
+    "parent": "world",
+    "translation": { "x": 500, "y": 0, "z": -20 },
+    "orientation": {
+      "type": "ov_degrees",
+      "value": { "x": 0, "y": 0, "z": 1, "th": 0 }
+    }
+  }
+}
+```
+
+- **`geometries`** (required) lists one or more geometries in the same form as a frame's `geometry`. Each entry's optional `translation` and `orientation` position it relative to the component's frame.
+- **`label`** names each geometry in the frame system as `<component>:<label>` (here, `table:top`). Labels must be unique within the component, can't contain `:`, and can't be `world`. An unlabeled geometry is named `geometry_<n>` by its position in the list, starting at 0.
+- **The component needs a frame.** Without one, the obstacle is not part of the frame system and motion planning does not avoid it. A `geometry` in the component's frame is ignored in favor of `geometries`.
+
 ## Configure a single primitive
 
-For a single primitive shape when you do not want to add the `erh:vmodutils` module, use a `generic`/`fake` component.
-The **3D SCENE** tab can create one for you: see [Add an obstacle](/visualization/3d-scene/editing-frames-visually/#add-an-obstacle).
-To add it from the **CONFIGURE** tab instead:
+On `viam-server` versions before v1.12.0, which don't have the built-in obstacle model, use a `generic`/`fake` component for a single primitive shape when you do not want to add the `erh:vmodutils` module.
+To add it from the **CONFIGURE** tab:
 
 1. Click the **+** icon and select **Blocks**.
 2. Search for `generic` and click the **generic/fake** result card. Click **Add to machine**.

docs/motion-planning/obstacles/overview.md

@@ -114,6 +114,12 @@ to the motion service at call time. It contains:
 
 You construct a WorldState in your code and pass it to the `Move` call.
 
+An obstacle is placed in world coordinates once, when planning starts, even if
+you express it in a moving frame such as the gripper's. It stays where it was
+for the whole plan. To model something that moves with a component, such as an
+object in a gripper, add it as a transform parented to that component instead.
+See [Attach and detach geometries at runtime](/motion-planning/obstacles/attach-detach-geometries/).
+
 Transforms merge into the frame system by addition only. The motion
 service builds a fresh frame system for each call, appends the configured
 parts, then appends each transform from `WorldState.transforms`. A

docs/visualization/3d-scene/build-mode.md

@@ -15,13 +15,14 @@ Build mode turns the 3D scene into a configuration editor. You can give componen
 
 - **The Details panel becomes editable** for configurable frames: the parent frame, local position and orientation, and geometry. For what each field maps to in configuration, see [Details panel fields](/visualization/3d-scene/controls-and-settings/#details-panel-fields).
 - **Transform tools appear**, so you can move, rotate, and scale a frame's geometry in the viewport instead of typing values, with optional snapping and a choice of local or world axes.
+- **Appearance changes are saved.** Color, opacity, visibility, and the axes helper you set on the Details panel's **Appearance** tab are saved to the component's `visualizer` configuration, and frames inside it, such as an obstacle's shapes, follow them unless they set their own.
 - **An editing banner appears** with **Undo** and **Redo** for stepping through your edits, and shows whether you have unsaved changes.
 
 ## Add frames and obstacles
 
 Components that don't have a frame yet appear in the **World** panel under **Frameless components**. Select one and choose **Add frame** to place it in the scene at the world origin. You can't remove a frame from the scene; see [What Build mode doesn't cover](#what-build-mode-doesnt-cover).
 
-To model a fixed obstacle, such as a wall or a table, use the **+** button in the **World** panel and choose **Obstacle**. It adds a `fake` generic component with a 100 mm box at the world origin, as an unsaved edit. Move and resize it like any other frame, then save. The motion planner avoids its geometry like any other obstacle in your frame system. For other ways to define obstacles, see [Define obstacles](/motion-planning/obstacles/).
+To model a fixed obstacle, such as a wall or a table, use the **+** button in the **World** panel, choose **Obstacle**, and pick a type: **Simple** (a single shape), **Bounds** (walls enclosing a box-shaped space), or **Complex** (a group of shapes). It adds a generic component with the built-in `obstacle` model (`rdk:builtin:obstacle`, `viam-server` v1.12.0 or later) as an unsaved edit, with its shapes in the component's `geometries` attribute. Move it like any other frame, edit its shapes in the Details panel, then save. For step-by-step instructions, see [Add an obstacle](/visualization/3d-scene/editing-frames-visually/#add-an-obstacle). The motion planner avoids its geometry like any other obstacle in your frame system. For other ways to define obstacles, see [Define obstacles](/motion-planning/obstacles/).
 
 ## Save your edits
 
@@ -33,7 +34,7 @@ The **LLM Scene Builder** takes a prompt describing a change to a frame or its g
 
 ## What Build mode doesn't cover
 
-Build mode edits a subset of frame configuration: the parent, translation, orientation, and a single geometry. Edit the JSON instead for:
+Build mode edits a subset of frame configuration: the parent, translation, orientation, and a single geometry (or, for an obstacle, its list of shapes). Edit the JSON instead for:
 
 - Bulk changes, such as renaming many frames.
 - Orientations you want to keep as axis angles, quaternions, or Euler angles. Build mode displays any orientation, but saving any change to a frame rewrites its orientation as an orientation vector in degrees (`ov_degrees`).

docs/visualization/3d-scene/controls-and-settings.md

@@ -33,16 +33,16 @@ Keyboard navigation pauses while you type in a field or hold `⌘` (or `Ctrl`).
 
 The Details panel shows the selected entity's pose and geometry on its **Details** tab, and how it draws on its **Appearance** tab. Fields that correspond to frame configuration are editable in [Build mode](/visualization/3d-scene/build-mode/) for configurable frames, and read-only otherwise. In [Move mode](/visualization/3d-scene/move-mode/), the panel becomes the move controls instead.
 
-| Field                                           | Meaning                                                                        | Frame configuration                                                                      |
-| ----------------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
-| **world position** (mm)                         | The entity's position in the world frame                                       | None. Computed from the local pose and the parent chain                                  |
-| **world orientation**                           | The entity's orientation in the world frame, as an orientation vector          | None. Computed                                                                           |
-| **parent frame**                                | The frame this entity is attached to                                           | `frame.parent`                                                                           |
-| **local position** (mm)                         | Position relative to the parent frame                                          | `frame.translation`                                                                      |
-| **local orientation**                           | Orientation relative to the parent frame, entered as **OV (deg)** or **Euler** | `frame.orientation`, stored as an orientation vector in degrees whichever form you enter |
-| **geometry**                                    | The collision geometry: `None`, `Box`, `Sphere`, or `Capsule`                  | `frame.geometry.type`                                                                    |
-| **dimensions** (mm)                             | `x`, `y`, `z` for a box; `r` for a sphere; `r` and `l` for a capsule           | `frame.geometry` `x`, `y`, `z`, `r`, `l`                                                 |
-| **Appearance** tab: color, opacity, axes helper | How the entity draws in the scene                                              | None. These change the rendering only, not the configuration                             |
+| Field                                                       | Meaning                                                                        | Frame configuration                                                                      |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| **world position** (mm)                                     | The entity's position in the world frame                                       | None. Computed from the local pose and the parent chain                                  |
+| **world orientation**                                       | The entity's orientation in the world frame, as an orientation vector          | None. Computed                                                                           |
+| **parent frame**                                            | The frame this entity is attached to                                           | `frame.parent`                                                                           |
+| **local position** (mm)                                     | Position relative to the parent frame                                          | `frame.translation`                                                                      |
+| **local orientation**                                       | Orientation relative to the parent frame, entered as **OV (deg)** or **Euler** | `frame.orientation`, stored as an orientation vector in degrees whichever form you enter |
+| **geometry**                                                | The collision geometry: `None`, `Box`, `Sphere`, or `Capsule`                  | `frame.geometry.type`                                                                    |
+| **dimensions** (mm)                                         | `x`, `y`, `z` for a box; `r` for a sphere; `r` and `l` for a capsule           | `frame.geometry` `x`, `y`, `z`, `r`, `l`                                                 |
+| **Appearance** tab: color, opacity, visibility, axes helper | How the entity draws in the scene                                              | In Build mode, the component's `visualizer` field. Not saved in other modes              |
 
 The panel header can open a [frame POV widget](/visualization/3d-scene/3d-scene-widgets/#frame-pov) and copy the entity's pose and geometry as JSON. To center the camera on the selected entity, use the scene's focus control or its keyboard shortcut.
 

docs/visualization/3d-scene/editing-frames-visually.md

@@ -39,14 +39,20 @@ You can then reposition it using the Details panel.
 
 ## Add an obstacle
 
-To add a box that motion planning avoids without leaving the tab:
+To add an obstacle that motion planning avoids without leaving the tab:
 
-1. In the **World** panel header, click **Add object** (**+**) and select **Obstacle**.
-2. In the **New obstacle** dialog, keep the suggested name (`obstacle-1`, `obstacle-2`, and so on) or enter your own, and click **Create**.
+In the **World** panel header, click **Add object** (**+**), select **Obstacle**, choose a type, and name it:
 
-The scene switches to build mode and adds a `generic` component with the `fake` model, a frame at the world origin, and a 100 mm box geometry, and selects it.
-Resize and position it using the Details panel, then [save your changes](#save-your-changes).
-For obstacle patterns beyond a single box, see [Configure workspace obstacles](/motion-planning/obstacles/configure-workspace-obstacles/).
+- **Simple**: a single shape.
+- **Bounds**: walls enclosing a box-shaped space. You set the interior size and wall thickness, and can turn individual walls, such as the floor or ceiling, on or off.
+- **Complex**: a group of shapes.
+
+The scene switches to build mode, adds a `generic` component with the built-in `obstacle` model (`rdk:builtin:obstacle`), and selects it.
+The obstacle's shapes are stored in the component's `geometries` attribute, positioned relative to the component's frame.
+
+Edit the shapes in the Details panel, then [save your changes](#save-your-changes).
+The `obstacle` model requires `viam-server` v1.12.0 or later.
+To configure obstacles in JSON instead, see [Configure workspace obstacles](/motion-planning/obstacles/configure-workspace-obstacles/).
 
 ## Edit a frame's position and orientation