three-usd-robot 0.2.0 → 0.4.0

package/dist/core.d.ts

@@ -1,5 +1,5 @@
-import { n as UsdaFile, g as MetadataMap, m as UsdValue, P as PrimSpec, k as Specifier, j as RelationshipSpec, S as SdfPath, b as AttributeSpec, V as Variability, M as Mat4, R as RobotDescription, d as JointType, A as Axis } from './buildKinematicTree-2fg6ZN8m.js';
-export { a as AssetPath, B as BuildTreeOptions, C as CompositionArc, D as DEG2RAD, J as JointDescription, c as JointDriveDescription, K as KinematicNode, e as KinematicTree, L as LinkDescription, f as ListOp, h as PropertySpec, Q as Quat, i as RAD2DEG, T as TreeEdge, U as UsdDictionary, l as UsdMatrix, 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 { o as UsdaFile, g as MetadataMap, n as UsdValue, P as PrimSpec, l as Specifier, j as RelationshipSpec, k as SdfPath, c as AttributeSpec, p as Variability, M as Mat4, R as RobotDescription, J as JointType, A as Axis } from './buildKinematicTree-CZjBMA1I.js';
+export { b as AssetPath, B as BuildTreeOptions, C as CompositionArc, D as DEG2RAD, a as JointDescription, d as JointDriveDescription, e as KinematicNode, K as KinematicTree, L as LinkDescription, f as ListOp, h as PropertySpec, Q as Quat, i as RAD2DEG, S as SampleChannel, T as TreeEdge, U as UsdDictionary, m as UsdMatrix, q as Vec2, V as Vec3, r as Vec4, s as buildKinematicTree, t as channelFromSamples, u as fromUsdMatrix, v as getTranslation, w as identity4, x as interpolate, y as invert, z as makeEuler, E as makeRotationFromQuat, F as makeRotationX, G as makeRotationY, H as makeRotationZ, I as makeScale, N as makeTranslation, O as multiply, W as multiplyAll } from './buildKinematicTree-CZjBMA1I.js';
 
 /** Package identity. Kept in one place so every entry point can re-export it. */
 declare const PACKAGE_NAME = "three-usd-robot";
@@ -90,6 +90,12 @@ declare class Stage {
     GetUpAxis(): UpAxis;
     /** Stage linear unit (`metersPerUnit` metadata); defaults to {@link DEFAULT_METERS_PER_UNIT}. */
     GetMetersPerUnit(): number;
+    /** Animation start time code, if authored. */
+    GetStartTimeCode(): number | undefined;
+    /** Animation end time code, if authored. */
+    GetEndTimeCode(): number | undefined;
+    /** Time codes per second for playback; defaults to 24. */
+    GetTimeCodesPerSecond(): number;
 }
 
 /**
@@ -211,19 +217,25 @@ declare class DefaultAssetResolver implements AssetResolver {
     fetchText(url: string): Promise<string>;
     fetchBytes(url: string): Promise<Uint8Array>;
 }
-/** Resolver over an in-memory `{ path: contents }` map, with posix-style joins. */
-declare function createMemoryResolver(files: Record<string, string>): AssetResolver;
+/**
+ * Resolver over an in-memory `{ path: contents }` map (text or bytes), with
+ * posix-style joins. Useful for tests and bundled assets.
+ */
+declare function createMemoryResolver(files: Record<string, string | Uint8Array>): AssetResolver;
 /** Resolve `rel` against `baseUrl` using posix semantics, normalizing `.`/`..`. */
 declare function joinPosix(baseUrl: string, rel: string): string;
 
 /**
- * Minimal USD composition: flattens references, payloads and sublayers into a
- * single {@link UsdaFile} so the rest of the pipeline keeps working on one layer.
+ * Minimal USD composition: flattens references, payloads, sublayers, variant
+ * selections, and internal (intra-layer) reference/inherit arcs into a single
+ * {@link UsdaFile} so the rest of the pipeline keeps working on one layer.
  *
- * Scope (M8): the arcs robots actually use. References and payloads pull a prim
- * subtree from another asset (weaker than local opinions); sublayers overlay a
- * weaker layer stack. Inherits / variants / specializes are out of scope (M10).
- * This is not a full LIVRPS implementation — it is a pragmatic flattener.
+ * Scope: the arcs robots actually use. References/payloads/inherits pull a prim
+ * subtree (weaker than local opinions); a `variants` selection grafts the chosen
+ * variant's content; internal arcs (`</Path>` with no asset) resolve within the
+ * same layer — which is what `instanceable` prims use to pull a prototype.
+ * Specializes ordering and live instancing are approximated. Not a full LIVRPS
+ * engine — a pragmatic flattener.
  */
 
 type ComposeOptions = {
@@ -231,12 +243,10 @@ type ComposeOptions = {
     /** Guard against pathological recursion (default 64). */
     maxDepth?: number;
 };
-/**
- * Parse and fully compose a layer: resolve its sublayers and every prim's
- * references/payloads (recursively), returning a flattened layer. Unresolvable
- * arcs are reported via `onWarn` and skipped.
- */
+/** Parse USDA text and fully compose it. */
 declare function composeLayer(text: string, baseUrl: string, resolver: AssetResolver, options?: ComposeOptions, stack?: ReadonlySet<string>): Promise<UsdaFile>;
+/** Compose an already-parsed layer (used by the binary-crate path too). */
+declare function composeFile(file: UsdaFile, baseUrl: string, resolver: AssetResolver, options?: ComposeOptions, stack?: ReadonlySet<string>): Promise<UsdaFile>;
 
 /**
  * USDZ (zipped USD package) support.
@@ -333,6 +343,12 @@ declare class CrateReader {
     private readIndexVector;
     /** Read an SdfListOp; returns the effective (explicit ∪ prepended ∪ added ∪ appended) items. */
     private readListOp;
+    /**
+     * Read a Reference/Payload list-op into composition arcs. Each item is
+     * `[assetPath: string-index][primPath: path-index][layerOffset: 2 doubles]`,
+     * and a Reference additionally carries a (usually empty) customData dict.
+     */
+    private readArcListOp;
 }
 
 /**
@@ -461,4 +477,4 @@ declare function getJointDrive(prim: Prim, kind: "angular" | "linear"): {
 /** Read `PhysicsJointStateAPI` position for the given instance, as authored. */
 declare function getJointStatePosition(prim: Prim, kind: "angular" | "linear"): number | undefined;
 
-export { ARTICULATION_ROOT_API, type AssetResolver, Attribute, AttributeSpec, Axis, COLLISION_API, type ComposeOptions, CrateReader, DEFAULT_METERS_PER_UNIT, DefaultAssetResolver, type ExtractOptions, JointType, Layer, Mat4, MetadataMap, PACKAGE_NAME, ParseError, Prim, PrimSpec, RIGID_BODY_API, Relationship, RelationshipSpec, type ResolvedXform, RobotDescription, SdfPath, Specifier, Stage, TokenizeError, type UpAxis, UsdValue, UsdaFile, type UsdzPackage, VERSION, Variability, 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 };
+export { ARTICULATION_ROOT_API, type AssetResolver, Attribute, AttributeSpec, Axis, COLLISION_API, type ComposeOptions, CrateReader, DEFAULT_METERS_PER_UNIT, DefaultAssetResolver, type ExtractOptions, JointType, Layer, Mat4, MetadataMap, PACKAGE_NAME, ParseError, Prim, PrimSpec, RIGID_BODY_API, Relationship, RelationshipSpec, type ResolvedXform, RobotDescription, SdfPath, Specifier, Stage, TokenizeError, type UpAxis, UsdValue, UsdaFile, type UsdzPackage, VERSION, Variability, composeFile, 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 };

package/dist/core.js

@@ -1,3 +1,3 @@
-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';
+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';
 //# sourceMappingURL=core.js.map
 //# sourceMappingURL=core.js.map

package/dist/extras.d.ts

@@ -1,6 +1,6 @@
-import { T as ThreeUsdRobot } from './ThreeUsdRobot-lMZHW-it.js';
+import { T as ThreeUsdRobot } from './ThreeUsdRobot-Deoh7zam.js';
 import 'three';
-import './buildKinematicTree-2fg6ZN8m.js';
+import './buildKinematicTree-CZjBMA1I.js';
 
 /**
  * `three-usd-robot/extras`

package/dist/helpers.d.ts

@@ -1,6 +1,6 @@
 import * as THREE from 'three';
-import { J as JointObject, T as ThreeUsdRobot } from './ThreeUsdRobot-lMZHW-it.js';
-import './buildKinematicTree-2fg6ZN8m.js';
+import { J as JointObject, T as ThreeUsdRobot } from './ThreeUsdRobot-Deoh7zam.js';
+import './buildKinematicTree-CZjBMA1I.js';
 
 /**
  * An arrow drawn along a joint's motion axis (the rotation axis for

package/dist/index.d.ts

@@ -1,14 +1,32 @@
-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 { AssetResolver, Stage, Prim } 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, composeFile, 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';
+import { A as Axis, R as RobotDescription, V as Vec3 } from './buildKinematicTree-CZjBMA1I.js';
+export { b as AssetPath, c as AttributeSpec, B as BuildTreeOptions, C as CompositionArc, D as DEG2RAD, a as JointDescription, d as JointDriveDescription, J as JointType, e as KinematicNode, K 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 SampleChannel, k as SdfPath, l as Specifier, T as TreeEdge, U as UsdDictionary, m as UsdMatrix, n as UsdValue, o as UsdaFile, p as Variability, q as Vec2, r as Vec4, s as buildKinematicTree, t as channelFromSamples, u as fromUsdMatrix, v as getTranslation, w as identity4, x as interpolate, y as invert, z as makeEuler, E as makeRotationFromQuat, F as makeRotationX, G as makeRotationY, H as makeRotationZ, I as makeScale, N as makeTranslation, O as multiply, W as multiplyAll } from './buildKinematicTree-CZjBMA1I.js';
+import { T as ThreeUsdRobot } from './ThreeUsdRobot-Deoh7zam.js';
+export { J as JointObject, L as LinkObject, a as ThreeUsdRobotOptions } from './ThreeUsdRobot-Deoh7zam.js';
 
 /** Unit vector for a USD joint axis token. Returns a fresh vector each call. */
 declare function axisVector(axis: Axis): THREE.Vector3;
 
+/**
+ * Loads texture image assets referenced by `UsdShade` materials.
+ *
+ * A {@link TextureProvider} maps an authored asset path to a `THREE.Texture`.
+ * The default provider resolves the path against the layer base URL and loads it
+ * with `THREE.TextureLoader` (so it works for textures served alongside the USD
+ * on the web). Textures load asynchronously and update the material when ready.
+ */
+
+/** Resolve an authored texture asset path to a `THREE.Texture` (or `null`). */
+type TextureProvider = (assetPath: string) => THREE.Texture | null;
+/**
+ * A {@link TextureProvider} backed by `THREE.TextureLoader`, resolving paths via
+ * `resolver` against `baseUrl`. Results are cached per resolved URL and tagged
+ * as sRGB color textures.
+ */
+declare function createTextureProvider(resolver: AssetResolver, baseUrl: string): TextureProvider;
+
 /**
  * Binds `UsdGeom.Mesh` prims to Three.js geometry and attaches them under the
  * robot's link objects.
@@ -23,11 +41,18 @@ type MeshKind = "visual" | "collision";
 type BindMeshesOptions = {
     loadVisuals?: boolean;
     loadCollisions?: boolean;
+    /** Resolves diffuse texture asset paths to `THREE.Texture` (M-tex). */
+    textureProvider?: TextureProvider;
 };
 /** 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;
+/**
+ * Build a material for a Mesh prim. Color priority: bound `UsdShade` material
+ * (when `stage` is given) → `primvars:displayColor` → default gray. A diffuse
+ * texture (via `textures`) becomes `material.map`; metalness / roughness /
+ * opacity come from the bound material when present.
+ */
+declare function buildMeshMaterial(meshPrim: Prim, stage?: Stage, textures?: TextureProvider): 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
@@ -35,6 +60,28 @@ declare function buildMeshMaterial(meshPrim: Prim): THREE.Material;
  */
 declare function bindRobotMeshes(stage: Stage, robot3d: ThreeUsdRobot, desc: RobotDescription, options?: BindMeshesOptions): void;
 
