three-usd-robot 0.7.0 → 0.8.0

package/README.md

@@ -23,8 +23,10 @@ exported back to `.usda` / `.usdz` in the browser.
   instanceable prims are composed for you.
 - **Robots** — links, joints (fixed / revolute / continuous / prismatic), limits,
   drives and the initial pose become a `setJointValue`-able hierarchy.
-- **Rendering** — meshes with `UsdShade` materials (UsdPreviewSurface / OmniPBR)
-  and textures; up-axis and units normalized automatically.
+- **Rendering** — meshes and solid gprims (`Cube` / `Sphere` / `Cylinder` /
+  `Capsule` / `Cone`) with `UsdShade` materials (UsdPreviewSurface / OmniPBR)
+  and textures; up-axis and units normalized automatically. Articulation-free
+  stages load as static scenes.
 - **Animation** — plays back time-sampled joint trajectories.
 - **Export** — write robots and whole cells back to `.usda` / `.usdz`,
   simulation-ready for Isaac Sim.
@@ -48,8 +50,8 @@ The CDN is public and CORS-enabled, so this works in the browser too. Try
 FK check, and a re-export to one self-contained file), or open the Vite example
 and pick a robot from the preset list.
 
-Not yet supported: time samples stored inside binary crate files, non-mesh
-gprims (`Cube`, `Sphere`, …), and full material/shader fidelity.
+Not yet supported: time samples stored inside binary crate files, point/curve
+gprims (`Points`, `BasisCurves`, …), and full material/shader fidelity.
 
 ## Install
 
@@ -79,8 +81,38 @@ robot.getJointNames(); // controllable joints
 robot.getKinematicTree(); // root, ordering, loop joints, ...
 ```
 
-Already have the bytes? Use `parse(usdaText)`, `parseCrate(usdcBytes)` or
-`parseUsdz(bytes)` instead of `loadAsync`.
+No URL? `parse` also takes in-memory content: USDA source text, or an
+`ArrayBuffer` / typed array / `Blob` holding any supported format — the zip /
+crate magic is sniffed, so a dropped `File` or a response body works as-is:
+
+```ts
+const loader = new ThreeUsdRobotLoader();
+await loader.parse(usdaText); // USDA source string
+await loader.parse(file); // File / Blob from drag & drop or <input type="file">
+await loader.parse(await res.arrayBuffer()); // a fetch you did yourself
+```
+
+`parseUsdz(data)` / `parseCrate(data, baseUrl)` stay as explicit-format entries,
+and `parseRobotDescription(data)` returns the Three.js-independent IR. Pass a
+`baseUrl` as the second `parse` argument if the layer has relative references
+or texture paths to resolve.
+
+### Stable addressing (naming contract)
+
+Joints and links are keyed by their prim's **leaf name** while it is unique
+across the robot; on a collision (say, two arms each with a `seg` link) the
+colliding entries are keyed by their **full prim path** instead —
+deterministically. Every accessor also takes the full prim path directly, so
+tooling can pin exact prims no matter how the asset is named:
+
+```ts
+robot.setJointValue("/World/armL/j1", 0.4); // same joint as its key
+robot.getLinkWorldMatrix("/World/armL/seg");
+robot.getLinkObjectsByPath(); // Map<primPath, LinkObject>
+robot.getJointObjectsByPath(); // Map<primPath, JointObject>
+```
+
+`LinkObject.primPath` / `JointObject.primPath` carry the reverse direction.
 
 ### Viewer toggles & helpers
 
@@ -94,9 +126,38 @@ import { addJointLimitHelpers } from "three-usd-robot/helpers";
 addJointLimitHelpers(robot); // arc (revolute) / segment (prismatic) per joint
 ```
 
+### Link highlighting & ghosts
+
+Per-link appearance helpers cover the common viewer chores — flagging
+colliding links, material swaps, and translucent "ghost" pose previews:
+
+```ts
+import {
+  createGhostRobot,
+  highlightLink,
+  restoreLinkMaterials,
+  setLinkMaterial,
+} from "three-usd-robot/helpers";
+
+highlightLink(robot, "link1"); // emissive red tint; maps/colors kept
+highlightLink(robot, "/World/armL/seg", { color: 0xffaa00, opacity: 0.6 });
+setLinkMaterial(robot, "link2", new THREE.MeshBasicMaterial({ wireframe: true }));
+restoreLinkMaterials(robot, "link1"); // exact original materials back
+
+const ghost = createGhostRobot(robot, { jointValues: { joint1: 1.2 } });
+scene.add(ghost); // translucent copy previewing the target pose
+ghost.setJointValues(ikSolution); // a full ThreeUsdRobot, driveable like the source
+```
+
+Highlights never stack (each call re-tints from the originals), and ghosts
+share the source's geometry — cloning is cheap enough for onion-skinning.
+
 Loading a whole cell rather than a bare robot? Pass
 `{ loadSceneGeometry: true }` to the loader to draw the static environment
