three-usd-robot 0.2.0

package/dist/helpers.js

@@ -0,0 +1,92 @@
+import * as THREE2 from 'three';
+
+// src/helpers/JointAxisHelper.ts
+var JointAxisHelper = class extends THREE2.ArrowHelper {
+  isJointAxisHelper = true;
+  constructor(joint, length = 0.2, color = 16764928) {
+    super(joint.axis.clone().normalize(), new THREE2.Vector3(0, 0, 0), length, color);
+    this.name = `${joint.jointName}:axis`;
+  }
+};
+var JointLimitHelper = class extends THREE2.Line {
+  isJointLimitHelper = true;
+  constructor(joint, radius = 0.15, color = 43775) {
+    super(buildLimitGeometry(joint, radius), new THREE2.LineBasicMaterial({ color }));
+    this.name = `${joint.jointName}:limit`;
+  }
+};
+function buildLimitGeometry(joint, radius) {
+  const axis = joint.axis.clone().normalize();
+  if (joint.jointType === "prismatic") {
+    const lo2 = joint.lower ?? -radius;
+    const hi2 = joint.upper ?? radius;
+    return new THREE2.BufferGeometry().setFromPoints([
+      axis.clone().multiplyScalar(lo2),
+      axis.clone().multiplyScalar(hi2)
+    ]);
+  }
+  const lo = joint.lower ?? 0;
+  const hi = joint.upper ?? Math.PI * 2;
+  const { u, v } = perpendicularBasis(axis);
+  const segments = 48;
+  const points = [];
+  for (let i = 0; i <= segments; i++) {
+    const t = lo + (hi - lo) * i / segments;
+    points.push(
+      u.clone().multiplyScalar(Math.cos(t) * radius).addScaledVector(v, Math.sin(t) * radius)
+    );
+  }
+  return new THREE2.BufferGeometry().setFromPoints(points);
+}
+function perpendicularBasis(axis) {
+  const ref = Math.abs(axis.x) < 0.9 ? new THREE2.Vector3(1, 0, 0) : new THREE2.Vector3(0, 1, 0);
+  const u = new THREE2.Vector3().crossVectors(axis, ref).normalize();
+  const v = new THREE2.Vector3().crossVectors(axis, u).normalize();
+  return { u, v };
+}
+var LinkFrameHelper = class extends THREE2.AxesHelper {
+  isLinkFrameHelper = true;
+  constructor(size = 0.2) {
+    super(size);
+    this.name = "linkFrame";
+  }
+};
+
+// src/helpers/attach.ts
+function addJointAxisHelpers(robot, length, color) {
+  const out = [];
+  for (const name of robot.getJointNames()) {
+    const joint = robot.getJointObject(name);
+    if (!joint?.articulated) continue;
+    const helper = new JointAxisHelper(joint, length, color);
+    joint.add(helper);
+    out.push(helper);
+  }
+  return out;
+}
+function addJointLimitHelpers(robot, radius, color) {
+  const out = [];
+  for (const name of robot.getJointNames()) {
+    const joint = robot.getJointObject(name);
+    if (!joint?.articulated) continue;
+    const helper = new JointLimitHelper(joint, radius, color);
+    joint.add(helper);
+    out.push(helper);
+  }
+  return out;
+}
+function addLinkFrameHelpers(robot, size) {
+  const out = [];
+  for (const name of robot.getLinkNames()) {
+    const link = robot.getLinkObject(name);
+    if (!link) continue;
+    const helper = new LinkFrameHelper(size);
+    link.add(helper);
+    out.push(helper);
+  }
+  return out;
+}
+
+export { JointAxisHelper, JointLimitHelper, LinkFrameHelper, addJointAxisHelpers, addJointLimitHelpers, addLinkFrameHelpers };
+//# sourceMappingURL=helpers.js.map
+//# sourceMappingURL=helpers.js.map

