@viamrobotics/motion-tools 1.13.1 → 1.14.0

package/dist/attribute.js

@@ -1,9 +1,16 @@
 import { BufferGeometry, BufferAttribute } from 'three';
+import { STRIDE } from './buffer';
+const colorStride = (colors, positions) => {
+    const numVertices = positions.length / STRIDE.POSITIONS;
+    const stride = colors.length / numVertices;
+    return stride === STRIDE.COLORS_RGBA ? STRIDE.COLORS_RGBA : STRIDE.COLORS_RGB;
+};
 export const createBufferGeometry = (positions, colors) => {
     const geometry = new BufferGeometry();
     geometry.setAttribute('position', new BufferAttribute(positions, 3));
     if (colors) {
-        geometry.setAttribute('color', new BufferAttribute(colors, 3, true));
+        const stride = colorStride(colors, positions);
+        geometry.setAttribute('color', new BufferAttribute(colors, stride, true));
     }
     return geometry;
 };
@@ -24,7 +31,8 @@ export const updateBufferGeometry = (geometry, positions, colors) => {
             colorAttr.needsUpdate = true;
         }
         else {
-            geometry.setAttribute('color', new BufferAttribute(colors, 3, true));
+            const stride = colorStride(colors, positions);
+            geometry.setAttribute('color', new BufferAttribute(colors, stride, true));
         }
     }
 };

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/components/Entities/Entities.svelte

@@ -6,9 +6,9 @@
 	import Line from './Line.svelte'
 	import Points from './Points.svelte'
 	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
@@ -62,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)}

package/dist/components/Entities/Frame.svelte

