three-usd-robot 0.4.0 → 0.6.0

package/dist/index.js

@@ -1,664 +1,304 @@
-import { AssetPath, identity4, multiply, computeLocalTransform, invert, interpolate, DefaultAssetResolver, CrateReader, openUsdz, crateToUsdaFile, composeFile, Stage, extractRobotDescription, buildKinematicTree, composeLayer } from './chunk-FYVZ7YPW.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, channelFromSamples, composeFile, composeLayer, computeLocalTransform, crateToUsdaFile, createMemoryResolver, driveKindFor, extractRobotDescription, fromUsdMatrix, gatherMeshDescendants, getJointAxis, getJointBodies, getJointDrive, getJointLimits, getJointLocalFrame, getJointStatePosition, getJointType, getTranslation, hasArticulationRootAPI, hasCollisionAPI, hasRigidBodyAPI, identity4, interpolate, invert, isMesh, isScope, isXform, iterDescendants, joinPosix, jointValueToSI, makeEuler, makeRotationFromQuat, makeRotationX, makeRotationY, makeRotationZ, makeScale, makeTranslation, multiply, multiplyAll, normalizeJointLimits, openUsdz, parseOpType, parseUsda, refineJointType, tokenize } from './chunk-FYVZ7YPW.js';
-import * as THREE4 from 'three';
+import { stageGeometryProvider, exportRobotUsda } from './chunk-JZMCABQO.js';
+export { PACKAGE_NAME, VERSION, exportRobotUsda, stageGeometryProvider, validateRobotDescription, writeUsdz } from './chunk-JZMCABQO.js';
+export { JointObject, LinkObject, ThreeUsdRobot, ThreeUsdRobotLoader, axisVector, bindRobotMeshes, bindSceneMeshes, buildMeshGeometry, buildMeshMaterial, createTextureProvider } from './chunk-YVWSO27W.js';
+import { identity4, refineJointType, multiply, invert, buildKinematicTree } from './chunk-4MEZM763.js';
+export { ARTICULATION_ROOT_API, AssetPath, Attribute, COLLISION_API, CrateReader, DEFAULT_METERS_PER_UNIT, DEG2RAD, DefaultAssetResolver, Layer, MASS_API, MESH_COLLISION_API, PHYSICS_MATERIAL_API, ParseError, Prim, Quat, RAD2DEG, RIGID_BODY_API, Relationship, Stage, TokenizeError, UsdMatrix, buildKinematicTree, channelFromSamples, composeFile, composeLayer, computeLocalTransform, computeWorldTransform, crateToUsdaFile, createMemoryResolver, decomposeRigid, driveKindFor, extractRobotDescription, fromUsdMatrix, gatherMeshDescendants, getJointAxis, getJointBodies, getJointDrive, getJointLimits, getJointLocalFrame, getJointStatePosition, getJointType, getMassProperties, getTranslation, hasArticulationRootAPI, hasCollisionAPI, hasRigidBodyAPI, identity4, interpolate, invert, isMesh, isScope, isXform, iterDescendants, joinPosix, jointValueFromSI, jointValueToSI, makeEuler, makeRotationFromQuat, makeRotationX, makeRotationY, makeRotationZ, makeScale, makeTranslation, multiply, multiplyAll, normalizeJointLimits, openUsdz, parseOpType, parseUsda, refineJointType, resolveBoundMaterial, serializeUsda, toUsdMatrix, tokenize } from './chunk-4MEZM763.js';
+import * as THREE 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 METALLIC_INPUTS = ["inputs:metallic", "inputs:metallic_constant"];
-var ROUGHNESS_INPUTS = ["inputs:roughness", "inputs:reflection_roughness_constant"];
-var SURFACE_OUTPUTS = ["outputs:surface", "outputs:mdl:surface"];
-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 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 texture = findDiffuseTexture(shader);
-  if (texture !== void 0) result.colorTexture = texture;
-  return result;
-}
-var DIFFUSE_TEXTURE_INPUTS = ["inputs:diffuse_texture", "inputs:diffuse_color_texture"];
-function findDiffuseTexture(shader) {
-  for (const name of DIFFUSE_TEXTURE_INPUTS) {
-    const v = shader.GetAttribute(name).Get();
-    if (v instanceof AssetPath && v.path) return v.path;
-  }
-  const conn = shader.GetAttribute("inputs:diffuseColor").GetConnections()[0];
-  if (conn) {
-    const texPrim = shader.GetStage().GetPrimAtPath(conn.split(".")[0]);
-    const file = texPrim?.GetAttribute("inputs:file").Get();
-    if (file instanceof AssetPath && file.path) return file.path;
-  }
-  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]];
+function geometryToExportMesh(geometry, options) {
+  const position = geometry.getAttribute("position");
+  if (!position || position.count === 0) return null;
+  const points = [];
+  for (let i = 0; i < position.count; i++) {
+    points.push([position.getX(i), position.getY(i), position.getZ(i)]);
+  }
+  const index = geometry.getIndex();
+  let faceVertexIndices = index ? Array.from(index.array) : points.map((_, i) => i);
+  const triangles = Math.floor(faceVertexIndices.length / 3);
+  if (triangles === 0) return null;
+  faceVertexIndices = faceVertexIndices.slice(0, triangles * 3);
+  const mesh = {
+    name: options.name,
+    kind: options.kind ?? "visual",
+    points,
+    faceVertexCounts: new Array(triangles).fill(3),
+    faceVertexIndices
+  };
+  const normal = geometry.getAttribute("normal");
+  if (normal && normal.count === position.count) {
+    const normals = [];
+    for (let i = 0; i < normal.count; i++) {
+      normals.push([normal.getX(i), normal.getY(i), normal.getZ(i)]);
     }
-  }
-  return void 0;
+    mesh.normals = normals;
+  }
+  const uv = geometry.getAttribute("uv");
+  if (uv && uv.count === position.count) {
+    const st = [];
+    for (let i = 0; i < uv.count; i++) st.push([uv.getX(i), uv.getY(i)]);
+    mesh.st = st;
+  }
+  if (options.transform && !isIdentityMat4(options.transform)) mesh.transform = options.transform;
+  if (options.material) mesh.material = options.material;
+  if (options.doubleSided) mesh.doubleSided = true;
+  return mesh;
 }
