three-usd-robot 0.11.0 → 0.13.0

package/README.md

@@ -22,14 +22,12 @@ exported back to `.usda` / `.usdz` in the browser.
   Multi-file assets (references / payloads / sublayers), variant selections and
   instanceable prims are composed for you.
 - **Robots** — links, joints (fixed / revolute / continuous / prismatic), limits,
-  drives and the initial pose become a `setJointValue`-able hierarchy.
-- **Rendering** — meshes, solid gprims (`Cube` / `Sphere` / `Cylinder` /
-  `Capsule` / `Cone`), point clouds (`Points`) and curves (`BasisCurves`:
-  linear / bezier / bspline / catmullRom, periodic wrap, and an opt-in
-  `curveTubes` mode that turns authored widths into tube meshes) with
-  `UsdShade` materials (UsdPreviewSurface / Omniverse MDL) and textures; up-axis
-  and units normalized automatically. Articulation-free stages load as
-  static scenes.
+  drives, mimic couplings (gripper finger linkages) and the initial pose become
+  a `setJointValue`-able hierarchy.
+- **Rendering** — meshes, solid gprims, point clouds and curves with `UsdShade`
+  materials (UsdPreviewSurface / Omniverse MDL / MaterialX, plus optional TSL
+  graph execution on WebGPU) and textures; up-axis and units normalized
+  automatically. Articulation-free stages load as static scenes.
 - **Animation** — plays back time-sampled joint trajectories, and replays
   baked body-transform recordings through `setLinkTransforms` with
   constraint diagnostics.
@@ -55,31 +53,6 @@ The CDN is public and CORS-enabled, so this works in the browser too. Try
 FK check, and a re-export to one self-contained file), or open the Vite example
 and pick a robot from the preset list.
 
-Materials target **UsdPreviewSurface fidelity plus an Omniverse MDL mapping**:
-constant and textured inputs, faceVarying / indexed UVs, multiple UV sets,
-per-vertex display colors, physical extensions (`ior` / `clearcoat` /
-specular workflow → `MeshPhysicalMaterial`), packed ORM maps,
-`sourceColorSpace`, and purpose/strength-aware bindings. MDL shaders are
-identified by `info:mdl:sourceAsset` and mapped **by family** — no shader
-execution — and referenced `.mdl` modules are fetched and parsed for their
-declaration values, so wrapper materials
-(`export material X(*) = OmniPBR(…)`) render correctly even when the USD
-shader authors no inputs at all. Value priority: authored USD inputs >
-wrapper arguments > declaration defaults.
-
-| MDL family | three.js mapping |
-| --- | --- |
-| `OmniPBR` (and derivatives, e.g. `OmniPBR_Opacity`) | color / metalness / roughness / emissive (`emissive_intensity`), per-channel texture maps and packed `ORM_texture`, opacity, normal map, `texture_translate/rotate/scale` |
-| `OmniPBR_ClearCoat` | the OmniPBR mapping plus `clearcoat` / `clearcoatRoughness` / `clearcoatNormalMap` |
-| `OmniGlass` | `MeshPhysicalMaterial` with `transmission` / `ior` (default 1.491) / `roughness` / `thickness`, glass color + texture |
-| `OmniSurface(Lite)` | constants subset: diffuse color / metalness / roughness / IOR / coat / emission / opacity |
-
-Executing MDL or MaterialX shader graphs is out of scope; unknown MDL
-materials fall back to the OmniPBR mapping with a warning. Not yet
-supported: collection-based material bindings, and the exotic curve schemas
-(`NurbsCurves`, `HermiteCurves`, `NurbsPatch`) which load with a warning and
-are skipped.
-
 ## Install
 
 ```sh
@@ -104,221 +77,33 @@ robot.setJointValues({ joint1: 0.4, joint2: -0.2 });
 const handMatrix = robot.getLinkWorldMatrix("tool0"); // THREE.Matrix4
 const handPos = robot.getLinkWorldPosition("tool0"); // THREE.Vector3
 
-robot.getJointNames(); // controllable joints
+robot.getJointNames(); // commandable joints
 robot.getKinematicTree(); // root, ordering, loop joints, ...
 ```
 
