@viamrobotics/motion-tools 1.27.1 → 1.28.1

package/dist/components/App.svelte

@@ -10,14 +10,14 @@
 	import { provideToast, ToastContainer } from '@viamrobotics/prime-core'
 	import { ThemeUtils } from 'svelte-tweakpane-ui'
 
-	import type { CameraPose } from '../hooks/useControls.svelte'
-
+	import Controls from './overlay/controls/Controls.svelte'
 	import Dashboard from './overlay/dashboard/Dashboard.svelte'
 	import Details from './overlay/Details.svelte'
 	import TreeContainer from './overlay/left-pane/TreeContainer.svelte'
 	import Settings from './overlay/settings/Settings.svelte'
 	import XR from './xr/XR.svelte'
 	import { provideWorld } from '../ecs'
+	import { type CameraPose, provideCameraControls } from '../hooks/useControls.svelte'
 	import {
 		type DrawConnectionConfig,
 		provideDrawConnectionConfig,
@@ -36,6 +36,7 @@
 	import Logs from './overlay/Logs.svelte'
 	import ArmPositions from './overlay/widgets/ArmPositions.svelte'
 	import Camera from './overlay/widgets/Camera.svelte'
+	import FramePov from './overlay/widgets/FramePov.svelte'
 	import Scene from './Scene.svelte'
 	import SceneProviders from './SceneProviders.svelte'
 
@@ -89,8 +90,10 @@
 	const settings = provideSettings()
 	const environment = provideEnvironment()
 	const currentRobotCameraWidgets = $derived(settings.current.openCameraWidgets[partID] || [])
+	const currentFramePovWidgets = $derived(settings.current.openFramePovWidgets[partID] || [])
 	const { isPresenting } = useXR()
 
+	provideCameraControls(() => cameraPose)
 	createPartIDContext(() => partID)
 	provideDrawConnectionConfig(() => drawConnectionConfig)
 	provideWeblabs()
@@ -129,7 +132,7 @@
 		renderMode="on-demand"
 		dpr={[1, 2]}
 	>
-		<SceneProviders {cameraPose}>
+		<SceneProviders>
 			{#snippet children({ focus })}
 				<Scene>
 					{@render appChildren?.()}
@@ -145,6 +148,7 @@
 				<div {@attach domPortal(root)}>
 					<FileDrop />
 					<Dashboard {dashboard} />
+					<Controls />
 					<Details {details} />
 
 					{#if environment.current.isStandalone}
@@ -163,6 +167,10 @@
 						{#each currentRobotCameraWidgets as cameraName (cameraName)}
 							<Camera name={cameraName} />
 						{/each}
+
+						{#each currentFramePovWidgets as povFrameName (povFrameName)}
+							<FramePov frameName={povFrameName} />
+						{/each}
 					{/if}
 
 					<PortalTarget id="dom" />

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

@@ -1,7 +1,7 @@
 import type { Struct } from '@viamrobotics/sdk';
 import type { Entity } from 'koota';
 import type { Snippet } from 'svelte';
-import type { CameraPose } from '../hooks/useControls.svelte';
+import { type CameraPose } from '../hooks/useControls.svelte';
 import { type DrawConnectionConfig } from '../hooks/useDrawConnectionConfig.svelte';
 interface LocalConfigProps {
     current: Struct;

package/dist/components/Camera.svelte

@@ -12,7 +12,7 @@
 {#if mode === 'perspective'}
 	<T.PerspectiveCamera
 		makeDefault
-		near={0.01}
+		near={0.001}
 		up={[0, 0, 1]}
 		oncreate={(ref) => {
 			ref.lookAt(0, 0, 0)

package/dist/components/CameraControls.svelte

@@ -1,8 +1,7 @@
 <script lang="ts">
-	import { CameraControls, type CameraControlsRef, Gizmo, Portal } from '@threlte/extras'
+	import { CameraControls, type CameraControlsRef, Gizmo } from '@threlte/extras'
 	import { MathUtils } from 'three'
 
-	import Button from './overlay/dashboard/Button.svelte'
 	import { useCameraControls, useTransformControls } from '../hooks/useControls.svelte'
 	import { useEnvironment } from '../hooks/useEnvironment.svelte'
 
@@ -15,19 +14,6 @@
 	const inputBindingsEnabled = $derived(environment.current.inputBindingsEnabled)
 </script>
 
-<Portal id="dashboard">
-	<fieldset>
-		<Button
-			active
-			icon="camera-outline"
-			description="Reset camera"
-			onclick={() => {
-				cameraControls.setInitialPose()
-			}}
-		/>
-	</fieldset>
-</Portal>
-
 <CameraControls
 	enabled={!transformControls.active}
 	oncreate={(ref) => {

package/dist/components/Focus.svelte

@@ -1,10 +1,9 @@
 <script lang="ts">
 	import { T } from '@threlte/core'
-	import { Gizmo, Portal, TrackballControls } from '@threlte/extras'
+	import { Gizmo, TrackballControls } from '@threlte/extras'
 	import { Box3, type Object3D, Vector3 } from 'three'
-	import { TrackballControls as ThreeTrackballControls } from 'three/examples/jsm/controls/TrackballControls.js'
 
-	import Button from './overlay/dashboard/Button.svelte'
+	import { useCameraControls } from '../hooks/useControls.svelte'
 
 	import Camera from './Camera.svelte'
 
@@ -14,14 +13,14 @@
 
 	let { object3d }: Props = $props()
 
+	const cameraControls = useCameraControls()
+
 	const box = new Box3()
 	const vec = new Vector3()
 
 	let center = $state.raw<[number, number, number]>([0, 0, 0])
 	let size = $state.raw<[number, number, number]>([0, 0, 0])
 
-	let controls = $state.raw<ThreeTrackballControls>()
-
 	$effect.pre(() => {
 		box.setFromObject(object3d)
 		size = box.getSize(vec).toArray()
@@ -29,23 +28,10 @@
 	})
 </script>
 
-<Portal id="dashboard">
-	<fieldset>
-		<Button
-			active
-			icon="camera-outline"
-			description="Reset camera"
-			onclick={() => {
-				controls?.reset()
-			}}
-		/>
-	</fieldset>
-</Portal>
-
 <Camera position={[size[0] + 1, size[0] + 1, size[0] + 1]}>
 	<TrackballControls
-		bind:ref={controls}
 		target={center}
+		oncreate={(ref) => cameraControls.set(ref)}
 	>
 		<Gizmo placement="bottom-right" />
 	</TrackballControls>

package/dist/components/MeasureTool/MeasureTool.svelte

@@ -84,6 +84,7 @@
 		<div class="flex">
 			<Button
 				active={enabled}
+				class="rounded-r-none"
 				icon="ruler"
 				description="{enabled ? 'Disable' : 'Enable'} measurement"
 				onclick={() => {
@@ -95,7 +96,7 @@
 					<Button
 						{...triggerProps}
 						active={enabled}
-						class="border-l-0"
+						class="rounded-l-none border-l-0"
 						icon="filter-sliders"
 						description="Measurement settings"
 					/>

package/dist/components/Scene.svelte

@@ -12,9 +12,9 @@
 	import Selected from './Selected.svelte'
 	import SelectedTransformControls from './SelectedTransformControls.svelte'
 	import StaticGeometries from './StaticGeometries.svelte'
+	import { bvh } from '../hooks/plugins/bvh.svelte'
 	import { useFocusedObject3d } from '../hooks/useSelection.svelte'
 	import { useSettings } from '../hooks/useSettings.svelte'
-	import { bvh } from '../plugins/bvh.svelte'
 
 	import hdrImage from '../assets/ferndale_studio_11_1k.hdr'
 	import BatchedArrows from './BatchedArrows.svelte'

package/dist/components/SceneProviders.svelte

@@ -6,11 +6,7 @@
 	import { provideArmClient } from '../hooks/useArmClient.svelte'
 	import { provideArmKinematics } from '../hooks/useArmKinematics.svelte'
 	import { provideConfigFrames } from '../hooks/useConfigFrames.svelte'
-	import {
-		type CameraPose,
-		provideCameraControls,
-		provideTransformControls,
-	} from '../hooks/useControls.svelte'
+	import { provideTransformControls } from '../hooks/useControls.svelte'
 	import { provideDrawAPI } from '../hooks/useDrawAPI.svelte'
 	import { provideDrawService } from '../hooks/useDrawService.svelte'
 	import { provideFrameEditSession } from '../hooks/useFrameEditSession.svelte'
@@ -30,15 +26,13 @@
 	import { provideOrigin } from './xr/useOrigin.svelte'
 
 	interface Props {
-		cameraPose?: CameraPose
 		children: Snippet<[{ focus: boolean }]>
 	}
 
-	let { cameraPose, children }: Props = $props()
+	let { children }: Props = $props()
 
 	const partID = usePartID()
 
-	provideCameraControls(() => cameraPose)
 	provideTransformControls()
 	provideLogs()
 

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

@@ -1,7 +1,5 @@
 import type { Snippet } from 'svelte';
-import { type CameraPose } from '../hooks/useControls.svelte';
 interface Props {
-    cameraPose?: CameraPose;
     children: Snippet<[{
         focus: boolean;
     }]>;

package/dist/components/Selection/Ellipse.svelte

@@ -263,16 +263,18 @@
 
 		const currentControls = controls.current
 
-		const { minPolarAngle, maxPolarAngle } = currentControls
+		if ('minPolarAngle' in currentControls) {
+			const { minPolarAngle, maxPolarAngle } = currentControls
 
-		// Locks the camera to top down while this component is mounted
-		currentControls.polarAngle = 0
-		currentControls.minPolarAngle = 0
-		currentControls.maxPolarAngle = 0
+			// Locks the camera to top down while this component is mounted
+			currentControls.polarAngle = 0
+			currentControls.minPolarAngle = 0
+			currentControls.maxPolarAngle = 0
 
-		return () => {
-			currentControls.minPolarAngle = minPolarAngle
-			currentControls.maxPolarAngle = maxPolarAngle
+			return () => {
+				currentControls.minPolarAngle = minPolarAngle
+				currentControls.maxPolarAngle = maxPolarAngle
+			}
 		}
 	})
 

package/dist/components/Selection/Lasso.svelte

@@ -244,16 +244,18 @@
 
 		const currentControls = controls.current
 
-		const { minPolarAngle, maxPolarAngle } = currentControls
+		if ('minPolarAngle' in currentControls) {
+			const { minPolarAngle, maxPolarAngle } = currentControls
 
-		// Locks the camera to top down while this component is mounted
-		currentControls.polarAngle = 0
-		currentControls.minPolarAngle = 0
-		currentControls.maxPolarAngle = 0
+			// Locks the camera to top down while this component is mounted
+			currentControls.polarAngle = 0
+			currentControls.minPolarAngle = 0
+			currentControls.maxPolarAngle = 0
 
-		return () => {
-			currentControls.minPolarAngle = minPolarAngle
-			currentControls.maxPolarAngle = maxPolarAngle
+			return () => {
+				currentControls.minPolarAngle = minPolarAngle
+				currentControls.maxPolarAngle = maxPolarAngle
+			}
 		}
 	})
 

package/dist/components/overlay/Details.svelte

@@ -45,6 +45,7 @@
 	import { useEnvironment } from '../../hooks/useEnvironment.svelte'
 	import { useLinkedEntities } from '../../hooks/useLinked.svelte'
 	import { usePartConfig } from '../../hooks/usePartConfig.svelte'
+	import { usePartID } from '../../hooks/usePartID.svelte'
 	import { useResourceByName } from '../../hooks/useResourceByName.svelte'
 	import {
 		useFocusedEntity,
@@ -52,6 +53,7 @@
 		useSelectedEntity,
 		useSelectedObject3d,
 	} from '../../hooks/useSelection.svelte'
+	import { useSettings } from '../../hooks/useSettings.svelte'
 	import { createPose, matrixToPose } from '../../transform'
 
 	interface Props {
@@ -67,6 +69,8 @@
 	const resourceByName = useResourceByName()
 	const configFrames = useConfigFrames()
 	const partConfig = usePartConfig()
+	const partID = usePartID()
+	const settings = useSettings()
 	const selectedEntity = useSelectedEntity()
 	const selectedObject3d = useSelectedObject3d()
 	const environment = useEnvironment()
@@ -331,11 +335,13 @@
 						onclick={() => {
 							const padding = 0.4
 
-							if (!controls.current) return
+							const currentControls = controls.current
 
-							const { azimuthAngle, polarAngle } = controls.current
+							if (!currentControls || !('fitToBox' in currentControls)) return
 
-							controls.current.fitToBox(object3d, true, {
+							const { azimuthAngle, polarAngle } = currentControls
+
+							currentControls.fitToBox(object3d, true, {
 								paddingTop: padding,
 								paddingBottom: padding,
 								paddingLeft: padding,
@@ -343,8 +349,8 @@
 							})
 
 							// Preserve previous rotation
-							controls.current?.rotateAzimuthTo(azimuthAngle, true)
-							controls.current?.rotatePolarTo(polarAngle, true)
+							currentControls.rotateAzimuthTo(azimuthAngle, true)
+							currentControls.rotatePolarTo(polarAngle, true)
 						}}
 					>
 						<Icon name="image-filter-center-focus" />
@@ -353,6 +359,32 @@
 				</Tooltip>
 			{/if}
 
+			{#if name.current}
+				<Tooltip
+					let:tooltipID
+					location="bottom"
+				>
+					<button
+						class="text-subtle-2"
+						aria-describedby={tooltipID}
+						aria-label="Open view from this frame"
+						onclick={() => {
+							const frameName = name.current
+							if (!frameName) return
+							const list = settings.current.openFramePovWidgets[partID.current] ?? []
+							if (list.includes(frameName)) return
+							settings.current.openFramePovWidgets = {
+								...settings.current.openFramePovWidgets,
+								[partID.current]: [...list, frameName],
+							}
+						}}
+					>
+						<Icon name="camera-outline" />
+					</button>
+					<p slot="description">View from this frame</p>
+				</Tooltip>
+			{/if}
+
 			{#if removable.current}
 				<Tooltip
 					let:tooltipID

package/dist/components/overlay/FloatingPanel.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte'
+	import type { ClassValue } from 'svelte/elements'
 
 	import { useThrelte } from '@threlte/core'
 	import { Icon } from '@viamrobotics/prime-core'
@@ -14,6 +15,9 @@
 		resizable?: boolean
 		persistRect?: boolean
 		isOpen?: boolean
+		bodyClass?: ClassValue
+		onPositionChange?: (details: floatingPanel.PositionChangeDetails) => void
+		onSizeChange?: (details: floatingPanel.SizeChangeDetails) => void
 		children: Snippet
 	}
 
@@ -25,6 +29,7 @@
 		resizable = false,
 		persistRect = true,
 		isOpen = $bindable(false),
+		bodyClass = 'bg-white',
 		children,
 		...props
 	}: Props = $props()
@@ -56,7 +61,7 @@
 >
 	<div
 		{...api.getContentProps()}
-		class="border-medium border-1 bg-white dark:text-black"
+		class="border-medium border-1 dark:text-black"
 	>
 		<div
 			{...api.getDragTriggerProps()}
@@ -64,7 +69,7 @@
 		>
 			<div
 				{...api.getHeaderProps()}
-				class="border-medium flex items-center justify-between border-b p-2"
+				class="border-medium flex items-center justify-between border-b bg-white p-2"
 			>
 				<h3
 					{...api.getTitleProps()}
@@ -97,7 +102,7 @@
 		-->
 		<div
 			{...api.getBodyProps()}
-			class="relative h-[calc(100%-33px)]"
+			class={['relative h-[calc(100%-33px)]', bodyClass]}
 		>
 			{#if isOpen}
 				{@render children()}

package/dist/components/overlay/FloatingPanel.svelte.d.ts

@@ -1,4 +1,6 @@
 import type { Snippet } from 'svelte';
+import type { ClassValue } from 'svelte/elements';
+import * as floatingPanel from '@zag-js/floating-panel';
 interface Props {
     title?: string;
     defaultSize?: {
@@ -13,6 +15,9 @@ interface Props {
     resizable?: boolean;
     persistRect?: boolean;
     isOpen?: boolean;
+    bodyClass?: ClassValue;
+    onPositionChange?: (details: floatingPanel.PositionChangeDetails) => void;
+    onSizeChange?: (details: floatingPanel.SizeChangeDetails) => void;
     children: Snippet;
 }
 declare const FloatingPanel: import("svelte").Component<Props, {}, "isOpen">;

package/dist/components/overlay/controls/Controls.svelte

@@ -0,0 +1,40 @@
+<script lang="ts">
+	import { PortalTarget } from '@threlte/extras'
+
+	import Button from '../dashboard/Button.svelte'
+	import { useCameraControls } from '../../../hooks/useControls.svelte'
+	import { useSettings } from '../../../hooks/useSettings.svelte'
+
+	const settings = useSettings()
+	const cameraControls = useCameraControls()
+
+	const isOrthographic = $derived(settings.current.cameraMode === 'orthographic')
+</script>
+
+<div class="absolute right-2 bottom-26 z-4 flex flex-col items-end gap-2">
+	<PortalTarget id="controls" />
+
+	<fieldset class="flex flex-col">
+		<Button
+			active
+			class="rounded-b-none"
+			icon="camera-outline"
+			description="Reset camera"
+			tooltipLocation="left"
+			onclick={() => {
+				cameraControls.setInitialPose()
+			}}
+		/>
+		<Button
+			active
+			class="-my-0.5 rounded-t-none"
+			icon={isOrthographic ? 'grid-orthographic' : 'grid-perspective'}
+			description={isOrthographic ? 'Switch to perspective view' : 'Switch to orthographic view'}
+			hotkey="C"
+			tooltipLocation="left"
+			onclick={() => {
+				settings.current.cameraMode = isOrthographic ? 'perspective' : 'orthographic'
+			}}
+		/>
+	</fieldset>
+</div>

package/dist/components/overlay/controls/Controls.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const Controls: import("svelte").Component<Record<string, never>, {}, "">;
+type Controls = ReturnType<typeof Controls>;
+export default Controls;

package/dist/components/overlay/dashboard/Button.svelte

@@ -10,7 +10,7 @@
 		description: string
 		hotkey?: string
 		class?: ClassValue | null | undefined
-		tooltipLocation?: 'bottom' | 'right'
+		tooltipLocation?: 'bottom' | 'right' | 'left' | 'top'
 		onclick?: MouseEventHandler<HTMLButtonElement> | null | undefined
 	}
 
@@ -33,13 +33,13 @@
 	<label
 		class={[
 			className,
-			'relative block border',
+			'relative block rounded-md border',
 			active ? 'border-gray-5 text-gray-8 z-4 bg-white' : 'bg-light border-medium text-disabled',
 		]}
 		aria-describedby={tooltipID}
 	>
 		<button
-			class="p-1.5"
+			class=" p-1.5"
 			role="radio"
 			aria-label={description}
 			aria-checked={active}

package/dist/components/overlay/dashboard/Button.svelte.d.ts

@@ -6,7 +6,7 @@ interface Props extends HTMLButtonAttributes {
     description: string;
     hotkey?: string;
     class?: ClassValue | null | undefined;
-    tooltipLocation?: 'bottom' | 'right';
+    tooltipLocation?: 'bottom' | 'right' | 'left' | 'top';
     onclick?: MouseEventHandler<HTMLButtonElement> | null | undefined;
 }
 declare const Button: import("svelte").Component<Props, {}, "">;

package/dist/components/overlay/dashboard/Dashboard.svelte

@@ -14,33 +14,11 @@
 	class="absolute top-2 z-4 flex w-full items-center justify-center gap-2"
 	{...rest}
 >
-	<!-- camera view -->
-	<fieldset class="flex">
-		<Button
-			icon="grid-orthographic"
-			active={settings.current.cameraMode === 'orthographic'}
-			description="Orthographic view"
-			hotkey="C"
-			onclick={() => {
-				settings.current.cameraMode = 'orthographic'
-			}}
-		/>
-		<Button
-			icon="grid-perspective"
-			active={settings.current.cameraMode === 'perspective'}
-			description="Perspective view"
-			hotkey="C"
-			class="-ml-px"
-			onclick={() => {
-				settings.current.cameraMode = 'perspective'
-			}}
-		/>
-	</fieldset>
-
 	<!-- transform -->
 	<fieldset class="flex">
 		<Button
 			icon="mouse-pointer"
+			class="rounded-r-none"
 			active={settings.current.transformMode === 'none'}
 			description="No transform controls"
 			hotkey="0"
@@ -50,30 +28,30 @@
 		/>
 		<Button
 			icon="cursor-move"
+			class="-ml-px rounded-none"
 			active={settings.current.transformMode === 'translate'}
 			description="Translate"
 			hotkey="1"
-			class="-ml-px"
 			onclick={() => {
 				settings.current.transformMode = 'translate'
 			}}
 		/>
 		<Button
 			icon="sync"
+			class="-ml-px rounded-none"
 			active={settings.current.transformMode === 'rotate'}
 			description="Rotate"
 			hotkey="2"
-			class="-ml-px"
 			onclick={() => {
 				settings.current.transformMode = 'rotate'
 			}}
 		/>
 		<Button
 			icon="resize"
+			class="-ml-px rounded-l-none"
 			active={settings.current.transformMode === 'scale'}
 			description="Scale"
 			hotkey="3"
-			class="-ml-px"
 			onclick={() => {
 				settings.current.transformMode = 'scale'
 			}}
@@ -81,18 +59,17 @@
 	</fieldset>
 
 	<!-- snapping -->
-	{#if settings.current.transformMode !== 'none'}
-		<fieldset class="flex">
-			<Button
-				icon={settings.current.snapping ? 'magnet' : 'magnet-off'}
-				active={settings.current.snapping}
-				description="Snapping"
-				onclick={() => {
-					settings.current.snapping = !settings.current.snapping
-				}}
-			/>
-		</fieldset>
-	{/if}
+
+	<fieldset class="flex">
+		<Button
+			icon={settings.current.snapping ? 'magnet' : 'magnet-off'}
+			active={settings.current.snapping}
+			description="Snapping"
+			onclick={() => {
+				settings.current.snapping = !settings.current.snapping
+			}}
+		/>
+	</fieldset>
 
 	<PortalTarget id="dashboard" />
 

package/dist/components/overlay/widgets/FramePov.svelte

@@ -0,0 +1,202 @@
+<script lang="ts">
+	import { useTask, useThrelte } from '@threlte/core'
+	import { Slider, type SliderChangeEvent } from 'svelte-tweakpane-ui'
+	import { Matrix4, OrthographicCamera, PerspectiveCamera, WebGLRenderer } from 'three'
+
+	import { traits, useQuery } from '../../../ecs'
+	import { usePartID } from '../../../hooks/usePartID.svelte'
+	import { useSettings } from '../../../hooks/useSettings.svelte'
+
+	import { useOrigin } from '../../xr/useOrigin.svelte'
+	import Button from '../dashboard/Button.svelte'
+	import FloatingPanel from '../FloatingPanel.svelte'
+
+	interface Props {
+		frameName: string
+	}
+
+	const { frameName }: Props = $props()
+
+	const { scene, renderer: mainRenderer, renderStage, invalidate } = useThrelte()
+	const settings = useSettings()
+	const partID = usePartID()
+	const origin = useOrigin()
+
+	// Three.js cameras look down -Z; Viam camera frames conventionally have the
+	// optical axis along +Z with image-down along +Y. A 180° rotation around X
+	// flips both axes so a Three.js render matches "what a sensor at this frame
+	// would see." If empirical testing shows the view is rolled, swap to
+	// makeRotationY for an X-flip instead.
+	const VIAM_TO_THREE_CAMERA = new Matrix4().makeRotationX(Math.PI)
+
+	const PERSPECTIVE_FOV_DEG = 60
+	// Ortho frustum vertical extent at zoom=1, sized to match what the
+	// perspective camera sees at 1 m. zoom > 1 narrows the frustum (zoom in);
+	// zoom < 1 widens it (zoom out).
+	const BASE_ORTHO_HEIGHT = 2 * Math.tan((PERSPECTIVE_FOV_DEG * Math.PI) / 360)
+
+	const namedEntities = useQuery(traits.Name)
+	const entity = $derived(namedEntities.current.find((e) => e.get(traits.Name) === frameName))
+
+	const perspectiveCamera = new PerspectiveCamera(PERSPECTIVE_FOV_DEG, 1, 0.01, 1000)
+	perspectiveCamera.up.set(0, 0, 1)
+
+	const orthographicCamera = new OrthographicCamera(-1, 1, 1, -1, 0.01, 1000)
+	orthographicCamera.up.set(0, 0, 1)
+
+	let isOpen = $state(true)
+	let cameraMode = $state<'perspective' | 'orthographic'>('perspective')
+	let orthoZoom = $state(1)
+	let canvasEl = $state.raw<HTMLCanvasElement>()
+	let povRenderer = $state.raw<WebGLRenderer | undefined>()
+
+	const orthoHeight = $derived(BASE_ORTHO_HEIGHT / orthoZoom)
+
+	const composed = new Matrix4()
+	const originMat = new Matrix4()
+
+	$effect(() => {
+		if (!canvasEl) return
+		const r = new WebGLRenderer({ canvas: canvasEl, antialias: true, alpha: true })
+		// Match the main renderer so colors/tone/transparency are consistent
+		// with the main view.
+		r.outputColorSpace = mainRenderer.outputColorSpace
+		r.toneMapping = mainRenderer.toneMapping
+		r.toneMappingExposure = mainRenderer.toneMappingExposure
+		r.setPixelRatio(mainRenderer.getPixelRatio())
+		r.setSize(canvasEl.clientWidth, canvasEl.clientHeight, false)
+		povRenderer = r
+		invalidate()
+		return () => {
+			r.dispose()
+			povRenderer = undefined
+		}
+	})
+
+	$effect(() => {
+		if (!canvasEl) return
+		const ro = new ResizeObserver(() => {
+			const r = povRenderer
+			if (!r || !canvasEl) return
+			r.setSize(canvasEl.clientWidth, canvasEl.clientHeight, false)
+			invalidate()
+		})
+		ro.observe(canvasEl)
+		return () => ro.disconnect()
+	})
+
+	$effect(() => {
+		void cameraMode
+		void orthoZoom
+		invalidate()
+	})
+
+	$effect(() => {
+		if (entity === undefined) {
+			isOpen = false
+		}
+	})
+
+	$effect(() => {
+		if (isOpen) return
+		const list = settings.current.openFramePovWidgets[partID.current] ?? []
+		const next = list.filter((n) => n !== frameName)
+		if (next.length === list.length) return
+		settings.current.openFramePovWidgets = {
+			...settings.current.openFramePovWidgets,
+			[partID.current]: next,
+		}
+	})
+
+	useTask(
+		() => {
+			const r = povRenderer
+			if (!r || !canvasEl || !entity) return
+			const worldMat = entity.get(traits.WorldMatrix)
+			if (!worldMat) return
+
+			const width = canvasEl.clientWidth
+			const height = canvasEl.clientHeight
+			if (width <= 0 || height <= 0) return
+
+			const povCamera = cameraMode === 'perspective' ? perspectiveCamera : orthographicCamera
+
+			// Compose origin × worldMatrix × VIAM_TO_THREE_CAMERA. The frame
+			// entities' WorldMatrix lives in ECS world space; the rendered scene
+			// is wrapped in a T.Group that applies `origin` on top, so the POV
+			// camera needs the same origin transform to share coordinate space
+			// with the meshes it's rendering.
+			originMat
+				.makeRotationZ(origin.rotation)
+				.setPosition(origin.position[0], origin.position[1], origin.position[2])
+			composed.copy(originMat).multiply(worldMat).multiply(VIAM_TO_THREE_CAMERA)
+			composed.decompose(povCamera.position, povCamera.quaternion, povCamera.scale)
+
+			const aspect = width / height
+			if (povCamera === perspectiveCamera) {
+				perspectiveCamera.aspect = aspect
+			} else {
+				const halfH = orthoHeight / 2
+				const halfW = halfH * aspect
+				orthographicCamera.left = -halfW
+				orthographicCamera.right = halfW
+				orthographicCamera.top = halfH
+				orthographicCamera.bottom = -halfH
+			}
+			povCamera.updateProjectionMatrix()
+			povCamera.updateMatrixWorld(true)
+
+			r.render(scene, povCamera)
+		},
+		{ stage: renderStage, autoInvalidate: false }
+	)
+
+	const handleZoomChange = (event: SliderChangeEvent) => {
+		if (event.detail.origin !== 'internal') return
+		orthoZoom = event.detail.value as number
+	}
+</script>
+
+<FloatingPanel
+	title={`POV: ${frameName}`}
+	bind:isOpen
+	defaultSize={{ width: 320, height: 240 }}
+	resizable
+	onPositionChange={invalidate}
+	onSizeChange={invalidate}
+>
+	<canvas
+		bind:this={canvasEl}
+		class="absolute inset-0 block h-full w-full"
+	></canvas>
+
+	<fieldset class="absolute top-1 right-1 z-1 flex">
+		<Button
+			icon="grid-orthographic"
+			active={cameraMode === 'orthographic'}
+			description="Orthographic view"
+			onclick={() => (cameraMode = 'orthographic')}
+		/>
+		<Button
+			icon="grid-perspective"
+			active={cameraMode === 'perspective'}
+			description="Perspective view"
+			class="-ml-px"
+			onclick={() => (cameraMode = 'perspective')}
+		/>
+	</fieldset>
+
+	{#if cameraMode === 'orthographic'}
+		<div class="absolute right-1 bottom-1 left-1 z-1 rounded bg-white/85 p-1">
+			<Slider
+				label="zoom"
+				value={orthoZoom}
+				min={0.25}
+				max={5}
+				step={0.05}
+				format={(v) => `${v.toFixed(2)}×`}
+				on:change={handleZoomChange}
+			/>
+		</div>
+	{/if}
+</FloatingPanel>

package/dist/components/overlay/widgets/FramePov.svelte.d.ts

@@ -0,0 +1,6 @@
+interface Props {
+    frameName: string;
+}
+declare const FramePov: import("svelte").Component<Props, {}, "">;
+type FramePov = ReturnType<typeof FramePov>;
+export default FramePov;

package/dist/ecs/hierarchy.d.ts

@@ -38,5 +38,21 @@ export declare const destroyEntityTree: (world: World, entity: Entity) => void;
  * the world. Called by `provideHierarchy` when the orphan/named query sets
  * change or when a `Name` is renamed; also exposed for tests so they can
  * drive resolution without mounting a component.
+ *
+ * The first loop builds a `name → entity` map. The second loop reads each
+ * orphan's wanted parent name from that map and attaches `ChildOf` to the
+ * entity it found.
+ *
+ * Two checks prevent an entity from being parented to itself (a `ChildOf`
+ * cycle would loop `recomputeWorldMatrix` forever):
+ *
+ *   1. When two entities have the same `Name`, the map keeps whichever
+ *      one does NOT have `Orphan`. An entity that still has `Orphan` is
+ *      one we're still trying to resolve — it could be the same entity
+ *      the second loop looks up. Letting it fill the slot would make the
+ *      lookup return the orphan itself.
+ *   2. In the second loop, if the lookup returns the orphan itself, skip
+ *      it. This catches the case where the orphan is the only entity in
+ *      the world with that `Name`.
  */
 export declare const resolveOrphans: (named: QueryResult<[Trait<() => string>]>, orphans: QueryResult<[Trait<() => string>]>) => void;

package/dist/ecs/hierarchy.js

@@ -1,6 +1,6 @@
 import {} from 'koota';
 import { ChildOf } from './relations';
-import { Name, Orphan } from './traits';
+import * as traits from './traits';
 /**
  * Trait list for `world.spawn(...)`. Always emits `Orphan(name)` for non-root
  * parents; the hierarchy resolver (`provideHierarchy`) swaps it to
@@ -10,7 +10,7 @@ import { Name, Orphan } from './traits';
 export const parentTraits = (name) => {
     if (!name || name === 'world')
         return [];
-    return [Orphan(name)];
+    return [traits.Orphan(name)];
 };
 /**
  * Set or clear an entity's parent. Strips any existing `ChildOf` or `Orphan`,
@@ -26,15 +26,15 @@ export const parentTraits = (name) => {
 export const setParent = (entity, name) => {
     const desired = !name || name === 'world' ? undefined : name;
     const target = entity.targetFor(ChildOf);
-    const current = (target?.isAlive() ? target.get(Name) : undefined) ?? entity.get(Orphan);
+    const current = (target?.isAlive() ? target.get(traits.Name) : undefined) ?? entity.get(traits.Orphan);
     if (current === desired)
         return;
     if (target)
         entity.remove(ChildOf(target));
-    entity.remove(Orphan);
+    entity.remove(traits.Orphan);
     if (desired === undefined)
         return;
-    entity.add(Orphan(desired));
+    entity.add(traits.Orphan(desired));
 };
 /** The parent entity, or `undefined` at the world root or while orphaned. */
 export const getParentEntity = (entity) => entity.targetFor(ChildOf);
@@ -45,9 +45,10 @@ export const getParentEntity = (entity) => entity.targetFor(ChildOf);
  */
 export const getParentName = (entity) => {
     const parent = entity.targetFor(ChildOf);
-    if (parent && parent.isAlive())
-        return parent.get(Name);
-    const orphanFor = entity.get(Orphan);
+    if (parent && parent.isAlive()) {
+        return parent.get(traits.Name);
+    }
+    const orphanFor = entity.get(traits.Orphan);
     return orphanFor || undefined;
 };
 /**
@@ -69,22 +70,43 @@ export const destroyEntityTree = (world, entity) => {
  * the world. Called by `provideHierarchy` when the orphan/named query sets
  * change or when a `Name` is renamed; also exposed for tests so they can
  * drive resolution without mounting a component.
+ *
+ * The first loop builds a `name → entity` map. The second loop reads each
+ * orphan's wanted parent name from that map and attaches `ChildOf` to the
+ * entity it found.
+ *
+ * Two checks prevent an entity from being parented to itself (a `ChildOf`
+ * cycle would loop `recomputeWorldMatrix` forever):
+ *
+ *   1. When two entities have the same `Name`, the map keeps whichever
+ *      one does NOT have `Orphan`. An entity that still has `Orphan` is
+ *      one we're still trying to resolve — it could be the same entity
+ *      the second loop looks up. Letting it fill the slot would make the
+ *      lookup return the orphan itself.
+ *   2. In the second loop, if the lookup returns the orphan itself, skip
+ *      it. This catches the case where the orphan is the only entity in
+ *      the world with that `Name`.
  */
 export const resolveOrphans = (named, orphans) => {
     const index = new Map();
     for (const entity of named) {
-        const name = entity.get(Name);
-        if (name)
-            index.set(name, entity);
+        const name = entity.get(traits.Name);
+        if (!name)
+            continue;
+        const existing = index.get(name);
+        if (existing && !existing.has(traits.Orphan)) {
+            continue;
+        }
+        index.set(name, entity);
     }
     for (const orphan of orphans) {
-        const wantedName = orphan.get(Orphan);
+        const wantedName = orphan.get(traits.Orphan);
         if (!wantedName)
             continue;
         const parent = index.get(wantedName);
-        if (!parent)
+        if (!parent || parent === orphan)
             continue;
-        orphan.remove(Orphan);
+        orphan.remove(traits.Orphan);
         orphan.add(ChildOf(parent));
     }
 };

package/dist/ecs/worldMatrix.js

@@ -2,7 +2,7 @@ import {} from 'koota';
 import { Matrix4 } from 'three';
 import { composeLocalMatrix } from '../transform';
 import { ChildOf } from './relations';
-import { EditedMatrix, LiveMatrix, Matrix, WorldMatrix } from './traits';
+import { EditedMatrix, LiveMatrix, Matrix, Name, WorldMatrix } from './traits';
 /**
  * Compute the entity's local-to-parent transform into `out`. Mirrors the
  * blend used by `Frame.svelte` so `WorldMatrix` agrees with the displayed
@@ -36,14 +36,25 @@ const toLocalMatrix = (entity, out) => {
  * Synchronously compute and write `WorldMatrix` for every entity in `dirty`
  * and every descendant via `ChildOf`. Memoizes per-entity world matrices in
  * `cache` so siblings reuse a parent's result. Caller passes a fresh `cache`
- * map per flush.
+ * map and `inProgress` set per flush.
+ *
+ * `inProgress` is the cycle guard: if the parent walk revisits an entity
+ * whose computation hasn't finished, we treat that branch as if it had no
+ * parent rather than recursing forever. `resolveOrphans` already prevents
+ * the only known way to introduce a `ChildOf` cycle; this is here so a
+ * future bug downgrades to a soft visual glitch instead of a hard crash.
  */
-const recomputeWorldMatrix = (world, entity, cache) => {
+const recomputeWorldMatrix = (world, entity, cache, inProgress) => {
     if (!entity.isAlive())
         return undefined;
     const cached = cache.get(entity);
     if (cached)
         return cached;
+    if (inProgress.has(entity)) {
+        console.warn('[worldMatrix] ChildOf cycle detected at entity', entity.get(Name) ?? entity);
+        return undefined;
+    }
+    inProgress.add(entity);
     // Reuse the entity's existing `WorldMatrix` storage when present so a
     // flush doesn't allocate a throwaway matrix per entity. First-time
     // entities get a fresh `Matrix4` that's added as the trait below.
@@ -53,10 +64,11 @@ const recomputeWorldMatrix = (world, entity, cache) => {
         out.identity();
     const parent = entity.targetFor(ChildOf);
     if (parent && parent.isAlive()) {
-        const parentWorld = recomputeWorldMatrix(world, parent, cache);
+        const parentWorld = recomputeWorldMatrix(world, parent, cache, inProgress);
         if (parentWorld)
             out.premultiply(parentWorld);
     }
+    inProgress.delete(entity);
     cache.set(entity, out);
     return out;
 };
@@ -64,6 +76,7 @@ const flushDirty = (world, dirty) => {
     if (dirty.size === 0)
         return;
     const cache = new Map();
+    const inProgress = new Set();
     const expanded = new Set();
     const collect = (entity) => {
         if (expanded.has(entity))
@@ -79,7 +92,7 @@ const flushDirty = (world, dirty) => {
     for (const entity of expanded) {
         if (!entity.isAlive())
             continue;
-        const worldMat = recomputeWorldMatrix(world, entity, cache);
+        const worldMat = recomputeWorldMatrix(world, entity, cache, inProgress);
         if (!worldMat)
             continue;
         if (entity.has(WorldMatrix)) {

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

@@ -1,12 +1,13 @@
 import type { CameraControlsRef } from '@threlte/extras';
 import type { Vector3Tuple } from 'three';
+import type { TrackballControls } from 'three/examples/jsm/Addons.js';
 export interface CameraPose {
     position: Vector3Tuple;
     lookAt: Vector3Tuple;
 }
 interface CameraControlsContext {
-    current: CameraControlsRef | undefined;
-    set(current: CameraControlsRef): void;
+    current: CameraControlsRef | TrackballControls | undefined;
+    set(current: CameraControlsRef | TrackballControls): void;
     setPose(pose: CameraPose, animate?: boolean): void;
     setInitialPose(): void;
     setZoom(zoom: number): void;

package/dist/hooks/useControls.svelte.js

@@ -6,15 +6,23 @@ export const provideCameraControls = (initialCameraPose) => {
     const setPose = (pose, animate = false) => {
         const [x, y, z] = pose.position;
         const [lookAtX, lookAtY, lookAtZ] = pose.lookAt;
-        controls?.setPosition(x, y, z, animate);
-        controls?.setLookAt(x, y, z, lookAtX, lookAtY, lookAtZ, animate);
+        if (controls && 'setPosition' in controls) {
+            controls.setPosition(x, y, z, animate);
+            controls.setLookAt(x, y, z, lookAtX, lookAtY, lookAtZ, animate);
+        }
     };
     const setZoom = (zoom) => {
-        controls?.zoomTo(zoom);
+        if (controls && 'zoomTo' in controls)
+            controls?.zoomTo(zoom);
     };
     const setInitialPose = () => {
-        const pose = initialCameraPose();
-        setPose(pose ?? { position: [3, 3, 3], lookAt: [0, 0, 0] }, true);
+        if (controls && 'setPosition' in controls) {
+            const pose = initialCameraPose();
+            setPose(pose ?? { position: [3, 3, 3], lookAt: [0, 0, 0] }, true);
+        }
+        else if (controls) {
+            controls.reset();
+        }
     };
     $effect(() => {
         const pose = initialCameraPose();

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

@@ -26,6 +26,7 @@ export interface Settings {
     enableQueryDevtools: boolean;
     enableArmPositionsWidget: boolean;
     openCameraWidgets: Record<string, string[]>;
+    openFramePovWidgets: Record<string, string[]>;
     renderStats: boolean;
     renderArmModels: 'colliders' | 'colliders+model' | 'model';
     renderSubEntityHoverDetail: boolean;

package/dist/hooks/useSettings.svelte.js

@@ -33,6 +33,7 @@ const defaults = () => ({
     enableQueryDevtools: false,
     enableArmPositionsWidget: false,
     openCameraWidgets: {},
+    openFramePovWidgets: {},
     renderStats: false,
     renderArmModels: 'colliders+model',
     renderSubEntityHoverDetail: false,

package/dist/plugins/Skybox/Skybox.svelte

@@ -0,0 +1,73 @@
+<script lang="ts">
+	import { T } from '@threlte/core'
+	import { EquirectangularReflectionMapping, type Texture, TextureLoader } from 'three'
+	import { GroundedSkybox } from 'three/examples/jsm/objects/GroundedSkybox.js'
+
+	interface Props {
+		url: string
+		/**
+		 * World-space position `[x, y, z]`. Defaults to `[0, 0, height]` so the
+		 * dome's ground sits flush with the world XY plane in this Z-up scene.
+		 */
+		position?: [x: number, y: number, z: number]
+		/**
+		 * Euler rotation `[x, y, z]` in radians. Default aligns the
+		 * equirectangular image's vertical axis (+Y) with this scene's vertical
+		 * axis (+Z); the Z component then acts as yaw around world +Z.
+		 */
+		rotation?: [x: number, y: number, z: number]
+		/**
+		 * Camera height above ground when the source photo was taken. Larger
+		 * values magnify the lower portion of the image.
+		 */
+		height?: number
+		/**
+		 * Skybox dome radius. Must exceed the scene camera's reach.
+		 */
+		radius?: number
+	}
+
+	const {
+		url,
+		position,
+		rotation = [Math.PI / 2, 0, 0],
+		height = 15,
+		radius = 100,
+	}: Props = $props()
+
+	let texture = $state.raw<Texture | undefined>()
+
+	$effect.pre(() => {
+		let cancelled = false
+		let loaded: Texture | undefined
+
+		new TextureLoader().load(url, (t) => {
+			if (cancelled) {
+				t.dispose()
+				return
+			}
+			t.mapping = EquirectangularReflectionMapping
+			loaded = t
+			texture = t
+		})
+
+		return () => {
+			cancelled = true
+			loaded?.dispose()
+			texture = undefined
+		}
+	})
+
+	const resolvedPosition = $derived(position ?? ([0, 0, height] as [number, number, number]))
+</script>
+
+{#if texture}
+	<T
+		is={GroundedSkybox}
+		args={[texture, height, radius]}
+		position={resolvedPosition}
+		{rotation}
+		raycast={() => null}
+		bvh={{ enabled: false }}
+	/>
+{/if}

package/dist/plugins/Skybox/Skybox.svelte.d.ts

@@ -0,0 +1,26 @@
+interface Props {
+    url: string;
+    /**
+     * World-space position `[x, y, z]`. Defaults to `[0, 0, height]` so the
+     * dome's ground sits flush with the world XY plane in this Z-up scene.
+     */
+    position?: [x: number, y: number, z: number];
+    /**
+     * Euler rotation `[x, y, z]` in radians. Default aligns the
+     * equirectangular image's vertical axis (+Y) with this scene's vertical
+     * axis (+Z); the Z component then acts as yaw around world +Z.
+     */
+    rotation?: [x: number, y: number, z: number];
+    /**
+     * Camera height above ground when the source photo was taken. Larger
+     * values magnify the lower portion of the image.
+     */
+    height?: number;
+    /**
+     * Skybox dome radius. Must exceed the scene camera's reach.
+     */
+    radius?: number;
+}
+declare const Skybox: import("svelte").Component<Props, {}, "">;
+type Skybox = ReturnType<typeof Skybox>;
+export default Skybox;

package/dist/plugins/index.d.ts

@@ -0,0 +1 @@
+export { default as Skybox } from './Skybox/Skybox.svelte';

package/dist/plugins/index.js

@@ -0,0 +1,2 @@
+// Skybox
+export { default as Skybox } from './Skybox/Skybox.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viamrobotics/motion-tools",
-  "version": "1.27.1",
+  "version": "1.28.1",
   "description": "Motion visualization with Viam",
   "license": "Apache-2.0",
   "type": "module",
@@ -122,6 +122,10 @@
     "./lib": {
       "types": "./dist/lib.d.ts",
       "svelte": "./dist/lib.js"
+    },
+    "./plugins": {
+      "types": "./dist/plugins/index.d.ts",
+      "svelte": "./dist/plugins/index.js"
     }
   },
   "repository": {