@viamrobotics/motion-tools 1.1.5 → 1.2.0

package/dist/WorldObject.svelte.js

@@ -98,6 +98,29 @@ export const parseMetadata = (fields = {}) => {
             case 'lineDotColor':
                 json[k] = readColor(unwrappedValue);
                 break;
+            case 'colors': {
+                let colorBytes;
+                // Handle base64-encoded string (from protobuf Struct)
+                if (typeof unwrappedValue === 'string') {
+                    const binary = atob(unwrappedValue);
+                    colorBytes = new Uint8Array(binary.length);
+                    for (let i = 0; i < binary.length; i++) {
+                        colorBytes[i] = binary.charCodeAt(i);
+                    }
+                }
+                else if (Array.isArray(unwrappedValue)) {
+                    colorBytes = unwrappedValue;
+                }
+                if (colorBytes && colorBytes.length >= 3) {
+                    const r = (colorBytes[0] ?? 0) / 255;
+                    const g = (colorBytes[1] ?? 0) / 255;
+                    const b = (colorBytes[2] ?? 0) / 255;
+                    const a = colorBytes.length >= 4 ? (colorBytes[3] ?? 255) / 255 : 1;
+                    json.color = new Color(r, g, b);
+                    json.opacity = a;
+                }
+                break;
+            }
             case 'opacity':
                 json[k] = parseOpacity(unwrappedValue);
                 break;

package/dist/buffer.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Zero-copy buffer utilities for converting protobuf bytes to Three.js typed arrays.
+ *
+ * Proto messages pack float32 data as `Uint8Array` (bytes fields). These utilities
+ * provide efficient conversion to `Float32Array` for Three.js BufferAttributes.
+ */
+/**
+ * Stride constants for proto binary data formats.
+ * Each value represents the number of float32 elements per item.
+ */
+export declare const STRIDE: {
+    /** Arrows: [x, y, z, ox, oy, oz] per arrow */
+    readonly ARROWS: 6;
+    /** Line/Points: [x, y, z] per point */
+    readonly POSITIONS: 3;
+    /** Nurbs control points: [x, y, z, ox, oy, oz, theta] per point */
+    readonly NURBS_CONTROL_POINTS: 7;
+    /** Nurbs knots/weights: single float per element */
+    readonly NURBS_KNOTS: 1;
+    /** Colors: [r, g, b, a] per color (uint8) */
+    readonly COLORS_RGBA: 4;
+};
+/**
+ * Creates a Float32Array view over a Uint8Array without copying data.
+ * Falls back to a copy if the buffer is not 4-byte aligned (rare with protobuf).
+ *
+ * @param bytes - The raw bytes from a protobuf bytes field
+ * @returns A Float32Array view or copy of the data
+ *
+ * @example
+ * ```ts
+ * const positions = asFloat32Array(line.positions)
+ * geometry.setAttribute('position', new BufferAttribute(positions, 3))
+ * ```
+ */
+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.
+ *
+ * @param colors - Uint8Array of RGBA color data [r, g, b, a, ...]
+ * @returns Float32Array with normalized color values
+ *
+ * @example
+ * ```ts
+ * const colors = normalizeColorsRGBA(metadata.colors)
+ * geometry.setAttribute('color', new BufferAttribute(colors, 4))
+ * ```
+ */
+export declare const normalizeColorsRGBA: (colors: Float32Array) => Float32Array;

package/dist/buffer.js

@@ -0,0 +1,69 @@
+/**
+ * Zero-copy buffer utilities for converting protobuf bytes to Three.js typed arrays.
+ *
+ * Proto messages pack float32 data as `Uint8Array` (bytes fields). These utilities
+ * provide efficient conversion to `Float32Array` for Three.js BufferAttributes.
+ */
+/**
+ * Stride constants for proto binary data formats.
+ * Each value represents the number of float32 elements per item.
+ */
+export const STRIDE = {
+    /** Arrows: [x, y, z, ox, oy, oz] per arrow */
+    ARROWS: 6,
+    /** Line/Points: [x, y, z] per point */
+    POSITIONS: 3,
+    /** Nurbs control points: [x, y, z, ox, oy, oz, theta] per point */
+    NURBS_CONTROL_POINTS: 7,
+    /** Nurbs knots/weights: single float per element */
+    NURBS_KNOTS: 1,
+    /** Colors: [r, g, b, a] per color (uint8) */
+    COLORS_RGBA: 4,
+};
+/**
+ * Creates a Float32Array view over a Uint8Array without copying data.
+ * Falls back to a copy if the buffer is not 4-byte aligned (rare with protobuf).
+ *
+ * @param bytes - The raw bytes from a protobuf bytes field
+ * @returns A Float32Array view or copy of the data
+ *
+ * @example
+ * ```ts
+ * const positions = asFloat32Array(line.positions)
+ * geometry.setAttribute('position', new BufferAttribute(positions, 3))
+ * ```
+ */
+export const asFloat32Array = (bytes) => {
+    if (bytes.length === 0) {
+        return new Float32Array(0);
+    }
+    if (bytes.byteOffset % 4 === 0 && bytes.byteLength % 4 === 0) {
+        return new Float32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength / 4);
+    }
+    const aligned = new Float32Array(bytes.byteLength / 4);
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    for (let i = 0; i < aligned.length; i++) {
+        aligned[i] = view.getFloat32(i * 4, true); // little-endian
+    }
+    return aligned;
+};
+/**
+ * Converts uint8 RGBA colors to normalized float32 colors (0-1 range).
+ * Three.js expects colors in 0-1 range for BufferAttributes.
+ *
+ * @param colors - Uint8Array of RGBA color data [r, g, b, a, ...]
+ * @returns Float32Array with normalized color values
+ *
+ * @example
+ * ```ts
+ * const colors = normalizeColorsRGBA(metadata.colors)
+ * geometry.setAttribute('color', new BufferAttribute(colors, 4))
+ * ```
+ */
+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;
+};