+/**
+ * Resolves `UsdShade` material bindings to flat PBR parameters.
+ *
+ * Follows a prim's (or an ancestor's) `material:binding` to a `Material`, finds
+ * its surface `Shader`, and reads constant color/metalness/roughness/opacity
+ * inputs plus the diffuse **texture** asset path. Handles both
+ * `UsdPreviewSurface` (`inputs:diffuseColor` constant or a `UsdUVTexture`
+ * network) and Omniverse `OmniPBR` MDL (`inputs:diffuse_color_constant`,
+ * `inputs:diffuse_texture`). Only the diffuse channel and constants are read.
+ */
+
+type ResolvedMaterial = {
+    color?: Vec3;
+    opacity?: number;
+    metalness?: number;
+    roughness?: number;
+    /** Authored asset path of the diffuse/albedo texture, if any. */
+    colorTexture?: string;
+};
+/** Resolve the bound material's flat parameters for `prim`, or `undefined`. */
+declare function resolveBoundMaterial(stage: Stage, prim: Prim): ResolvedMaterial | undefined;
+
 type ThreeUsdRobotLoaderOptions = {
     /** Resolver for references / payloads / sublayers (default {@link DefaultAssetResolver}). */
     assetResolver?: AssetResolver;
@@ -42,6 +89,8 @@ type ThreeUsdRobotLoaderOptions = {
     loadVisuals?: boolean;
     /** Render collision meshes (M6). */
     loadCollisions?: boolean;
+    /** Load diffuse textures referenced by materials (default `true`). */
+    loadTextures?: boolean;
     /** Up-axis correction strategy (M9). */
     upAxisConversion?: "auto" | "Y" | "Z" | "none";
     /** Extra uniform scale multiplied with `metersPerUnit` (M9). */
@@ -77,7 +126,7 @@ declare class ThreeUsdRobotLoader {
     /** 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>;
+    parseCrate(bytes: Uint8Array, baseUrl?: string): Promise<ThreeUsdRobot>;
     /** Parse + compose USDA source into the Three.js-independent robot IR. */
     parseRobotDescription(text: string, baseUrl?: string): Promise<RobotDescription>;
     private buildFromStage;
@@ -86,4 +135,4 @@ declare class ThreeUsdRobotLoader {
     private extractOptions;
 }
 
-export { AssetResolver, Axis, type BindMeshesOptions, type MeshKind, Prim, RobotDescription, Stage, ThreeUsdRobot, ThreeUsdRobotLoader, type ThreeUsdRobotLoaderOptions, axisVector, bindRobotMeshes, buildMeshGeometry, buildMeshMaterial };
+export { AssetResolver, Axis, type BindMeshesOptions, type MeshKind, Prim, type ResolvedMaterial, RobotDescription, Stage, type TextureProvider, ThreeUsdRobot, ThreeUsdRobotLoader, type ThreeUsdRobotLoaderOptions, Vec3, axisVector, bindRobotMeshes, buildMeshGeometry, buildMeshMaterial, createTextureProvider, resolveBoundMaterial };

package/dist/index.js

@@ -1,5 +1,5 @@
-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 { 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';
 
 function axisVector(axis) {
@@ -71,6 +71,93 @@ var LinkObject = class extends THREE4.Object3D {
     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]];
+    }
+  }
+  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;
+}
+
+// src/three/MeshBinding.ts
 var DEFAULT_COLOR = 10132122;
 function buildMeshGeometry(meshPrim) {
   const points = meshPrim.GetAttribute("points").Get();
@@ -96,24 +183,41 @@ function buildMeshGeometry(meshPrim) {
   }
   return geometry;
 }
-function buildMeshMaterial(meshPrim) {
+function buildMeshMaterial(meshPrim, stage, textures) {
   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);
+  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);
+    }
   }
