@viamrobotics/motion-tools 1.33.0 → 1.33.2

package/dist/components/Entities/labelLayout/spatialHash.js

@@ -0,0 +1,53 @@
+/**
+ * Uniform grid over label anchors, used to prune the O(n^2) cost evaluation to a
+ * bounded neighborhood. The cell size is chosen so any two labels whose boxes
+ * could possibly interact share or border a cell, so scanning the 3x3 block
+ * around a node finds every candidate.
+ */
+const KEY_OFFSET = 2048;
+const KEY_STRIDE = 4096;
+export class SpatialHash {
+    cell = 1;
+    buckets = new Map();
+    static key(gx, gy) {
+        return (gx + KEY_OFFSET) * KEY_STRIDE + (gy + KEY_OFFSET);
+    }
+    build(nodes, cell) {
+        this.cell = Math.max(cell, 1);
+        this.buckets.clear();
+        for (const node of nodes) {
+            const k = SpatialHash.key(Math.floor(node.ax / this.cell), Math.floor(node.ay / this.cell));
+            const bucket = this.buckets.get(k);
+            if (bucket)
+                bucket.push(node);
+            else
+                this.buckets.set(k, [node]);
+        }
+    }
+    /** Nearest `max` nodes (by anchor distance) in the 3x3 cell block around `node`, excluding itself. */
+    queryNeighbors(node, max) {
+        const gx = Math.floor(node.ax / this.cell);
+        const gy = Math.floor(node.ay / this.cell);
+        const found = [];
+        for (let ox = -1; ox <= 1; ox++) {
+            for (let oy = -1; oy <= 1; oy++) {
+                const bucket = this.buckets.get(SpatialHash.key(gx + ox, gy + oy));
+                if (!bucket)
+                    continue;
+                for (const other of bucket) {
+                    if (other !== node)
+                        found.push(other);
+                }
+            }
+        }
+        if (found.length <= max)
+            return found;
+        found.sort((a, b) => {
+            const da = (a.ax - node.ax) ** 2 + (a.ay - node.ay) ** 2;
+            const db = (b.ax - node.ax) ** 2 + (b.ay - node.ay) ** 2;
+            return da - db;
+        });
+        found.length = max;
+        return found;
+    }
+}