-No URL? `parse` also takes in-memory content: USDA source text, or an
-`ArrayBuffer` / typed array / `Blob` holding any supported format — the zip /
-crate magic is sniffed, so a dropped `File` or a response body works as-is:
-
-```ts
-const loader = new ThreeUsdRobotLoader();
-await loader.parse(usdaText); // USDA source string
-await loader.parse(file); // File / Blob from drag & drop or <input type="file">
-await loader.parse(await res.arrayBuffer()); // a fetch you did yourself
-```
-
-`parseUsdz(data)` / `parseCrate(data, baseUrl)` stay as explicit-format entries,
-and `parseRobotDescription(data)` returns the Three.js-independent IR. Pass a
-`baseUrl` as the second `parse` argument if the layer has relative references
-or texture paths to resolve.
-
-### World up-axis & units
-
-Stages load normalized: `metersPerUnit` scales the root, and the authored
-`upAxis` (`"Y"` or `"Z"`) is rotated into your world convention via `worldUp`:
-
-```ts
-new ThreeUsdRobotLoader(); // default: "Y" — upright in a stock three.js scene
-new ThreeUsdRobotLoader({ worldUp: "Z" }); // robotics-style Z-up world
-new ThreeUsdRobotLoader({ worldUp: "keep" }); // leave the authored orientation
-
-robot.upAxis; // authored stage value ("Y" | "Z"), independent of normalization
-robot.metersPerUnit; // authored stage scale (already applied to the root)
-```
-
-Isaac Sim assets are Z-up, so the default makes them stand upright in a plain
-three.js scene; a Z-up app (ROS-style) passes `worldUp: "Z"` once instead of
-counter-rotating per asset. The M9 option `upAxisConversion` remains as a
-deprecated alias (`"auto"` ≡ `worldUp: "Y"`, `"none"` ≡ `"keep"`).
-
-### Stable addressing (naming contract)
-
-Joints and links are keyed by their prim's **leaf name** while it is unique
-across the robot; on a collision (say, two arms each with a `seg` link) the
-colliding entries are keyed by their **full prim path** instead —
-deterministically. Every accessor also takes the full prim path directly, so
-tooling can pin exact prims no matter how the asset is named:
-
-```ts
-robot.setJointValue("/World/armL/j1", 0.4); // same joint as its key
-robot.getLinkWorldMatrix("/World/armL/seg");
-robot.getLinkObjectsByPath(); // Map<primPath, LinkObject>
-robot.getJointObjectsByPath(); // Map<primPath, JointObject>
-```
-
-`LinkObject.primPath` / `JointObject.primPath` carry the reverse direction.
-
-### Viewer toggles & helpers
-
-```ts
-robot.showVisual = true;
-robot.showCollision = false;
-robot.showJointAxes = true; // built-in axes gizmos on each joint
-robot.showLinkFrames = false;
-
-import { addJointLimitHelpers } from "three-usd-robot/helpers";
-addJointLimitHelpers(robot); // arc (revolute) / segment (prismatic) per joint
-```
-
-### Link highlighting & ghosts
-
-Per-link appearance helpers cover the common viewer chores — flagging
-colliding links, material swaps, and translucent "ghost" pose previews:
-
-```ts
-import {
-  createGhostRobot,
-  highlightLink,
-  restoreLinkMaterials,
-  setLinkMaterial,
-} from "three-usd-robot/helpers";
-
-highlightLink(robot, "link1"); // emissive red tint; maps/colors kept
-highlightLink(robot, "/World/armL/seg", { color: 0xffaa00, opacity: 0.6 });
-setLinkMaterial(robot, "link2", new THREE.MeshBasicMaterial({ wireframe: true }));
-restoreLinkMaterials(robot, "link1"); // exact original materials back
-
-const ghost = createGhostRobot(robot, { jointValues: { joint1: 1.2 } });
-scene.add(ghost); // translucent copy previewing the target pose
-ghost.setJointValues(ikSolution); // a full ThreeUsdRobot, driveable like the source
-```
-
-Highlights never stack (each call re-tints from the originals), and ghosts
-share the source's geometry — cloning is cheap enough for onion-skinning.
-
-Loading a whole cell rather than a bare robot? Pass
-`{ loadSceneGeometry: true }` to the loader to draw the static environment
-(floor, guarding, racking, …) around the machines. A stage with **no
-articulation at all** — a plain static USD scene — is detected and rendered as
-scene geometry automatically, with the same unit / up-axis normalization; pass
-`loadSceneGeometry: false` to opt out.
-
-### Joint slider panel (lil-gui)
-
-```ts
-import GUI from "lil-gui";
-import { createJointSliderPanel } from "three-usd-robot/extras";
-
-createJointSliderPanel(robot, new GUI()); // one slider per articulated joint
-```
-
-The panel takes the GUI instance from you, so the library never bundles
-`lil-gui`.
-
-### Animation playback
-
-If the asset has time-sampled joint trajectories, the robot plays them back:
-
-```ts
-const range = robot.getTimeRange();
-if (range) {
-  // in your render loop, advance a time code between range.start and range.end:
-  robot.setTime(t); // interpolates every animated joint and updates FK
-}
-```
-
-### Baked link transforms (recorded playback)
-
-Recordings baked as **body transforms** (Isaac Sim stage-recorder output,
-maximal-coordinate solver playback) can drive link poses directly, bypassing
-the joints — usdview-style display semantics:
-
-```ts
-// A world-pose track keyed by prim path (or link key), quaternion in [x, y, z, w]:
-robot.setLinkTransforms({
-  "/World/link1": { position: [0, 0, 1], quaternion: [0, 0, 0, 1] },
-  "/World/link2": { position: [0.3, 0, 2], quaternion: [0, 0, 0, 1] },
-}); // batched — one matrix update; unlisted links keep their current world pose
-
-robot.displayMode; // "baked": joint values are untouched and no longer place links
-robot.setJointValues(liveValues); // recompute all links from joint values → "fk"
-```
-
-Poses are read in the **three.js scene world after `worldUp` normalization** —
-pair a Z-up meter track (Isaac / ROS convention) with `worldUp: "Z"`; feeding
-it into the default Y-up normalization lays the robot on its side. Transforms
-on the `robot` object itself (placement, uniform scaling) are accounted for,
-and `{ space: "stage" }` reads authored stage coordinates instead.
-
-Constraint deviations — a recording from a different model version, solver
-drift, a coordinate-convention bug — are shown, never silently corrected.
-Measure them, or project onto the joints instead:
-
-```ts
-robot.validateLinkTransforms(poses);
-// { "/World/joint1": { anchorError /* m */, axisError /* rad */, q, limitExceeded }, … }
-// covers every joint: fixed joints, loop joints dropped from the FK tree,
-// and the world-fixed root attachment
-
-const { values, residuals } = robot.jointValuesFromLinkTransforms(poses, {
-  previous: lastValues, // ±π branch continuity, frame to frame
-});
-robot.setJointValues(values); // constraint-respecting playback of the same track
-```
+`parse` also takes in-memory content (USDA text, an `ArrayBuffer` / typed
+array / `Blob` — the format is sniffed, so a dropped `File` works as-is), and
+the loader normalizes units and up-axis for you: Isaac's Z-up assets stand
+upright in a Y-up three.js scene by default, or pass `worldUp: "Z"` for a
+robotics-style Z-up world. Details in the [runtime guide](./docs/runtime.md).
 