package/dist/color.d.ts

@@ -34,3 +34,5 @@ export declare const parseColor: (color: unknown, defaultColor?: ColorRepresenta
 export declare const isRGB: (color: unknown) => color is RGB;
 export declare const parseRGB: (color: unknown, defaultColor?: RGB) => Color;
 export declare const parseOpacity: (opacity: unknown, defaultOpacity?: number) => number;
+export declare const rgbaToHex: (rgba: Uint8Array) => string;
+export declare const rgbaBytesToFloat32: (bytes: Uint8Array<ArrayBuffer>) => Float32Array<ArrayBuffer>;

package/dist/color.js

@@ -40,6 +40,8 @@ const oklchToHex = (raw) => {
     const b = Math.max(0, Math.min(1, linearToSrgb(b_linear)));
     return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
 };
+const original = new Color();
+const hsl = { h: 0, s: 0, l: 0 };
 /**
  * Darkens a THREE.Color by a given percentage while preserving hue.
  * @param color The original THREE.Color instance.
@@ -47,17 +49,17 @@ const oklchToHex = (raw) => {
  * @returns A new THREE.Color instance with the darkened color.
  */
 export const darkenColor = (value, percent) => {
-    const original = new Color(value);
-    const hsl = original.getHSL({ h: 0, s: 0, l: 0 });
+    original.set(value);
+    original.getHSL(hsl);
     hsl.l = Math.max(0, hsl.l * (1 - percent / 100));
     return new Color().setHSL(hsl.h, hsl.s, hsl.l);
 };
-const darkness = '600';
 export const resourceNameToColor = (resourceName) => {
     return resourceName
         ? new Color(resourceColors[resourceName.subtype])
         : undefined;
 };
+const darkness = '600';
 export const colors = {
     default: oklchToHex(twColors.red[darkness]),
 };
@@ -139,3 +141,18 @@ const isColorHex = (color) => {
     }
     return false;
 };