-function firstNumber(shader, names) {
-  for (const name of names) {
-    const v = shader.GetAttribute(name).Get();
-    if (typeof v === "number") return v;
-  }
-  return void 0;
-}
-
-// src/three/MeshBinding.ts
-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));
+function materialToExportMaterial(material, name, onWarn) {
+  const std = material;
+  if (!std.isMeshStandardMaterial) {
+    onWarn?.(`material "${name}": only MeshStandardMaterial exports to UsdPreviewSurface; skipped`);
+    return void 0;
+  }
+  if (std.map || std.normalMap || std.roughnessMap || std.metalnessMap || std.aoMap || std.emissiveMap || std.alphaMap) {
+    onWarn?.(
+      `material "${name}": texture maps are not carried from Three.js materials (image extraction is app-side); constants only`
+    );
   }
-  return geometry;
-}
-function buildMeshMaterial(meshPrim, stage, textures) {
-  const color = new THREE4.Color(DEFAULT_COLOR);
-  let metalness = 0.1;
-  let roughness = 0.8;
-  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);
-    }
+  const out = {
+    name,
+    diffuseColor: [std.color.r, std.color.g, std.color.b],
+    metallic: std.metalness,
+    roughness: std.roughness
+  };
+  if (std.transparent && std.opacity < 1) out.opacity = std.opacity;
+  if (std.emissive.r > 0 || std.emissive.g > 0 || std.emissive.b > 0) {
+    out.emissiveColor = [std.emissive.r, std.emissive.g, std.emissive.b];
   }
-  if (bound?.metalness !== void 0) metalness = bound.metalness;
-  if (bound?.roughness !== void 0) roughness = bound.roughness;
-  if (bound?.opacity !== void 0) opacity = bound.opacity;
-  const map = bound?.colorTexture && textures ? textures(bound.colorTexture) : null;
-  if (map) color.setRGB(1, 1, 1);
-  const doubleSided = meshPrim.GetAttribute("doubleSided").Get() === true;
-  return new THREE4.MeshStandardMaterial({
-    color,
-    metalness,
-    roughness,
-    transparent: opacity < 1,
-    opacity,
-    side: doubleSided ? THREE4.DoubleSide : THREE4.FrontSide,
-    ...map ? { map } : {}
-  });
+  return out;
 }