@@ -1,17 +1,27 @@
+<!--
+@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 { Color, Group, type Object3D } from 'three'
-	import Geometry from './Geometry.svelte'
-	import { useSelectedEntity } from '../../hooks/useSelection.svelte'
-	import { useSettings } from '../../hooks/useSettings.svelte'
-	import { use3DModels } from '../../hooks/use3DModels.svelte'
-	import { colors, darkenColor, resourceColors } from '../../color'
+	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 { Portal, PortalTarget } from '@threlte/extras'
+	import { poseToObject3d } from '../../transform'
 
 	interface Props {
 		entity: Entity
@@ -21,69 +31,56 @@
 
 	let { entity, pose, children }: Props = $props()
 
-	let ref = $state<Group>()
-
-	const colorUtil = new Color()
-
-	const settings = useSettings()
-	const componentModels = use3DModels()
-	const selectedEntity = useSelectedEntity()
+	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 resourceColor = $derived.by(() => {
-		if (!name.current) {
-			return undefined
-		}
-		const subtype = resourceByName.current[name.current]?.subtype
-		return resourceColors[subtype as keyof typeof resourceColors]
-	})
 
 	const color = $derived.by(() => {
 		if (entityColor.current) {
-			return colorUtil.set(entityColor.current.r, entityColor.current.g, entityColor.current.b)
+			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 model = $derived.by(() => {
-		if (!name.current) {
-			return
-		}
+	const group = new Group()
 
-		const [componentName, id] = name.current.split(':')
-		if (!componentName || !id) {
-			return
+	const resolvedPose = $derived(pose ?? entityPose.current)
+	$effect.pre(() => {
+		if (resolvedPose) {
+			poseToObject3d(resolvedPose, group)
+			invalidate()
 		}
-		return componentModels.current?.[componentName]?.[id].clone()
 	})
 </script>
 
 <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}
-	>
+	<T is={group}>
+		<Mesh
+			{entity}
+			{color}
+			{...events}
+			center={center.current}
+		/>
+
 		{#if name.current}
 			<PortalTarget id={name.current} />
 		{/if}
 
-		{#if ref}
-			{@render children?.({ ref })}
-		{/if}
-	</Geometry>
+		{@render children?.({ ref: group })}
+	</T>
 </Portal>

package/dist/components/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/Entities/Geometry.svelte

@@ -1,206 +1,75 @@
+<!--
+@component
+
+Renders a Viam Geometry object
+-->
 <script lang="ts">
-	import { T, useThrelte, type Props as ThrelteProps } from '@threlte/core'
-	import { type Snippet } from 'svelte'
-	import { meshBounds } from '@threlte/extras'
-	import { BufferGeometry, Color, DoubleSide, FrontSide, Group, Mesh } from 'three'
-	import { Line2, LineMaterial } from 'three/examples/jsm/Addons.js'
-	import { CapsuleGeometry } from '../../three/CapsuleGeometry'
-	import { colors, darkenColor } from '../../color'
-	import AxesHelper from '../AxesHelper.svelte'
-	import type { Entity } from 'koota'
+	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 type { Pose } from '@viamrobotics/sdk'
-	import LineGeometry from './LineGeometry.svelte'
+	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 extends ThrelteProps<Group> {
+	interface Props {
 		entity: Entity
-		color?: string
-		model?: Group
-		pose?: Pose
-		renderMode?: 'model' | 'colliders' | 'colliders+model'
-		ref?: Group
-		children?: Snippet<[{ ref: Group }]>
+		children?: Snippet
 	}
 
-	let {
-		entity,
-		color: overrideColor,
-		model,
-		renderMode = 'colliders',
-		pose,
-		ref = $bindable(),
-		children,
-		...rest
-	}: Props = $props()
+	const { entity, children }: Props = $props()
 
-	const colorUtil = new Color()
+	const settings = useSettings()
 
 	const { invalidate } = useThrelte()
+	const models = use3DModels()
+
 	const name = useTrait(() => entity, traits.Name)
-	const entityColor = useTrait(() => entity, traits.Color)
-	const opacity = useTrait(() => entity, traits.Opacity)
-	const box = useTrait(() => entity, traits.Box)
-	const capsule = useTrait(() => entity, traits.Capsule)
-	const sphere = useTrait(() => entity, traits.Sphere)
-	const bufferGeometry = useTrait(() => entity, traits.BufferGeometry)
-	const linePositions = useTrait(() => entity, traits.LinePositions)
-	const lineWidth = useTrait(() => entity, traits.LineWidth)
+	const parent = useTrait(() => entity, traits.Parent)
 	const center = useTrait(() => entity, traits.Center)
-	const showAxesHelper = useTrait(() => entity, traits.ShowAxesHelper)
-	const materialProps = useTrait(() => entity, traits.Material)
-	const renderOrder = useTrait(() => entity, traits.RenderOrder)
 
-	const geometryType = $derived.by(() => {
-		if (box.current) return 'box'
-		if (capsule.current) return 'capsule'
-		if (sphere.current) return 'sphere'
-		if (bufferGeometry.current) return 'buffer'
-		if (linePositions.current) return 'line'
-	})
-
-	const color = $derived.by(() => {
-		if (overrideColor) {
-			return overrideColor
-		}
-		if (entityColor.current) {
-			return colorUtil
-				.setRGB(entityColor.current.r, entityColor.current.g, entityColor.current.b)
-				.getHexString()
+	const model = $derived.by(() => {
+		if (!settings.current.renderArmModels.includes('model')) {
+			return
 		}
-		return colors.default
-	})
 
-	const group = new Group()
-	ref = group
-
-	const mesh = $derived.by(() => {
-		if (geometryType === undefined) {
+		if (!name.current) {
 			return
 		}
 
-		const result = geometryType === 'line' ? new Line2() : new Mesh()
-
-		if (geometryType === 'line') {
-			result.raycast = meshBounds
+		const [componentName, id] = name.current.split(':')
+		if (!componentName || !id) {
+			return
 		}
 
-		return result
-	})
-
-	$effect.pre(() => {
-		if (mesh && center.current) {
-			poseToObject3d(center.current, mesh)
-			invalidate()
-		}
+		return models.current[componentName]?.[id].clone()
 	})
 
-	const entityPose = useTrait(() => entity, traits.Pose)
-	const resolvedPose = $derived(pose ?? entityPose.current)
 	$effect.pre(() => {
-		if (resolvedPose) {
-			poseToObject3d(resolvedPose, group)
+		if (model && center.current) {
+			poseToObject3d(center.current, model)
 			invalidate()
 		}
 	})
 
-	let geo = $state.raw<BufferGeometry>()
-
-	const oncreate = (bufferGeometry: BufferGeometry) => {
-		geo = bufferGeometry
-	}
-
-	$effect.pre(() => {
-		if (mesh && bufferGeometry.current) {
-			mesh.geometry = bufferGeometry.current
-			oncreate(bufferGeometry.current)
-
-			return () => {
-				geo = undefined
-				mesh?.geometry?.dispose()
-			}
-		}
-	})
+	const events = useEntityEvents(() => entity)
 </script>
 
-<T
-	is={group}
-	{...rest}
->
-	{#if geometryType}
-		{#if model && renderMode.includes('model')}
-			<T is={model} />
-		{/if}
-
-		{#if !model || renderMode.includes('colliders')}
-			<T
-				is={mesh}
-				name={entity}
-				userData.name={name}
-				renderOrder={renderOrder.current}
-			>
-				{#if linePositions.current}
-					<LineGeometry positions={linePositions.current} />
-				{:else if box.current}
-					{@const { x, y, z } = box.current ?? { x: 0, y: 0, z: 0 }}
-					<T.BoxGeometry
-						args={[x * 0.001, y * 0.001, z * 0.001]}
-						{oncreate}
-					/>
-				{:else if sphere.current}
-					{@const { r } = sphere.current ?? { r: 0 }}
-					<T.SphereGeometry
-						args={[r * 0.001]}
-						{oncreate}
-					/>
-				{:else if capsule.current}
-					{@const { r, l } = capsule.current ?? { r: 0, l: 0 }}
-					<T
-						is={CapsuleGeometry}
-						args={[r * 0.001, l * 0.001]}
-						{oncreate}
-					/>
-				{/if}
-
-				{#if linePositions.current}
-					<T
-						is={LineMaterial}
-						{color}
-						width={lineWidth.current ? lineWidth.current * 0.001 : 0.5}
-						depthTest={materialProps.current?.depthTest ?? true}
-					/>
-				{:else}
-					{@const currentOpacity = opacity.current ?? 0.7}
-					<T.MeshToonMaterial
-						{color}
-						side={geometryType === 'buffer' ? DoubleSide : FrontSide}
-						transparent={currentOpacity < 1}
-						depthWrite={currentOpacity === 1}
-						opacity={currentOpacity}
-						depthTest={materialProps.current?.depthTest ?? true}
-					/>
-
-					{#if geo && (renderMode.includes('colliders') || !model)}
-						<T.LineSegments
-							raycast={() => null}
-							bvh={{ enabled: false }}
-						>
-							<T.EdgesGeometry args={[geo, 0]} />
-							<T.LineBasicMaterial color={darkenColor(color, 10)} />
-						</T.LineSegments>
-					{/if}
-				{/if}
-			</T>
-		{/if}
+<Portal id={parent.current}>
+	{#if model}
+		<T is={model} />
 	{/if}
 
-	{#if showAxesHelper.current}
-		<AxesHelper
-			name={entity}
-			width={3}
-			length={0.1}
-		/>
+	{#if settings.current.renderArmModels.includes('colliders') || !model}
+		<Mesh
+			{entity}
+			center={center.current}
+			{...events}
+		>
+			{@render children?.()}
+		</Mesh>
 	{/if}
-
-	{@render children?.({ ref: group })}
-</T>
+</Portal>

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

@@ -1,19 +1,10 @@
-import { type Props as ThrelteProps } from '@threlte/core';
-import { type Snippet } from 'svelte';
-import { Group } from 'three';
 import type { Entity } from 'koota';
-import type { Pose } from '@viamrobotics/sdk';
-interface Props extends ThrelteProps<Group> {
+import type { Snippet } from 'svelte';
+interface Props {
     entity: Entity;
-    color?: string;
-    model?: Group;
-    pose?: Pose;
-    renderMode?: 'model' | 'colliders' | 'colliders+model';
-    ref?: Group;
-    children?: Snippet<[{
-        ref: Group;
-    }]>;
+    children?: Snippet;
 }
-declare const Geometry: import("svelte").Component<Props, {}, "ref">;
+/** Renders a Viam Geometry object */
+declare const Geometry: import("svelte").Component<Props, {}, "">;
 type Geometry = ReturnType<typeof Geometry>;
 export default Geometry;