-`new ThreeUsdRobotLoader({ debugBakedTransforms: true })` warns once per baked
-session when poses deviate beyond 1 mm / 0.01 rad.
-
-### React Three Fiber
-
-`three-usd-robot/react` provides a declarative `<UsdRobot>` (`react` and
-`@react-three/fiber` are **optional** peer deps):
-
-```tsx
-import { Canvas } from "@react-three/fiber";
-import { Suspense } from "react";
-import { UsdRobot } from "three-usd-robot/react";
-
-<Canvas camera={{ position: [2, 2, 2] }}>
-  <Suspense fallback={null}>
-    <UsdRobot
-      url="/robot.usda"
-      jointValues={{ joint1: 0.4 }} // controlled
-      showJointAxes
-      animate // play time-sampled trajectories
-      onLoad={(robot) => console.log(robot.getJointNames())}
-    />
-  </Suspense>
-  <ambientLight />
-</Canvas>;
-```
+## Documentation
 
-Also exported: `useUsdRobot(url)` (Suspense loader), `useRobotAnimation(robot)`,
-`preloadUsdRobot`, `clearUsdRobotCache`. Pass a `ref` to `<UsdRobot>` for the
-imperative API.
+| Doc | Contents |
+| --- | --- |
+| [Runtime guide](./docs/runtime.md) | Input sources, up-axis & units, naming contract, mimic joints, viewer helpers & ghosts, static scenes, joint sliders, React Three Fiber, using the core without Three.js |
+| [Materials](./docs/materials.md) | UsdPreviewSurface fidelity, Omniverse MDL family mappings, MaterialX, optional TSL graph execution (WebGPU) |
+| [Animation & recorded playback](./docs/recorded-playback.md) | Time-sampled trajectories, baked body-transform recordings, constraint diagnostics & joint projection |
+| [Exporting USD](./docs/export.md) | Re-export, `RobotBuilder` authoring, simulation-ready assets (mass / collision / Isaac Robot Schema), USDZ packaging |
 
 ## Export USD
 
