@viamrobotics/motion-tools 1.13.0 → 1.14.0

package/dist/buffer.d.ts

@@ -4,6 +4,7 @@
  * Proto messages pack float32 data as `Uint8Array` (bytes fields). These utilities
  * provide efficient conversion to `Float32Array` for Three.js BufferAttributes.
  */
+import { Color } from 'three';
 /**
  * Stride constants for proto binary data formats.
  * Each value represents the number of float32 elements per item.
@@ -37,16 +38,64 @@ export declare const STRIDE: {
  */
 export declare const asFloat32Array: (bytes: Uint8Array<ArrayBuffer>) => Float32Array<ArrayBuffer>;
 /**
- * Converts uint8 RGBA colors to normalized float32 colors (0-1 range).
- * Three.js expects colors in 0-1 range for BufferAttributes.
+ * Sets a Three.js Color from 3 bytes of a uint8 color array starting at `offset`.
+ * Mutates and returns `target` — pass a pre-allocated Color to avoid allocations
+ * in hot paths.
  *
- * @param colors - Uint8Array of RGBA color data [r, g, b, a, ...]
- * @returns Float32Array with normalized color values
+ * @param bytes - Uint8Array with at least `offset + 3` elements [r, g, b, ...]
+ * @param target - Color instance to write into
+ * @param offset - Byte offset to start reading from (default 0)
+ * @returns The mutated `target`, or black if the array has fewer than `offset + 3` elements
  *
  * @example
  * ```ts
- * const colors = normalizeColorsRGBA(metadata.colors)
- * geometry.setAttribute('color', new BufferAttribute(colors, 4))
+ * asColor(colors.current, material.color)
+ * asColor(colors.current, pointColorUtil, stride) // read second color
  * ```
  */
-export declare const normalizeColorsRGBA: (colors: Float32Array) => Float32Array;
+export declare const asColor: (bytes: Uint8Array<ArrayBuffer>, target: Color, offset?: number) => Color;
+/**
+ * Creates a Uint8Array from a Three.js Color.
+ *
+ * @param color - The Three.js Color to convert
+ * @returns A Uint8Array with the RGBA values
+ *
+ * @example
+ * ```ts
+ * const color = fromColor(new Color(0, 1, 0))
+ * ```
+ */
+export declare const fromColor: (color: Color) => Uint8Array<ArrayBuffer>;
+/**
+ * Reads a byte from a uint8 color array at `offset` and normalizes it to 0-1.
+ * Returns `fallback` when the array has fewer than `offset + 1` elements.
+ *
+ * @param bytes - ArrayLike of uint8 color values
+ * @param fallback - Value to return when no alpha byte is present (default 1)
+ * @param offset - Byte index to read from (default 3, the alpha channel of the first color)
+ * @returns Normalized opacity in 0-1 range, or the fallback value
+ *
+ * @example
+ * ```ts
+ * material.opacity = asOpacity(colors.current)
+ * material.opacity = asOpacity(colors.current, 1, stride + 3) // alpha of second color
+ * ```
+ */
+export declare const asOpacity: (bytes: Uint8Array<ArrayBuffer>, fallback?: number, offset?: number) => number;
+/**
+ * Returns true when `colors` contains exactly one color entry per point (RGB or RGBA).
+ * Use this to distinguish per-vertex color buffers from a single uniform color.
+ *
+ * @param colors - Uint8Array of packed color bytes
+ * @param numVertex - Number of points/vertices the color buffer should cover
+ *
+ * @example
+ * ```ts
+ * if (isPerVertexColors(colors, positions.length / STRIDE.POSITIONS)) {
+ *   // treat as per-vertex
+ * } else {
+ *   addColorTraits(entityTraits, colors)
+ * }
+ * ```
+ */
+export declare const isPerVertexColors: (colors: Uint8Array<ArrayBuffer>, numVertex: number) => boolean;

package/dist/buffer.js

@@ -4,6 +4,7 @@
  * Proto messages pack float32 data as `Uint8Array` (bytes fields). These utilities
  * provide efficient conversion to `Float32Array` for Three.js BufferAttributes.
  */