+export const rgbaToHex = (rgba) => {
+    if (rgba.length < 3)
+        return '#333333';
+    const r = rgba[0].toString(16).padStart(2, '0');
+    const g = rgba[1].toString(16).padStart(2, '0');
+    const b = rgba[2].toString(16).padStart(2, '0');
+    return `#${r}${g}${b}`;
+};
+export const rgbaBytesToFloat32 = (bytes) => {
+    const out = new Float32Array(bytes.length);
+    for (let i = 0; i < bytes.length; i++) {
+        out[i] = bytes[i] / 255;
+    }
+    return out;
+};

package/dist/components/BatchedArrows.svelte

@@ -28,7 +28,7 @@
 
 		const instanceID = batched.addArrow(
 			direction.set(pose?.oX ?? 0, pose?.oY ?? 0, pose?.oZ ?? 0),
-			origin.set(pose?.x ?? 0, pose?.y ?? 0, pose?.z ?? 0),
+			origin.set(pose?.x ?? 0, pose?.y ?? 0, pose?.z ?? 0).multiplyScalar(0.001),
 			colorRGB ? color.set(colorRGB.r, colorRGB.g, colorRGB.b) : color.set('yellow')
 		)
 
@@ -47,7 +47,7 @@
 			batch?.updateArrow(
 				instanceID,
 				direction.set(pose.oX, pose.oY, pose.oZ),
-				origin.set(pose.x, pose.y, pose.z)
+				origin.set(pose.x, pose.y, pose.z).multiplyScalar(0.001)
 			)
 		}
 	}

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

@@ -0,0 +1,26 @@
+export default BatchedGeometry;
+type BatchedGeometry = SvelteComponent<{
+    [x: string]: never;
+}, {
+    [evt: string]: CustomEvent<any>;
+}, {}> & {
+    $$bindings?: string | undefined;
+};
+declare const BatchedGeometry: $$__sveltets_2_IsomorphicComponent<{
+    [x: string]: never;
+}, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import("svelte").ComponentConstructorOptions<Props>): import("svelte").SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}

package/dist/components/Entities.svelte

@@ -1,70 +1,85 @@
 <script lang="ts">
 	import Pose from './Pose.svelte'
 	import Frame from './Frame.svelte'
-	import Line from './Line.svelte'
-	import Pointcloud from './Pointcloud.svelte'
 	import GLTF from './GLTF.svelte'
 	import Label from './Label.svelte'
+	import Line from './Line.svelte'
+	import Points from './Points.svelte'
 	import { traits, useQuery } from '../ecs'
-	import { Or } from 'koota'
+	import { Not, Or } from 'koota'
 