-The loader's inverse: re-export something you loaded, or author a robot from
-Three.js objects and open the result in Isaac Sim.
-
-![The exported cell opened in Isaac Sim](assets/isaacsim.png)
+The loader's inverse — author a robot from Three.js meshes and open it in
+Isaac Sim:
 
 ```ts
-import {
-  exportThreeUsdRobot,
-  RobotBuilder,
-  serializeUsda,
-  writeUsdz,
-} from "three-usd-robot";
-
-// Re-export a loaded robot (meshes harvested from the Three.js scene):
-const usda = serializeUsda(exportThreeUsdRobot(robot));
-
-// …or build one from Three.js meshes. Z-up and metres by default; each joint
-// takes ONE world-space frame, and the build-time arrangement is the zero pose.
+import { RobotBuilder, serializeUsda } from "three-usd-robot";
+
 const builder = new RobotBuilder({ name: "my_robot" });
 builder.addLink({ name: "base", visuals: [baseMesh] });
 builder.addLink({ name: "arm", frame: armFrame, visuals: [armMesh] });
@@ -327,46 +112,11 @@ builder.addRevoluteJoint({
   name: "j1", parent: "base", child: "arm",
   frame: jointFrame, axis: "Z", lower: -Math.PI, upper: Math.PI,
 });
-
-const file = builder.toUsda();
-writeFileSync("robot.usda", serializeUsda(file));
-writeFileSync("robot.usdz", writeUsdz({ "robot.usda": serializeUsda(file) }));
-```
-
-Joints export as `UsdPhysics` prims with their limits, drives and initial pose.
-For a simulation-ready asset, links also take mass properties, and collision
-meshes take physics materials and a collision approximation:
-
-```ts
-builder.addLink({
-  name: "arm",
-  visuals: [armMesh],
-  collisions: [armCollisionMesh],
-  inertial: { mass: 2.5, centerOfMass: [0, 0, 0.2], diagonalInertia: [0.02, 0.02, 0.004] },
-  collisionApproximation: "convexHull",
-  physicsMaterial: { name: "steel", staticFriction: 0.6, dynamicFriction: 0.5 },
-});
-```
-
-Both screenshots above come from `npx tsx scripts/demo-factory.ts`, which
-authors a complete robot cell — a 7-DOF arm with a gripper, a conveyor, a
-turntable and the surrounding scenery — and exports it to
-`out/factory.usda` / `.usdz`.
-
-## Use it without Three.js
-
-`three-usd-robot/core` is a standalone USD parser, writer and robot IR — handy
-for server-side validation or asset tooling:
-
-```ts
-import { parseUsda, Stage, extractRobotDescription } from "three-usd-robot/core";
-
-const desc = extractRobotDescription(Stage.OpenFromString(usdaText));
-console.log(desc.rootLink, Object.keys(desc.joints));
+writeFileSync("robot.usda", serializeUsda(builder.toUsda()));
 ```
 
-Command line: `npx tsx scripts/usdc-to-usda.ts robot.usd` converts binary crate
-and `.usdz` packages to ASCII USDA.
+Limits, drives, mimic couplings, the initial pose, mass properties and
+collision setup all serialize — see [Exporting USD](./docs/export.md).
 
 ## Examples
 
@@ -377,10 +127,11 @@ and `.usdz` packages to ASCII USDA.
   (prim tree + attribute inspector), a transform gizmo, joint sliders,
   animation playback and USD export.
 - **`vite-basic-viewer`** — the same thing through React Three Fiber.
+- **`vite-webgpu-nodes`** — MaterialX graph execution (TSL) on `WebGPURenderer`.
 
-Both take `?asset=<url>` for any asset, or `?isaac=<path under Isaac/>` to pull
-one straight from NVIDIA's CDN. `npm run demo:build` generates the factory cell
-and builds the deployable site.
+The viewers take `?asset=<url>` for any asset, or `?isaac=<path under Isaac/>`
+to pull one straight from NVIDIA's CDN. `npm run demo:build` generates the
+factory cell and builds the deployable site.
 
 ## Package entry points
 