+  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: 0.1,
-    roughness: 0.8,
-    side: doubleSided ? THREE4.DoubleSide : THREE4.FrontSide
+    metalness,
+    roughness,
+    transparent: opacity < 1,
+    opacity,
+    side: doubleSided ? THREE4.DoubleSide : THREE4.FrontSide,
+    ...map ? { map } : {}
   });
 }
 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);
@@ -122,22 +226,22 @@ function bindRobotMeshes(stage, robot3d, desc, options = {}) {
     if (loadVisuals) {
       for (const meshPath of link.visualPrims) {
         if (collisionSet.has(meshPath)) continue;
-        attachMesh(stage, linkPrim, meshPath, linkObj, "visual");
+        attachMesh(stage, linkPrim, meshPath, linkObj, "visual", textures);
       }
     }
     if (loadCollisions) {
       for (const meshPath of link.collisionPrims ?? []) {
-        attachMesh(stage, linkPrim, meshPath, linkObj, "collision");
+        attachMesh(stage, linkPrim, meshPath, linkObj, "collision", textures);
       }
     }
   }
 }
-function attachMesh(stage, linkPrim, meshPath, parent, kind) {
+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));
+  const mesh = new THREE4.Mesh(geometry, buildMeshMaterial(meshPrim, stage, textures));
   mesh.name = meshPrim.GetName();
   mesh.userData.kind = kind;
   mesh.userData.primPath = meshPath;
