three-usd-robot 0.9.0 → 0.11.0

package/dist/chunk-ENWFOYHU.js

@@ -0,0 +1,701 @@
+import { identity4, multiply, invert, nearestAngleBranch, multiplyAll, decomposeJointRelative, interpolate } from './chunk-LDO5FKQS.js';
+import * as THREE4 from 'three';
+
+function axisVector(axis) {
+  switch (axis) {
+    case "X":
+      return new THREE4.Vector3(1, 0, 0);
+    case "Y":
+      return new THREE4.Vector3(0, 1, 0);
+    case "Z":
+      return new THREE4.Vector3(0, 0, 1);
+  }
+}
+var JointObject = class extends THREE4.Object3D {
+  isJointObject = true;
+  jointName;
+  /** Full USD prim path of the joint — the collision-proof address. */
+  primPath;
+  jointType;
+  axisToken;
+  axis;
+  lower;
+  upper;
+  _value = 0;
+  constructor(joint) {
+    super();
+    this.name = joint.name;
+    this.jointName = joint.name;
+    this.primPath = joint.primPath;
+    this.jointType = joint.type;
+    this.axisToken = joint.axis;
+    this.axis = axisVector(joint.axis);
+    this.lower = joint.lower;
+    this.upper = joint.upper;
+  }
+  get value() {
+    return this._value;
+  }
+  get articulated() {
+    return this.jointType !== "fixed";
+  }
+  /**
+   * Set the joint value (radians for revolute/continuous, length for prismatic).
+   * Optionally clamps to authored limits. Returns the value actually applied.
+   */
+  setValue(value, clampToLimits = true) {
+    if (!this.articulated) return this._value;
+    let v = value;
+    if (clampToLimits) {
+      if (this.lower !== void 0 && v < this.lower) v = this.lower;
+      if (this.upper !== void 0 && v > this.upper) v = this.upper;
+    }
+    this._value = v;
+    if (this.jointType === "prismatic") {
+      this.position.copy(this.axis).multiplyScalar(v);
+      this.quaternion.identity();
+    } else {
+      this.quaternion.setFromAxisAngle(this.axis, v);
+      this.position.set(0, 0, 0);
+    }
+    return v;
+  }
+};
+var LinkObject = class extends THREE4.Object3D {
+  isLinkObject = true;
+  linkName;
+  primPath;
+  constructor(link) {
+    super();
+    this.name = link.name;
+    this.linkName = link.name;
+    this.primPath = link.primPath;
+    this.matrixAutoUpdate = false;
+  }
+};
+var ThreeUsdRobot = class extends THREE4.Object3D {
+  isThreeUsdRobot = true;
+  robot;
+  tree;
+  clampJointLimits;
+  /**
+   * The composed USD stage this robot was built from — the full prim tree, for
+   * inspection tooling (structure panels, attribute browsers). Attached by
+   * {@link ThreeUsdRobotLoader}; `undefined` for programmatically-built robots.
+   */
+  stage;
+  linkObjects = /* @__PURE__ */ new Map();
+  jointObjects = /* @__PURE__ */ new Map();
+  linkKeyByPath = /* @__PURE__ */ new Map();
+  jointKeyByPath = /* @__PURE__ */ new Map();
+  dirty = true;
+  /** Constructed (fk rest) local matrix of every link, for baked→fk restore. */
+  restLocal = /* @__PURE__ */ new Map();
+  _displayMode = "fk";
+  /** Stage-space link worlds while baked (`null` in fk mode). */
+  bakedStageWorld = null;
+  /** Frozen `frame0 · motion · frame1⁻¹` per tree joint while baked. */
+  bakedChainRel = null;
+  debugBaked;
+  bakedDebugWarned = false;
+  warnedPoseKeys = /* @__PURE__ */ new Set();
+  warnedNonUniformScale = false;
+  helperSize;
+  _showVisual = true;
+  _showCollision = false;
+  _showJointAxes = false;
+  _showLinkFrames = false;
+  jointAxesHelpers = [];
+  linkFrameHelpers = [];
+  constructor(robot, tree, options = {}) {
+    super();
+    this.name = robot.name;
+    this.robot = robot;
+    this.tree = tree;
+    this.clampJointLimits = options.clampJointLimits ?? true;
+    this.helperSize = options.helperSize ?? 0.15;
+    for (const [key, link] of Object.entries(robot.links)) {
+      this.linkObjects.set(key, new LinkObject(link));
+      this.linkKeyByPath.set(link.primPath, key);
+    }
+    for (const [key, joint] of Object.entries(robot.joints)) {
+      this.jointKeyByPath.set(joint.primPath, key);
+    }
+    this.attachRoot();
+    this.attachTreeEdges();
+    this.attachIsolatedLinks();
+    this.applyStageNormalization(robot, options);
+    if (options.applyInitialPose ?? true) this.applyInitialPose(robot);
+    for (const [key, obj] of this.linkObjects) this.restLocal.set(key, obj.matrix.toArray());
+    const debug = options.debugBakedTransforms;
+    this.debugBaked = debug ? {
+      anchorTolerance: (typeof debug === "object" ? debug.anchorTolerance : void 0) ?? 1e-3,
+      axisTolerance: (typeof debug === "object" ? debug.axisTolerance : void 0) ?? 0.01
+    } : null;
+  }
+  /** Orient (authored upAxis → target world up) and scale (metersPerUnit × unitScale) the root. */
+  applyStageNormalization(robot, options) {
+    const scale = (robot.metersPerUnit || 1) * (options.unitScale ?? 1);
+    if (scale !== 1) this.scale.setScalar(scale);
+    const rotateX = (angle) => this.quaternion.setFromAxisAngle(new THREE4.Vector3(1, 0, 0), angle);
+    if (options.worldUp) {
+      if (options.worldUp === "Y" && robot.upAxis === "Z") rotateX(-Math.PI / 2);
+      else if (options.worldUp === "Z" && robot.upAxis === "Y") rotateX(Math.PI / 2);
+      return;
+    }
+    const conv = options.upAxisConversion ?? "none";
+    if (conv === "Z" || conv === "auto" && robot.upAxis === "Z") rotateX(-Math.PI / 2);
+  }
+  /** Apply each joint's authored initial value, if any. */
+  applyInitialPose(robot) {
+    for (const [key, joint] of Object.entries(robot.joints)) {
+      if (joint.initialValue === void 0) continue;
+      this.jointObjects.get(key)?.setValue(joint.initialValue, this.clampJointLimits);
+    }
+    this.dirty = true;
+  }
+  attachRoot() {
+    const rootObj = this.linkObjects.get(this.tree.root);
+    if (!rootObj) return;
+    const rootJointKey = this.tree.rootJoint;
+    const rootLink = this.robot.links[this.tree.root];
+    if (rootJointKey) {
+      const j = this.robot.joints[rootJointKey];
+      if (j) setMatrix(rootObj, multiply(j.jointFrame0, invert(j.jointFrame1)));
+    } else if (rootLink?.worldTransform) {
+      setMatrix(rootObj, rootLink.worldTransform);
+    }
+    this.add(rootObj);
+  }
+  attachTreeEdges() {
+    for (const linkKey of this.tree.order) {
+      const node = this.tree.nodes[linkKey];
+      if (!node || node.parent === null || node.jointToParent === null) continue;
+      const parentObj = this.linkObjects.get(node.parent);
+      const childObj = this.linkObjects.get(linkKey);
+      const joint = this.robot.joints[node.jointToParent];
+      if (!parentObj || !childObj || !joint) continue;
+      this.attachJointChain(parentObj, childObj, node.jointToParent, joint);
+    }
+  }
+  /** Build `parent → frame0 → motion → frame1⁻¹ → child` for one joint. */
+  attachJointChain(parent, child, jointKey, joint) {
+    const frame0 = new THREE4.Group();
+    frame0.name = `${joint.name}:frame0`;
+    setMatrix(frame0, joint.jointFrame0);
+    const motion = new JointObject(joint);
+    const frame1Inv = new THREE4.Group();
+    frame1Inv.name = `${joint.name}:frame1Inv`;
+    setMatrix(frame1Inv, invert(joint.jointFrame1));
+    parent.add(frame0);
+    frame0.add(motion);
+    motion.add(frame1Inv);
+    frame1Inv.add(child);
+    this.jointObjects.set(jointKey, motion);
+  }
+  attachIsolatedLinks() {
+    for (const key of this.tree.isolatedLinks) {
+      const obj = this.linkObjects.get(key);
+      if (!obj || obj.parent) continue;
+      const worldTransform = this.robot.links[key]?.worldTransform;
+      if (worldTransform) setMatrix(obj, worldTransform);
+      this.add(obj);
+    }
+  }
+  // -- Naming --------------------------------------------------------------
+  /** Resolve a link reference — key or full prim path — to the extractor key. */
+  linkKey(ref) {
+    if (this.linkObjects.has(ref)) return ref;
+    return this.linkKeyByPath.get(ref) ?? ref;
+  }
+  /** Resolve a joint reference — key or full prim path — to the extractor key. */
+  jointKey(ref) {
+    if (this.jointObjects.has(ref)) return ref;
+    return this.jointKeyByPath.get(ref) ?? ref;
+  }
+  // -- Joint control -------------------------------------------------------
+  /**
+   * Set one joint value, addressed by key or full prim path. Unknown joints
+   * are ignored. Returns whether it applied. Always restores `"fk"` display
+   * mode first (see {@link setLinkTransforms}).
+   */
+  setJointValue(name, value) {
+    this.exitBakedMode();
+    const joint = this.jointObjects.get(this.jointKey(name));
+    if (!joint) return false;
+    joint.setValue(value, this.clampJointLimits);
+    this.dirty = true;
+    return true;
+  }
+  /**
+   * Set several joint values at once (matrix update is coalesced). Always
+   * restores `"fk"` display mode first, recomputing every link purely from
+   * joint values — even an empty batch returns from baked playback (see
+   * {@link setLinkTransforms}).
+   */
+  setJointValues(values) {
+    this.exitBakedMode();
+    for (const [name, value] of Object.entries(values)) {
+      const joint = this.jointObjects.get(this.jointKey(name));
+      if (joint) {
+        joint.setValue(value, this.clampJointLimits);
+        this.dirty = true;
+      }
+    }
+  }
+  getJointValue(name) {
+    return this.jointObjects.get(this.jointKey(name))?.value;
+  }
+  /** Recompute world matrices. Called lazily by the getters; safe to call directly. */
+  updateKinematics() {
+    this.updateMatrixWorld(true);
+    this.dirty = false;
+  }
+  ensureUpdated() {
+    if (this.dirty) this.updateKinematics();
+  }
+  // -- Baked link transforms (M23) -----------------------------------------
+  /**
+   * `"fk"` (default): link placements derive from joint values. `"baked"`:
+   * {@link setLinkTransforms} wrote link poses directly and the joints no
+   * longer constrain the display; any `setJointValue`-family call restores fk.
+   */
+  get displayMode() {
+    return this._displayMode;
+  }
+  /**
+   * Drive link world poses directly — the display path for baked recordings
+   * (Isaac Sim body-transform time samples, maximal-coordinate playback).
+   * usdview-like semantics: constraint deviations are shown, never corrected —
+   * {@link validateLinkTransforms} measures them,
+   * {@link jointValuesFromLinkTransforms} projects onto the joints instead.
+   *
+   * Enters `"baked"` display mode; joint values stay untouched. Return to fk
+   * with {@link setJointValues} (any batch, even `{}`), which recomputes
+   * every link purely from joint values.
+   *
+   * Keys are link keys or full prim paths; unknown keys warn once and are
+   * skipped. Unspecified links KEEP their current world pose — a track that
+   * omits a link means "it did not move". Poses are rigid, `quaternion` in
+   * `[x, y, z, w]` order, interpreted per `opts.space` (default `"world"`:
+   * the Three.js scene world after `worldUp` normalization — pair a Z-up
+   * meter track with `worldUp: "Z"`). Matrix updates are coalesced into the
+   * next render / world query. Returns the number of poses applied.
+   */
+  setLinkTransforms(poses, opts = {}) {
+    const targets = this.resolvePoseTargets(poses, opts.space ?? "world");
+    if (this._displayMode !== "baked") this.enterBakedMode();
+    const current = this.bakedStageWorld ?? /* @__PURE__ */ new Map();
+    const rels = this.bakedChainRel ?? /* @__PURE__ */ new Map();
+    const next = /* @__PURE__ */ new Map();
+    for (const key of this.tree.order) {
+      const node = this.tree.nodes[key];
+      const obj = this.linkObjects.get(key);
+      if (!node || !obj) continue;
+      const world = targets.get(key) ?? current.get(key);
+      if (!world) continue;
+      if (node.parent === null || node.jointToParent === null) {
+        next.set(key, world);
+        setMatrix(obj, world);
+        continue;
+      }
+      const parentWorld = next.get(node.parent);
+      const chainRel = rels.get(node.jointToParent);
+      if (!parentWorld || !chainRel) continue;
+      next.set(key, world);
+      setMatrix(obj, multiply(invert(multiply(parentWorld, chainRel)), world));
+    }
+    for (const key of this.tree.isolatedLinks) {
+      const obj = this.linkObjects.get(key);
+      const world = targets.get(key) ?? current.get(key);
+      if (!obj || !world) continue;
+      next.set(key, world);
+      setMatrix(obj, world);
+    }
+    this.bakedStageWorld = next;
+    this.dirty = true;
+    this.warnBakedDeviationOnce(next);
+    return targets.size;
+  }
+  /**
+   * Measure how far a link-pose batch deviates from the joint constraints,
+   * without touching the display. Unspecified links resolve to their current
+   * displayed pose, so the report predicts exactly what
+   * {@link setLinkTransforms} with the same batch would show.
+   *
+   * Keyed by joint prim path; covers every joint — fixed joints (`q` = 0
+   * check), loop joints dropped from the fk tree (closure error) and the
+   * world-fixed root attachment (a moved base against a fixed-base model).
+   * Typical signatures: a constant `anchorError` offset on every joint —
+   * recording/model mismatch (wrong version or scale); growth over time —
+   * maximal-coordinate solver drift; large uniform `axisError` — a
+   * coordinate-convention bug (Y/Z-up or quaternion order).
+   */
+  validateLinkTransforms(poses, opts = {}) {
+    const out = {};
+    for (const { joint, rel } of this.decomposeJoints(poses, opts.space ?? "world")) {
+      out[joint.primPath] = this.buildResidual(joint, rel.q, rel);
+    }
+    return out;
+  }
+  /**
+   * Project a link-pose batch onto the joint manifold: the closed-form 1-DOF
+   * joint values that best reproduce it, plus the same residuals as
+   * {@link validateLinkTransforms}. `values` covers the articulated tree
+   * joints, keyed by joint prim path, and feeds {@link setJointValues}
+   * directly — the constraint-respecting playback of the same track:
+   *
+   * ```ts
+   * robot.setJointValues(robot.jointValuesFromLinkTransforms(poses, { previous }).values);
+   * ```
+   *
+   * Residual `q` / `limitExceeded` always report the unclamped projection,
+   * also when `clampLimits` clamps `values`.
+   */
+  jointValuesFromLinkTransforms(poses, opts = {}) {
+    const values = {};
+    const residuals = {};
+    for (const { key, joint, rel } of this.decomposeJoints(poses, opts.space ?? "world")) {
+      let q = rel.q;
+      if (joint.type === "revolute" || joint.type === "continuous") {
+        const previous = opts.previous?.[joint.primPath] ?? opts.previous?.[key];
+        if (previous !== void 0) q = nearestAngleBranch(q, previous);
+      }
+      residuals[joint.primPath] = this.buildResidual(joint, q, rel);
+      if (!this.jointObjects.get(key)?.articulated) continue;
+      if (opts.clampLimits) {
+        if (joint.lower !== void 0 && q < joint.lower) q = joint.lower;
+        if (joint.upper !== void 0 && q > joint.upper) q = joint.upper;
+      }
+      values[joint.primPath] = q;
+    }
+    return { values, residuals };
+  }
+  /** Restore the constructed fk link placements (no-op when already `"fk"`). */
+  exitBakedMode() {
+    if (this._displayMode === "fk") return;
+    for (const [key, local] of this.restLocal) {
+      const obj = this.linkObjects.get(key);
+      if (obj) setMatrix(obj, local);
+    }
+    this.bakedStageWorld = null;
+    this.bakedChainRel = null;
+    this.bakedDebugWarned = false;
+    this._displayMode = "fk";
+    this.dirty = true;
+  }
+  /** Freeze the fk state a baked session builds on (joints cannot move while baked). */
+  enterBakedMode() {
+    const rels = this.computeChainRels();
+    this.bakedChainRel = rels;
+    this.bakedStageWorld = this.computeStageWorlds(rels);
+    this._displayMode = "baked";
+  }
+  /** `frame0 · motion(q) · frame1⁻¹` of every tree joint, from live joint values. */
+  computeChainRels() {
+    const rels = /* @__PURE__ */ new Map();
+    for (const [key, motion] of this.jointObjects) {
+      const joint = this.robot.joints[key];
+      if (!joint) continue;
+      motion.updateMatrix();
+      rels.set(
+        key,
+        multiplyAll([joint.jointFrame0, motion.matrix.toArray(), invert(joint.jointFrame1)])
+      );
+    }
+    return rels;
+  }
+  /** Stage-space world transform of every link under the current display state. */
+  computeStageWorlds(rels) {
+    const worlds = /* @__PURE__ */ new Map();
+    for (const key of this.tree.order) {
+      const node = this.tree.nodes[key];
+      const obj = this.linkObjects.get(key);
+      if (!node || !obj) continue;
+      const local = obj.matrix.toArray();
+      if (node.parent === null || node.jointToParent === null) {
+        worlds.set(key, local);
+        continue;
+      }
+      const parentWorld = worlds.get(node.parent);
+      const chainRel = rels.get(node.jointToParent);
+      if (!parentWorld || !chainRel) continue;
+      worlds.set(key, multiplyAll([parentWorld, chainRel, local]));
+    }
+    for (const key of this.tree.isolatedLinks) {
+      const obj = this.linkObjects.get(key);
+      if (obj) worlds.set(key, obj.matrix.toArray());
+    }
+    return worlds;
+  }
+  currentStageWorlds() {
+    return this.bakedStageWorld ?? this.computeStageWorlds(this.computeChainRels());
+  }
+  /** Resolve pose keys to link keys and convert each pose to a rigid stage-space matrix. */
+  resolvePoseTargets(poses, space) {
+    const targets = /* @__PURE__ */ new Map();
+    const entries = Object.entries(poses);
+    if (entries.length === 0) return targets;
+    const toStage = space === "world" ? this.sceneToStageConverter() : null;
+    const position = new THREE4.Vector3();
+    const quaternion = new THREE4.Quaternion();
+    const matrix = new THREE4.Matrix4();
+    for (const [ref, pose] of entries) {
+      const key = this.linkKey(ref);
+      if (!this.linkObjects.has(key)) {
+        this.warnUnknownPoseKey(ref);
+        continue;
+      }
+      position.fromArray(pose.position);
+      quaternion.fromArray(pose.quaternion).normalize();
+      toStage?.(position, quaternion);
+      targets.set(key, matrix.compose(position, quaternion, UNIT_SCALE).toArray());
+    }
+    return targets;
+  }
+  /**
+   * Scene world → stage space, undoing the robot's own world transform
+   * (up-axis rotation, unit scale, any user placement) as a similarity — so
+   * link locals stay rigid and the root keeps carrying the scale.
+   */
+  sceneToStageConverter() {
+    this.updateWorldMatrix(true, false);
+    const rootPosition = new THREE4.Vector3();
+    const rootQuaternion = new THREE4.Quaternion();
+    const rootScale = new THREE4.Vector3();
+    this.matrixWorld.decompose(rootPosition, rootQuaternion, rootScale);
+    const s = rootScale.x;
+    if (!this.warnedNonUniformScale && (Math.abs(rootScale.y - s) > 1e-6 * Math.abs(s) || Math.abs(rootScale.z - s) > 1e-6 * Math.abs(s))) {
+      this.warnedNonUniformScale = true;
+      console.warn(
+        `three-usd-robot: non-uniform world scale on "${this.name}"; space:"world" poses are off`
+      );
+    }
+    const invQuaternion = rootQuaternion.clone().invert();
+    const invScale = s !== 0 ? 1 / s : 1;
+    return (position, quaternion) => {
+      position.sub(rootPosition).applyQuaternion(invQuaternion).multiplyScalar(invScale);
+      quaternion.premultiply(invQuaternion);
+    };
+  }
+  /**
+   * Decompose every joint's parent→child transform under a pose batch
+   * (unspecified links resolve to their current displayed pose, mirroring
+   * {@link setLinkTransforms}). Pure — the display is untouched.
+   */
+  decomposeJoints(poses, space) {
+    const worlds = new Map(this.currentStageWorlds());
+    for (const [key, world] of this.resolvePoseTargets(poses, space)) worlds.set(key, world);
+    const out = [];
+    for (const [key, joint] of Object.entries(this.robot.joints)) {
+      const childWorld = worlds.get(joint.child);
+      const parentWorld = joint.parent === "" ? IDENTITY4 : worlds.get(joint.parent);
+      if (!childWorld || !parentWorld) continue;
+      out.push({ key, joint, rel: decomposeJointRelative(joint, parentWorld, childWorld) });
+    }
+    return out;
+  }
+  buildResidual(joint, q, rel) {
+    return {
+      anchorError: rel.anchorError * this.robot.metersPerUnit,
+      axisError: rel.axisError,
+      q,
+      limitExceeded: joint.lower !== void 0 && q < joint.lower - LIMIT_EPS || joint.upper !== void 0 && q > joint.upper + LIMIT_EPS
+    };
+  }
+  warnUnknownPoseKey(ref) {
+    if (this.warnedPoseKeys.has(ref)) return;
+    this.warnedPoseKeys.add(ref);
+    console.warn(`three-usd-robot: unknown link "${ref}" in a pose batch; ignoring`);
+  }
+  /** `debugBakedTransforms`: warn once per baked session when poses break the constraints. */
+  warnBakedDeviationOnce(worlds) {
+    if (!this.debugBaked || this.bakedDebugWarned) return;
+    const { anchorTolerance, axisTolerance } = this.debugBaked;
+    let count = 0;
+    let worst = null;
+    for (const joint of Object.values(this.robot.joints)) {
+      const childWorld = worlds.get(joint.child);
+      const parentWorld = joint.parent === "" ? IDENTITY4 : worlds.get(joint.parent);
+      if (!childWorld || !parentWorld) continue;
+      const rel = decomposeJointRelative(joint, parentWorld, childWorld);
+      const anchor = rel.anchorError * this.robot.metersPerUnit;
+      if (anchor <= anchorTolerance && rel.axisError <= axisTolerance) continue;
+      count++;
+      const score = anchor / anchorTolerance + rel.axisError / axisTolerance;
+      if (!worst || score > worst.score) {
+        worst = { path: joint.primPath, anchor, axis: rel.axisError, score };
+      }
+    }
+    if (!worst) return;
+    this.bakedDebugWarned = true;
+    console.warn(
+      `three-usd-robot: baked poses deviate from ${count} joint constraint(s) \u2014 worst ${worst.path}: anchor ${(worst.anchor * 1e3).toFixed(3)} mm, axis ${worst.axis.toFixed(4)} rad (recording/model mismatch? warned once per baked session)`
+    );
+  }
+  // -- Queries -------------------------------------------------------------
+  /** World matrix of a link, addressed by key or full prim path. */
+  getLinkWorldMatrix(name) {
+    const obj = this.linkObjects.get(this.linkKey(name));
+    if (!obj) throw new Error(`unknown link "${name}"`);
+    this.ensureUpdated();
+    return obj.matrixWorld.clone();
+  }
+  getLinkWorldPosition(name) {
+    return new THREE4.Vector3().setFromMatrixPosition(this.getLinkWorldMatrix(name));
+  }
+  /** Link object by key or full prim path. */
+  getLinkObject(name) {
+    return this.linkObjects.get(this.linkKey(name));
+  }
+  /** Joint object by key or full prim path. */
+  getJointObject(name) {
+    return this.jointObjects.get(this.jointKey(name));
+  }
+  /**
+   * Table of link prim path → {@link LinkObject}. Prim paths are the
+   * collision-proof way to pin a link (e.g. to attach tools or gizmos).
+   */
+  getLinkObjectsByPath() {
+    const out = /* @__PURE__ */ new Map();
+    for (const [path, key] of this.linkKeyByPath) {
+      const obj = this.linkObjects.get(key);
+      if (obj) out.set(path, obj);
+    }
+    return out;
+  }
+  /**
+   * Table of joint prim path → {@link JointObject}, covering the joints
+   * realized in the kinematic tree (loop joints have no motion node).
+   */
+  getJointObjectsByPath() {
+    const out = /* @__PURE__ */ new Map();
+    for (const [path, key] of this.jointKeyByPath) {
+      const obj = this.jointObjects.get(key);
+      if (obj) out.set(path, obj);
+    }
+    return out;
+  }
+  getJoints() {
+    return Object.values(this.robot.joints);
+  }
+  getLinks() {
+    return Object.values(this.robot.links);
+  }
+  /** Names of the articulated (controllable) joints. */
+  getJointNames() {
+    return [...this.jointObjects.keys()];
+  }
+  getLinkNames() {
+    return [...this.linkObjects.keys()];
+  }
+  getKinematicTree() {
+    return this.tree;
+  }
+  /** Authored stage up-axis (`"Y"` or `"Z"`) — unaffected by `worldUp` normalization. */
+  get upAxis() {
+    return this.robot.upAxis;
+  }
+  /** Authored stage scale in meters per unit (already applied to the root). */
+  get metersPerUnit() {
+    return this.robot.metersPerUnit;
+  }
+  // -- Animation playback --------------------------------------------------
+  /** Playback rate in time codes per second (from the stage; default 24). */
+  getTimeCodesPerSecond() {
+    return this.robot.timeCodesPerSecond ?? 24;
+  }
+  /** Whether any joint has a time-sampled trajectory. */
+  hasAnimation() {
+    return Object.values(this.robot.joints).some((j) => j.valueSamples !== void 0);
+  }
+  /**
+   * Animation range in time codes: the union of authored joint sample ranges,
+   * falling back to the stage `startTimeCode`/`endTimeCode`. `null` if neither.
+   */
+  getTimeRange() {
+    let start = Number.POSITIVE_INFINITY;
+    let end = Number.NEGATIVE_INFINITY;
+    for (const joint of Object.values(this.robot.joints)) {
+      const times = joint.valueSamples?.times;
+      if (!times || times.length === 0) continue;
+      start = Math.min(start, times[0]);
+      end = Math.max(end, times[times.length - 1]);
+    }
+    if (start <= end) return { start, end };
+    const { startTimeCode, endTimeCode } = this.robot;
+    if (startTimeCode !== void 0 && endTimeCode !== void 0) {
+      return { start: startTimeCode, end: endTimeCode };
+    }
+    return null;
+  }
+  /** Sample every animated joint at time code `t` and apply the values (an fk drive — leaves baked mode). */
+  setTime(t) {
+    this.exitBakedMode();
+    for (const [key, joint] of Object.entries(this.robot.joints)) {
+      if (joint.valueSamples) this.setJointValue(key, interpolate(joint.valueSamples, t));
+    }
+  }
+  // -- Display toggles -----------------------------------------------------
+  get showVisual() {
+    return this._showVisual;
+  }
+  set showVisual(v) {
+    this._showVisual = v;
+    this.setKindVisibility("visual", v);
+  }
+  get showCollision() {
+    return this._showCollision;
+  }
+  set showCollision(v) {
+    this._showCollision = v;
+    this.setKindVisibility("collision", v);
+  }
+  get showJointAxes() {
+    return this._showJointAxes;
+  }
+  set showJointAxes(v) {
+    this._showJointAxes = v;
+    if (v && this.jointAxesHelpers.length === 0) {
+      for (const joint of this.jointObjects.values()) {
+        const h = new THREE4.AxesHelper(this.helperSize);
+        h.name = `${joint.jointName}:axes`;
+        joint.add(h);
+        this.jointAxesHelpers.push(h);
+      }
+    }
+    for (const h of this.jointAxesHelpers) h.visible = v;
+  }
+  get showLinkFrames() {
+    return this._showLinkFrames;
+  }
+  set showLinkFrames(v) {
+    this._showLinkFrames = v;
+    if (v && this.linkFrameHelpers.length === 0) {
+      for (const link of this.linkObjects.values()) {
+        const h = new THREE4.AxesHelper(this.helperSize);
+        h.name = `${link.linkName}:frame`;
+        link.add(h);
+        this.linkFrameHelpers.push(h);
+      }
+    }
+    for (const h of this.linkFrameHelpers) h.visible = v;
+  }
+  setKindVisibility(kind, visible) {
+    this.traverse((o) => {
+      if (o.userData.kind === kind) o.visible = visible;
+    });
+  }
+};
+var UNIT_SCALE = new THREE4.Vector3(1, 1, 1);
+var IDENTITY4 = identity4();
+var LIMIT_EPS = 1e-9;
+function setMatrix(obj, m) {
+  obj.matrixAutoUpdate = false;
+  obj.matrix.fromArray(m);
+  obj.matrixWorldNeedsUpdate = true;
+}
+
+export { JointObject, LinkObject, ThreeUsdRobot, axisVector };
+//# sourceMappingURL=chunk-ENWFOYHU.js.map
+//# sourceMappingURL=chunk-ENWFOYHU.js.map