package/dist/components/Entities/labelLayout/types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Shared types for the label layout engine.
+ *
+ * All spatial fields are in viewport pixels (one shared screen-space for every
+ * label) except where noted. Slots store dot-relative offsets so a camera pan
+ * never invalidates them.
+ */
+/** Axis-aligned rectangle as center + half-extents (viewport px). */
+export interface Rect {
+    cx: number;
+    cy: number;
+    hw: number;
+    hh: number;
+}
+/** Line segment (viewport px). */
+export interface Segment {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+/** A candidate placement for a label box, expressed as the box-center offset from the dot. */
+export interface Slot {
+    /** Box-center offset from the dot, viewport px. */
+    dx: number;
+    dy: number;
+    /** Direction of the slot from the dot, radians. */
+    angle: number;
+    /** Distance from the dot to the box center, viewport px. */
+    radius: number;
+    /** Ring index (0 = innermost). */
+    ring: number;
+    /** Length-only cost (`W.len * radius`); slots are sorted ascending by this for early-out. */
+    baseCost: number;
+}
+export interface LabelNode {
+    /** Stable per-element id, assigned once. */
+    id: string;
+    /** FNV hash of `id`, used for deterministic tie-breaks and per-node slot phase. */
+    idHash: number;
+    ax: number;
+    ay: number;
+    dotR: number;
+    w: number;
+    h: number;
+    /** Per-island CSS scale (screenPx / localPx). */
+    scale: number;
+    /** Cached computed CSS width of the dot (local px); read once. */
+    cssDotW: number;
+    /** Dot center relative to the island origin, island-local px. Fixed CSS offset, measured once (NaN until then). */
+    dotLocalX: number;
+    dotLocalY: number;
+    slots: Slot[];
+    /** Hash of the box/dot geometry; slots regenerate only when this or `crowded` changes. */
+    geomKey: string;
+    crowded: boolean;
+    /** Committed slot (target). -1 before first placement. */
+    slotIndex: number;
+    /** Slot committed by the previous solve, for stickiness. */
+    prevSlotIndex: number;
+    cx: number;
+    cy: number;
+    tx: number;
+    ty: number;
+    settled: boolean;
+    /** Conflict cost of the current slot — the local-search loop key. */
+    conflict: number;
+    /** Locked at a local optimum for the current solve. */
+    locked: boolean;
+    /** Local cluster centroid (self + neighbors) for the outward-fan term. */
+    centroidX: number;
+    centroidY: number;
+    /** Anchor at the previous solve, for teleport detection. NaN before first solve. */
+    prevAx: number;
+    prevAy: number;
+    /** Pruned interaction set for the current solve (symmetric). */
+    neighbors: LabelNode[];
+    labelEl: HTMLElement;
+    textEl: HTMLElement;
+    dotEl: HTMLElement;
+    lineEl: SVGLineElement;
+}
+export interface SolverConfig {
+    /** Label-label clearance (viewport px). */
+    labelPadding: number;
+    /** Dot clearance (viewport px). */
+    dotPadding: number;
+    /** Candidate angles per ring (doubled for crowded nodes). */
+    anglesPerRing: number;
+    /** Ring radius multipliers for sparse nodes. */
+    ringRadii: number[];
+    /** Ring radius multipliers for crowded nodes (more escape room). */
+    ringRadiiCrowded: number[];
+    /** Max accepted local-search moves per solve. */
+    polishBudget: number;
+    /** Max neighbors considered per node (caps cost in dense clusters). */
+    maxNeighbors: number;
+    /** Distance (viewport px) under which a box is considered arrived. */
+    settleEps: number;
+    /** Neighbor count above which a node is "crowded". */
+    crowdedThreshold: number;
+    /** Fraction of the viewport diagonal that counts as a camera teleport. */
+    teleportFrac: number;
+}
+export declare const defaultSolverConfig: SolverConfig;

package/dist/components/Entities/labelLayout/types.js

@@ -0,0 +1,19 @@
+/**
+ * Shared types for the label layout engine.
+ *
+ * All spatial fields are in viewport pixels (one shared screen-space for every
+ * label) except where noted. Slots store dot-relative offsets so a camera pan
+ * never invalidates them.
+ */
+export const defaultSolverConfig = {
+    labelPadding: 6,
+    dotPadding: 6,
+    anglesPerRing: 12,
+    ringRadii: [1, 1.55, 2.2],
+    ringRadiiCrowded: [1, 1.45, 1.95, 2.6],
+    polishBudget: 240,
+    maxNeighbors: 24,
+    settleEps: 0.4,
+    crowdedThreshold: 8,
+    teleportFrac: 0.5,
+};

package/dist/components/Entities/labelLayout/writeBack.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Per-frame animation and DOM write-back. The solver produces a target box
+ * center; the animated center eases toward it (framerate-independent), and the
+ * eased position is written to the label as a scale-corrected local transform
+ * plus leader-line endpoints — the same coordinate handling the old engine used.
+ */
+import type { LabelNode } from './types';
+/**
+ * Ease `node`'s animated center toward its target. Returns true while still
+ * moving, false once arrived (and snapped). `delta` is seconds, pre-clamped by
+ * the engine so a long idle gap can't produce an overshoot.
+ */
+export declare function lerpStep(node: LabelNode, delta: number, settleEps: number): boolean;
+/**
+ * Write the eased position to the DOM. The label island is positioned at the dot
+ * by Threlte's <HTML>, so we work in island-local px: convert the viewport-space
+ * offset by the island's CSS scale, place the text box, and draw the leader from
+ * the dot's island-local position to the box center.
+ */
+export declare const writeBack: (node: LabelNode) => void;

package/dist/components/Entities/labelLayout/writeBack.js

@@ -0,0 +1,51 @@
+/**
+ * Per-frame animation and DOM write-back. The solver produces a target box
+ * center; the animated center eases toward it (framerate-independent), and the
+ * eased position is written to the label as a scale-corrected local transform
+ * plus leader-line endpoints — the same coordinate handling the old engine used.
+ */
+/** Easing time constant (seconds): ~3-4 frames to arrive at 60fps. */
+const TAU = 0.08;
+/**
+ * Ease `node`'s animated center toward its target. Returns true while still
+ * moving, false once arrived (and snapped). `delta` is seconds, pre-clamped by
+ * the engine so a long idle gap can't produce an overshoot.
+ */
+export function lerpStep(node, delta, settleEps) {
+    const dx = node.tx - node.cx;
+    const dy = node.ty - node.cy;
+    if (dx * dx + dy * dy <= settleEps * settleEps) {
+        node.cx = node.tx;
+        node.cy = node.ty;
+        node.settled = true;
+        return false;
+    }
+    const alpha = 1 - Math.exp(-delta / TAU);
+    node.cx += dx * alpha;
+    node.cy += dy * alpha;
+    node.settled = false;
+    return true;
+}
+/**
+ * Write the eased position to the DOM. The label island is positioned at the dot
+ * by Threlte's <HTML>, so we work in island-local px: convert the viewport-space
+ * offset by the island's CSS scale, place the text box, and draw the leader from
+ * the dot's island-local position to the box center.
+ */
+export const writeBack = (node) => {
+    const inv = 1 / node.scale;
+    // Box-center offset from the dot, in island-local px.
+    const dx = (node.cx - node.ax) * inv;
+    const dy = (node.cy - node.ay) * inv;
+    const wL = node.w * inv;
+    const hL = node.h * inv;
+    // The dot may not sit at the island origin, so anchor everything at the dot's
+    // measured local position rather than assuming (0, 0).
+    const ox = node.dotLocalX;
+    const oy = node.dotLocalY;
+    node.textEl.style.transform = `translate(${ox + dx - wL / 2}px, ${oy + dy - hL / 2}px)`;
+    node.lineEl.setAttribute('x1', `${ox}`);
+    node.lineEl.setAttribute('y1', `${oy}`);
+    node.lineEl.setAttribute('x2', `${ox + dx}`);
+    node.lineEl.setAttribute('y2', `${oy + dy}`);
+};

package/dist/components/Scene.svelte

@@ -49,7 +49,8 @@
 	const bvhEnabled = $derived(
 		settings.current.renderSubEntityHoverDetail ||
 			settings.current.interactionMode === 'measure' ||
-			settings.current.interactionMode === 'select'
+			settings.current.interactionMode === 'select' ||
+			settings.current.interactionMode === 'gizmo'
 	)
 
 	bvh(raycaster, () => ({ helper: false, enabled: bvhEnabled }))

package/dist/components/SelectedTransformControls.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
 	import { useThrelte } from '@threlte/core'
 	import { TransformControls } from '@threlte/extras'
-	import { Matrix4, Quaternion, Vector3 } from 'three'
+	import { Matrix4 } from 'three'
 
 	import type { FrameEditSession } from '../editing/FrameEditSession'
 
@@ -11,14 +11,7 @@
 	import { useFrameEditSession } from '../hooks/useFrameEditSession.svelte'
 	import { usePartConfig } from '../hooks/usePartConfig.svelte'
 	import { useSettings } from '../hooks/useSettings.svelte'
-	import {
-		createPose,
-		matrixToPose,
-		poseToMatrix,
-		quaternionToPose,
-		solveEditedMatrix,
-		vector3ToPose,
-	} from '../transform'
+	import { createPose, matrixToPose, poseToMatrix, solveEditedMatrix } from '../transform'
 
 	const { scene } = useThrelte()
 	const settings = useSettings()
@@ -64,9 +57,10 @@
 	})
 	const isSphereScale = $derived(activeMode === 'scale' && sphere.current !== undefined)
 	const isCapsuleScale = $derived(activeMode === 'scale' && capsule.current !== undefined)
