three-usd-robot 0.2.0 → 0.3.0

package/README.md

@@ -10,11 +10,13 @@ and drives forward kinematics on a Three.js `Object3D` hierarchy.
 
 > 🚧 **Status: v0.2 + USDC.** Loads **ASCII `.usda`**, **binary `.usdc` / `.usd`
 > (crate)**, and **`.usdz`** robots — including multi-file assets via
-> references/payloads/sublayers — drives forward kinematics with meshes,
-> normalizes up-axis & units, and seeds the initial pose from joint drives. The
+> references/payloads/sublayers, **variant selections**, and **instanceable**
+> prims (internal-reference prototypes) — drives forward kinematics with meshes,
+> applies flat **`UsdShade` material colors** (UsdPreviewSurface / OmniPBR
+> constants), normalizes up-axis & units, and seeds the initial pose. The
 > crate reader is a from-scratch TypeScript implementation (no OpenUSD/WASM
-> dependency). Not yet: variants, instancing, and time-sampled (animated)
-> values (see [`MILESTONES.md`](./MILESTONES.md), M10–M11).
+> dependency). Not yet: variant resolution inside binary crate, and time-sampled
+> (animated) values.
 
 ```ts
 // .usda / .usdc / binary .usd / .usdz are all auto-detected:

package/dist/{ThreeUsdRobot-lMZHW-it.d.ts → ThreeUsdRobot-C6uqpNZA.d.ts}

@@ -1,5 +1,5 @@
 import * as THREE from 'three';
-import { d as JointType, A as Axis, J as JointDescription, L as LinkDescription, R as RobotDescription, e as KinematicTree } from './buildKinematicTree-2fg6ZN8m.js';
+import { J as JointType, A as Axis, a as JointDescription, L as LinkDescription, R as RobotDescription, K as KinematicTree } from './buildKinematicTree-BJuC_-5_.js';
 
 /**
  * The articulated "motion" node of a joint, inserted between the joint's two

package/dist/{buildKinematicTree-2fg6ZN8m.d.ts → buildKinematicTree-BJuC_-5_.d.ts}

@@ -80,9 +80,22 @@ type PrimSpec = {
     metadata: MetadataMap;
     properties: PropertySpec[];
     children: PrimSpec[];
+    /** Authored variant sets (`variantSet "name" = { ... }`), if any. */
+    variantSets?: VariantSetMap;
     /** 1-based source line of the prim declaration (for diagnostics). */
     line: number;
 };
+/** The opinions a single variant contributes when selected. */
+type VariantContent = {
+    properties: PropertySpec[];
+    children: PrimSpec[];
+};
+/** `variantSetName → variantName → content`. */
+type VariantSetMap = {
+    [setName: string]: {
+        [variantName: string]: VariantContent;
+    };
+};
 type PropertySpec = AttributeSpec | RelationshipSpec;
 type AttributeSpec = {
     kind: "attribute";
@@ -280,4 +293,4 @@ type BuildTreeOptions = {
 };
 declare function buildKinematicTree(robot: RobotDescription, options?: BuildTreeOptions): KinematicTree;
 
-export { type Axis as A, type BuildTreeOptions as B, type CompositionArc as C, DEG2RAD as D, makeRotationZ as E, makeScale as F, makeTranslation as G, multiply as H, multiplyAll as I, type JointDescription as J, type KinematicNode as K, type LinkDescription as L, type Mat4 as M, type PrimSpec as P, Quat as Q, type RobotDescription as R, type SdfPath as S, type TreeEdge as T, type UsdDictionary as U, type Variability as V, AssetPath as a, type AttributeSpec as b, type JointDriveDescription as c, type JointType as d, type KinematicTree as e, type ListOp as f, type MetadataMap as g, type PropertySpec as h, RAD2DEG as i, type RelationshipSpec as j, type Specifier as k, UsdMatrix as l, type UsdValue as m, type UsdaFile as n, type Vec2 as o, type Vec3 as p, type Vec4 as q, buildKinematicTree as r, fromUsdMatrix as s, getTranslation as t, identity4 as u, invert as v, makeEuler as w, makeRotationFromQuat as x, makeRotationX as y, makeRotationY as z };
+export { type Axis as A, type BuildTreeOptions as B, type CompositionArc as C, DEG2RAD as D, makeRotationZ as E, makeScale as F, makeTranslation as G, multiply as H, multiplyAll as I, type JointType as J, type KinematicTree as K, type LinkDescription as L, type Mat4 as M, type PrimSpec as P, Quat as Q, type RobotDescription as R, type SdfPath as S, type TreeEdge as T, type UsdDictionary as U, type Vec3 as V, type JointDescription as a, AssetPath as b, type AttributeSpec as c, type JointDriveDescription as d, type KinematicNode as e, type ListOp as f, type MetadataMap as g, type PropertySpec as h, RAD2DEG as i, type RelationshipSpec as j, type Specifier as k, UsdMatrix as l, type UsdValue as m, type UsdaFile as n, type Variability as o, type Vec2 as p, type Vec4 as q, buildKinematicTree as r, fromUsdMatrix as s, getTranslation as t, identity4 as u, invert as v, makeEuler as w, makeRotationFromQuat as x, makeRotationX as y, makeRotationY as z };

package/dist/{chunk-XCP5GZPY.js → chunk-XH3L7XDJ.js}

@@ -507,26 +507,54 @@ function parsePrim(r) {
   if (r.is("ident")) typeName = r.expectIdent();
   const name = r.expect("string").value;
   const metadata = r.is("lparen") ? parseMetadataBlock(r) : {};
+  r.expect("lbrace");
+  const body = parseBody(r);
+  r.expect("rbrace");
+  const prim = {
+    specifier,
+    typeName,
+    name,
+    metadata,
+    properties: body.properties,
+    children: body.children,
+    line: head.line
+  };
+  if (body.variantSets) prim.variantSets = body.variantSets;
+  return prim;
+}
+function parseBody(r) {
   const properties = [];
   const children = [];
-  r.expect("lbrace");
+  let variantSets;
   while (!r.is("rbrace") && !r.atEnd()) {
     if (r.is("ident") && SPECIFIERS.has(r.peek().value)) {
       children.push(parsePrim(r));
+    } else if (r.isIdent("variantSet")) {
+      const { setName, variants } = parseVariantSet(r);
+      variantSets ??= {};
+      variantSets[setName] = variants;
     } else {
       properties.push(parseProperty(r));
     }
   }
+  return variantSets ? { properties, children, variantSets } : { properties, children };
+}
+function parseVariantSet(r) {
+  r.expectIdent();
+  const setName = r.expect("string").value;
+  r.expect("equals");
+  r.expect("lbrace");
+  const variants = {};
+  while (!r.is("rbrace") && !r.atEnd()) {
+    const variantName = r.expect("string").value;
+    if (r.is("lparen")) parseMetadataBlock(r);
+    r.expect("lbrace");
+    const body = parseBody(r);
+    r.expect("rbrace");
+    variants[variantName] = { properties: body.properties, children: body.children };
+  }
   r.expect("rbrace");
-  return {
-    specifier,
-    typeName,
-    name,
-    metadata,
-    properties,
-    children,
-    line: head.line
-  };
+  return { setName, variants };
 }
 function parseProperty(r) {
   const line = r.peek().line;
@@ -652,6 +680,10 @@ function parseMetadataValue(r) {
   if (raw.t === "asset") {
     return raw.v;
   }
+  if (raw.t === "path") {
+    const arc = { primPath: raw.v };
+    return arc;
+  }
   return rawToUsdValue(raw);
 }
 function parseMetadataList(r) {
@@ -666,6 +698,9 @@ function parseMetadataList(r) {
       } else {
         items.push(assetPath);
       }
+    } else if (r.is("path")) {
+      const arc = { primPath: r.next().value };
+      items.push(arc);
     } else {
       items.push(rawToUsdValue(parseLiteral(r)));
     }
@@ -1056,7 +1091,8 @@ function normalizePosix(path) {
 }
 
 // src/usd/composition.ts
-var ARC_KEYS = ["references", "payload", "payloads"];
+var ARC_KEYS = ["references", "payload", "payloads", "inherits", "specializes"];
+var STRIP_KEYS = [...ARC_KEYS, "variants", "variantSets"];
 async function composeLayer(text, baseUrl, resolver, options = {}, stack = /* @__PURE__ */ new Set()) {
   const warn = options.onWarn ?? (() => {
   });
@@ -1064,47 +1100,89 @@ async function composeLayer(text, baseUrl, resolver, options = {}, stack = /* @_
   let weak = [];
   const subLayers = toArcs(file.metadata.subLayers);
   for (let i = subLayers.length - 1; i >= 0; i--) {
-    const sub = await loadComposedFile(subLayers[i], baseUrl, resolver, options, stack, warn);
+    const sub = await loadExternalFile(subLayers[i], baseUrl, resolver, options, stack, warn);
     if (sub) weak = mergePrimLists(weak, sub.prims);
   }
+  const ctx = {
+    baseUrl,
+    resolver,
+    options,
+    warn,
+    stack,
+    index: buildPathIndex(file.prims),
+    resolving: /* @__PURE__ */ new Set()
+  };
   const resolved = [];
-  for (const prim of file.prims) {
-    resolved.push(await resolvePrimArcs(prim, baseUrl, resolver, options, stack, warn));
-  }
+  for (const prim of file.prims) resolved.push(await resolvePrim(prim, ctx));
   const prims = weak.length > 0 ? mergePrimLists(weak, resolved) : resolved;
-  return { version: file.version, metadata: stripKeys(file.metadata, ["subLayers"]), prims };
-}
-async function resolvePrimArcs(spec, baseUrl, resolver, options, stack, warn) {
-  const children = [];
-  for (const child of spec.children) {
-    children.push(await resolvePrimArcs(child, baseUrl, resolver, options, stack, warn));
-  }
-  const local = { ...spec, children, metadata: stripKeys(spec.metadata, ARC_KEYS) };
+  return { version: file.version, metadata: stripKeys(file.metadata, STRIP_KEYS), prims };
+}
+async function resolvePrim(spec, ctx) {
+  let properties = spec.properties;
+  let children = spec.children;
+  const selection = spec.metadata.variants;
+  if (spec.variantSets && isDictionary(selection)) {
+    for (const [setName, variantName] of Object.entries(selection)) {
+      const variant = spec.variantSets[setName]?.[String(variantName)];
+      if (!variant) continue;
+      properties = mergeProperties(variant.properties, properties);
+      children = mergePrimLists(variant.children, children);
+    }
+  }
+  const resolvedChildren = [];
+  for (const child of children) resolvedChildren.push(await resolvePrim(child, ctx));
+  const local = {
+    specifier: spec.specifier,
+    typeName: spec.typeName,
+    name: spec.name,
+    metadata: stripKeys(spec.metadata, STRIP_KEYS),
+    properties,
+    children: resolvedChildren,
+    line: spec.line
+  };
   const arcs = ARC_KEYS.flatMap((k) => toArcs(spec.metadata[k]));
-  if (arcs.length === 0) return local;
   let base = null;
   for (const arc of arcs) {
-    const target = await loadReferencedPrim(arc, baseUrl, resolver, options, stack, warn);
-    if (!target) continue;
-    base = base ? mergePrim(target, base) : target;
+    const target = await loadReferencedPrim(arc, ctx);
+    if (target) base = base ? mergePrim(target, base) : target;
   }
   return base ? mergePrim(base, local) : local;
 }
-async function loadReferencedPrim(arc, baseUrl, resolver, options, stack, warn) {
-  if (!arc.assetPath) {
-    warn(`internal references (no asset path) are not supported yet: <${arc.primPath ?? "?"}>`);
-    return null;
+async function loadReferencedPrim(arc, ctx) {
+  if (arc.assetPath) {
+    const composed = await loadExternalFile(
+      arc,
+      ctx.baseUrl,
+      ctx.resolver,
+      ctx.options,
+      ctx.stack,
+      ctx.warn
+    );
+    if (!composed) return null;
+    const target = arc.primPath ? findPrimByPath(composed, arc.primPath) : defaultPrim(composed, ctx.warn);
+    if (!target) {
+      ctx.warn(
+        `reference target ${arc.primPath ?? "(defaultPrim)"} not found in ${arc.assetPath.path}`
+      );
+      return null;
+    }
+    return target;
   }
-  const composed = await loadComposedFile(arc, baseUrl, resolver, options, stack, warn);
-  if (!composed) return null;
-  const target = arc.primPath ? findPrimByPath(composed, arc.primPath) : defaultPrim(composed, warn);
-  if (!target) {
-    warn(`reference target ${arc.primPath ?? "(defaultPrim)"} not found in ${arc.assetPath.path}`);
-    return null;
+  if (arc.primPath) {
+    if (ctx.resolving.has(arc.primPath)) {
+      ctx.warn(`internal composition cycle at ${arc.primPath}; skipping`);
+      return null;
+    }
+    const target = ctx.index.get(arc.primPath);
+    if (!target) {
+      ctx.warn(`internal reference target ${arc.primPath} not found`);
+      return null;
+    }
+    return resolvePrim(target, { ...ctx, resolving: /* @__PURE__ */ new Set([...ctx.resolving, arc.primPath]) });
   }
-  return target;
+  return null;
 }
-async function loadComposedFile(arc, baseUrl, resolver, options, stack, warn) {
+async function loadExternalFile(arc, baseUrl, resolver, options, stack, warn) {
   if (!arc.assetPath) return null;
   const url = resolver.resolve(arc.assetPath.path, baseUrl);
   if (stack.has(url)) {
@@ -1126,7 +1204,6 @@ async function loadComposedFile(arc, baseUrl, resolver, options, stack, warn) {
 }
 function mergePrim(base, over) {
   return {
-    // `over` (def) wins; a pure `over` opinion keeps the base's specifier.
     specifier: over.specifier === "over" ? base.specifier : over.specifier,
     typeName: over.typeName || base.typeName,
     name: over.name,
@@ -1196,6 +1273,14 @@ function mergeMetadata(base, over) {
   }
   return merged;
 }
+function buildPathIndex(prims, parent = "/", map = /* @__PURE__ */ new Map()) {
+  for (const p of prims) {
+    const path = parent === "/" ? `/${p.name}` : `${parent}/${p.name}`;
+    map.set(path, p);
+    buildPathIndex(p.children, path, map);
+  }
+  return map;
+}
 function findPrimByPath(file, path) {
   const segments = path.split("/").filter(Boolean);
   let level = file.prims;
@@ -1209,9 +1294,7 @@ function findPrimByPath(file, path) {
 }
 function defaultPrim(file, warn) {
   const name = file.metadata.defaultPrim;
-  if (typeof name === "string") {
-    return file.prims.find((p) => p.name === name) ?? null;
-  }
+  if (typeof name === "string") return file.prims.find((p) => p.name === name) ?? null;
   const first = file.prims[0];
   if (first) warn(`referenced layer has no defaultPrim; using first root prim "${first.name}"`);
   return first ?? null;
@@ -1222,10 +1305,14 @@ function toArcs(value) {
   const arcs = [];
   for (const v of list) {
     if (v instanceof AssetPath) arcs.push({ assetPath: v });
-    else if (v && typeof v === "object" && "assetPath" in v) arcs.push(v);
+    else if (v && typeof v === "object" && ("assetPath" in v || "primPath" in v))
+      arcs.push(v);
   }
   return arcs;
 }
+function isDictionary(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v) && !(v instanceof Quat) && !(v instanceof UsdMatrix) && !(v instanceof AssetPath);
+}
 function stripKeys(meta, keys) {
   const out = {};
   for (const [k, v] of Object.entries(meta)) {
@@ -2681,5 +2768,5 @@ function leafName(path) {
 }
 
 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 };
-//# sourceMappingURL=chunk-XCP5GZPY.js.map
-//# sourceMappingURL=chunk-XCP5GZPY.js.map
+//# sourceMappingURL=chunk-XH3L7XDJ.js.map
+//# sourceMappingURL=chunk-XH3L7XDJ.js.map