-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);
-      }
+function threeGeometryProvider(robot, onWarn) {
+  const materialNames = /* @__PURE__ */ new Map();
+  let autoId = 0;
+  const convertMaterial = (material) => {
+    if (!materialNames.has(material)) {
+      const name = material.name || `Material_${autoId++}`;
+      materialNames.set(material, materialToExportMaterial(material, name, onWarn));
     }
-    if (loadCollisions) {
-      for (const meshPath of link.collisionPrims ?? []) {
-        attachMesh(stage, linkPrim, meshPath, linkObj, "collision", textures);
+    return materialNames.get(material);
+  };
+  return (linkKey) => {
+    const linkObj = robot.getLinkObject(linkKey);
+    if (!linkObj) return [];
+    const out = [];
+    for (const childObj of linkObj.children) {
+      const meshObj = childObj;
+      if (!meshObj.isMesh) continue;
+      const material = Array.isArray(meshObj.material) ? meshObj.material[0] : meshObj.material;
+      if (Array.isArray(meshObj.material) && meshObj.material.length > 1) {
+        onWarn?.(`mesh "${meshObj.name}": multi-material meshes export their first material only`);
       }
+      const exportMaterial = material ? convertMaterial(material) : void 0;
+      const mesh = geometryToExportMesh(meshObj.geometry, {
+        name: meshObj.name || "mesh",
+        kind: meshObj.userData.kind === "collision" ? "collision" : "visual",
+        transform: [...meshObj.matrix.elements],
+        ...exportMaterial ? { material: exportMaterial } : {},
+        doubleSided: material?.side === THREE.DoubleSide
+      });
+      if (mesh) out.push(mesh);
     }
-  }
-}
-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);
+    return out;
+  };
 }
-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 exportThreeUsdRobot(robot, options = {}) {
+  const { stage, ...rest } = options;
+  const geometry = stage ? stageGeometryProvider(stage) : threeGeometryProvider(robot, options.onWarn);
+  return exportRobotUsda(robot.robot, { ...rest, geometry });
 }
-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;
+function isIdentityMat4(m) {
+  for (let i = 0; i < 16; i++) {
+    if (m[i] !== (i % 5 === 0 ? 1 : 0)) return false;
   }
-  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;
+  return true;
 }