+import { Color } from 'three';
 /**
  * Stride constants for proto binary data formats.
  * Each value represents the number of float32 elements per item.
@@ -50,22 +51,79 @@ export const asFloat32Array = (bytes) => {
     return aligned;
 };
 /**
- * Converts uint8 RGBA colors to normalized float32 colors (0-1 range).
- * Three.js expects colors in 0-1 range for BufferAttributes.
+ * Sets a Three.js Color from 3 bytes of a uint8 color array starting at `offset`.
+ * Mutates and returns `target` — pass a pre-allocated Color to avoid allocations
+ * in hot paths.
  *
- * @param colors - Uint8Array of RGBA color data [r, g, b, a, ...]
- * @returns Float32Array with normalized color values
+ * @param bytes - Uint8Array with at least `offset + 3` elements [r, g, b, ...]
+ * @param target - Color instance to write into
+ * @param offset - Byte offset to start reading from (default 0)
+ * @returns The mutated `target`, or black if the array has fewer than `offset + 3` elements
  *
  * @example
  * ```ts
- * const colors = normalizeColorsRGBA(metadata.colors)
- * geometry.setAttribute('color', new BufferAttribute(colors, 4))
+ * asColor(colors.current, material.color)
+ * asColor(colors.current, pointColorUtil, stride) // read second color
  * ```
  */