+	const transforming = $derived(
+		ref && entity && activeMode && !isFragmentComponentWithVariables && !invisible.current
+	)
 
-	const quaternion = new Quaternion()
-	const vector3 = new Vector3()
 	const refPose = createPose()
 	const tempRefMatrix = new Matrix4()
 	const tempEditedMatrix = new Matrix4()
@@ -119,28 +113,14 @@
 	}
 
 	const onChange = () => {
-		if (!ref || !entity || !activeMode) {
-			return
-		}
+		if (!ref || !entity || !activeMode) return
 
 		const isFrameEntity = entity.has(traits.FramesAPI)
-
 		if (activeMode === 'translate' || activeMode === 'rotate') {
 			if (isFrameEntity) {
 				stageFrameTransform()
 			} else {
-				const matrix = entity.get(traits.Matrix)
-				if (matrix) {
-					matrixToPose(matrix, tempPose)
-					if (activeMode === 'translate') {
-						vector3ToPose(ref.getWorldPosition(vector3), tempPose)
-					} else {
-						quaternionToPose(ref.getWorldQuaternion(quaternion), tempPose)
-						ref.quaternion.copy(quaternion)
-					}
-					poseToMatrix(tempPose, matrix)
-					entity.changed(traits.Matrix)
-				}
+				stageLocalTransform()
 			}
 		} else {
 			// scale → bake the gizmo's scale factor into the geometry trait,
@@ -194,40 +174,46 @@
 	}
 
 	/**
-	 * Frame.svelte renders frame entities by writing the entity's WorldMatrix
-	 * into group.matrix and decomposing it into position/quaternion. The gizmo's
-	 * Three.js parent has identity world, so `ref.position` / `ref.quaternion`
-	 * are world-space values. Matrix and EditedMatrix store local-to-parent
-	 * transforms, so we left-multiply by the parent's inverted WorldMatrix
-	 * before staging — otherwise WorldMatrix recomposition (parent × edited)
-	 * re-applies the parent's rotation/translation and the frame ends up at
-	 * parent × where-the-user-pulled-it.
+	 * Build the entity's parent-relative drag target from the gizmo's world-space
+	 * `ref` transform into `out`.
 	 *
-	 * With a kinematic offset (LiveMatrix + Matrix both present), the local
-	 * target M(local) feeds solveEditedMatrix to back out the EditedMatrix
-	 * that satisfies live × baseline⁻¹ × edited = local.
+	 * Entity renderers mount at the scene root with `matrixAutoUpdate = false`
+	 * and recompose `group.matrix` from the `WorldMatrix` trait, so
+	 * `ref.position` / `ref.quaternion` are world-space. Matrix-shaped traits
+	 * store local-to-parent, so we left-multiply by the parent's inverted
+	 * WorldMatrix. Otherwise recomposition (parentWorld × local) re-applies the
+	 * parent transform and the entity lands at parentWorld × where-it-was-dragged.
 	 */
-	const stageFrameTransform = () => {
+	const computeLocalDragTarget = (out: Matrix4) => {
 		if (!ref || !entity) return
 
-		tempRefMatrix.makeRotationFromQuaternion(ref.quaternion)
-		tempRefMatrix.setPosition(ref.position)
+		out.makeRotationFromQuaternion(ref.quaternion)
+		out.setPosition(ref.position)
 
-		const parentEntity = entity.targetFor(relations.ChildOf)
-		const parentWorld = parentEntity?.get(traits.WorldMatrix)
+		const parentWorld = entity.targetFor(relations.ChildOf)?.get(traits.WorldMatrix)
 		if (parentWorld) {
 			tempParentInverse.copy(parentWorld).invert()
-			tempRefMatrix.premultiply(tempParentInverse)
+			out.premultiply(tempParentInverse)
 		}
+	}
+
+	/**
+	 * Stages a translate/rotate drag for a frame system entity into the edit
+	 * session. With a kinematic offset (LiveMatrix + Matrix both present), the
+	 * parent-relative target feeds solveEditedMatrix to back out the EditedMatrix
+	 * satisfying live × baseline⁻¹ × edited = local. Without one, Frame.svelte's
+	 * blend short-circuits to EditedMatrix, so we stage the target pose directly.
+	 */
+	const stageFrameTransform = () => {
+		if (!ref || !entity) return
 
+		computeLocalDragTarget(tempRefMatrix)
 		matrixToPose(tempRefMatrix, refPose)
 
 		const live = liveMatrix.current
 		const config = configMatrix.current
 
 		if (!live || !config) {
-			// No live matrix available — Frame.svelte's blend short-circuits to
-			// editedMatrix, so the parent-relative target is what we stage.
 			if (activeMode === 'translate') {
 				session?.stagePose(entity, {
 					x: refPose.x,
@@ -249,9 +235,41 @@
 		matrixToPose(tempEditedMatrix, tempPose)
 		session?.stagePose(entity, { ...tempPose })
 	}
+
+	/**
+	 * Stages a translate/rotate drag for a non-frame-system entity (e.g. a gizmo)
+	 * by writing the dragged component into the Matrix trait. Gizmos carry no
+	 * LiveMatrix, so there's no live-pose blend to invert — the parent-relative
+	 * target is the new local transform.
+	 */
+	const stageLocalTransform = () => {
+		if (!ref || !entity) return
+
+		const matrix = entity.get(traits.Matrix)
+		if (!matrix) return
+
+		computeLocalDragTarget(tempRefMatrix)
+
+		// update only the dragged component
+		matrixToPose(matrix, tempPose)
+		matrixToPose(tempRefMatrix, refPose)
+		if (activeMode === 'translate') {
+			tempPose.x = refPose.x
+			tempPose.y = refPose.y
+			tempPose.z = refPose.z
+		} else {
+			tempPose.oX = refPose.oX
+			tempPose.oY = refPose.oY
+			tempPose.oZ = refPose.oZ
+			tempPose.theta = refPose.theta
+		}
+
+		poseToMatrix(tempPose, matrix)
+		entity.changed(traits.Matrix)
+	}
 </script>
 
-{#if ref && entity && activeMode && !isFragmentComponentWithVariables && !invisible.current}
+{#if transforming}
 	{#key entity}
 		<TransformControls
 			object={ref}