-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);
-}
-function createTextureProvider(resolver, baseUrl) {
-  const loader = new THREE4.TextureLoader();
-  const cache = /* @__PURE__ */ new Map();
-  return (assetPath) => {
-    let url;
-    try {
-      url = resolver.resolve(assetPath, baseUrl);
-    } catch {
-      return null;
-    }
-    const cached = cache.get(url);
-    if (cached) return cached;
-    const texture = loader.load(url);
-    texture.colorSpace = THREE4.SRGBColorSpace;
-    texture.wrapS = THREE4.RepeatWrapping;
-    texture.wrapT = THREE4.RepeatWrapping;
-    cache.set(url, texture);
-    return texture;
-  };
-}
-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;
+
+// src/three/RobotBuilder.ts
+var RobotBuilder = class {
+  robotName;
+  upAxis;
+  metersPerUnit;
+  articulationRoot;
+  warn;
+  links = /* @__PURE__ */ new Map();
+  joints = /* @__PURE__ */ new Map();
+  materialCache = /* @__PURE__ */ new Map();
+  materialAutoId = 0;
+  constructor(options) {
+    this.robotName = options.name;
+    this.upAxis = options.upAxis ?? "Z";
+    this.metersPerUnit = options.metersPerUnit ?? 1;
+    if (options.articulationRoot !== void 0) this.articulationRoot = options.articulationRoot;
+    this.warn = options.onWarn ?? (() => {
+    });
   }
-  /** 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;
-      }
+  addLink(options) {
+    if (this.links.has(options.name)) {
+      throw new Error(`RobotBuilder: link "${options.name}" is already defined`);
     }
+    const world = resolveFrame(options.frame) ?? identity4();
+    const collisionExtras = {
+      ...options.collisionApproximation !== void 0 ? { approximation: options.collisionApproximation } : {},
+      ...options.physicsMaterial ? { material: options.physicsMaterial } : {}
+    };
+    const meshes = [
+      ...this.gatherMeshes(options.visuals ?? [], world, "visual"),
+      ...this.gatherMeshes(options.collisions ?? [], world, "collision", collisionExtras)
+    ];
+    this.links.set(options.name, {
+      world,
+      meshes,
+      ...options.inertial ? { inertial: options.inertial } : {}
+    });
+    return this;
   }
-  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;
+  addFixedJoint(options) {
+    return this.addJoint("fixed", options);
   }
-  // -- Animation playback --------------------------------------------------
-  /** Playback rate in time codes per second (from the stage; default 24). */
-  getTimeCodesPerSecond() {
-    return this.robot.timeCodesPerSecond ?? 24;
+  addRevoluteJoint(options) {
+    return this.addJoint("revolute", options);
   }
-  /** Whether any joint has a time-sampled trajectory. */
-  hasAnimation() {
-    return Object.values(this.robot.joints).some((j) => j.valueSamples !== void 0);
+  addPrismaticJoint(options) {
+    return this.addJoint("prismatic", options);
   }
-  /**
-   * 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 };
+  addJoint(type, options) {
+    if (this.joints.has(options.name)) {
+      throw new Error(`RobotBuilder: joint "${options.name}" is already defined`);
     }
-    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));
+    const world = resolveFrame(options.frame);
+    this.joints.set(options.name, { type, options, ...world ? { world } : {} });
+    return this;
+  }
+  /** Assemble the IR + geometry provider (validates the kinematic graph). */
+  build() {
+    const links = {};
+    for (const [name, link] of this.links) {
+      links[name] = {
+        name,
+        primPath: `/${this.robotName}/${name}`,
+        visualPrims: [],
+        ...link.inertial ? { inertial: link.inertial } : {},
+        // Authored placement, so links no joint reaches keep their build pose.
+        ...isIdentityMat42(link.world) ? {} : { worldTransform: link.world }
+      };
     }
-  }
-  // -- 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);
+    const joints = {};
+    for (const [name, pending] of this.joints) {
+      const { options } = pending;
+      const parent = options.parent ?? "";
+      if (parent !== "" && !this.links.has(parent)) {
+        throw new Error(`RobotBuilder: joint "${name}" references unknown parent "${parent}"`);
       }
-    }
-    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);
+      const childLink = this.links.get(options.child);
+      if (!childLink) {
+        throw new Error(
+          `RobotBuilder: joint "${name}" references unknown child "${options.child}"`
+        );
       }
+      const jointWorld = pending.world ?? childLink.world;
+      const parentWorld = parent === "" ? identity4() : this.links.get(parent).world;
+      const type = refineJointType(pending.type, options.lower, options.upper);
+      joints[name] = {
+        name,
+        primPath: `/${this.robotName}/${name}`,
+        type,
+        parent,
+        child: options.child,
+        axis: options.axis ?? "X",
+        jointFrame0: multiply(invert(parentWorld), jointWorld),
+        jointFrame1: multiply(invert(childLink.world), jointWorld),
+        ...options.lower !== void 0 ? { lower: options.lower } : {},
+        ...options.upper !== void 0 ? { upper: options.upper } : {},
+        ...options.initialValue !== void 0 ? { initialValue: options.initialValue } : {},
+        ...options.drive ? { drive: options.drive } : {}
+      };
     }
-    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));
+    if (this.articulationRoot !== void 0 && !this.links.has(this.articulationRoot)) {
+      throw new Error(`RobotBuilder: articulationRoot "${this.articulationRoot}" is not a link`);
     }