@@ -388,8 +139,9 @@ and builds the deployable site.
 | --- | --- |
 | `three-usd-robot` | Three.js runtime — `ThreeUsdRobotLoader`, `ThreeUsdRobot`, `RobotBuilder`, export helpers |
 | `three-usd-robot/core` | Three.js-independent USD parser & writer, robot IR, forward-kinematics math |
-| `three-usd-robot/helpers` | Viewer helpers (joint axes, link frames, joint limits) |
+| `three-usd-robot/helpers` | Viewer helpers (joint axes, link frames, joint limits, highlights, ghosts) |
 | `three-usd-robot/extras` | Joint slider panel (bring your own `lil-gui`) |
+| `three-usd-robot/nodes` | Optional MaterialX → TSL execution (`three/webgpu`) — `createMaterialXNodeFactory`, `loadMaterialXDocument` |
 | `three-usd-robot/react` | React Three Fiber `<UsdRobot>` component + hooks |
 
 ## Development

package/dist/MeshBinding-B_8RhuQE.d.ts

@@ -0,0 +1,288 @@
+import * as THREE from 'three';
+import { y as Vec2, z as Vec3, S as Stage, P as Prim, R as RobotDescription } from './buildKinematicTree-Q9JOjAjM.js';
+import { b as MdlModuleProvider, A as AssetResolver } from './parseMdl-vfzBGoMr.js';
+import { T as ThreeUsdRobot } from './ThreeUsdRobot-X1zbpRZo.js';
+
+/**
+ * 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/
+ * emissive inputs plus the **texture** asset paths for the diffuse, normal,
+ * roughness, metallic, occlusion and emissive channels. Handles both
+ * `UsdPreviewSurface` (constant inputs or a connected `UsdUVTexture` network)
+ * and the Omniverse MDL material families (M20): `OmniPBR` (and derivatives
+ * such as `OmniPBR_Opacity`), `OmniPBR_ClearCoat`, `OmniGlass`, and an
+ * `OmniSurface(Lite)` constants subset. MDL shaders are identified by
+ * `info:mdl:sourceAsset` / `:subIdentifier`; when the referenced `.mdl` module
+ * text is available (see `loadMdlModules`), parameter values fall back from
+ * authored USD inputs to the module's wrapper arguments and declaration
+ * defaults. Executing MDL remains out of scope.
+ *
+ * MaterialX networks authored natively in UsdShade (M21) resolve here too:
+ * `ND_standard_surface_surfaceshader` has a dedicated reader (see
+ * `MaterialXBinding.ts`), while the `ND_Usd*` compatibility nodes share
+ * `UsdPreviewSurface` input names and reuse the generic reads.
+ */
+
+/** `UsdUVTexture` wrap mode for one axis (`black` ≈ clamp; three has no border). */
+type TextureWrap = "repeat" | "clamp" | "mirror" | "black";
+/** `UsdTransform2d` applied to the `st` coords feeding a texture. */
+type TextureTransform = {
+    /** `inputs:translation` (UV offset). */
+    translation?: Vec2;
+    /** `inputs:rotation` in degrees (CCW about the origin). */
+    rotation?: number;
+    /** `inputs:scale` (UV tiling). */
+    scale?: Vec2;
+};
+/** A resolved texture reference plus its `UsdUVTexture` sampler/transform state. */
+type ResolvedTexture = {
+    /** Authored asset path of the image. */
+    path: string;
+    wrapS?: TextureWrap;
+    wrapT?: TextureWrap;
+    /** `UsdTransform2d` on the `st` input, if any. */
+    transform?: TextureTransform;
+    /** `inputs:scale` — multiplies the sampled value (folded into material factors). */
+    scale?: [number, number, number, number];
+    /** `inputs:bias` — added to the sampled value. */
+    bias?: [number, number, number, number];
+    /**
+     * UV-set (primvar) name the texture reads, resolved through the `inputs:st`
+     * connection to a `UsdPrimvarReader_float2.inputs:varname`. Absent ⇒ `"st"`.
+     */
+    uvSet?: string;
+    /**
+     * Direct UV channel index (MaterialX `ND_texcoord_*.inputs:index`, M21).
+     * Beats `uvSet`; channel N is the mesh's N-th UV set in `meshUvSetNames`
+     * order (`st` first, extras sorted).
+     */
+    uvChannel?: number;
+    /** `inputs:sourceColorSpace` — overrides the per-channel colorspace default. */
+    sourceColorSpace?: "raw" | "sRGB" | "auto";
+    /**
+     * Which output the consuming input connects to (`outputs:r` → `"r"`, …).
+     * three.js samples fixed channels (roughness = G, metalness = B, ao = R);
+     * a mismatch is surfaced as a load warning.
+     */
+    outputChannel?: "r" | "g" | "b" | "a" | "rgb";
+};
+type ResolvedMaterial = {
+    /** Name of the bound `Material` prim, for round-tripping and debugging. */
+    name?: string;
+    color?: Vec3;
+    opacity?: number;
+    metalness?: number;
+    roughness?: number;
+    emissiveColor?: Vec3;
+    /**
+     * `inputs:opacityThreshold`. When `> 0`, opacity is a binary mask (alpha
+     * clip / cutout); when `0`/absent, sub-unit opacity blends translucently.
+     */
+    opacityThreshold?: number;
+    /** `inputs:ior` — promotes the three material to `MeshPhysicalMaterial`. */
+    ior?: number;
+    /** `inputs:clearcoat` (physical promotion). */
+    clearcoat?: number;
+    /** `inputs:clearcoatRoughness` (physical promotion). */
+    clearcoatRoughness?: number;
+    /** `inputs:specularColor`, only when `inputs:useSpecularWorkflow = 1`. */
+    specularColor?: Vec3;
+    /** OmniPBR `inputs:emissive_intensity` — multiplies the emissive color. */
+    emissiveIntensity?: number;
+    /** OmniGlass — `1` marks a transmissive dielectric (physical promotion, M20). */
+    transmission?: number;
+    /** OmniGlass `inputs:depth` — refraction volume thickness (scene units, M20). */
+    thickness?: number;
+    /** Diffuse/albedo texture, if any. */
+    colorTexture?: ResolvedTexture;
+    /** Opacity / alpha texture (may be the same image as `colorTexture`). */
+    opacityTexture?: ResolvedTexture;
+    /** Tangent-space normal map, if any. */
+    normalTexture?: ResolvedTexture;
+    /** Roughness map, if any. */
+    roughnessTexture?: ResolvedTexture;
+    /** Metallic map, if any. */
+    metalnessTexture?: ResolvedTexture;
+    /** Ambient-occlusion map, if any. */
+    occlusionTexture?: ResolvedTexture;
+    /** Emissive map, if any. */
+    emissiveTexture?: ResolvedTexture;
+    /** OmniPBR_ClearCoat `clearcoat_normalmap_texture` (physical promotion, M20). */
+    clearcoatNormalTexture?: ResolvedTexture;
+};
+type ResolveMaterialOptions = {
+    /** Parsed `.mdl` modules for MDL family detection and value fallback (M20). */
+    mdl?: MdlModuleProvider;
+    /** Receives diagnostics (unknown MDL material families). */
+    onWarn?: (message: string) => void;
+};
+/** Resolve the bound material's flat parameters for `prim`, or `undefined`. */
+declare function resolveBoundMaterial(stage: Stage, prim: Prim, options?: ResolveMaterialOptions): ResolvedMaterial | undefined;
+/**
+ * The `Shader` prim driving `prim`'s bound material surface, or `undefined`.
+ * Follows the same binding/surface-output resolution as
+ * {@link resolveBoundMaterial} — exposed for custom material factories (M22)
+ * that need the raw shader network rather than the flattened parameters.
+ */
+declare function findBoundSurfaceShader(stage: Stage, prim: Prim): Prim | undefined;
+
+/**
+ * Loads texture image assets referenced by `UsdShade` materials.
+ *
+ * A {@link TextureProvider} maps an authored asset path (plus sampler/transform
+ * options) to a `THREE.Texture`. The default provider fetches the image **bytes**
+ * through the {@link AssetResolver} and decodes them via a blob URL — so it works
+ * uniformly for textures served over HTTP and for images embedded inside a
+ * `.usdz` package (whose resolver serves zip entries, not real URLs). Decoded
+ * images are cached per resolved URL and shared across every texture that uses
+ * them; each `THREE.Texture` carries its own color space / wrap / transform.
+ */
+
+/**
+ * Color space to interpret a texture in. Color/albedo and emissive maps are
+ * `"srgb"`; data maps (normal, roughness, metalness, occlusion) are `"linear"`.
+ */
+type TextureColorSpace = "srgb" | "linear";
+/** Per-use sampler state applied to the returned `THREE.Texture`. */
+type TextureOptions = {
+    /** Defaults to `"srgb"`. */
+    colorSpace?: TextureColorSpace;
+    wrapS?: TextureWrap;
+    wrapT?: TextureWrap;
+    transform?: TextureTransform;
+    /** UV channel index (0 = `uv`, 1 = `uv1`, …) for multi-UV-set meshes. */
+    channel?: number;
+};
+/** Resolve an authored texture asset path to a `THREE.Texture` (or `null`). */
+type TextureProvider = (assetPath: string, options?: TextureOptions) => THREE.Texture | null;
+/**
+ * A {@link TextureProvider} backed by the {@link AssetResolver}, resolving paths
+ * against `baseUrl`. Image bytes are fetched once per URL (works for HTTP and
+ * `.usdz` entries alike) and the decoded image is shared; each call returns a
+ * distinct `THREE.Texture` carrying the requested color space / wrap / transform.
+ */
+declare function createTextureProvider(resolver: AssetResolver, baseUrl: string): TextureProvider;
+
+/**
+ * Binds renderable gprims — `UsdGeom.Mesh` plus the parametric solids (`Cube` /
+ * `Sphere` / `Cylinder` / `Capsule` / `Cone`) — to Three.js geometry and
+ * attaches them under the robot's link objects.
+ *
+ * Meshes are triangulated with a simple fan. Primvars (`st` UV sets, `normals`,
+ * `displayColor`) resolve with USD interpolation semantics — `:indices`
+ * de-referencing, vertex vs faceVarying (de-indexed) layouts, multiple UV
+ * channels. Solids tessellate from their schema attributes. Geometry is left
+ * in stage units; the global `metersPerUnit` scale is applied at the root in M9.
+ */
+
+type MeshKind = "visual" | "collision";
+/**
+ * Replaces material creation for mesh-like gprims (`Mesh` and the parametric
+ * solids). Return `null` to fall back to the default `UsdShade` resolution —
+ * the hook that lets the optional `three-usd-robot/nodes` entry build TSL
+ * `NodeMaterial`s without the core depending on `three/webgpu` (M22).
+ */
+type MaterialFactory = (prim: Prim, stage: Stage) => THREE.Material | null;
+type BindMeshesOptions = {
+    loadVisuals?: boolean;
+    loadCollisions?: boolean;
+    /** Resolves diffuse texture asset paths to `THREE.Texture` (M-tex). */
+    textureProvider?: TextureProvider;
+    /** Render `BasisCurves` with authored `widths` as tube meshes (M18). */
+    curveTubes?: boolean;
+    /** Receives fidelity diagnostics (channel-packing mismatches, M19). */
+    onWarn?: (message: string) => void;
+    /** Parsed `.mdl` modules for MDL material family/value resolution (M20). */
+    mdl?: MdlModuleProvider;
+    /** Overrides material creation for mesh-like gprims (M22). */
+    materialFactory?: MaterialFactory;
+};
+/**
+ * Build a `BufferGeometry` from a Mesh prim, or `null` if it has no points.
+ *
+ * Primvars resolve with full interpolation semantics (M19): `:indices` arrays
+ * are de-referenced, vertex-interpolated `st` sets / `normals` /
+ * `displayColor` bind onto the shared vertices, and any faceVarying primvar
+ * (or per-face color) switches the mesh to a de-indexed layout where every
+ * face corner owns its vertex. Extra UV sets become `uv1`, `uv2`, … in
+ * {@link meshUvSetNames} order.
+ *
+ * When the mesh carries `materialBind` face subsets, the triangles are ordered
+ * subset by subset and a geometry group is added for each — so the mesh can be
+ * drawn with one material per subset (see {@link buildMeshMaterials}). Group
+ * order matches {@link getMaterialSubsets}, with any unassigned faces last.
+ */
+declare function buildMeshGeometry(meshPrim: Prim): THREE.BufferGeometry | null;
+/**
+ * Build geometry for any renderable gprim: `Mesh` via {@link buildMeshGeometry},
+ * parametric solids from their schema attributes. Solids follow UsdGeom
+ * semantics — sizes in stage units, centered at the origin, `axis` (default
+ * `"Z"`) along the spine, and a capsule's `height` spans only its cylindrical
+ * section. Returns `null` for unsupported prim types.
+ */
+declare function buildGprimGeometry(prim: Prim): THREE.BufferGeometry | null;
+type BuildGprimOptions = {
+    /** Resolves texture asset paths for mesh materials. */
+    textureProvider?: TextureProvider;
+    /**
+     * Render `BasisCurves` that author `widths` as tube meshes instead of
+     * 1-px lines (default `false`).
+     */
+    curveTubes?: boolean;
+    /** Receives fidelity diagnostics (channel-packing mismatches, M19). */
+    onWarn?: (message: string) => void;
+    /** Parsed `.mdl` modules for MDL material family/value resolution (M20). */
+    mdl?: MdlModuleProvider;
+    /** Overrides material creation for mesh-like gprims (M22). */
+    materialFactory?: MaterialFactory;
+};
+/**
+ * Build a renderable `THREE.Object3D` for any supported gprim (M18):
+ * `Mesh` and the parametric solids become a `THREE.Mesh` (via
+ * {@link buildGprimGeometry} + {@link buildMeshMaterials}), `Points` a
+ * `THREE.Points`, and `BasisCurves` a `THREE.Group` holding one line — or,
+ * with {@link BuildGprimOptions.curveTubes}, one tube mesh — per curve.
+ * Returns `null` for unsupported prim types and degenerate geometry.
+ */
+declare function buildGprimObject(prim: Prim, stage?: Stage, options?: BuildGprimOptions): THREE.Object3D | null;
+/**
+ * Build a material for a gprim. Color priority: bound `UsdShade` material
+ * (when `stage` is given) → `primvars:displayColor` → default gray. Textures
+ * (via `textures`) become the matching `MeshStandardMaterial` maps — diffuse →
+ * `map` (sRGB), plus `normalMap` / `roughnessMap` / `metalnessMap` / `aoMap`
+ * (linear data) and emissive `emissiveMap`. Metalness / roughness / opacity /
+ * emissive constants come from the bound material when present.
+ */
+declare function buildMeshMaterial(meshPrim: Prim, stage?: Stage, textures?: TextureProvider, 
+/** Resolve the material binding from here instead (a `GeomSubset`). */
+bindingPrim?: Prim, 
+/** Receives fidelity diagnostics (channel-packing mismatches, M19). */
+onWarn?: (message: string) => void, 
+/** Parsed `.mdl` modules for MDL material family/value resolution (M20). */
+mdl?: MdlModuleProvider): THREE.Material;
+/**
+ * Attach visual (and optionally collision) meshes to every link of a built
+ * {@link ThreeUsdRobot}. Each mesh is positioned by its transform relative to
+ * the owning link prim.
+ */
+declare function bindRobotMeshes(stage: Stage, robot3d: ThreeUsdRobot, desc: RobotDescription, options?: BindMeshesOptions): void;
+/**
+ * Attach the gprims that belong to no link — the static scenery of a cell that
+ * also contains robots. The authored prim hierarchy is mirrored with
+ * `THREE.Group` nodes (each carrying `userData.primPath` and its prim's local
+ * transform), so grouped scenery — a pallet and its cartons, a fence and its
+ * wires — stays one movable subtree. World placements are unchanged, and the
+ * loader's up-axis and unit normalization still applies at the robot root.
+ * Collision-only and guide/proxy prims are skipped.
+ */
+declare function bindSceneMeshes(stage: Stage, robot3d: ThreeUsdRobot, desc: RobotDescription, options?: {
+    textureProvider?: TextureProvider;
+    curveTubes?: boolean;
+    onWarn?: (message: string) => void;
+    mdl?: MdlModuleProvider;
+    materialFactory?: MaterialFactory;
+}): number;
+
+export { type BindMeshesOptions as B, type MaterialFactory as M, type ResolveMaterialOptions as R, type TextureProvider as T, type BuildGprimOptions as a, type MeshKind as b, type ResolvedMaterial as c, type ResolvedTexture as d, type TextureColorSpace as e, type TextureOptions as f, type TextureTransform as g, type TextureWrap as h, bindRobotMeshes as i, bindSceneMeshes as j, buildGprimGeometry as k, buildGprimObject as l, buildMeshGeometry as m, buildMeshMaterial as n, createTextureProvider as o, findBoundSurfaceShader as p, resolveBoundMaterial as r };