Visualization: positive prose, overview hub, code accuracy

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

Author: btshrewsbury-viam

docs/motion-planning/3d-scene/debug-motion-plan.md

@@ -7,12 +7,11 @@ type: "docs"
 description: "Publish a motion plan's trajectory and goals as custom visuals so the 3D scene renders the path, then compare it against obstacles and reach to debug failures."
 ---
 
-The **3D SCENE** tab does not show motion plans on its own. It is a static
-inspector of the configured frame system and live component poses: it has no
-timeline, no scrubber, and no plan playback. To see a plan, the trajectory the
-arm will follow, the goals it aims for, and how that path relates to your
-obstacles, you publish the plan as **custom visuals** through a world state store
-service. The scene then renders the path you can otherwise only read as numbers.
+The **3D SCENE** tab is a static inspector: it shows the configured frame system
+and live component poses. To see a motion plan, the trajectory the arm will follow,
+the goals it aims for, and how that path relates to your obstacles, you publish the
+plan as **custom visuals** through a world state store service. The scene then renders
+the path you can otherwise only read as numbers.
 
 This page shows how to turn a plan into transforms the scene can draw, and how to
 use the rendered path to debug a plan that failed or moved unexpectedly.
@@ -81,7 +80,7 @@ from the trajectory leading to it.
 
 Serve the transforms through a world state store service so the **3D SCENE** tab
 renders them. The plan markers stream in alongside the frames and obstacle
-geometry the scene already shows. For the service interface, the poll-and-update
+geometry the scene already shows. For the service methods, the poll-and-update
 loop, and how a module pulls data from its dependencies, see
 [Publish visuals from a module](/visualization/publish-visuals-from-a-module/).
 
@@ -94,11 +93,10 @@ the rest of the scene:
   geometry, that is where the planner reports a collision. Check whether the
   obstacle is real or an oversized geometry.
 - **Does the goal fall outside the arm's reach?** If a goal marker sits far from
-  any reachable arm configuration, the planner cannot get there. Move the goal or
+  any reachable arm configuration, the goal is out of reach. Move the goal or
   check the frame system.
 - **Why the detour?** An unexpected route usually means an obstacle is forcing
-  the planner around it. Look for geometry between the start and goal you did not
-  intend to add.
+  the planner around it. Look for stray geometry between the start and goal.
 
 For checking the obstacle geometry itself, separate from the plan, see
 [Verify obstacles](/motion-planning/3d-scene/set-up-obstacle-avoidance/).
@@ -112,7 +110,7 @@ The 3D scene serves three distinct purposes, and it helps to keep them straight:
 - **Inspect static frames and geometry**: use the stock scene to check frame
   positions and obstacle coverage with no plan involved.
 - **Check feasibility**: use `armplanning.PlanMotion` to confirm a goal is
-  reachable and a path exists before you visualize or execute anything.
+  reachable and a path exists before you visualize or run anything.
 
 Visualization shows you _what the path looks like_; static inspection shows you
 _what the world looks like_; feasibility checking tells you _whether a plan

docs/visualization/_index.md

@@ -5,90 +5,6 @@ weight: 165
 layout: "docs"
 type: "docs"
 no_list: true
+manualLink: "/visualization/overview/"
 description: "See your machine in 3D: frames, geometries, point clouds, and custom visuals your modules publish."
 ---
