@viamrobotics/motion-tools 1.22.0 → 1.23.0

package/README.md

@@ -1,119 +1,37 @@
-# motion-tools
+# Viam Visualization
 
-`motion-tools` aims to provide a visualization interface for any spatial information using Viam's APIs. This typically means motion-related monitoring, testing, and debugging.
+3D visualization interface for spatial data using Viam's APIs — frame systems, geometries, point clouds, drawings — for motion-related monitoring, testing, and debugging.
 
-## Getting started
+## Documentation
 
-To run the app, you will need to set your project up by installing the app dependencies and ensuring you can connect
-to your machines if required.
+📚 **[viamrobotics.github.io/visualization](https://viamrobotics.github.io/visualization/)** is the canonical guide. It covers:
 
-### Project setup
+- [Running locally](https://viamrobotics.github.io/visualization/guides/local-usage/) — set up the app and drive it from Go via `client/api`.
+- [Embedding `<MotionTools />`](https://viamrobotics.github.io/visualization/guides/embedding/) — drop the visualizer into your own Svelte app.
+- [Implementing WorldStateStoreService](https://viamrobotics.github.io/visualization/guides/worldstatestore/) — produce `Transform`s for a Viam WSS module with `draw`.
+- API reference for [`client/api`](https://viamrobotics.github.io/visualization/api/client-api/) and [`draw`](https://viamrobotics.github.io/visualization/api/draw/).
+- [v1 → v2 migration guide](https://viamrobotics.github.io/visualization/migration/v1-to-v2/).
+- A live [playground](https://viamrobotics.github.io/visualization/playground/) rendering a baked snapshot.
 
-The easiest way to get started is using our automated setup script:
+## Quick start
 
 ```bash
-make setup
+make setup     # one-time: install Node 22, pnpm, bun, Go, buf, project deps
+make up        # http://localhost:5173
 ```
 
-This single command will:
+For manual setup, machine configs, multiple instances, and troubleshooting see the [local-usage guide](https://viamrobotics.github.io/visualization/guides/local-usage/).
 
-1. Install **fnm** (Fast Node Manager) and **Node.js 22**
-2. Install **pnpm** package manager
-3. Install **bun** runtime
-4. Install **Go** and **buf** (for protobuf generation)
-5. Install all project dependencies
-6. Generate protobuf code
+## Contributing
 
-After setup completes, add the shell configuration it prints to your shell config file (`~/.zshrc` or `~/.bashrc`), then restart your terminal.
-
-#### Manual setup
-
-If the above does not work for you, or if you prefer to install dependencies manually:
-
-1. [Install fnm](https://github.com/Schniz/fnm#installation): `curl -fsSL https://fnm.vercel.app/install | bash`
-2. Install Node.js: `fnm install 22 && fnm use 22`
-3. [Install pnpm](https://pnpm.io/installation): `curl -fsSL https://get.pnpm.io/install.sh | sh -`
-4. [Install bun](https://bun.sh/docs/installation): `curl -fsSL https://bun.sh/install | bash`
-5. [Install Go](https://go.dev/doc/install)
-6. [Install buf](https://buf.build/docs/installation): download from GitHub releases
-7. Install Go tools: `go install google.golang.org/protobuf/cmd/protoc-gen-go@latest`
-8. Install dependencies: `pnpm install`
-9. Generate protobufs: `make proto`
-
-### Env files for machine configs
-
-To add a list of connection configs in an `.env.local` file, use the following format:
-
-```
-VITE_CONFIGS='
-{
-  "fleet-rover-01": {
-    "host": "fleet-rover-01-main.ve4ba7w5qr.viam.cloud",
-    "partId": "myPartID",
-    "apiKeyId": "myApiKeyId",
-    "apiKeyValue": "MyApiKeyValue",
-    "signalingAddress": "https://app.viam.com:443"
-  }
-}
-'
-```
-
-### Running the app locally
-
-After setup completes, you can start a local app server with:
+Run the dev server with HMR:
 
 ```bash
-make up
-```
-
-This starts the app as a static site. The build part of the process will only run if you have not built the app yet as a part of `make up`, or your build is out of date.
-
-#### Running multiple apps
-
-If you want to be able to run multiple versions of the app, you can configure how the servers run. The `make up` command can accept two options:
-
-1. `STATIC_PORT` is the port for the static file server, and defaults to `5173`
-2. `WS_PORT` is the port for the websocket server used to communicate with the draw client API
-
-> [!NOTE]
-> The `WS_PORT` is not fully configurable at the moment, so passing it will only affect where the frontend listens for the websocket server, but calls with the draw client API are currently hardcoded to point to `"http://localhost:3000/"`. If this is a feature you require, please submit a request to the viz team!
-
-To run two apps using the same web socket server, run:
-
-```
-# in one terminal
-make up
-
-# in another terminal
-make up STATIC_PORT=5174
-```
-
-The apps should be available on `http://localhost:5173/` and `http://localhost:5174/`, and calls to the draw client API should render in both.
-
-### Local development
-
-If you are contributing to `motion-tools`, you should just run the development web server with:
-
-```
 pnpm dev
 ```
 
-## Running the visualizer
-
-To visit the visualizer, go to `http://localhost:5173/`
-
-Open the machine config page (bottom right) and enter in connection details to visualize a specific machine. You can also add machine configs from an env file (see below).
-
-## Executing drawing commands
-
-The visualizer includes a golang package that allows executing commands to the visualizer.
-
-The list of available commands [can be found here](https://pkg.go.dev/github.com/viam-labs/motion-tools@v0.9.0/client/client).
+See [CLAUDE.md](CLAUDE.md) for contributor conventions.
 
 ## Programmatic camera control
 
-It is possible to programmatically move the viewer camera and even modify the camera settings during runtime.
-
-To do this, open the Javascript console while using the visualizer and call methods or set properties on the `cameraControls` object.
-
-The following APIs are available: https://github.com/yomotsu/camera-controls?tab=readme-ov-file#properties
+The visualizer exposes a `cameraControls` object on `window`. Open the browser console and call methods on it to move the camera or tweak its settings at runtime. Full API: <https://github.com/yomotsu/camera-controls#properties>.

package/dist/components/App.svelte

@@ -47,7 +47,7 @@
 
 	interface Props {
 		partID?: string
-		enableKeybindings?: boolean
+		inputBindingsEnabled?: boolean
 		localConfigProps?: LocalConfigProps
 		drawConnectionConfig?: DrawConnectionConfig
 
@@ -74,7 +74,7 @@
 
 	let {
 		partID = '',
-		enableKeybindings = true,
+		inputBindingsEnabled = true,
 		localConfigProps,
 		cameraPose,
 		drawConnectionConfig,
@@ -91,7 +91,7 @@
 	const { isPresenting } = useXR()
 
 	$effect(() => {
-		settings.current.enableKeybindings = enableKeybindings
+		environment.current.inputBindingsEnabled = inputBindingsEnabled
 	})
 
 	createPartIDContext(() => partID)

package/dist/components/App.svelte.d.ts

@@ -11,7 +11,7 @@ interface LocalConfigProps {
 }
 interface Props {
     partID?: string;
-    enableKeybindings?: boolean;
+    inputBindingsEnabled?: boolean;
     localConfigProps?: LocalConfigProps;
     drawConnectionConfig?: DrawConnectionConfig;
     /**

package/dist/components/CameraControls.svelte

@@ -4,15 +4,15 @@
 
 	import Button from './overlay/dashboard/Button.svelte'
 	import { useCameraControls, useTransformControls } from '../hooks/useControls.svelte'
-	import { useSettings } from '../hooks/useSettings.svelte'
+	import { useEnvironment } from '../hooks/useEnvironment.svelte'
 
-	import KeyboardControls from './KeyboardControls.svelte'
+	import InputBindings from './InputBindings.svelte'
 
 	const cameraControls = useCameraControls()
-	const settings = useSettings()
+	const environment = useEnvironment()
 	const transformControls = useTransformControls()
 
-	const enableKeybindings = $derived(settings.current.enableKeybindings)
+	const inputBindingsEnabled = $derived(environment.current.inputBindingsEnabled)
 </script>
 
 <Portal id="dashboard">
@@ -37,8 +37,8 @@
 	}}
 >
 	{#snippet children({ ref }: { ref: CameraControlsRef })}
-		{#if enableKeybindings}
-			<KeyboardControls cameraControls={ref} />
+		{#if inputBindingsEnabled}
+			<InputBindings cameraControls={ref} />
 		{/if}
 		<Gizmo placement="bottom-right" />
 	{/snippet}

package/dist/components/{KeyboardControls.svelte → InputBindings.svelte}

@@ -2,6 +2,7 @@
 	import type { CameraControlsRef } from '@threlte/extras'
 
 	import { isInstanceOf, useTask } from '@threlte/core'
+	import { useGamepad, useInputMap, useKeyboard } from '@threlte/extras'
 	import { PressedKeys } from 'runed'
 	import { MathUtils, Vector3 } from 'three'
 
@@ -22,19 +23,33 @@
 
 	const settings = useSettings()
 
-	const keys = new PressedKeys()
-	const meta = $derived(keys.has('meta'))
-	const w = $derived(keys.has('w'))
-	const s = $derived(keys.has('s'))
-	const a = $derived(keys.has('a'))
-	const d = $derived(keys.has('d'))
-	const r = $derived(keys.has('r'))
-	const f = $derived(keys.has('f'))
-	const up = $derived(keys.has('arrowup'))
-	const left = $derived(keys.has('arrowleft'))
-	const down = $derived(keys.has('arrowdown'))
-	const right = $derived(keys.has('arrowright'))
-	const anyKeysPressed = $derived(w || s || a || d || r || f || up || left || down || right)
+	const keyboard = useKeyboard()
+	const gamepad = useGamepad()
+	const input = useInputMap(
+		({ key, gamepadAxis, gamepadButton }) => ({
+			truckLeft: [key('a'), gamepadAxis('leftStick', 'x', -1)],
+			truckRight: [key('d'), gamepadAxis('leftStick', 'x', 1)],
+			forward: [key('w'), gamepadAxis('leftStick', 'y', -1)],
+			backward: [key('s'), gamepadAxis('leftStick', 'y', 1)],
+			dollyIn: [key('r'), gamepadButton('rightBumper')],
+			dollyOut: [key('f'), gamepadButton('leftBumper')],
+			rotateLeft: [key('arrowleft'), gamepadAxis('rightStick', 'x', -1)],
+			rotateRight: [key('arrowright'), gamepadAxis('rightStick', 'x', 1)],
+			tiltUp: [key('arrowup'), gamepadAxis('rightStick', 'y', 1)],
+			tiltDown: [key('arrowdown'), gamepadAxis('rightStick', 'y', -1)],
+		}),
+		{ keyboard, gamepad }
+	)
+
+	const truckAxis = $derived(input.axis('truckLeft', 'truckRight'))
+	const forwardAxis = $derived(input.axis('backward', 'forward'))
+	const dollyAxis = $derived(input.axis('dollyOut', 'dollyIn'))
+	const yawAxis = $derived(input.axis('rotateLeft', 'rotateRight'))
+	const pitchAxis = $derived(input.axis('tiltUp', 'tiltDown'))
+
+	const anyKeysPressed = $derived(
+		truckAxis !== 0 || forwardAxis !== 0 || dollyAxis !== 0 || yawAxis !== 0 || pitchAxis !== 0
+	)
 
 	const target = new Vector3()
 
@@ -70,7 +85,7 @@
 			const dt = delta * 1000
 
 			// Disallow keyboard navigation if the user is holding down the meta key
-			if (meta) {
+			if (keyboard.key('meta').pressed) {
 				return
 			}
 
@@ -80,64 +95,41 @@
 			const dollySpeed = 0.005 * dt
 			const zoomSpeed = 0.5 * dt
 
-			if (a) {
-				cameraControls.truck(-moveSpeed * dt, 0, true)
-			}
-
-			if (d) {
-				cameraControls.truck(moveSpeed * dt, 0, true)
-			}
-
-			if (w) {
-				cameraControls.forward(moveSpeed * dt, true)
-			}
-
-			if (s) {
-				cameraControls.forward(-moveSpeed * dt, true)
+			if (truckAxis !== 0) {
+				cameraControls.truck(truckAxis * moveSpeed * dt, 0, true)
 			}
 
-			if (r) {
-				if (isInstanceOf(cameraControls.camera, 'PerspectiveCamera')) {
-					cameraControls.dolly(dollySpeed, true)
-				} else {
-					cameraControls.zoom(zoomSpeed, true)
-				}
+			if (forwardAxis !== 0) {
+				cameraControls.forward(forwardAxis * moveSpeed * dt, true)
 			}
 
-			if (f) {
+			if (dollyAxis !== 0) {
 				if (isInstanceOf(cameraControls.camera, 'PerspectiveCamera')) {
-					cameraControls.dolly(-dollySpeed, true)
+					cameraControls.dolly(dollyAxis * dollySpeed, true)
 				} else {
-					cameraControls.zoom(-zoomSpeed, true)
+					cameraControls.zoom(dollyAxis * zoomSpeed, true)
 				}
 			}
 
-			if (left) {
-				cameraControls.rotate(-rotateSpeed, 0, true)
-			}
-
-			if (right) {
-				cameraControls.rotate(rotateSpeed, 0, true)
+			if (yawAxis !== 0) {
+				cameraControls.rotate(yawAxis * rotateSpeed, 0, true)
 			}
 
-			if (up) {
-				cameraControls.rotate(0, -tiltSpeed, true)
-			}
-
-			if (down) {
-				cameraControls.rotate(0, tiltSpeed, true)
+			if (pitchAxis !== 0) {
+				cameraControls.rotate(0, pitchAxis * tiltSpeed, true)
 			}
 		},
 		{
+			after: input.task,
 			running: () => anyKeysPressed,
 			autoInvalidate: false,
 		}
 	)
 
+	const keys = new PressedKeys()
+
 	keys.onKeys('escape', () => {
-		if (keys.has('escape')) {
-			focusedEntity.set()
-		}
+		focusedEntity.set()
 	})
 
 	keys.onKeys('c', () => {
@@ -157,30 +149,11 @@
 		settings.current.transformMode = 'scale'
 	})
 
-	keys.onKeys('x', () => {
-		settings.current.enableXR = !settings.current.enableXR
-	})
-
-	/**
-	 * Handler for any keybindings that need to access the event object
-	 */
-	const onkeydown = (event: KeyboardEvent) => {
-		const key = event.key.toLowerCase()
-
-		if (key === 'h') {
-			if (!entity) return
-
-			event.stopImmediatePropagation()
-
-			if (entity.has(traits.Invisible)) {
-				entity.remove(traits.Invisible)
-			} else {
-				entity.add(traits.Invisible)
-			}
-
-			return
+	keys.onKeys('h', () => {
+		if (entity?.has(traits.Invisible)) {
+			entity.remove(traits.Invisible)
+		} else {
+			entity?.add(traits.Invisible)
 		}
-	}
+	})
 </script>
-
-<svelte:window {onkeydown} />

package/dist/components/InputBindings.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { CameraControlsRef } from '@threlte/extras';
+interface Props {
+    cameraControls: CameraControlsRef;
+}
+declare const InputBindings: import("svelte").Component<Props, {}, "">;
+type InputBindings = ReturnType<typeof InputBindings>;
+export default InputBindings;

package/dist/components/overlay/Details.svelte

@@ -18,7 +18,7 @@
 	import type { Snippet } from 'svelte'
 
 	import { draggable } from '@neodrag/svelte'
-	import { isInstanceOf, useTask } from '@threlte/core'
+	import { isInstanceOf, useTask, useThrelte } from '@threlte/core'
 	import { Button, Icon, Tooltip } from '@viamrobotics/prime-core'
 	import { Check, Copy } from 'lucide-svelte'
 	import {
@@ -62,6 +62,7 @@
 	const { details }: Props = $props()
 
 	const world = useWorld()
+	const { invalidate } = useThrelte()
 	const drawService = useDrawService()
 	const controls = useCameraControls()
 	const resourceByName = useResourceByName()
@@ -86,6 +87,7 @@
 	const removable = useTrait(() => entity, traits.Removable)
 	const points = useTrait(() => entity, traits.Points)
 	const arrows = useTrait(() => entity, traits.Arrows)
+	const opacity = useTrait(() => entity, traits.Opacity)
 
 	const framesAPI = useTrait(() => entity, traits.FramesAPI)
 	const isFrameNode = $derived(!!framesAPI.current)
@@ -197,6 +199,23 @@
 		detailConfigUpdater.updateGeometry(entity, { type: 'capsule', l: event.detail.value })
 	}
 
+	const opacityValue = $derived(opacity.current ?? 1)
+
+	const handleOpacityChange = (event: SliderChangeEvent) => {
+		if (event.detail.origin !== 'internal' || !entity) return
+		const next = event.detail.value
+		// No trait === fully opaque, so drop the trait when the user returns to 1
+		// instead of leaving an Opacity(1) entry on the entity.
+		if (next >= 1) {
+			entity.remove(traits.Opacity)
+		} else if (entity.has(traits.Opacity)) {
+			entity.set(traits.Opacity, next)
+		} else {
+			entity.add(traits.Opacity(next))
+		}
+		invalidate()
+	}
+
 	const handleParentChange = (event: ListChangeEvent) => {
 		if (event.detail.origin !== 'internal' || !entity) return
 		const value = event.detail.value as string
@@ -668,6 +687,20 @@
 				</div>
 			{/if}
 
+			<div>
+				<strong class="font-semibold">opacity</strong>
+				<div aria-label="mutable opacity">
+					<Slider
+						value={opacityValue}
+						min={0}
+						max={1}
+						step={0.01}
+						format={(v) => v.toFixed(2)}
+						on:change={handleOpacityChange}
+					/>
+				</div>
+			</div>
+
 			{#if isInstanceOf(object3d, 'Points')}
 				<div>
 					<strong class="font-semibold">points</strong>

package/dist/hooks/useEnvironment.svelte.d.ts

@@ -2,6 +2,7 @@ export declare const ENVIRONMENT_CONTEXT_KEY: unique symbol;
 interface Environemnt {
     viewerMode: 'edit' | 'monitor' | 'focus';
     isStandalone: boolean;
+    inputBindingsEnabled: boolean;
 }
 interface Context {
     current: Environemnt;

package/dist/hooks/useEnvironment.svelte.js

@@ -3,6 +3,7 @@ export const ENVIRONMENT_CONTEXT_KEY = Symbol('environment');
 const defaults = () => ({
     viewerMode: 'monitor',
     isStandalone: true,
+    inputBindingsEnabled: true,
 });
 export const createEnvironment = () => {
     const environment = $state(defaults());

package/dist/hooks/useFrames.svelte.js

@@ -29,8 +29,9 @@ export const provideFrames = (partID) => {
     $effect.pre(() => {
         const id = partID();
         if (lastPartID !== undefined && lastPartID !== id) {
-            // Stale across parts: keeps the configFrames-priority merge branch
-            // active when switching to a new part that hasn't been edited.
+            // Don't let an edited flag from the previous part bleed into the
+            // new one — the merge condition would otherwise stay forced on for
+            // a freshly-switched part the user hasn't touched.
             didRecentlyEdit = false;
         }
         lastPartID = id;
@@ -59,11 +60,15 @@ export const provideFrames = (partID) => {
                 frames[frame.referenceFrame] = frame;
             }
         }
-        // Let config frames take priority if the user has made edits,
-        // has a pending save, or is disconnected
+        // Let config frames take priority if the user has made edits, has a
+        // pending save, or we don't have a live robot connection. The latter
+        // covers DISCONNECTED, CONNECTING, and the undefined case where the
+        // embedder never provided a dial config (e.g. the Viam app's
+        // dialConfigsForParts filters to live parts only, so offline parts
+        // never transition through DISCONNECTED).
         if (didRecentlyEdit ||
             partConfig.hasPendingSave ||
-            connectionStatus.current === MachineConnectionEvent.DISCONNECTED) {
+            connectionStatus.current !== MachineConnectionEvent.CONNECTED) {
             const mergedFrames = {
                 ...frames,
                 ...configFrames.current,

package/dist/hooks/useSettings.svelte.d.ts

@@ -23,7 +23,6 @@ export interface Settings {
     enableMeasureAxisY: boolean;
     enableMeasureAxisZ: boolean;
     enableLabels: boolean;
-    enableKeybindings: boolean;
     enableQueryDevtools: boolean;
     enableArmPositionsWidget: boolean;
     openCameraWidgets: Record<string, string[]>;

package/dist/hooks/useSettings.svelte.js

@@ -30,7 +30,6 @@ const defaults = () => ({
     enableMeasureAxisY: true,
     enableMeasureAxisZ: true,
     enableLabels: false,
-    enableKeybindings: true,
     enableQueryDevtools: false,
     enableArmPositionsWidget: false,
     openCameraWidgets: {},

package/dist/index.d.ts

@@ -1,4 +1,6 @@
+/** @deprecated MotionTools has been renamed to Visualizer. This export will be removed in v2. */
 export { default as MotionTools } from './components/App.svelte';
+export { default as Visualizer } from './components/App.svelte';
 export { default as SelectionTool } from './components/Selection/Tool.svelte';
 export { default as PCD } from './components/PCD.svelte';
 export * as relations from './ecs/relations';

package/dist/index.js

@@ -1,4 +1,6 @@
+/** @deprecated MotionTools has been renamed to Visualizer. This export will be removed in v2. */
 export { default as MotionTools } from './components/App.svelte';
+export { default as Visualizer } from './components/App.svelte';
 // Plugins
 export { default as SelectionTool } from './components/Selection/Tool.svelte';
 export { default as PCD } from './components/PCD.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viamrobotics/motion-tools",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "Motion visualization with Viam",
   "license": "Apache-2.0",
   "type": "module",
@@ -147,9 +147,8 @@
     "uuid-tool": "^2.0.3"
   },
   "scripts": {
-    "dev": "pnpm dev:bun",
+    "dev": "concurrently \"pnpm dev:bun\" \"go run cmd/draw-server/main.go -port 3030\"",
     "dev:bun": "tsx server/check-bun && bun run server/server.ts",
-    "dev:next": "concurrently \"pnpm dev:bun\" \"go run cmd/draw-server/main.go -port 3030\"",
     "dev:https": "vite dev -- --https",
     "build": "vite build && npm run prepack",
     "build:workers": "node scripts/build-workers.js",
@@ -174,6 +173,9 @@
     "vet:client": "go vet ./client/...",
     "vet": "pnpm vet:draw && pnpm vet:client",
     "model-pipeline:run": "node scripts/model-pipeline.js",
-    "release": "changeset publish"
+    "release": "changeset publish",
+    "docs:dev": "pnpm --dir docs dev",
+    "docs:build": "pnpm --dir docs build",
+    "docs:preview": "pnpm --dir docs preview"
   }
 }

package/dist/components/KeyboardControls.svelte.d.ts

@@ -1,7 +0,0 @@
-import type { CameraControlsRef } from '@threlte/extras';
-interface Props {
-    cameraControls: CameraControlsRef;
-}
-declare const KeyboardControls: import("svelte").Component<Props, {}, "">;
-type KeyboardControls = ReturnType<typeof KeyboardControls>;
-export default KeyboardControls;