package/dist/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/helpers/JointAxisHelper.ts","../src/helpers/JointLimitHelper.ts","../src/helpers/LinkFrameHelper.ts","../src/helpers/attach.ts"],"names":["THREE","lo","hi","THREE3"],"mappings":"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","file":"helpers.js","sourcesContent":["import * as THREE from \"three\";\nimport type { JointObject } from \"../three/JointObject.js\";\n\n/**\n * An arrow drawn along a joint's motion axis (the rotation axis for\n * revolute/continuous joints, the slide direction for prismatic). Add it to the\n * joint's motion node so it tracks the joint.\n */\nexport class JointAxisHelper extends THREE.ArrowHelper {\n  readonly isJointAxisHelper = true;\n\n  constructor(joint: JointObject, length = 0.2, color: THREE.ColorRepresentation = 0xffd000) {\n    super(joint.axis.clone().normalize(), new THREE.Vector3(0, 0, 0), length, color);\n    this.name = `${joint.jointName}:axis`;\n  }\n}\n","import * as THREE from \"three\";\nimport type { JointObject } from \"../three/JointObject.js\";\n\n/**\n * Visualizes a joint's range of motion: an arc swept between the lower and\n * upper limits (revolute/continuous) or a line segment between them\n * (prismatic). A limitless revolute joint draws a full circle. Add it to the\n * joint's motion node's parent frame (or the joint node) to anchor it.\n */\nexport class JointLimitHelper extends THREE.Line {\n  readonly isJointLimitHelper = true;\n\n  constructor(joint: JointObject, radius = 0.15, color: THREE.ColorRepresentation = 0x00aaff) {\n    super(buildLimitGeometry(joint, radius), new THREE.LineBasicMaterial({ color }));\n    this.name = `${joint.jointName}:limit`;\n  }\n}\n\nfunction buildLimitGeometry(joint: JointObject, radius: number): THREE.BufferGeometry {\n  const axis = joint.axis.clone().normalize();\n\n  if (joint.jointType === \"prismatic\") {\n    const lo = joint.lower ?? -radius;\n    const hi = joint.upper ?? radius;\n    return new THREE.BufferGeometry().setFromPoints([\n      axis.clone().multiplyScalar(lo),\n      axis.clone().multiplyScalar(hi),\n    ]);\n  }\n\n  // Revolute / continuous: sweep an arc in the plane perpendicular to the axis.\n  const lo = joint.lower ?? 0;\n  const hi = joint.upper ?? Math.PI * 2;\n  const { u, v } = perpendicularBasis(axis);\n  const segments = 48;\n  const points: THREE.Vector3[] = [];\n  for (let i = 0; i <= segments; i++) {\n    const t = lo + ((hi - lo) * i) / segments;\n    points.push(\n      u\n        .clone()\n        .multiplyScalar(Math.cos(t) * radius)\n        .addScaledVector(v, Math.sin(t) * radius),\n    );\n  }\n  return new THREE.BufferGeometry().setFromPoints(points);\n}\n\nfunction perpendicularBasis(axis: THREE.Vector3): { u: THREE.Vector3; v: THREE.Vector3 } {\n  const ref = Math.abs(axis.x) < 0.9 ? new THREE.Vector3(1, 0, 0) : new THREE.Vector3(0, 1, 0);\n  const u = new THREE.Vector3().crossVectors(axis, ref).normalize();\n  const v = new THREE.Vector3().crossVectors(axis, u).normalize();\n  return { u, v };\n}\n","import * as THREE from \"three\";\n\n/** A small RGB axes gizmo for a link's local frame. Add it to a `LinkObject`. */\nexport class LinkFrameHelper extends THREE.AxesHelper {\n  readonly isLinkFrameHelper = true;\n\n  constructor(size = 0.2) {\n    super(size);\n    this.name = \"linkFrame\";\n  }\n}\n","import type * as THREE from \"three\";\nimport type { ThreeUsdRobot } from \"../three/ThreeUsdRobot.js\";\nimport { JointAxisHelper } from \"./JointAxisHelper.js\";\nimport { JointLimitHelper } from \"./JointLimitHelper.js\";\nimport { LinkFrameHelper } from \"./LinkFrameHelper.js\";\n\n/** Attach a {@link JointAxisHelper} to every articulated joint. Returns the helpers. */\nexport function addJointAxisHelpers(\n  robot: ThreeUsdRobot,\n  length?: number,\n  color?: THREE.ColorRepresentation,\n): JointAxisHelper[] {\n  const out: JointAxisHelper[] = [];\n  for (const name of robot.getJointNames()) {\n    const joint = robot.getJointObject(name);\n    if (!joint?.articulated) continue;\n    const helper = new JointAxisHelper(joint, length, color);\n    joint.add(helper);\n    out.push(helper);\n  }\n  return out;\n}\n\n/** Attach a {@link JointLimitHelper} to every articulated joint. Returns the helpers. */\nexport function addJointLimitHelpers(\n  robot: ThreeUsdRobot,\n  radius?: number,\n  color?: THREE.ColorRepresentation,\n): JointLimitHelper[] {\n  const out: JointLimitHelper[] = [];\n  for (const name of robot.getJointNames()) {\n    const joint = robot.getJointObject(name);\n    if (!joint?.articulated) continue;\n    const helper = new JointLimitHelper(joint, radius, color);\n    joint.add(helper);\n    out.push(helper);\n  }\n  return out;\n}\n\n/** Attach a {@link LinkFrameHelper} to every link. Returns the helpers. */\nexport function addLinkFrameHelpers(robot: ThreeUsdRobot, size?: number): LinkFrameHelper[] {\n  const out: LinkFrameHelper[] = [];\n  for (const name of robot.getLinkNames()) {\n    const link = robot.getLinkObject(name);\n    if (!link) continue;\n    const helper = new LinkFrameHelper(size);\n    link.add(helper);\n    out.push(helper);\n  }\n  return out;\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+import { Stage, Prim, AssetResolver } from './core.js';
+export { ARTICULATION_ROOT_API, Attribute, COLLISION_API, ComposeOptions, CrateReader, DEFAULT_METERS_PER_UNIT, DefaultAssetResolver, ExtractOptions, Layer, PACKAGE_NAME, ParseError, RIGID_BODY_API, Relationship, ResolvedXform, TokenizeError, UpAxis, UsdzPackage, VERSION, composeLayer, computeLocalTransform, crateToUsdaFile, createMemoryResolver, driveKindFor, extractRobotDescription, gatherMeshDescendants, getJointAxis, getJointBodies, getJointDrive, getJointLimits, getJointLocalFrame, getJointStatePosition, getJointType, hasArticulationRootAPI, hasCollisionAPI, hasRigidBodyAPI, isMesh, isScope, isXform, iterDescendants, joinPosix, jointValueToSI, normalizeJointLimits, openUsdz, parseOpType, parseUsda, refineJointType, tokenize } from './core.js';
+import * as THREE from 'three';
+import { A as Axis, R as RobotDescription } from './buildKinematicTree-2fg6ZN8m.js';
+export { a as AssetPath, b as AttributeSpec, B as BuildTreeOptions, C as CompositionArc, D as DEG2RAD, J as JointDescription, c as JointDriveDescription, d as JointType, K as KinematicNode, e as KinematicTree, L as LinkDescription, f as ListOp, M as Mat4, g as MetadataMap, P as PrimSpec, h as PropertySpec, Q as Quat, i as RAD2DEG, j as RelationshipSpec, S as SdfPath, k as Specifier, T as TreeEdge, U as UsdDictionary, l as UsdMatrix, m as UsdValue, n as UsdaFile, V as Variability, o as Vec2, p as Vec3, q as Vec4, r as buildKinematicTree, s as fromUsdMatrix, t as getTranslation, u as identity4, v as invert, w as makeEuler, x as makeRotationFromQuat, y as makeRotationX, z as makeRotationY, E as makeRotationZ, F as makeScale, G as makeTranslation, H as multiply, I as multiplyAll } from './buildKinematicTree-2fg6ZN8m.js';
+import { T as ThreeUsdRobot } from './ThreeUsdRobot-lMZHW-it.js';
+export { J as JointObject, L as LinkObject, a as ThreeUsdRobotOptions } from './ThreeUsdRobot-lMZHW-it.js';
+
+/** Unit vector for a USD joint axis token. Returns a fresh vector each call. */
+declare function axisVector(axis: Axis): THREE.Vector3;
+
+/**
+ * Binds `UsdGeom.Mesh` prims to Three.js geometry and attaches them under the
+ * robot's link objects.
+ *
+ * Triangulates polygons with a simple fan, uses authored per-vertex normals
+ * when present (else computes smooth normals), and reads `primvars:st` UVs and
+ * `primvars:displayColor`. Geometry is left in stage units; the global
+ * `metersPerUnit` scale is applied at the root in M9.
+ */
+
+type MeshKind = "visual" | "collision";
+type BindMeshesOptions = {
+    loadVisuals?: boolean;
+    loadCollisions?: boolean;
+};
+/** Build a `BufferGeometry` from a Mesh prim, or `null` if it has no points. */
+declare function buildMeshGeometry(meshPrim: Prim): THREE.BufferGeometry | null;
+/** Build a default material for a Mesh prim from `displayColor` / `doubleSided`. */
+declare function buildMeshMaterial(meshPrim: Prim): THREE.Material;
+/**
+ * Attach visual (and optionally collision) meshes to every link of a built
+ * {@link ThreeUsdRobot}. Each mesh is positioned by its transform relative to
+ * the owning link prim.
+ */
+declare function bindRobotMeshes(stage: Stage, robot3d: ThreeUsdRobot, desc: RobotDescription, options?: BindMeshesOptions): void;
+
+type ThreeUsdRobotLoaderOptions = {
+    /** Resolver for references / payloads / sublayers (default {@link DefaultAssetResolver}). */
+    assetResolver?: AssetResolver;
+    /** Render visual meshes (M6). */
+    loadVisuals?: boolean;
+    /** Render collision meshes (M6). */
+    loadCollisions?: boolean;
+    /** Up-axis correction strategy (M9). */
+    upAxisConversion?: "auto" | "Y" | "Z" | "none";
+    /** Extra uniform scale multiplied with `metersPerUnit` (M9). */
+    unitScale?: number;
+    /** Clamp `setJointValue` to authored limits (default `true`). */
+    clampJointLimits?: boolean;
+    /** Seed joints from drive targets / joint state (M9). */
+    applyDriveTargetsAsInitialPose?: boolean;
+    /** Override the robot name. */
+    robotName?: string;
+    /** Receives non-fatal load diagnostics. */
+    onWarn?: (message: string) => void;
+};
+/**
+ * Loads Isaac Sim / OpenUSD robot assets into a controllable {@link ThreeUsdRobot}.
+ *
+ * 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.
+ */
+declare class ThreeUsdRobotLoader {
+    readonly options: ThreeUsdRobotLoaderOptions;
+    constructor(options?: ThreeUsdRobotLoaderOptions);
+    private get resolver();
+    /**
+     * Fetch an asset by URL and build the robot. `.usdz` packages are unzipped and
+     * composed from their entries; everything else is treated as 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): Promise<ThreeUsdRobot>;
+    /** Parse + compose USDA source into the Three.js-independent robot IR. */
+    parseRobotDescription(text: string, baseUrl?: string): Promise<RobotDescription>;
+    private buildFromStage;
+    private composeStage;
+    private robotOptions;
+    private extractOptions;
+}
+
+export { AssetResolver, Axis, type BindMeshesOptions, type MeshKind, Prim, RobotDescription, Stage, ThreeUsdRobot, ThreeUsdRobotLoader, type ThreeUsdRobotLoaderOptions, axisVector, bindRobotMeshes, buildMeshGeometry, buildMeshMaterial };