-
-Spatial configuration is invisible in JSON. A frame translation of
-`{x: 50, y: 0, z: 110}` tells you nothing about whether the gripper actually
-sits where the arm needs it, and a list of obstacle geometries tells you nothing
-about whether they cover the real workspace. Visualization renders these in 3D
-so you can see the spatial model your machine is actually working with, catch
-misconfigurations before they cause a failure, and watch live data in context.
-
-This section covers the **3D SCENE** tab in the Viam app, the transforms and
-metadata that make up a custom visual, how a module publishes visuals, and the
-standalone Viam Visualization app for previewing spatial data outside the app.
-
-## What the 3D scene renders
-
-The **3D SCENE** tab on your machine's page renders an interactive 3D view of
-your machine. It draws four kinds of content, each from a different source:
-
-- **Component frames**, from the [frame system](#the-frame-system). Each
-  configured component appears as a set of coordinate axes at its computed
-  position.
-- **Geometries**, from the components' `frame.geometry` configuration and from
-  obstacles. These render as translucent shapes the motion planner uses for
-  collision checking.
-- **Point clouds**, from depth cameras, rendered as colored point sets.
-- **Custom visuals**, from a [world state store service](/visualization/publish-visuals-from-a-module/).
-  A module publishes these at runtime, and the scene streams them in as they
-  change.
-
-The scene reads your saved configuration, and when the machine is online it
-connects for live data, so frames move to their current poses and point clouds
-update as the cameras report them.
-
-## The frame system
-
-Everything in the scene is positioned by the **frame system**: the single
-coordinate tree that records where every component sits relative to every other.
-
-Each component has a frame with a parent, a translation, and an orientation.
-A component's frame is defined relative to its parent's frame, not to the world
-directly, so the frames form a tree rooted at the fixed **world frame**. A
-gripper's frame is a child of the arm's, the arm's is a child of the world, and
-so on. Because the tree is connected, the frame system can compute the transform
-between any two frames: it walks the path between them, composing each frame's
-local transform along the way. When the arm's joints move, every frame below it
-in the tree moves with it automatically.
-
-This is what makes the scene meaningful. A point cloud from a wrist camera and an
-obstacle defined in world coordinates can be drawn in the same view because the
-frame system relates both back to the world frame. The same machinery lets the
-motion planner reason about where the gripper is while the arm moves, and lets a
-custom visual attach itself to a moving component.
-
-For configuring frames in detail (parent, translation, orientation, geometry),
-see the [frame system documentation](/motion-planning/frame-system/).
-
-## Built-in content versus custom visuals
-
-Two kinds of content reach the scene by two different routes, and the difference
-determines where you change them:
-
-- **Built-in content** (component frames and configured geometry) comes from
-  your machine **configuration**. You change it by editing the frame system and
-  obstacle config. The scene reads it directly.
-- **Custom visuals** come from a **module** that implements a world state store
-  service and publishes transforms at runtime. You change them in **code**, not
-  config, and the scene streams them in as the module adds, updates, and removes
-  them.
-
-If a frame or geometry looks wrong, fix the configuration. If a custom visual
-looks wrong, the module that publishes it is where to look.
-
-## Topics
-
-{{< cards >}}
-{{% card link="/visualization/visuals-and-collisions/" noimage="true" %}}
-{{% card link="/visualization/publish-visuals-from-a-module/" noimage="true" %}}
-{{% card link="/visualization/drawing-library/" noimage="true" %}}
-{{< /cards >}}
-
-## Use the 3D scene with motion planning
-
-{{< cards >}}
-{{% card link="/motion-planning/3d-scene/set-up-obstacle-avoidance/" noimage="true" %}}
-{{% card link="/motion-planning/3d-scene/debug-motion-plan/" noimage="true" %}}
-{{< /cards >}}

docs/visualization/drawing-library.md

@@ -77,17 +77,34 @@ then push visuals to it from Go with the client API. Reusing an entity ID update
 that visual in place; a new ID adds another:
 
 ```go
-import "github.com/viam-labs/motion-tools/client/api"
-
-// Update in place by reusing the ID; add a new entity with a different ID.
-err := api.DrawGeometry(box, api.WithID("obstacle-1"), api.WithColor(red))
+import (
+    "github.com/viam-labs/motion-tools/client/api"
+    "github.com/viam-labs/motion-tools/draw"
+)
+
+// Reuse an ID to update that visual in place; change or omit it to add another.
+_, err := api.DrawGeometry(api.DrawGeometryOptions{
+    ID:       "obstacle-1",
+    Geometry: box,
+    Color:    draw.NewColor(draw.WithName("red")),
+})
 ```
 
 This lets you preview spatial data, a point cloud, a set of detections, a planned
 path, straight from a script or test, without deploying a module or connecting
 through the Viam app. For setup, the local server, and the full client API, see
 the [Viam Visualization documentation](https://viamrobotics.github.io/visualization/).
 
+## How updates reach the browser
+
+The Viam Visualization app runs a **draw service** that the client API calls. The service
+exposes `AddEntity`, `UpdateEntity`, and `RemoveEntity` for the changes you push, and a
+`StreamEntity` stream the browser subscribes to. When you draw, update, or remove an
+entity, the service fans that single change out over `StreamEntity` to the browser, which
+applies it incrementally instead of re-rendering the whole scene. This is the same add,
+update, and remove model the world state store service uses to feed the in-app 3D scene,
+so a busy scene stays in sync as your data changes.
+
 ## What's next
 
 - [Publish visuals from a module](/visualization/publish-visuals-from-a-module/):

docs/visualization/overview.md

@@ -0,0 +1,57 @@
+---
+linkTitle: "Overview"
+title: "Visualization"
+weight: 1
+layout: "docs"
+type: "docs"
+description: "Ways to visualize a Viam machine: the 3D scene, the standalone Viam Visualization app, component data in apps, and time-series dashboards."
+---
+
+There are several approaches to visualizing information in Viam. For things like frames,
+robot state, motion, collisions, and perception data, you can use the 3D scene view or an
+offline visualizer called Viam Visualization. This data can be retrieved from components
+and used in Viam apps or custom user applications. For time series data, services and
+modules can push data to the cloud and visualize it with Viam's Teleop workspaces and
+dashboards to get live information across a machine or fleet.
+
+## The 3D scene
+
+The **3D SCENE** tab on your machine's page renders an interactive 3D view of your
+machine: component frames from the frame system, configured geometries, depth-camera
+point clouds, and custom visuals a module publishes at runtime. Use it to check spatial
+configuration and watch live data in context.
+
+{{< cards >}}
+{{% card link="/visualization/visuals-and-collisions/" noimage="true" %}}
+{{% card link="/visualization/publish-visuals-from-a-module/" noimage="true" %}}
+{{% card link="/motion-planning/3d-scene/debug-motion-plan/" noimage="true" %}}
+{{< /cards >}}
+
+## Viam Visualization
+
+Viam Visualization is a standalone 3D app you run yourself to preview and debug spatial
+data from a Go client, without deploying a module or opening the Viam app. It shares the
+same `draw` library as the in-app 3D scene, so the visuals you build work either way.
+
+{{< cards >}}
+{{% card link="/visualization/drawing-library/" noimage="true" %}}
+{{< /cards >}}
+
+## Component data in your applications
+
+Components report spatial data, geometries and poses, through their APIs. Read it with an
+SDK and render or process it yourself in a Viam app or a custom application.
+
+{{< cards >}}
+{{% card link="/build-apps/" noimage="true" %}}
+{{< /cards >}}
+
+## Time series data
+
+Services and modules push readings to the cloud, where you watch them live with Viam's
+Teleop workspaces and dashboards across a single machine or a whole fleet.
+
+{{< cards >}}
+{{% card link="/monitor/teleop-workspaces/" noimage="true" %}}
+{{% card link="/monitor/dashboards/overview/" noimage="true" %}}
+{{< /cards >}}

docs/visualization/publish-visuals-from-a-module.md

@@ -13,22 +13,21 @@ shapes, you implement a **world state store service**. A module that implements
 this service is a producer: it reads data from other resources, turns that data
 into transforms, and streams them to the scene as they change.
 
-This page covers when to implement the service, the interface to implement, how
+This page covers when to implement the service, the methods to implement, how
 to build transforms with the `draw` library, and the poll-and-update loop that
 keeps the scene in sync. The pattern throughout is **pull**: the module depends
 on the resources it visualizes and reads their data, rather than having those
 resources push into it.
 
 ## When to implement a world state store service
 
-Implement one when you want custom visuals in the 3D scene that the default
-content cannot show. The scene already draws component frames and configured
-geometry, so you do not need a module to see those. You do need one to visualize
-anything computed or sensed at runtime: a vision service's detections, a sensor's
-obstacle readings, a motion plan's trajectory, or any annotation specific to your
-application.
+Implement one when you want custom visuals in the 3D scene beyond the default
+content. The scene already draws component frames and configured geometry on its
+own. A module adds anything computed or sensed at runtime: a vision service's
+detections, a sensor's obstacle readings, a motion plan's trajectory, or any
+annotation specific to your application.
 
-## Implement the service interface
+## Implement the service methods
 
 The world state store service exposes three read methods, which the 3D scene
 calls to discover and follow your visuals:
@@ -83,7 +82,7 @@ func buildTransform(o obstacle) (*commonpb.Transform, error) {
 ```
 
 The library produces standard `commonpb.Transform` values, the same type the
-service interface returns, so the transforms you build this way flow straight
+service methods return, so the transforms you build this way flow straight
 through `ListUUIDs`, `GetTransform`, and `StreamTransformChanges` to the scene.
 
 ## Drive a poll-and-update loop
@@ -135,10 +134,10 @@ reads everything else. Data flows one way:
 This is why the loop above calls `s.sensor.Readings(...)`: the sensor is a
 dependency, and the module pulls from it.
 
-## Visualize a resource that is not a world state store
+## Visualize any other resource
 
-A module whose primary job is something else, an arm, a sensor, a planner, does
-not push visuals into the scene. Instead, you write a world state store module
+A module whose primary job is something else (an arm, a sensor, a planner) stays
+focused on that job. To visualize it, you write a separate world state store module
 that takes that resource as a dependency and pulls from its existing API:
 
 - a sensor's `Readings`
@@ -163,7 +162,7 @@ func newVisualizer(deps resource.Dependencies, conf resource.Config) (worldstate
 ## What's next
 
 - [Visuals and collisions](/visualization/visuals-and-collisions/):
-  what a transform contains and why a visual is not an obstacle.
+  what a transform contains, and which geometry the planner collision-checks.
 - [The drawing library and Viam visualization](/visualization/drawing-library/):
   the `draw` primitives and the standalone visualizer app.
 - [Frame system](/motion-planning/frame-system/): position the transforms you

docs/visualization/visuals-and-collisions.md

@@ -4,15 +4,15 @@ title: "Visuals and collisions"
 weight: 10
 layout: "docs"
 type: "docs"
-description: "How a Transform defines a custom visual, and why a visual in the scene is not the same as geometry the motion planner avoids."
+description: "How a Transform defines a custom visual, and which geometry the motion planner actually collision-checks."
 ---
 
 A custom visual in the 3D scene is a `Transform`: a piece of geometry placed
 somewhere in the frame system, with styling that controls how it draws. The
 world state store service streams these transforms to the scene. This page
-covers what a transform contains, how the scene tracks it over time, and the
-distinction that trips people up most: a visual you can see is not automatically
-an obstacle the motion planner avoids.
+covers what a transform contains, how the scene tracks it over time, and the point
+that trips people up most: the scene draws your visual, while the planner avoids a
+separate collision geometry.
 
 ## Anatomy of a transform
 
@@ -63,27 +63,25 @@ geometry:
 - `collision_allowed`: a hint about whether the geometry represents an allowed
   collision
 
-These are **visualization attributes**, not planning inputs. They change how a
-visual looks in the scene. They do not change what the motion planner does,
-including `collision_allowed`: setting it affects how the visual is presented,
-not whether the planner treats anything as solid.
+These are **visualization attributes**: the scene reads them when it draws the
+geometry. They control how the visual looks, including `collision_allowed`, which is
+a rendering hint about the visual. The planner reads its solid geometry from the frame
+system and `WorldState` instead, so these attributes shape the picture while the
+planner's obstacles come from elsewhere.
 
-## A visual is not an obstacle
+## The scene draws, the planner collision-checks
 
-This is the distinction to internalize: the geometry on a world state store
-transform renders in the 3D scene, but the motion planner does not read the
-world state store. Publishing a box to the scene draws a box. It does not add an
-obstacle the arm will avoid.
-
-The geometry the planner actually collision-checks comes from two places:
+The geometry on a world state store transform renders in the 3D scene: publishing a
+box draws a box. The motion planner collision-checks a separate geometry, which it
+reads from two places:
 
 - The **frame system**: each component's `frame.geometry`.
 - The **`WorldState`** you pass to a `Move` call: obstacles and transforms
   supplied for that single planning request.
 
-A transform in the world state store and an obstacle in a `WorldState` are
-therefore different things on different paths, even when they describe the same
-shape.
+A world state store transform and a `WorldState` obstacle travel two paths, each with
+its own job: one is drawn in the scene, the other is planned around. The same shape can
+take both paths.
 
 ## Making a geometry both visible and collision-checked
 
@@ -95,8 +93,8 @@ you do both, separately:
 - **For planning**: add it to the frame system, or include it in the
   `WorldState` you pass to `Move`.
 
-There is no single field today that does both. Treat the visual and the
-collision geometry as two outputs you produce from the same source data.
+Today these are two separate outputs you produce from the same source data: one
+transform for the scene, one geometry for the planner.
 
 ## What's next