Embedding <Visualizer />

Common use cases: embedding a snapshot viewer next to a robot’s data, rendering test fixtures in a custom dashboard, or shipping the visualizer in a larger debugging surface.

Getting started

Prerequisites

A Svelte 5 / SvelteKit (or Astro+Svelte, Vite+Svelte, etc.) project. The package is svelte-typed and built for runes; you cannot consume it from Svelte 4.

Install

pnpm add @viamrobotics/visualization

The package declares a list of peerDependencies (Svelte, Threlte, Three.js, the Viam SDK, prime-core, several Zag.js components, etc.). pnpm will print warnings for any that aren’t already in your project — install whatever it asks for.

Peers that only a plugin needs are marked optional, so you install them only if you mount that plugin: @dimforge/rapier3d-compat and @threlte/rapier for MoveFrame, @zag-js/tree-view and svelte-virtuallists for <WorldTree />, @zag-js/tabs for <Settings />, @threlte/xr for <XR />, earcut for <SelectionTool />, and the Connect RPC client for <DrawService />.

Auto-install peers

If you don’t want to chase peer warnings one at a time, set auto-install-peers=true in your .npmrc, or pass --strict-peer-dependencies=false on install.

Configure your bundler

The visualizer’s scene imports an HDR environment map, which a stock Vite config won’t handle. Add it to assetsInclude, or the build fails parsing it as JavaScript.

// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
	assetsInclude: ['**/*.hdr'],
	resolve: {
		// three is a peer of both your app and the visualizer; resolve it from one place
		// so a second copy can't slip in. Two three instances break `instanceof`.
		dedupe: ['three'],
	},
})

Disable SSR for the page

The visualizer renders with WebGPU (falling back to WebGL2), which needs the browser. Disable SSR on any page that mounts <Visualizer />. In SvelteKit:

// src/routes/visualizer/+page.ts
export const ssr = false

Astro

In Astro, add client:only="svelte" to the component tag instead.

Mounting <Visualizer />

<Visualizer /> is the entire visualizer rendered as a single Svelte component. It expects an explicitly-sized parent because it stretches to fill its container:

<script lang="ts">
	import { Visualizer } from '@viamrobotics/visualization'
</script>

<div class="h-screen w-screen">
	<Visualizer />
</div>

That’s enough to get an empty scene: the camera and its controls, the grid, the entity renderer, and the portal targets plugins render into. From there, you can:

• Pass partID to bind it to a specific Viam machine part.
• Pass cameraPose to set an initial camera position and look-at target.
• Provide a children snippet to render your own Threlte primitives or the <Snapshot /> component inside the scene.

What’s in the box, and what isn’t

<Visualizer /> is the scene, not the app. It renders:

• the <Canvas>, in renderMode="on-demand"
• the camera, camera controls, and the reset / orthographic buttons
• the grid, lighting, and environment
• the entity renderer — everything spawned into the ECS world, including <PCD />
• selection and hover affordances
• the portal targets that plugins render their UI into

Everything else is a plugin you opt into — including the workspace modes: with no mode plugin mounted the mode is none and the visualizer is a bare renderer, with no toggle, no details cards, and no live-query pausing. The visualizer’s own chrome ships as six plugins:

Plugin	Adds
<Monitor />	Monitor mode: the mode button and details cards
<WorldTree />	The scene hierarchy panel
<Settings />	The settings cog and its tabbed popover
<BuildFrames />	Build mode: gizmos, snapping, frame editing
<FileDrop />	Drag-and-drop loading of snapshots, PCD and PLY
<FramePov />	Per-frame point-of-view panels

To reproduce the standalone app, mount all six plus the feature plugins you want, keeping Monitor before BuildFrames before MoveFrame — mode plugins’ mount order sets both the toggle’s button order and the fallback priority. To embed a focused viewer, mount none of them — or just the one or two that earn their space.

Chrome that reaches past the visualizer

FileDrop listens for drags on the window, so it intercepts drops meant for the host app — leave it out of embedded viewers. Keyboard shortcuts are also window-level, but only the bindings your mounted features contribute exist at all (a bare visualizer binds just c and h); pass inputBindingsEnabled={false} to silence keyboard input entirely.

A focused point-cloud viewer

The smallest useful embed: a scene, a point cloud you already have the bytes for, and a ruler. <PCD /> parses in a worker and spawns an entity the visualizer’s renderer picks up, so nothing else is needed — no partID, and no network calls of its own.

<script lang="ts">
	import { PCD, Visualizer } from '@viamrobotics/visualization'
	import { MeasureTool } from '@viamrobotics/visualization/plugins'

	interface Props {
		data: Uint8Array
	}

	let { data }: Props = $props()
</script>

<div class="h-120 w-full">
	<Visualizer>
		<PCD {data} />
		<MeasureTool />
	</Visualizer>
</div>

Rebinding data reparses and respawns the entity, so this works for a polling feed as well as a one-shot capture.

Point size lives in settings

Point size comes from useSettings().current.pointSize (in metres), which the Settings plugin normally edits. To expose one control without the whole popover, write that field from your own plugin — and call invalidate() from useThrelte() afterward, because the canvas only repaints on demand and the settings popover is what usually triggers it. See Authoring plugins.

Passing props and children