-	const frames = useQuery(traits.FramesAPI)
-	const geometries = useQuery(traits.GeometriesAPI)
-	const points = useQuery(traits.PointsGeometry)
-	const lines = useQuery(traits.LineGeometry)
-	const gltfs = useQuery(traits.GLTF)
-	const droppedMeshes = useQuery(traits.DroppedFile, traits.BufferGeometry)
-	const drawnMeshes = useQuery(
-		traits.DrawAPI,
+	/**
+	 * Frames from a live machine are bucketed into their own query
+	 * due to needing to call `getPose` on each one
+	 */
+	const machineFramesEntities = useQuery(traits.FramesAPI)
+
+	/**
+	 * Geometries from a live machine are bucketed into their own query
+	 * to avoid thrashing other query results due to them being
+	 * potentially being polled at 30/60fps.
+	 */
+	const resourceGeometriesEntities = useQuery(traits.GeometriesAPI)
+
+	/**
+	 * Geometries from the world state API are bucketed into their own query
+	 * to avoid thrashing other query results due to them being potentially polled at 60fps.
+	 */
+	const worldStateEntities = useQuery(
+		traits.WorldStateStoreAPI,
 		Or(traits.Box, traits.Capsule, traits.Sphere, traits.BufferGeometry, traits.ReferenceFrame)
 	)
-	const worldStateMeshes = useQuery(
-		traits.WorldStateStoreAPI,
+
+	/**
+	 * All remaining meshes can be bucketed into a query due to lower frequency updates.
+	 */
+	const meshEntities = useQuery(
+		Not(traits.FramesAPI),
+		Not(traits.GeometriesAPI),
+		Not(traits.WorldStateStoreAPI),
 		Or(traits.Box, traits.Capsule, traits.Sphere, traits.BufferGeometry, traits.ReferenceFrame)
 	)
+
+	const points = useQuery(traits.PointsPositions)
+	const lines = useQuery(traits.LinePositions)
+	const gltfs = useQuery(traits.GLTF)
 </script>
 
-{#each drawnMeshes.current as entity (entity)}
+{#each machineFramesEntities.current as entity (entity)}
+	<Pose {entity}>
+		{#snippet children({ pose })}
+			<Frame
+				{pose}
+				{entity}
+			>
+				<Label text={entity.get(traits.Name)} />
+			</Frame>
+		{/snippet}
+	</Pose>
+{/each}
+
+{#each resourceGeometriesEntities.current as entity (entity)}
 	<Frame {entity}>
 		<Label text={entity.get(traits.Name)} />
 	</Frame>
 {/each}
 
-{#each worldStateMeshes.current as entity (entity)}
+{#each worldStateEntities.current as entity (entity)}
 	<Frame {entity}>
 		<Label text={entity.get(traits.Name)} />
 	</Frame>
 {/each}
 
-{#each droppedMeshes.current as entity (entity)}
+{#each meshEntities.current as entity (entity)}
 	<Frame {entity}>
 		<Label text={entity.get(traits.Name)} />
 	</Frame>
 {/each}
 
 {#each points.current as entity (entity)}
-	<Pointcloud {entity}>
+	<Points {entity}>
 		<Label text={entity.get(traits.Name)} />
-	</Pointcloud>
-{/each}
-
-{#each frames.current as entity (entity)}
-	<Pose {entity}>
-		{#snippet children({ pose })}
-			<Frame
-				{pose}
-				{entity}
-			>
-				<Label text={entity.get(traits.Name)} />
-			</Frame>
-		{/snippet}
-	</Pose>
-{/each}
-
-{#each geometries.current as entity (entity)}
-	<Frame {entity}>
-		<Label text={entity.get(traits.Name)} />
-	</Frame>
+	</Points>
 {/each}
 
 {#each lines.current as entity (entity)}

package/dist/components/FileDrop/FileDrop.svelte

@@ -5,59 +5,39 @@
 	import { useWorld } from '../../ecs/useWorld'
 	import type { FileDropperSuccess } from './file-dropper'
 	import { traits } from '../../ecs'
-	import { parseMetadata } from '../../WorldObject.svelte'
-	import type { Snapshot } from '../../draw/v1/snapshot_pb'
+	import { spawnSnapshotEntities } from '../../snapshot'
+	import { useCameraControls } from '../../hooks/useControls.svelte'
 
 	const props: HTMLAttributes<HTMLDivElement> = $props()
 
 	const world = useWorld()
 	const toast = useToast()
-
-	const addSnapshotToWorld = (snapshot: Snapshot) => {
-		for (const transform of snapshot.transforms) {
-			const entity = world.spawn(
-				traits.Name(transform.referenceFrame),
-				traits.Pose(transform.poseInObserverFrame?.pose),
-				traits.Parent(transform.poseInObserverFrame?.referenceFrame)
-			)
-
-			if (transform.physicalObject) {
-				entity.add(traits.Geometry(transform.physicalObject))
-			}
-
-			if (transform.metadata) {
-				const metadata = parseMetadata(transform.metadata.fields)
-				if (metadata.color) {
-					entity.add(traits.Color(metadata.color))
-				}
-			}
-		}
-
-		for (const drawing of snapshot.drawings) {
-			world.spawn(
-				traits.Name(drawing.referenceFrame),
-				traits.Pose(drawing.poseInObserverFrame?.pose),
-				traits.Parent(drawing.poseInObserverFrame?.referenceFrame)
-				// TODO: Add shape
-			)
-
-			if (drawing.metadata) {
-				// add shape colors
-			}
-		}
-	}
+	const cameraControls = useCameraControls()
 
 	const fileDrop = useFileDrop(
 		(result: FileDropperSuccess) => {
 			switch (result.type) {
 				case 'snapshot': {
-					addSnapshotToWorld(result.snapshot)
+					spawnSnapshotEntities(world, result.snapshot)
+
+					const { sceneCamera } = result.snapshot.sceneMetadata ?? {}
+
+					if (sceneCamera) {
+						const { x = 0, y = 0, z = 0 } = sceneCamera.position ?? {}
+						const { x: lx = 0, y: ly = 0, z: lz = 0 } = sceneCamera.lookAt ?? {}
+
+						cameraControls.setPose({
+							position: [x * 0.001, y * 0.001, z * 0.001],
+							lookAt: [lx * 0.001, ly * 0.001, lz * 0.001],
+						})
+					}
+
 					break
 				}
 				case 'pcd':
 					world.spawn(
 						traits.Name(result.name),
-						traits.PointsGeometry(result.pcd.positions),
+						traits.PointsPositions(result.pcd.positions),
 						result.pcd.colors ? traits.VertexColors(result.pcd.colors) : traits.Color,
 						traits.DroppedFile
 					)

package/dist/components/Frame.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte'
 	import { useObjectEvents } from '../hooks/useObjectEvents.svelte'
-	import { Color, type Object3D } from 'three'
+	import { Color, Group, type Object3D } from 'three'
 	import Geometry from './Geometry2.svelte'
 	import { useWeblabs } from '../hooks/useWeblabs.svelte'
 	import { useSelectedEntity } from '../hooks/useSelection.svelte'
@@ -13,6 +13,7 @@
 	import { traits, useTrait } from '../ecs'
 	import type { Pose } from '@viamrobotics/sdk'
 	import { useResourceByName } from '../hooks/useResourceByName.svelte'
+	import { Portal, PortalTarget } from '@threlte/extras'
 
 	interface Props {
 		entity: Entity
@@ -22,14 +23,20 @@
 
 	let { entity, pose, children }: Props = $props()
 
+	let ref = $state<Group>()
+
 	const colorUtil = new Color()
+
 	const settings = useSettings()
 	const componentModels = use3DModels()
 	const selectedEntity = useSelectedEntity()
 	const resourceByName = useResourceByName()
 	const weblabs = useWeblabs()
+
 	const name = useTrait(() => entity, traits.Name)
+	const parent = useTrait(() => entity, traits.Parent)
 	const entityColor = useTrait(() => entity, traits.Color)
+
 	const events = useObjectEvents(() => entity)
 	const resourceColor = $derived.by(() => {
 		if (!name.current) {
@@ -66,14 +73,24 @@
 	})
 </script>
 
-<Geometry
-	{entity}
-	{model}
-	{pose}
-	{children}
-	renderMode={settings.current.renderArmModels}
-	color={selectedEntity.current === entity
-		? `#${darkenColor(color, 75).getHexString()}`
-		: `#${colorUtil.set(color).getHexString()}`}
-	{...events}
-/>
+<Portal id={parent.current}>
+	<Geometry
+		bind:ref
+		{entity}
+		{model}
+		{pose}
+		renderMode={settings.current.renderArmModels}
+		color={selectedEntity.current === entity
+			? `#${darkenColor(color, 75).getHexString()}`
+			: `#${colorUtil.set(color).getHexString()}`}
+		{...events}
+	>
+		{#if name.current}
+			<PortalTarget id={name.current} />
+		{/if}
+
+		{#if ref}
+			{@render children?.({ ref })}
+		{/if}
+	</Geometry>
+</Portal>

package/dist/components/GLTF.svelte

@@ -1,11 +1,25 @@
+<script
+	module
+	lang="ts"
+>
+	import { GLTFLoader, DRACOLoader } from 'three/examples/jsm/Addons.js'
+
+	const dracoLoader = new DRACOLoader()
+	const gltfLoader = new GLTFLoader()
+
+	dracoLoader.setDecoderPath('https://www.gstatic.com/draco/versioned/decoders/1.5.6/')
+	gltfLoader.setDRACOLoader(dracoLoader)
+</script>
+
 <script lang="ts">
 	import { T, type Props as ThrelteProps } from '@threlte/core'
-	import { Portal, PortalTarget } from '@threlte/extras'
+	import { Portal, PortalTarget, useGltfAnimations, type ThrelteGltf } from '@threlte/extras'
 	import type { Snippet } from 'svelte'
-	import type { Object3D } from 'three'
+	import { Group, type Object3D } from 'three'
 	import { useObjectEvents } from '../hooks/useObjectEvents.svelte'
 	import type { Entity } from 'koota'
 	import { traits, useTrait } from '../ecs'
+	import { poseToObject3d } from '../transform'
 
 	interface Props extends ThrelteProps<Object3D> {
 		entity: Entity
@@ -14,23 +28,70 @@
 
 	let { entity, children, ...rest }: Props = $props()
 
+	const { gltf, actions } = useGltfAnimations()
+
 	const name = useTrait(() => entity, traits.Name)
 	const parent = useTrait(() => entity, traits.Parent)
-	const gltf = useTrait(() => entity, traits.GLTF)
+	const pose = useTrait(() => entity, traits.Pose)
+	const gltfTrait = useTrait(() => entity, traits.GLTF)
+	const scale = useTrait(() => entity, traits.Scale)
 	const objectProps = useObjectEvents(() => entity)
+
+	const animationName = $derived(gltfTrait.current?.animationName)
+
+	const group = new Group()
+
+	$effect.pre(() => {
+		if (pose.current) {
+			poseToObject3d(pose.current, group)
+		}
+	})
+
+	$effect.pre(() => {
+		if (!gltfTrait.current) {
+			return
+		}
+
+		const { source } = gltfTrait.current
+
+		const load = async () => {
+			if ('url' in source) {
+				$gltf = (await gltfLoader.loadAsync(source.url)) as ThrelteGltf
+			} else if ('glb' in source) {
+				const buffer = source.glb.buffer.slice(
+					source.glb.byteOffset,
+					source.glb.byteOffset + source.glb.byteLength
+				)
+				$gltf = (await gltfLoader.parseAsync(buffer, '')) as ThrelteGltf
+			} else if ('gltf' in source) {
+				$gltf = source.gltf as ThrelteGltf
+			}
+		}
+
+		load()
+	})
+
+	$effect.pre(() => {
+		if (animationName) {
+			$actions[animationName]?.play()
+		}
+	})
 </script>
 
 <Portal id={parent.current}>
-	{#if gltf.current?.scene}
-		<T
-			is={gltf.current.scene as Object3D}
-			name={name.current}
-			{...objectProps}
-			{...rest}
-		>
-			{@render children?.()}
-
-			<PortalTarget id={name.current} />
-		</T>
-	{/if}
+	<T is={group}>
+		{#if $gltf}
+			<T
+				is={$gltf.scene as Object3D}
+				scale={[scale.current?.x ?? 1, scale.current?.y ?? 1, scale.current?.z ?? 1]}
+				name={name.current}
+				{...objectProps}
+				{...rest}
+			>
+				{@render children?.()}
+
+				<PortalTarget id={name.current} />
+			</T>
+		{/if}
+	</T>
 </Portal>

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

@@ -1,6 +1,6 @@
 import { type Props as ThrelteProps } from '@threlte/core';
 import type { Snippet } from 'svelte';
-import type { Object3D } from 'three';
+import { type Object3D } from 'three';
 import type { Entity } from 'koota';
 interface Props extends ThrelteProps<Object3D> {
     entity: Entity;