-(floor, guarding, racking, …) around the machines.
+(floor, guarding, racking, …) around the machines. A stage with **no
+articulation at all** — a plain static USD scene — is detected and rendered as
+scene geometry automatically, with the same unit / up-axis normalization; pass
+`loadSceneGeometry: false` to opt out.
 
 ### Joint slider panel (lil-gui)
 

package/dist/{ThreeUsdRobot-Ljh4PDVD.d.ts → ThreeUsdRobot-CsjraHqP.d.ts}

@@ -1,5 +1,5 @@
 import * as THREE from 'three';
-import { J as JointType, A as Axis, a as JointDescription, L as LinkDescription, R as RobotDescription, K as KinematicTree } from './buildKinematicTree-Ccd2DIKH.js';
+import { J as JointType, A as Axis, a as JointDescription, L as LinkDescription, R as RobotDescription, K as KinematicTree } from './buildKinematicTree-D4R0hEtN.js';
 
 /**
  * The articulated "motion" node of a joint, inserted between the joint's two
@@ -10,6 +10,8 @@ import { J as JointType, A as Axis, a as JointDescription, L as LinkDescription,
 declare class JointObject extends THREE.Object3D {
     readonly isJointObject = true;
     readonly jointName: string;
+    /** Full USD prim path of the joint — the collision-proof address. */
+    readonly primPath: string;
     readonly jointType: JointType;
     readonly axisToken: Axis;
     readonly axis: THREE.Vector3;