<script lang="ts">
	import { Visualizer } from '@viamrobotics/visualization'
</script>

<div class="h-screen w-screen">
	<Visualizer
		partID="my-part-id"
		cameraPose={{ position: [2, 2, 2], lookAt: [0, 0, 0] }}
	>
		{#snippet children()}
			<!-- Anything Threlte-compatible. Runs inside <Canvas>. -->
		{/snippet}
	</Visualizer>
</div>

Rendering snapshots

A snapshot is a serialized scene — every transform, drawing, and camera setting captured into one protobuf payload. Snapshots render purely client-side; no draw server, no live machine, no network calls.

Use the <Snapshot /> component as a child of <Visualizer />:

From a static file

Put the snapshot in your app’s public/ (or static/) directory and fetch it at runtime. This is the pattern the playground uses.

<script lang="ts">
  import { onMount } from 'svelte'
  import { Visualizer } from '@viamrobotics/visualization'
  import { Snapshot, SnapshotProto } from '@viamrobotics/visualization/lib'

  let snapshot = $state<SnapshotProto | undefined>()

  onMount(async () => {
    const response = await fetch('/scene.snapshot.pb')
    const buffer = await response.arrayBuffer()
    snapshot = SnapshotProto.fromBinary(new Uint8Array(buffer))
  })
</script>

<div class="h-screen w-screen">
  <Visualizer>
    {#if snapshot}
      <Snapshot {snapshot} />
    {/if}
  </Visualizer>
</div>

From a URL

Fetch and decode at runtime:

<script lang="ts">
  import { onMount } from 'svelte'
  import { Visualizer } from '@viamrobotics/visualization'
  import { Snapshot, SnapshotProto } from '@viamrobotics/visualization/lib'

  let snapshot = $state<SnapshotProto | undefined>()

  onMount(async () => {
    const response = await fetch('/api/snapshots/latest.pb')
    const buffer = await response.arrayBuffer()
    snapshot = SnapshotProto.fromBinary(new Uint8Array(buffer))
  })
</script>

<div class="h-screen w-screen">
  <Visualizer>
    {#if snapshot}
      <Snapshot {snapshot} />
    {/if}
  </Visualizer>
</div>

From JSON

JSON snapshots are bigger but easier to debug:

<script lang="ts">
  import { Visualizer } from '@viamrobotics/visualization'
  import { Snapshot, SnapshotProto } from '@viamrobotics/visualization/lib'
  import sceneJson from './scene.snapshot.json?raw'

  const snapshot = SnapshotProto.fromJsonString(sceneJson)
</script>

<div class="h-screen w-screen">
  <Visualizer>
    <Snapshot {snapshot} />
  </Visualizer>
</div>

You can re-bind a different snapshot at any time — <Snapshot /> watches the prop and respawns the scene entities when the value changes.

The playground renders this snapshot by default. To experiment with it, download visualization_snapshot.json, edit a few values, and drag the modified file onto the playground — the scene re-renders with your changes. The drop zone accepts .json, .pb, and .pb.gz snapshot files, but they must be named with a visualization_snapshot prefix (see src/lib/plugins/FileDrop/file-names.ts) for the loader to recognize them.

Producing snapshots

Snapshots are produced from Go using the draw package. The most common pattern: build up a *draw.Snapshot, then call MarshalBinary() (or MarshalJSON() for human-readable output) and ship the bytes wherever your frontend can fetch them.

A minimal producer:

package main

import (
    "os"

    "github.com/golang/geo/r3"
    "github.com/viamrobotics/visualization/draw"
    "go.viam.com/rdk/spatialmath"
)

func main() {
    snapshot := draw.NewSnapshot(
        draw.WithGrid(true),
        draw.WithSceneCamera(draw.NewSceneCamera(
            r3.Vector{X: 2000, Y: 2000, Z: 2000},
            r3.Vector{X: 0, Y: 0, Z: 0},
        )),
    )

    box, _ := spatialmath.NewBox(
        spatialmath.NewZeroPose(),
        r3.Vector{X: 100, Y: 100, Z: 100},
        "box",
    )
    _, _ = snapshot.DrawGeometry(draw.DrawGeometryOptions{
        Geometry: box,
        Pose:     spatialmath.NewZeroPose(),
        Parent:   "world",
        Color:    draw.ColorFromName("red"),
    })

    bytes, _ := snapshot.MarshalBinary()
    _ = os.WriteFile("scene.snapshot.pb", bytes, 0644)
}

See the draw API reference for the full set of Snapshot.Draw* methods.

Using only the standalone components

A few components are exported via the /lib subpath and work without a <Visualizer /> parent — useful if you just need a piece of the visualizer (e.g. an axes helper) inside your own Threlte canvas:

<script lang="ts">
	import { Canvas } from '@threlte/core/webgpu'
	import { AxesHelper } from '@viamrobotics/visualization/lib'
</script>

<Canvas>
	<AxesHelper />
</Canvas>

The standalone components use node materials, so they render only inside a WebGPURenderer. Use the Canvas from @threlte/core/webgpu, not the one from @threlte/core.

<Snapshot /> is also exported from /lib, but unlike <AxesHelper /> it requires the context that <Visualizer /> provides — use it as a child of <Visualizer />, not standalone.