-    const bytes = await this.fetchRootBytes(url);
-    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 rootText = await pkg.resolver.fetchText(pkg.rootEntry);
-    const stage = await this.composeStage(rootText, 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 file = crateToUsdaFile(new CrateReader(bytes));
-    const composeOptions = this.options.onWarn ? { onWarn: this.options.onWarn } : {};
-    const composed = await composeFile(file, baseUrl, this.resolver, composeOptions);
-    return this.buildFromStage(Stage.OpenFromFile(composed), 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 } : {}
+    const desc = {
+      name: this.robotName,
+      rootLink: "",
+      links,
+      joints,
+      upAxis: this.upAxis,
+      metersPerUnit: this.metersPerUnit,
+      ...this.articulationRoot !== void 0 ? { articulationRoots: [this.articulationRoot] } : {}
+    };
+    const tree = buildKinematicTree(desc, { onWarn: this.warn });
+    desc.rootLink = tree.root;
+    if (tree.loopJoints.length > 0) desc.loopJoints = tree.loopJoints;
+    if (tree.warnings.length > 0) desc.warnings = tree.warnings;
+    const byLink = this.links;
+    const geometry = (linkKey) => byLink.get(linkKey)?.meshes ?? [];
+    return { desc, geometry, tree };
+  }
+  /** Build and export in one step (pass the result to `serializeUsda`). */
+  toUsda(options = {}) {
+    const { desc, geometry } = this.build();
+    return exportRobotUsda(desc, { onWarn: this.warn, ...options, geometry });
+  }
+  /** Collect `THREE.Mesh` descendants of `roots` as link-relative export meshes. */
+  gatherMeshes(roots, linkWorld, kind, collisionExtras = {}) {
+    const linkInverse = invert(linkWorld);
+    const out = [];
+    for (const root of roots) {
+      root.updateWorldMatrix(true, true);
+      root.traverse((obj) => {
+        const meshObj = obj;
+        if (!meshObj.isMesh) return;
+        const material = Array.isArray(meshObj.material) ? meshObj.material[0] : meshObj.material;
+        if (Array.isArray(meshObj.material) && meshObj.material.length > 1) {
+          this.warn(
+            `mesh "${meshObj.name}": multi-material meshes export their first material only`
+          );
+        }
+        const exportMaterial = material ? this.convertMaterial(material) : void 0;
+        const mesh = geometryToExportMesh(meshObj.geometry, {
+          name: meshObj.name || "mesh",
+          kind,
+          transform: multiply(linkInverse, [...meshObj.matrixWorld.elements]),
+          ...exportMaterial ? { material: exportMaterial } : {},
+          doubleSided: material?.side === THREE.DoubleSide
+        });
+        if (mesh) {
+          if (kind === "collision") {
+            if (collisionExtras.approximation !== void 0) {
+              mesh.collisionApproximation = collisionExtras.approximation;
+            }
+            if (collisionExtras.material) mesh.physicsMaterial = collisionExtras.material;
+          }
+          out.push(mesh);
+        } else {
+          this.warn(`mesh "${meshObj.name}": no triangle geometry; skipped`);
+        }
       });
     }
-    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));
+    return out;
   }
-  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 } : {}
-    };
+  convertMaterial(material) {
+    if (!this.materialCache.has(material)) {
+      const name = material.name || `Material_${this.materialAutoId++}`;
+      this.materialCache.set(material, materialToExportMaterial(material, name, this.warn));
+    }
+    return this.materialCache.get(material);
   }
 };
+function isIdentityMat42(m) {
+  for (let i = 0; i < 16; i++) {
+    if (m[i] !== (i % 5 === 0 ? 1 : 0)) return false;
+  }
+  return true;
+}
+function resolveFrame(frame) {
+  if (!frame) return void 0;
+  if (frame.isObject3D) {
+    const obj = frame;
+    obj.updateWorldMatrix(true, false);
+    return [...obj.matrixWorld.elements];
+  }
+  return [...frame.elements];
+}
 
-export { JointObject, LinkObject, ThreeUsdRobot, ThreeUsdRobotLoader, axisVector, bindRobotMeshes, buildMeshGeometry, buildMeshMaterial, createTextureProvider, resolveBoundMaterial };
+export { RobotBuilder, exportThreeUsdRobot, geometryToExportMesh, materialToExportMaterial, threeGeometryProvider };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map