three-usd-robot 0.4.0 → 0.5.0

package/dist/chunk-Y3NXBSX3.js

@@ -0,0 +1,841 @@
+import { AssetPath, identity4, multiply, computeLocalTransform, invert, interpolate, DefaultAssetResolver, CrateReader, openUsdz, extractRobotDescription, buildKinematicTree, Stage, composeLayer, composeFile, crateToUsdaFile } from './chunk-36T6YOEX.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;
+  }
+};
+
+// src/three/MaterialBinding.ts
+var DIFFUSE_INPUTS = [
+  "inputs:diffuseColor",
+  // UsdPreviewSurface
+  "inputs:diffuse_color_constant",
+  // OmniPBR
+  "inputs:diffuse_tint",
+  "inputs:base_color",
+  "inputs:baseColor"
+];
+var OPACITY_INPUTS = ["inputs:opacity", "inputs:opacity_constant"];
+var OPACITY_THRESHOLD_INPUTS = ["inputs:opacityThreshold", "inputs:opacity_threshold"];
+var METALLIC_INPUTS = ["inputs:metallic", "inputs:metallic_constant"];
+var ROUGHNESS_INPUTS = ["inputs:roughness", "inputs:reflection_roughness_constant"];
+var EMISSIVE_INPUTS = ["inputs:emissiveColor", "inputs:emissive_color"];
+var SURFACE_OUTPUTS = ["outputs:surface", "outputs:mdl:surface"];
+var TEXTURE_LOOKUPS = {
+  color: {
+    surface: ["inputs:diffuseColor"],
+    direct: ["inputs:diffuse_texture", "inputs:diffuse_color_texture"]
+  },
+  opacity: {
+    surface: ["inputs:opacity"],
+    direct: ["inputs:opacity_texture", "inputs:opacity_color_texture"]
+  },
+  normal: {
+    surface: ["inputs:normal"],
+    direct: ["inputs:normalmap_texture", "inputs:normal_texture"]
+  },
+  roughness: {
+    surface: ["inputs:roughness"],
+    direct: ["inputs:reflectionroughness_texture", "inputs:roughness_texture"]
+  },
+  metalness: {
+    surface: ["inputs:metallic"],
+    direct: ["inputs:metallic_texture"]
+  },
+  occlusion: {
+    surface: ["inputs:occlusion"],
+    direct: ["inputs:ao_texture", "inputs:occlusion_texture"]
+  },
+  emissive: {
+    surface: ["inputs:emissiveColor"],
+    direct: ["inputs:emissive_color_texture", "inputs:emissive_mask_texture"]
+  }
+};
+function resolveBoundMaterial(stage, prim) {
+  const materialPath = findBinding(prim);
+  if (!materialPath) return void 0;
+  const material = stage.GetPrimAtPath(materialPath);
+  if (!material) return void 0;
+  const shader = findSurfaceShader(material);
+  if (!shader) return void 0;
+  const result = {};
+  const color = firstColor(shader, DIFFUSE_INPUTS);
+  if (color) result.color = color;
+  const opacity = firstNumber(shader, OPACITY_INPUTS);
+  if (opacity !== void 0) result.opacity = opacity;
+  const opacityThreshold = firstNumber(shader, OPACITY_THRESHOLD_INPUTS);
+  if (opacityThreshold !== void 0) result.opacityThreshold = opacityThreshold;
+  const metalness = firstNumber(shader, METALLIC_INPUTS);
+  if (metalness !== void 0) result.metalness = metalness;
+  const roughness = firstNumber(shader, ROUGHNESS_INPUTS);
+  if (roughness !== void 0) result.roughness = roughness;
+  const emissive = firstColor(shader, EMISSIVE_INPUTS);
+  if (emissive && shader.GetAttribute("inputs:enable_emission").Get() !== false) {
+    result.emissiveColor = emissive;
+  }
+  const colorTex = findTexture(shader, TEXTURE_LOOKUPS.color);
+  if (colorTex !== void 0) result.colorTexture = colorTex;
+  const opacityTex = findTexture(shader, TEXTURE_LOOKUPS.opacity);
+  if (opacityTex !== void 0) result.opacityTexture = opacityTex;
+  const normal = findTexture(shader, TEXTURE_LOOKUPS.normal);
+  if (normal !== void 0) result.normalTexture = normal;
+  const roughTex = findTexture(shader, TEXTURE_LOOKUPS.roughness);
+  if (roughTex !== void 0) result.roughnessTexture = roughTex;
+  const metalTex = findTexture(shader, TEXTURE_LOOKUPS.metalness);
+  if (metalTex !== void 0) result.metalnessTexture = metalTex;
+  const aoTex = findTexture(shader, TEXTURE_LOOKUPS.occlusion);
+  if (aoTex !== void 0) result.occlusionTexture = aoTex;
+  const emissiveTex = findTexture(shader, TEXTURE_LOOKUPS.emissive);
+  if (emissiveTex !== void 0) result.emissiveTexture = emissiveTex;
+  return result;
+}
+function findTexture(shader, lookup) {
+  for (const name of lookup.direct) {
+    const v = shader.GetAttribute(name).Get();
+    if (v instanceof AssetPath && v.path) return { path: v.path };
+  }
+  for (const name of lookup.surface) {
+    const conn = shader.GetAttribute(name).GetConnections()[0];
+    if (!conn) continue;
+    const texPrim = shader.GetStage().GetPrimAtPath(conn.split(".")[0]);
+    if (!texPrim) continue;
+    const file = texPrim.GetAttribute("inputs:file").Get();
+    if (file instanceof AssetPath && file.path) return readUvTexture(texPrim, file.path);
+  }
+  return void 0;
+}
+var WRAP_VALUES = /* @__PURE__ */ new Set(["repeat", "clamp", "mirror", "black"]);
+function readUvTexture(texPrim, path) {
+  const tex = { path };
+  const wrapS = texPrim.GetAttribute("inputs:wrapS").Get();
+  if (typeof wrapS === "string" && WRAP_VALUES.has(wrapS)) tex.wrapS = wrapS;
+  const wrapT = texPrim.GetAttribute("inputs:wrapT").Get();
+  if (typeof wrapT === "string" && WRAP_VALUES.has(wrapT)) tex.wrapT = wrapT;
+  const scale = numArray(texPrim, "inputs:scale", 4);
+  if (scale) tex.scale = scale;
+  const bias = numArray(texPrim, "inputs:bias", 4);
+  if (bias) tex.bias = bias;
+  const transform = readTransform2d(texPrim);
+  if (transform) tex.transform = transform;
+  return tex;
+}
+function readTransform2d(texPrim) {
+  const conn = texPrim.GetAttribute("inputs:st").GetConnections()[0];
+  if (!conn) return void 0;
+  const node = texPrim.GetStage().GetPrimAtPath(conn.split(".")[0]);
+  if (!node || node.GetAttribute("info:id").Get() !== "UsdTransform2d") return void 0;
+  const transform = {};
+  const translation = numArray(node, "inputs:translation", 2);
+  if (translation) transform.translation = translation;
+  const scale = numArray(node, "inputs:scale", 2);
+  if (scale) transform.scale = scale;
+  const rotation = node.GetAttribute("inputs:rotation").Get();
+  if (typeof rotation === "number") transform.rotation = rotation;
+  return Object.keys(transform).length > 0 ? transform : void 0;
+}
+function numArray(prim, name, length) {
+  const v = prim.GetAttribute(name).Get();
+  if (Array.isArray(v) && v.length >= length && v.every((n) => typeof n === "number")) {
+    return v.slice(0, length);
+  }
+  return void 0;
+}
+function findBinding(prim) {
+  let p = prim;
+  while (p) {
+    const targets = p.GetRelationship("material:binding").GetTargets();
+    if (targets.length > 0) return targets[0];
+    p = p.GetParent();
+  }
+  return void 0;
+}
+function findSurfaceShader(material) {
+  for (const out of SURFACE_OUTPUTS) {
+    const conn = material.GetAttribute(out).GetConnections()[0];
+    if (conn) {
+      const shaderPath = conn.split(".")[0];
+      const shader = material.GetStage().GetPrimAtPath(shaderPath);
+      if (shader) return shader;
+    }
+  }
+  return material.GetChildren().find((c) => c.GetTypeName() === "Shader") ?? void 0;
+}
+function firstColor(shader, names) {
+  for (const name of names) {
+    const v = shader.GetAttribute(name).Get();
+    if (Array.isArray(v) && v.length >= 3 && v.every((n) => typeof n === "number")) {
+      return [v[0], v[1], v[2]];
+    }
+  }
+  return void 0;
+}
+function firstNumber(shader, names) {
+  for (const name of names) {
+    const v = shader.GetAttribute(name).Get();
+    if (typeof v === "number") return v;
+  }
+  return void 0;
+}
+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, stage, textures) {
+  const color = new THREE4.Color(DEFAULT_COLOR);
+  let opacity = 1;
+  const bound = stage ? resolveBoundMaterial(stage, meshPrim) : void 0;
+  if (bound?.color) {
+    color.setRGB(bound.color[0], bound.color[1], bound.color[2]);
+  } else {
+    const displayColor = meshPrim.GetAttribute("primvars:displayColor").Get();
+    if (isVec3Array(displayColor) && displayColor[0]) {
+      const [r, g, b] = displayColor[0];
+      color.setRGB(r, g, b);
+    }
+  }
+  if (bound?.opacity !== void 0) opacity = bound.opacity;
+  const tex = (rt, cs) => rt && textures ? textures(rt.path, {
+    colorSpace: cs,
+    ...rt.wrapS ? { wrapS: rt.wrapS } : {},
+    ...rt.wrapT ? { wrapT: rt.wrapT } : {},
+    ...rt.transform ? { transform: rt.transform } : {}
+  }) : null;
+  const map = tex(bound?.colorTexture, "srgb");
+  if (map) {
+    const s = bound?.colorTexture?.scale;
+    if (s) color.setRGB(s[0], s[1], s[2]);
+    else color.setRGB(1, 1, 1);
+  }
+  const normalMap = tex(bound?.normalTexture, "linear");
+  const roughnessMap = tex(bound?.roughnessTexture, "linear");
+  const metalnessMap = tex(bound?.metalnessTexture, "linear");
+  const aoMap = tex(bound?.occlusionTexture, "linear");
+  const emissiveMap = tex(bound?.emissiveTexture, "srgb");
+  const metalness = bound?.metalness ?? bound?.metalnessTexture?.scale?.[0] ?? (metalnessMap ? 1 : 0.1);
+  const roughness = bound?.roughness ?? bound?.roughnessTexture?.scale?.[0] ?? (roughnessMap ? 1 : 0.8);
+  const emissive = new THREE4.Color(0);
+  if (bound?.emissiveColor) {
+    emissive.setRGB(bound.emissiveColor[0], bound.emissiveColor[1], bound.emissiveColor[2]);
+  } else if (emissiveMap) {
+    emissive.setRGB(1, 1, 1);
+  }
+  const opacityTex = bound?.opacityTexture;
+  const sharesColorMap = !!(opacityTex && opacityTex.path === bound?.colorTexture?.path);
+  const alphaMap = sharesColorMap ? null : tex(opacityTex, "linear");
+  const hasAlphaSource = opacity < 1 || sharesColorMap || !!alphaMap;
+  const threshold = bound?.opacityThreshold;
+  const alphaTest = threshold !== void 0 && threshold > 0 ? threshold : 0;
+  const transparent = alphaTest === 0 && hasAlphaSource;
+  const doubleSided = meshPrim.GetAttribute("doubleSided").Get() === true;
+  return new THREE4.MeshStandardMaterial({
+    color,
+    metalness,
+    roughness,
+    emissive,
+    transparent,
+    opacity,
+    ...alphaTest > 0 ? { alphaTest } : {},
+    side: doubleSided ? THREE4.DoubleSide : THREE4.FrontSide,
+    ...map ? { map } : {},
+    ...alphaMap ? { alphaMap } : {},
+    ...normalMap ? { normalMap } : {},
+    ...roughnessMap ? { roughnessMap } : {},
+    ...metalnessMap ? { metalnessMap } : {},
+    ...aoMap ? { aoMap } : {},
+    ...emissiveMap ? { emissiveMap } : {}
+  });
+}
+function bindRobotMeshes(stage, robot3d, desc, options = {}) {
+  const loadVisuals = options.loadVisuals ?? true;
+  const loadCollisions = options.loadCollisions ?? false;
+  const textures = options.textureProvider;
+  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", textures);
+      }
+    }
+    if (loadCollisions) {
+      for (const meshPath of link.collisionPrims ?? []) {
+        attachMesh(stage, linkPrim, meshPath, linkObj, "collision", textures);
+      }
+    }
+  }
+}
+function attachMesh(stage, linkPrim, meshPath, parent, kind, textures) {
+  const meshPrim = stage.GetPrimAtPath(meshPath);
+  if (!meshPrim) return;
+  const geometry = buildMeshGeometry(meshPrim);
+  if (!geometry) return;
+  const mesh = new THREE4.Mesh(geometry, buildMeshMaterial(meshPrim, stage, textures));
+  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 DEG2RAD = Math.PI / 180;
+function createTextureProvider(resolver, baseUrl) {
+  const images = /* @__PURE__ */ new Map();
+  const imageFor = (url) => {
+    let p = images.get(url);
+    if (!p) {
+      p = loadImage(resolver, url);
+      images.set(url, p);
+    }
+    return p;
+  };
+  return (assetPath, options = {}) => {
+    let url;
+    try {
+      url = resolver.resolve(assetPath, baseUrl);
+    } catch {
+      return null;
+    }
+    const texture = new THREE4.Texture();
+    texture.colorSpace = options.colorSpace === "linear" ? THREE4.NoColorSpace : THREE4.SRGBColorSpace;
+    texture.wrapS = toThreeWrap(options.wrapS);
+    texture.wrapT = toThreeWrap(options.wrapT);
+    applyTransform(texture, options.transform);
+    imageFor(url).then((image) => {
+      texture.image = image;
+      texture.needsUpdate = true;
+    }).catch(() => {
+    });
+    return texture;
+  };
+}
+async function loadImage(resolver, url) {
+  const bytes = resolver.fetchBytes ? await resolver.fetchBytes(url) : new TextEncoder().encode(await resolver.fetchText(url));
+  const blob = new Blob([bytes], { type: mimeOf(url) });
+  const objectUrl = URL.createObjectURL(blob);
+  try {
+    return await new Promise((resolve, reject) => {
+      const img = new Image();
+      img.onload = () => resolve(img);
+      img.onerror = () => reject(new Error(`failed to decode texture: ${url}`));
+      img.src = objectUrl;
+    });
+  } finally {
+    URL.revokeObjectURL(objectUrl);
+  }
+}
+function toThreeWrap(wrap) {
+  switch (wrap) {
+    case "clamp":
+    case "black":
+      return THREE4.ClampToEdgeWrapping;
+    case "mirror":
+      return THREE4.MirroredRepeatWrapping;
+    default:
+      return THREE4.RepeatWrapping;
+  }
+}
+function applyTransform(texture, t) {
+  if (!t) return;
+  if (t.scale) texture.repeat.set(t.scale[0], t.scale[1]);
+  if (t.translation) texture.offset.set(t.translation[0], t.translation[1]);
+  if (t.rotation !== void 0) {
+    texture.rotation = t.rotation * DEG2RAD;
+    texture.center.set(0, 0);
+  }
+}
+function mimeOf(url) {
+  if (/\.jpe?g$/i.test(url)) return "image/jpeg";
+  if (/\.webp$/i.test(url)) return "image/webp";
+  return "image/png";
+}
+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;
+  }
+  // -- 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;
+}
+
+// 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 sniffed for the crate magic
+   * and parsed as binary USDC or USDA text.
+   */
+  async loadAsync(url) {
+    const bytes = await this.fetchRootBytes(url);
+    if (/\.usdz$/i.test(url)) return this.parseUsdz(bytes);
+    if (CrateReader.isCrate(bytes)) return this.parseCrate(bytes, url);
+    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),
+      baseUrl,
+      this.resolver
+    );
+  }
+  /** Build a robot from the bytes of a `.usdz` package. */
+  async parseUsdz(bytes) {
+    const pkg = openUsdz(bytes);
+    const rootBytes = await pkg.resolver.fetchBytes(pkg.rootEntry);
+    const stage = await this.composeStageFromBytes(rootBytes, pkg.rootEntry, pkg.resolver);
+    return this.buildFromStage(stage, pkg.rootEntry, pkg.resolver);
+  }
+  /** Build a robot from the bytes of a binary crate (`.usdc` / binary `.usd`). */
+  async parseCrate(bytes, baseUrl = "") {
+    const stage = await this.composeStageFromBytes(bytes, baseUrl, this.resolver);
+    return this.buildFromStage(stage, baseUrl, this.resolver);
+  }
+  /** 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, baseUrl, resolver) {
+    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) {
+      const textureProvider = this.options.loadTextures ?? true ? createTextureProvider(resolver, baseUrl) : void 0;
+      bindRobotMeshes(stage, robot3d, robot, {
+        loadVisuals,
+        loadCollisions,
+        ...textureProvider ? { textureProvider } : {}
+      });
+    }
+    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));
+  }
+  /** Compose a layer from raw bytes, sniffing binary crate vs USDA text. */
+  async composeStageFromBytes(bytes, baseUrl, resolver) {
+    const composeOptions = this.options.onWarn ? { onWarn: this.options.onWarn } : {};
+    const composed = CrateReader.isCrate(bytes) ? await composeFile(
+      crateToUsdaFile(new CrateReader(bytes)),
+      baseUrl,
+      resolver,
+      composeOptions
+    ) : await composeLayer(new TextDecoder().decode(bytes), baseUrl, resolver, composeOptions);
+    return Stage.OpenFromFile(composed);
+  }
+  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, createTextureProvider, resolveBoundMaterial };
+//# sourceMappingURL=chunk-Y3NXBSX3.js.map
+//# sourceMappingURL=chunk-Y3NXBSX3.js.map