package/dist/index.js

@@ -0,0 +1,493 @@
+import { identity4, multiply, computeLocalTransform, invert, DefaultAssetResolver, CrateReader, openUsdz, crateToUsdaFile, Stage, extractRobotDescription, buildKinematicTree, composeLayer } from './chunk-XCP5GZPY.js';
+export { ARTICULATION_ROOT_API, AssetPath, Attribute, COLLISION_API, CrateReader, DEFAULT_METERS_PER_UNIT, DEG2RAD, DefaultAssetResolver, Layer, PACKAGE_NAME, ParseError, Prim, Quat, RAD2DEG, RIGID_BODY_API, Relationship, Stage, TokenizeError, UsdMatrix, VERSION, buildKinematicTree, composeLayer, computeLocalTransform, crateToUsdaFile, createMemoryResolver, driveKindFor, extractRobotDescription, fromUsdMatrix, gatherMeshDescendants, getJointAxis, getJointBodies, getJointDrive, getJointLimits, getJointLocalFrame, getJointStatePosition, getJointType, getTranslation, hasArticulationRootAPI, hasCollisionAPI, hasRigidBodyAPI, identity4, invert, isMesh, isScope, isXform, iterDescendants, joinPosix, jointValueToSI, makeEuler, makeRotationFromQuat, makeRotationX, makeRotationY, makeRotationZ, makeScale, makeTranslation, multiply, multiplyAll, normalizeJointLimits, openUsdz, parseOpType, parseUsda, refineJointType, tokenize } from './chunk-XCP5GZPY.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;
+  jointType;
+  axisToken;
+  axis;
+  lower;
+  upper;
+  _value = 0;
+  constructor(joint) {
+    super();
+    this.name = joint.name;
+    this.jointName = joint.name;
+    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 DEFAULT_COLOR = 10132122;
+function buildMeshGeometry(meshPrim) {
+  const points = meshPrim.GetAttribute("points").Get();
+  if (!isVec3Array(points) || points.length === 0) return null;
+  const geometry = new THREE4.BufferGeometry();
+  geometry.setAttribute("position", new THREE4.Float32BufferAttribute(flat3(points), 3));
+  const counts = meshPrim.GetAttribute("faceVertexCounts").Get();
+  const indices = meshPrim.GetAttribute("faceVertexIndices").Get();
+  if (isNumberArray(counts) && isNumberArray(indices)) {
+    geometry.setIndex(triangulate(counts, indices));
+  } else if (isNumberArray(indices)) {
+    geometry.setIndex(indices.slice());
+  }
+  const normals = meshPrim.GetAttribute("normals").Get();
+  if (isVec3Array(normals) && normals.length === points.length) {
+    geometry.setAttribute("normal", new THREE4.Float32BufferAttribute(flat3(normals), 3));
+  } else {
+    geometry.computeVertexNormals();
+  }
+  const st = meshPrim.GetAttribute("primvars:st").Get();
+  if (isVec2Array(st) && st.length === points.length) {
+    geometry.setAttribute("uv", new THREE4.Float32BufferAttribute(flat2(st), 2));
+  }
+  return geometry;
+}
+function buildMeshMaterial(meshPrim) {
+  const color = new THREE4.Color(DEFAULT_COLOR);
+  const displayColor = meshPrim.GetAttribute("primvars:displayColor").Get();
+  if (isVec3Array(displayColor) && displayColor[0]) {
+    const [r, g, b] = displayColor[0];
+    color.setRGB(r, g, b);
+  }
+  const doubleSided = meshPrim.GetAttribute("doubleSided").Get() === true;
+  return new THREE4.MeshStandardMaterial({
+    color,
+    metalness: 0.1,
+    roughness: 0.8,
+    side: doubleSided ? THREE4.DoubleSide : THREE4.FrontSide
+  });
+}
+function bindRobotMeshes(stage, robot3d, desc, options = {}) {
+  const loadVisuals = options.loadVisuals ?? true;
+  const loadCollisions = options.loadCollisions ?? false;
+  for (const [key, link] of Object.entries(desc.links)) {
+    const linkObj = robot3d.getLinkObject(key);
+    const linkPrim = stage.GetPrimAtPath(link.primPath);
+    if (!linkObj || !linkPrim) continue;
+    const collisionSet = new Set(link.collisionPrims ?? []);
+    if (loadVisuals) {
+      for (const meshPath of link.visualPrims) {
+        if (collisionSet.has(meshPath)) continue;
+        attachMesh(stage, linkPrim, meshPath, linkObj, "visual");
+      }
+    }
+    if (loadCollisions) {
+      for (const meshPath of link.collisionPrims ?? []) {
+        attachMesh(stage, linkPrim, meshPath, linkObj, "collision");
+      }
+    }
+  }
+}
+function attachMesh(stage, linkPrim, meshPath, parent, kind) {
+  const meshPrim = stage.GetPrimAtPath(meshPath);
+  if (!meshPrim) return;
+  const geometry = buildMeshGeometry(meshPrim);
+  if (!geometry) return;
+  const mesh = new THREE4.Mesh(geometry, buildMeshMaterial(meshPrim));
+  mesh.name = meshPrim.GetName();
+  mesh.userData.kind = kind;
+  mesh.userData.primPath = meshPath;
+  if (kind === "collision") mesh.visible = false;
+  mesh.matrixAutoUpdate = false;
+  mesh.matrix.fromArray(relativeTransform(linkPrim, meshPrim));
+  mesh.matrixWorldNeedsUpdate = true;
+  parent.add(mesh);
+}
+function relativeTransform(linkPrim, meshPrim) {
+  const chain = [];
+  let p = meshPrim;
+  const stop = linkPrim.GetPath();
+  while (p && p.GetPath() !== stop) {
+    chain.push(p);
+    p = p.GetParent();
+  }
+  chain.reverse();
+  let m = identity4();
+  for (const prim of chain) {
+    m = multiply(m, computeLocalTransform(prim).matrix);
+  }
+  return m;
+}
+function triangulate(faceVertexCounts, faceVertexIndices) {
+  const tris = [];
+  let offset = 0;
+  for (const count of faceVertexCounts) {
+    for (let k = 2; k < count; k++) {
+      tris.push(
+        faceVertexIndices[offset],
+        faceVertexIndices[offset + k - 1],
+        faceVertexIndices[offset + k]
+      );
+    }
+    offset += count;
+  }
+  return tris;
+}
+function flat3(v) {
+  const out = new Array(v.length * 3);
+  for (let i = 0; i < v.length; i++) {
+    out[i * 3] = v[i][0];
+    out[i * 3 + 1] = v[i][1];
+    out[i * 3 + 2] = v[i][2];
+  }
+  return out;
+}
+function flat2(v) {
+  const out = new Array(v.length * 2);
+  for (let i = 0; i < v.length; i++) {
+    out[i * 2] = v[i][0];
+    out[i * 2 + 1] = v[i][1];
+  }
+  return out;
+}
+function isNumberArray(v) {
+  return Array.isArray(v) && v.every((n) => typeof n === "number");
+}
+function isVec3Array(v) {
+  return Array.isArray(v) && v.every((e) => Array.isArray(e) && e.length === 3);
+}
+function isVec2Array(v) {
+  return Array.isArray(v) && v.every((e) => Array.isArray(e) && e.length === 2);
+}
+var ThreeUsdRobot = class extends THREE4.Object3D {
+  isThreeUsdRobot = true;
+  robot;
+  tree;
+  clampJointLimits;
+  linkObjects = /* @__PURE__ */ new Map();
+  jointObjects = /* @__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.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;
+    if (rootJointKey) {
+      const j = this.robot.joints[rootJointKey];
+      if (j) setMatrix(rootObj, multiply(j.jointFrame0, invert(j.jointFrame1)));
+    }
+    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) this.add(obj);
+    }
+  }
+  // -- Joint control -------------------------------------------------------
+  /** Set one joint value. Unknown joints are ignored. Returns whether it applied. */
+  setJointValue(name, value) {
+    const joint = this.jointObjects.get(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(name);
+      if (joint) {
+        joint.setValue(value, this.clampJointLimits);
+        this.dirty = true;
+      }
+    }
+  }
+  getJointValue(name) {
+    return this.jointObjects.get(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 -------------------------------------------------------------
+  getLinkWorldMatrix(name) {
+    const obj = this.linkObjects.get(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));
+  }
+  getLinkObject(name) {
+    return this.linkObjects.get(name);
+  }
+  getJointObject(name) {
+    return this.jointObjects.get(name);
+  }
+  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;
+  }
+  // -- 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;
+}
+
+// src/three/ThreeUsdRobotLoader.ts
+var ThreeUsdRobotLoader = class {
+  options;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  get resolver() {
+    return this.options.assetResolver ?? new DefaultAssetResolver();
+  }
+  /**
+   * Fetch an asset by URL and build the robot. `.usdz` packages are unzipped and
+   * composed from their entries; everything else is treated as USDA text.
+   */
+  async loadAsync(url) {
+    if (/\.usdz$/i.test(url)) {
+      return this.parseUsdz(await this.fetchRootBytes(url));
+    }
+    const bytes = await this.fetchRootBytes(url);
+    if (CrateReader.isCrate(bytes)) return this.parseCrate(bytes);
+    return this.parse(new TextDecoder().decode(bytes), url);
+  }
+  async fetchRootBytes(url) {
+    const resolver = this.resolver;
+    if (resolver.fetchBytes) return resolver.fetchBytes(url);
+    return new TextEncoder().encode(await resolver.fetchText(url));
+  }
+  /** Build a robot (composed, with meshes) from USDA source text. */
+  async parse(text, baseUrl = "") {
+    return this.buildFromStage(await this.composeStage(text, baseUrl, this.resolver));
+  }
+  /** Build a robot from the bytes of a `.usdz` package. */
+  async parseUsdz(bytes) {
+    const pkg = openUsdz(bytes);
+    const rootText = await pkg.resolver.fetchText(pkg.rootEntry);
+    return this.buildFromStage(await this.composeStage(rootText, pkg.rootEntry, pkg.resolver));
+  }
+  /** Build a robot from the bytes of a binary crate (`.usdc` / binary `.usd`). */
+  parseCrate(bytes) {
+    const file = crateToUsdaFile(new CrateReader(bytes));
+    return Promise.resolve(this.buildFromStage(Stage.OpenFromFile(file)));
+  }
+  /** Parse + compose USDA source into the Three.js-independent robot IR. */
+  async parseRobotDescription(text, baseUrl = "") {
+    const stage = await this.composeStage(text, baseUrl, this.resolver);
+    return extractRobotDescription(stage, this.extractOptions());
+  }
+  buildFromStage(stage) {
+    const robot = extractRobotDescription(stage, this.extractOptions());
+    const tree = buildKinematicTree(robot);
+    const robot3d = new ThreeUsdRobot(robot, tree, this.robotOptions());
+    const loadVisuals = this.options.loadVisuals ?? true;
+    const loadCollisions = this.options.loadCollisions ?? false;
+    if (loadVisuals || loadCollisions) {
+      bindRobotMeshes(stage, robot3d, robot, { loadVisuals, loadCollisions });
+    }
+    return robot3d;
+  }
+  async composeStage(text, baseUrl, resolver) {
+    const composeOptions = this.options.onWarn ? { onWarn: this.options.onWarn } : {};
+    return Stage.OpenFromFile(await composeLayer(text, baseUrl, resolver, composeOptions));
+  }
+  robotOptions() {
+    return {
+      upAxisConversion: this.options.upAxisConversion ?? "auto",
+      ...this.options.clampJointLimits !== void 0 ? { clampJointLimits: this.options.clampJointLimits } : {},
+      ...this.options.unitScale !== void 0 ? { unitScale: this.options.unitScale } : {},
+      ...this.options.applyDriveTargetsAsInitialPose !== void 0 ? { applyInitialPose: this.options.applyDriveTargetsAsInitialPose } : {}
+    };
+  }
+  extractOptions() {
+    return {
+      ...this.options.robotName !== void 0 ? { robotName: this.options.robotName } : {},
+      ...this.options.onWarn !== void 0 ? { onWarn: this.options.onWarn } : {}
+    };
+  }
+};
+
+export { JointObject, LinkObject, ThreeUsdRobot, ThreeUsdRobotLoader, axisVector, bindRobotMeshes, buildMeshGeometry, buildMeshMaterial };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map