@@ -63,6 +65,12 @@ type ThreeUsdRobotOptions = {
  * `parentLink → jointFrame0 → jointMotion → jointFrame1⁻¹ → childLink`,
  * where only `jointMotion` (a {@link JointObject}) changes with the joint value;
  * world poses then fall out of Three.js's `updateMatrixWorld`.
+ *
+ * **Naming contract** — a link/joint's key is its prim's leaf name when that
+ * is unique across the robot, else its full prim path (deterministic; see the
+ * extractor). Every accessor taking a name equally accepts the full prim path,
+ * which is stable regardless of collisions; {@link getLinkObjectsByPath} /
+ * {@link getJointObjectsByPath} enumerate the path-keyed tables.
  */
 declare class ThreeUsdRobot extends THREE.Object3D {
     readonly isThreeUsdRobot = true;
@@ -71,6 +79,8 @@ declare class ThreeUsdRobot extends THREE.Object3D {
     readonly clampJointLimits: boolean;
     private readonly linkObjects;
     private readonly jointObjects;
+    private readonly linkKeyByPath;
+    private readonly jointKeyByPath;
     private dirty;
     private readonly helperSize;
     private _showVisual;
@@ -89,7 +99,14 @@ declare class ThreeUsdRobot extends THREE.Object3D {
     /** Build `parent → frame0 → motion → frame1⁻¹ → child` for one joint. */
     private attachJointChain;
     private attachIsolatedLinks;
-    /** Set one joint value. Unknown joints are ignored. Returns whether it applied. */
+    /** Resolve a link reference — key or full prim path — to the extractor key. */
+    private linkKey;
+    /** Resolve a joint reference — key or full prim path — to the extractor key. */
+    private jointKey;
+    /**
+     * Set one joint value, addressed by key or full prim path. Unknown joints
+     * are ignored. Returns whether it applied.
+     */
     setJointValue(name: string, value: number): boolean;
     /** Set several joint values at once (matrix update is coalesced). */
     setJointValues(values: Record<string, number>): void;
@@ -97,10 +114,23 @@ declare class ThreeUsdRobot extends THREE.Object3D {
     /** Recompute world matrices. Called lazily by the getters; safe to call directly. */
     updateKinematics(): void;
     private ensureUpdated;
+    /** World matrix of a link, addressed by key or full prim path. */
     getLinkWorldMatrix(name: string): THREE.Matrix4;
     getLinkWorldPosition(name: string): THREE.Vector3;
+    /** Link object by key or full prim path. */
     getLinkObject(name: string): LinkObject | undefined;
+    /** Joint object by key or full prim path. */
     getJointObject(name: string): JointObject | undefined;
+    /**
+     * 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(): Map<string, LinkObject>;
+    /**
+     * Table of joint prim path → {@link JointObject}, covering the joints
+     * realized in the kinematic tree (loop joints have no motion node).
+     */
+    getJointObjectsByPath(): Map<string, JointObject>;
     getJoints(): JointDescription[];
     getLinks(): LinkDescription[];
     /** Names of the articulated (controllable) joints. */

package/dist/{ThreeUsdRobotLoader-BSIVFA48.d.ts → ThreeUsdRobotLoader-CxOGRLXH.d.ts}

@@ -1,6 +1,6 @@
-import { R as RobotDescription } from './buildKinematicTree-Ccd2DIKH.js';
-import { A as AssetResolver } from './AssetResolver-CpIJNgWZ.js';
-import { T as ThreeUsdRobot } from './ThreeUsdRobot-Ljh4PDVD.js';
+import { R as RobotDescription } from './buildKinematicTree-D4R0hEtN.js';
+import { A as AssetResolver, U as UsdSource, B as BinarySource } from './bytes-MOJ2oN-u.js';
+import { T as ThreeUsdRobot } from './ThreeUsdRobot-CsjraHqP.js';
 
 type ThreeUsdRobotLoaderOptions = {
     /** Resolver for references / payloads / sublayers (default {@link DefaultAssetResolver}). */
@@ -10,9 +10,10 @@ type ThreeUsdRobotLoaderOptions = {
     /** Render collision meshes (M6). */
     loadCollisions?: boolean;
     /**
-     * Also render Mesh prims that belong to no link — the static scenery of a
-     * cell that contains robots (floor, guarding, racking, …). Placed by their
-     * authored stage transform. Default `false`.
+     * Also render gprims that belong to no link — the static scenery of a cell
+     * that contains robots (floor, guarding, racking, …). Placed by their
+     * authored stage transform. Default `false`; a stage with no articulation at
+     * all (a pure static scene) defaults to `true` so it renders out of the box.
      */
     loadSceneGeometry?: boolean;
     /** Load diffuse textures referenced by materials (default `true`). */
@@ -33,6 +34,8 @@ type ThreeUsdRobotLoaderOptions = {
 /**
  * Loads Isaac Sim / OpenUSD robot assets into a controllable {@link ThreeUsdRobot}.
  *
+ * Assets load by URL ({@link loadAsync}) or from in-memory content
+ * ({@link parse} — USDA text, `ArrayBuffer`, typed array, or `Blob`/`File`).
  * Composition (references / payloads / sublayers, M8) is resolved through an
  * {@link AssetResolver}. Mesh rendering is M6; unit / up-axis / initial-pose
  * handling is M9; USDC and variants are M10.
@@ -43,19 +46,31 @@ declare class ThreeUsdRobotLoader {
     private get resolver();
     /**
      * Fetch an asset by URL and build the robot. `.usdz` packages are unzipped and
-     * composed from their entries; everything else is sniffed for the crate magic
-     * and parsed as binary USDC or USDA text.
+     * composed from their entries; everything else is sniffed for the zip / crate
+     * magic and parsed as USDZ, binary USDC, or USDA text.
      */
     loadAsync(url: string): Promise<ThreeUsdRobot>;
     private fetchRootBytes;
-    /** Build a robot (composed, with meshes) from USDA source text. */
-    parse(text: string, baseUrl?: string): Promise<ThreeUsdRobot>;
-    /** Build a robot from the bytes of a `.usdz` package. */
-    parseUsdz(bytes: Uint8Array): Promise<ThreeUsdRobot>;
-    /** Build a robot from the bytes of a binary crate (`.usdc` / binary `.usd`). */
-    parseCrate(bytes: Uint8Array, baseUrl?: string): Promise<ThreeUsdRobot>;
-    /** Parse + compose USDA source into the Three.js-independent robot IR. */
-    parseRobotDescription(text: string, baseUrl?: string): Promise<RobotDescription>;
+    /**
+     * Build a robot from in-memory content — no fetch involved. Accepts USDA
+     * source text, or an `ArrayBuffer` / typed array / `Blob` (e.g. a dropped
+     * `File`) holding USDA text, a binary crate, or a `.usdz` package; binary
+     * input is sniffed for the zip / crate magic. `baseUrl` anchors relative
+     * references, payloads, and texture paths of non-package input.
+     */
+    parse(data: UsdSource, baseUrl?: string): Promise<ThreeUsdRobot>;
+    /** Build a robot from a `.usdz` package (bytes, `ArrayBuffer`, or `Blob`). */
+    parseUsdz(data: BinarySource): Promise<ThreeUsdRobot>;
+    /** Build a robot from a binary crate (`.usdc` / binary `.usd`). */
+    parseCrate(data: BinarySource, baseUrl?: string): Promise<ThreeUsdRobot>;
+    /**
+     * Parse + compose in-memory content (same formats as {@link parse}) into the
+     * Three.js-independent robot IR.
+     */
+    parseRobotDescription(data: UsdSource, baseUrl?: string): Promise<RobotDescription>;
+    /** Sniff in-memory content (text / zip / crate) and compose it into a stage. */
+    private openSource;
+    private openUsdzStage;
     private buildFromStage;
     private composeStage;
     /** Compose a layer from raw bytes, sniffing binary crate vs USDA text. */

package/dist/{buildKinematicTree-Ccd2DIKH.d.ts → buildKinematicTree-D4R0hEtN.d.ts}

@@ -256,9 +256,9 @@ type LinkDescription = {
     /** Display name (leaf prim name). */
     name: string;
     primPath: string;
-    /** Mesh prim paths to render. */
+    /** Renderable gprim paths (Mesh / Cube / Sphere / Cylinder / Capsule / Cone). */
     visualPrims: string[];
-    /** Mesh prim paths flagged with a collision API. */
+    /** Gprim paths flagged with a collision API (or a non-visual purpose). */
     collisionPrims?: string[];
     /** Mass properties (`UsdPhysicsMassAPI`), if authored (M16). */
     inertial?: LinkInertialDescription;

package/dist/{AssetResolver-CpIJNgWZ.d.ts → bytes-MOJ2oN-u.d.ts}

@@ -26,4 +26,17 @@ declare function createMemoryResolver(files: Record<string, string | Uint8Array>
 /** Resolve `rel` against `baseUrl` using posix semantics, normalizing `.`/`..`. */
 declare function joinPosix(baseUrl: string, rel: string): string;
 
-export { type AssetResolver as A, DefaultAssetResolver as D, createMemoryResolver as c, joinPosix as j };
+/**
+ * In-memory input normalization for the loader entry points. Callers hold USD
+ * content in many shapes — a `fetch` response's `ArrayBuffer`, a `Uint8Array`
+ * (or any typed-array view), a dropped `File` / `Blob` — and every byte-eating
+ * API here funnels through {@link toBytes} so all of them are accepted.
+ */
+/** Binary USD content: an `ArrayBuffer`, any typed-array view, or a `Blob`/`File`. */
+type BinarySource = ArrayBuffer | ArrayBufferView | Blob;
+/** In-memory USD content: USDA source text, or {@link BinarySource} bytes. */
+type UsdSource = string | BinarySource;
+/** Normalize a {@link BinarySource} to bytes, honoring a view's offset/length. */
+declare function toBytes(data: BinarySource): Promise<Uint8Array>;
+
+export { type AssetResolver as A, type BinarySource as B, DefaultAssetResolver as D, type UsdSource as U, createMemoryResolver as c, joinPosix as j, toBytes as t };

package/dist/chunk-3CANZKP3.js

@@ -0,0 +1,374 @@
+import { multiply, invert, interpolate } from './chunk-IYKPVUZ2.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;
+  linkObjects = /* @__PURE__ */ new Map();
+  jointObjects = /* @__PURE__ */ new Map();
+  linkKeyByPath = /* @__PURE__ */ new Map();
+  jointKeyByPath = /* @__PURE__ */ new Map();
+  dirty = true;
+  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);
+  }
+  /** Orient (Z-up → Y-up) and scale (metersPerUnit × unitScale) the robot root. */
+  applyStageNormalization(robot, options) {
+    const scale = (robot.metersPerUnit || 1) * (options.unitScale ?? 1);
+    if (scale !== 1) this.scale.setScalar(scale);
+    const conv = options.upAxisConversion ?? "none";
+    const toY = conv === "Z" || conv === "auto" && robot.upAxis === "Z";
+    if (toY) this.quaternion.setFromAxisAngle(new THREE4.Vector3(1, 0, 0), -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.
+   */
+  setJointValue(name, value) {
+    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). */
+  setJointValues(values) {
+    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();
+  }
+  // -- 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;
+  }
+  // -- 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. */
+  setTime(t) {
+    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;
+    });
+  }
+};
+function setMatrix(obj, m) {
+  obj.matrixAutoUpdate = false;
+  obj.matrix.fromArray(m);
+  obj.matrixWorldNeedsUpdate = true;
+}
+
+export { JointObject, LinkObject, ThreeUsdRobot, axisVector };
+//# sourceMappingURL=chunk-3CANZKP3.js.map
+//# sourceMappingURL=chunk-3CANZKP3.js.map