-export const normalizeColorsRGBA = (colors) => {
-    const normalized = new Float32Array(colors.length);
-    for (let i = 0; i < colors.length; i++) {
-        normalized[i] = colors[i] / 255;
-    }
-    return normalized;
+export const asColor = (bytes, target, offset = 0) => {
+    if (bytes.length < offset + 3)
+        return target.setRGB(0, 0, 0);
+    return target.setRGB(bytes[offset] / 255, bytes[offset + 1] / 255, bytes[offset + 2] / 255);
+};
+/**
+ * Creates a Uint8Array from a Three.js Color.
+ *
+ * @param color - The Three.js Color to convert
+ * @returns A Uint8Array with the RGBA values
+ *
+ * @example
+ * ```ts
+ * const color = fromColor(new Color(0, 1, 0))
+ * ```
+ */
+export const fromColor = (color) => {
+    return new Uint8Array([
+        Math.round(color.r * 255),
+        Math.round(color.g * 255),
+        Math.round(color.b * 255),
+    ]);
+};
+/**
+ * Reads a byte from a uint8 color array at `offset` and normalizes it to 0-1.
+ * Returns `fallback` when the array has fewer than `offset + 1` elements.
+ *
+ * @param bytes - ArrayLike of uint8 color values
+ * @param fallback - Value to return when no alpha byte is present (default 1)
+ * @param offset - Byte index to read from (default 3, the alpha channel of the first color)
+ * @returns Normalized opacity in 0-1 range, or the fallback value
+ *
+ * @example
+ * ```ts
+ * material.opacity = asOpacity(colors.current)
+ * material.opacity = asOpacity(colors.current, 1, stride + 3) // alpha of second color
+ * ```
+ */
+export const asOpacity = (bytes, fallback = 1, offset = 3) => {
+    if (bytes.length < offset + 1)
+        return fallback;
+    return bytes[offset] / 255;
 };
+/**
+ * Returns true when `colors` contains exactly one color entry per point (RGB or RGBA).
+ * Use this to distinguish per-vertex color buffers from a single uniform color.
+ *
+ * @param colors - Uint8Array of packed color bytes
+ * @param numVertex - Number of points/vertices the color buffer should cover
+ *
+ * @example
+ * ```ts
+ * if (isPerVertexColors(colors, positions.length / STRIDE.POSITIONS)) {
+ *   // treat as per-vertex
+ * } else {
+ *   addColorTraits(entityTraits, colors)
+ * }
+ * ```
+ */
+export const isPerVertexColors = (colors, numVertex) => colors.length === numVertex * STRIDE.COLORS_RGB ||
+    colors.length === numVertex * STRIDE.COLORS_RGBA;

package/dist/color.js

@@ -17,9 +17,9 @@ const oklchToHex = (raw) => {
     if (!match) {
         return raw;
     }
-    const l = parseFloat(match[1]) / 100;
-    const c = parseFloat(match[2]);
-    const h = parseFloat(match[3]);
+    const l = Number.parseFloat(match[1]) / 100;
+    const c = Number.parseFloat(match[2]);
+    const h = Number.parseFloat(match[3]);
     // Convert h from degrees to radians
     const hRad = (h * Math.PI) / 180;
     // Step 1: OKLCH → OKLab

package/dist/components/App.svelte

@@ -87,11 +87,7 @@
 	)
 
 	$effect.pre(() => {
-		if (localConfigProps) {
-			environment.current.isStandalone = false
-		} else {
-			environment.current.isStandalone = true
-		}
+		environment.current.isStandalone = !localConfigProps
 	})
 </script>
 

package/dist/components/Camera.svelte

@@ -1,17 +1,11 @@
 <script lang="ts">
-	import { T, useThrelte } from '@threlte/core'
+	import { T } from '@threlte/core'
 	import { useSettings } from '../hooks/useSettings.svelte'
-	import type { Camera } from 'three'
 
 	let { children, ...rest } = $props()
 
-	const { camera } = useThrelte()
 	const settings = useSettings()
 	const mode = $derived(settings.current.cameraMode)
-
-	$effect(() => {
-		;(window as unknown as { camera: Camera }).camera = $camera
-	})
 </script>
 
 {#if mode === 'perspective'}

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

@@ -1,4 +1,3 @@
-import type { Camera } from 'three';
 declare const Camera: import("svelte").Component<{
     children: any;
 } & Record<string, any>, {}, "">;

package/dist/components/CameraControls.svelte

@@ -30,8 +30,8 @@
 	enabled={!transformControls.active}
 	oncreate={(ref) => {
 		cameraControls.set(ref)
-		;(window as unknown as { MathUtils: typeof MathUtils }).MathUtils = MathUtils
-		;(window as unknown as { cameraControls: CameraControlsRef }).cameraControls = ref
+		;(globalThis as unknown as { MathUtils: typeof MathUtils }).MathUtils = MathUtils
+		;(globalThis as unknown as { cameraControls: CameraControlsRef }).cameraControls = ref
 	}}
 >
 	{#snippet children({ ref }: { ref: CameraControlsRef })}

package/dist/components/{Arrows → Entities/Arrows}/ArrowGroups.svelte

@@ -1,8 +1,8 @@
 <script lang="ts">
-	import { InstancedArrows } from '../../three/InstancedArrows/InstancedArrows'
-	import { traits, useWorld } from '../../ecs'
+	import { InstancedArrows } from '../../../three/InstancedArrows/InstancedArrows'
+	import { traits, useWorld } from '../../../ecs'
 	import type { Entity } from 'koota'
-	import { STRIDE } from '../../buffer'
+	import { STRIDE } from '../../../buffer'
 	import { SvelteMap } from 'svelte/reactivity'
 	import { Color } from 'three'
 	import Arrows from './Arrows.svelte'

package/dist/components/{Arrows → Entities/Arrows}/Arrows.svelte

@@ -2,11 +2,11 @@
 	import { T } from '@threlte/core'
 	import { Portal } from '@threlte/extras'
 	import type { Entity } from 'koota'
-	import { traits } from '../../ecs'
-	import { useObjectEvents } from '../../hooks/useObjectEvents.svelte'
-	import type { InstancedArrows } from '../../three/InstancedArrows/InstancedArrows'
-	import { useFocusedEntity, useSelectedEntity } from '../../hooks/useSelection.svelte'
-	import { meshBoundsRaycast, raycast } from '../../three/InstancedArrows/raycast'
+	import { traits } from '../../../ecs'
+	import { useEntityEvents } from '../hooks/useEntityEvents.svelte'
+	import type { InstancedArrows } from '../../../three/InstancedArrows/InstancedArrows'
+	import { useFocusedEntity, useSelectedEntity } from '../../../hooks/useSelection.svelte'
+	import { meshBoundsRaycast, raycast } from '../../../three/InstancedArrows/raycast'
 
 	interface Props {
 		entity: Entity
@@ -15,7 +15,7 @@
 
 	let { entity, arrows }: Props = $props()
 
-	const events = useObjectEvents(() => entity)
+	const events = useEntityEvents(() => entity)
 	const selectedEntity = useSelectedEntity()
 	const focusedEntity = useFocusedEntity()
 

package/dist/components/{Arrows → Entities/Arrows}/Arrows.svelte.d.ts

@@ -1,5 +1,5 @@
 import type { Entity } from 'koota';
-import type { InstancedArrows } from '../../three/InstancedArrows/InstancedArrows';
+import type { InstancedArrows } from '../../../three/InstancedArrows/InstancedArrows';
 interface Props {
     entity: Entity;
     arrows: InstancedArrows;

package/dist/components/{Entities.svelte → Entities/Entities.svelte}

@@ -5,8 +5,10 @@
 	import Label from './Label.svelte'
 	import Line from './Line.svelte'
 	import Points from './Points.svelte'
-	import { traits, useQuery } from '../ecs'
+	import Arrows from './Arrows/ArrowGroups.svelte'
+	import { traits, useQuery } from '../../ecs'
 	import { Not, Or } from 'koota'
+	import Geometry from './Geometry.svelte'
 
 	/**
 	 * Frames from a live machine are bucketed into their own query
@@ -60,9 +62,9 @@
 {/each}
 
 {#each resourceGeometriesEntities.current as entity (entity)}
-	<Frame {entity}>
+	<Geometry {entity}>
 		<Label text={entity.get(traits.Name)} />
-	</Frame>
+	</Geometry>
 {/each}
 
 {#each worldStateEntities.current as entity (entity)}
@@ -94,3 +96,5 @@
 		<Label text={entity.get(traits.Name)} />
 	</GLTF>
 {/each}
+
+<Arrows />

package/dist/components/Entities/Frame.svelte

@@ -0,0 +1,86 @@
+<!--
+@component
+
+Renders a Viam Frame object
+-->
+<script module>
+	import { Color } from 'three'
+
+	const colorUtil = new Color()
+</script>
+
+<script lang="ts">
+	import type { Snippet } from 'svelte'
+	import { Group, type Object3D } from 'three'
+	import { T, useThrelte } from '@threlte/core'
+	import { Portal, PortalTarget } from '@threlte/extras'
+	import { useEntityEvents } from './hooks/useEntityEvents.svelte'
+	import Mesh from './Mesh.svelte'
+	import { colors, resourceColors } from '../../color'
+	import type { Entity } from 'koota'
+	import { traits, useTrait } from '../../ecs'
+	import type { Pose } from '@viamrobotics/sdk'
+	import { useResourceByName } from '../../hooks/useResourceByName.svelte'
+	import { poseToObject3d } from '../../transform'
+
+	interface Props {
+		entity: Entity
+		pose?: Pose
+		children?: Snippet<[{ ref: Object3D }]>
+	}
+
+	let { entity, pose, children }: Props = $props()
+
+	const { invalidate } = useThrelte()
+	const resourceByName = useResourceByName()
+
+	const name = useTrait(() => entity, traits.Name)
+	const parent = useTrait(() => entity, traits.Parent)
+	const entityColor = useTrait(() => entity, traits.Color)
+	const entityPose = useTrait(() => entity, traits.Pose)
+	const center = useTrait(() => entity, traits.Center)
+
+	const events = useEntityEvents(() => entity)
+
+	const color = $derived.by(() => {
+		if (entityColor.current) {
+			return `#${colorUtil.set(entityColor.current.r, entityColor.current.g, entityColor.current.b).getHexString()}`
+		}
+
+		const subtype = resourceByName.current[name.current ?? '']?.subtype
+		const resourceColor = resourceColors[subtype as keyof typeof resourceColors]
+
+		if (resourceColor) {
+			return resourceColor
+		}
+
+		return colors.default
+	})
+
+	const group = new Group()
+
+	const resolvedPose = $derived(pose ?? entityPose.current)
+	$effect.pre(() => {
+		if (resolvedPose) {
+			poseToObject3d(resolvedPose, group)
+			invalidate()
+		}
+	})
+</script>
+
+<Portal id={parent.current}>
+	<T is={group}>
+		<Mesh
+			{entity}
+			{color}
+			{...events}
+			center={center.current}
+		/>
+
+		{#if name.current}
+			<PortalTarget id={name.current} />
+		{/if}
+
+		{@render children?.({ ref: group })}
+	</T>
+</Portal>

package/dist/components/{Frame.svelte.d.ts → Entities/Frame.svelte.d.ts}

@@ -9,6 +9,7 @@ interface Props {
         ref: Object3D;
     }]>;
 }
+/** Renders a Viam Frame object */
 declare const Frame: import("svelte").Component<Props, {}, "">;
 type Frame = ReturnType<typeof Frame>;
 export default Frame;

package/dist/components/{GLTF.svelte → Entities/GLTF.svelte}

@@ -16,10 +16,10 @@
 	import { Portal, PortalTarget, useGltfAnimations, type ThrelteGltf } from '@threlte/extras'
 	import type { Snippet } from 'svelte'
 	import { Group, type Object3D } from 'three'
-	import { useObjectEvents } from '../hooks/useObjectEvents.svelte'
+	import { useEntityEvents } from './hooks/useEntityEvents.svelte'
 	import type { Entity } from 'koota'
-	import { traits, useTrait } from '../ecs'
-	import { poseToObject3d } from '../transform'
+	import { traits, useTrait } from '../../ecs'
+	import { poseToObject3d } from '../../transform'
 
 	interface Props extends ThrelteProps<Object3D> {
 		entity: Entity
@@ -35,7 +35,7 @@
 	const pose = useTrait(() => entity, traits.Pose)
 	const gltfTrait = useTrait(() => entity, traits.GLTF)
 	const scale = useTrait(() => entity, traits.Scale)
-	const objectProps = useObjectEvents(() => entity)
+	const events = useEntityEvents(() => entity)
 
 	const animationName = $derived(gltfTrait.current?.animationName)
 
@@ -85,7 +85,7 @@
 				is={$gltf.scene as Object3D}
 				scale={[scale.current?.x ?? 1, scale.current?.y ?? 1, scale.current?.z ?? 1]}
 				name={entity}
-				{...objectProps}
+				{...events}
 				{...rest}
 			>
 				{@render children?.()}

package/dist/components/Entities/Geometry.svelte

@@ -0,0 +1,75 @@
+<!--
+@component
+
+Renders a Viam Geometry object
+-->
+<script lang="ts">
+	import { T, useThrelte } from '@threlte/core'
+	import { traits, useTrait } from '../../ecs'
+	import { use3DModels } from '../../hooks/use3DModels.svelte'
+	import { Portal } from '@threlte/extras'
+	import { poseToObject3d } from '../../transform'
+	import { useSettings } from '../../hooks/useSettings.svelte'
+	import Mesh from './Mesh.svelte'
+	import { useEntityEvents } from './hooks/useEntityEvents.svelte'
+	import type { Entity } from 'koota'
+	import type { Snippet } from 'svelte'
+
+	interface Props {
+		entity: Entity
+		children?: Snippet
+	}
+
+	const { entity, children }: Props = $props()
+
+	const settings = useSettings()
+
+	const { invalidate } = useThrelte()
+	const models = use3DModels()
+
+	const name = useTrait(() => entity, traits.Name)
+	const parent = useTrait(() => entity, traits.Parent)
+	const center = useTrait(() => entity, traits.Center)
+
+	const model = $derived.by(() => {
+		if (!settings.current.renderArmModels.includes('model')) {
+			return
+		}
+
+		if (!name.current) {
+			return
+		}
+
+		const [componentName, id] = name.current.split(':')
+		if (!componentName || !id) {
+			return
+		}
+
+		return models.current[componentName]?.[id].clone()
+	})
+
+	$effect.pre(() => {
+		if (model && center.current) {
+			poseToObject3d(center.current, model)
+			invalidate()
+		}
+	})
+
+	const events = useEntityEvents(() => entity)
+</script>
+
+<Portal id={parent.current}>
+	{#if model}
+		<T is={model} />
+	{/if}
+
+	{#if settings.current.renderArmModels.includes('colliders') || !model}
+		<Mesh
+			{entity}
+			center={center.current}
+			{...events}
+		>
+			{@render children?.()}
+		</Mesh>
+	{/if}
+</Portal>

package/dist/components/Entities/Geometry.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { Entity } from 'koota';
+import type { Snippet } from 'svelte';
+interface Props {
+    entity: Entity;
+    children?: Snippet;
+}
+/** Renders a Viam Geometry object */
+declare const Geometry: import("svelte").Component<Props, {}, "">;
+type Geometry = ReturnType<typeof Geometry>;
+export default Geometry;

package/dist/components/{Label.svelte → Entities/Label.svelte}

@@ -1,7 +1,7 @@
 <script lang="ts">
 	import { HTML } from '@threlte/extras'
 
-	import { useSettings } from '../hooks/useSettings.svelte'
+	import { useSettings } from '../../hooks/useSettings.svelte'
 
 	interface Props {
 		text?: string

package/dist/components/Entities/Line.svelte

@@ -0,0 +1,90 @@
+<script module>
+	import { Color } from 'three'
+
+	const colorUtil = new Color()
+</script>
+
+<script lang="ts">
+	import type { Snippet } from 'svelte'
+	import { T, useThrelte } from '@threlte/core'
+	import { meshBounds, Portal, PortalTarget } from '@threlte/extras'
+	import type { Entity } from 'koota'
+	import { traits, useTrait } from '../../ecs'
+	import LineDots from './LineDots.svelte'
+	import { darkenColor } from '../../color'
+	import { useEntityEvents } from './hooks/useEntityEvents.svelte'
+	import { Line2, LineMaterial } from 'three/examples/jsm/Addons.js'
+	import LineGeometry from './LineGeometry.svelte'
+	import { poseToObject3d } from '../../transform'
+
+	interface Props {
+		entity: Entity
+		children?: Snippet
+	}
+
+	let { entity, children }: Props = $props()
+
+	const { invalidate } = useThrelte()
+	const name = useTrait(() => entity, traits.Name)
+	const parent = useTrait(() => entity, traits.Parent)
+	const pose = useTrait(() => entity, traits.Pose)
+	const color = useTrait(() => entity, traits.Color)
+	const pointSize = useTrait(() => entity, traits.PointSize)
+	const linePositions = useTrait(() => entity, traits.LinePositions)
+	const lineWidth = useTrait(() => entity, traits.LineWidth)
+	const opacity = useTrait(() => entity, traits.Opacity)
+	const materialProps = useTrait(() => entity, traits.Material)
+	const renderOrder = useTrait(() => entity, traits.RenderOrder)
+
+	const events = useEntityEvents(() => entity)
+
+	const currentOpacity = $derived(opacity.current ?? 0.7)
+
+	const mesh = new Line2()
+
+	$effect.pre(() => {
+		if (pose.current) {
+			poseToObject3d(pose.current, mesh)
+			invalidate()
+		}
+	})
+</script>
+
+<Portal id={parent.current}>
+	<T
+		is={mesh}
+		name={entity}
+		userData.name={name}
+		raycast={meshBounds}
+		renderOrder={renderOrder.current}
+		{...events}
+	>
+		<LineGeometry positions={linePositions.current} />
+		<T
+			is={LineMaterial}
+			color={[color.current?.r ?? 1, color.current?.g ?? 0, color.current?.b ?? 0]}
+			transparent={currentOpacity < 1}
+			depthWrite={currentOpacity === 1}
+			opacity={currentOpacity}
+			width={lineWidth.current ? lineWidth.current * 0.001 : 0.5}
+			depthTest={materialProps.current?.depthTest ?? true}
+		/>
+	</T>
+
+	{#if linePositions.current && pointSize.current}
+		<LineDots
+			color={darkenColor(
+				colorUtil.setRGB(color.current?.r ?? 1, color.current?.g ?? 0, color.current?.b ?? 0),
+				10
+			)}
+			positions={linePositions.current}
+			scale={pointSize.current * 0.001}
+		/>
+	{/if}
+
+	{#if name.current}
+		<PortalTarget id={name.current} />
+	{/if}
+
+	{@render children?.()}
+</Portal>