@@ -203,6 +307,26 @@ function isVec3Array(v) {
 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;
@@ -354,6 +478,41 @@ var ThreeUsdRobot = class extends THREE4.Object3D {
   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;
@@ -429,7 +588,7 @@ var ThreeUsdRobotLoader = class {
       return this.parseUsdz(await this.fetchRootBytes(url));
     }
     const bytes = await this.fetchRootBytes(url);
-    if (CrateReader.isCrate(bytes)) return this.parseCrate(bytes);
+    if (CrateReader.isCrate(bytes)) return this.parseCrate(bytes, url);
     return this.parse(new TextDecoder().decode(bytes), url);
   }
   async fetchRootBytes(url) {
@@ -439,32 +598,44 @@ var ThreeUsdRobotLoader = class {
   }
   /** Build a robot (composed, with meshes) from USDA source text. */
   async parse(text, baseUrl = "") {
-    return this.buildFromStage(await this.composeStage(text, baseUrl, this.resolver));
+    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);
-    return this.buildFromStage(await this.composeStage(rootText, pkg.rootEntry, pkg.resolver));
+    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`). */
-  parseCrate(bytes) {
+  async parseCrate(bytes, baseUrl = "") {
     const file = crateToUsdaFile(new CrateReader(bytes));
-    return Promise.resolve(this.buildFromStage(Stage.OpenFromFile(file)));
+    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) {
+  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) {
-      bindRobotMeshes(stage, robot3d, robot, { loadVisuals, loadCollisions });
+      const textureProvider = this.options.loadTextures ?? true ? createTextureProvider(resolver, baseUrl) : void 0;
+      bindRobotMeshes(stage, robot3d, robot, {
+        loadVisuals,
+        loadCollisions,
+        ...textureProvider ? { textureProvider } : {}
+      });
     }
     return robot3d;
   }
@@ -488,6 +659,6 @@ var ThreeUsdRobotLoader = class {
   }
 };
 
-export { JointObject, LinkObject, ThreeUsdRobot, ThreeUsdRobotLoader, axisVector, bindRobotMeshes, buildMeshGeometry, buildMeshMaterial };
+export { JointObject, LinkObject, ThreeUsdRobot, ThreeUsdRobotLoader, axisVector, bindRobotMeshes, buildMeshGeometry, buildMeshMaterial, createTextureProvider, resolveBoundMaterial };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map