three-usd-robot 0.4.0 → 0.6.0

package/README.md

@@ -1,32 +1,32 @@
 # three-usd-robot
 
-> **Kinematic OpenUSD robot loader for Three.js.**
-> Load Isaac Sim / OpenUSD robot assets, extract joints and links, and control
-> articulations directly in the browser — no physics engine required.
+> **Kinematic OpenUSD robot loader — and exporter — for Three.js.**
+> Load Isaac Sim / OpenUSD robot assets, control their joints in the browser,
+> and write scenes back out as USD. No physics engine, no OpenUSD/WASM
+> dependency.
 
 Think of it as a **USD version of [`urdf-loader`](https://www.npmjs.com/package/urdf-loader)**:
-it reads the link / joint / xform / mesh structure out of `UsdPhysics` robot assets
+it reads the link / joint / xform / mesh structure out of `UsdPhysics` assets
 and drives forward kinematics on a Three.js `Object3D` hierarchy.
 
-> 🚧 **Status: v0.3.** Loads **ASCII `.usda`**, **binary `.usdc` / `.usd`
-> (crate)**, and **`.usdz`** robots — including **multi-file assets** via
-> references / payloads / sublayers (resolved across `.usda` *and* binary layers,
-> with relationship-path remapping), **variant selections**, and **instanceable**
-> prims — drives forward kinematics with meshes, applies flat **`UsdShade`
-> material colors** (UsdPreviewSurface / OmniPBR constants) and **diffuse
-> textures** (`UsdUVTexture`), normalizes up-axis & units, seeds the initial
-> pose, and **plays back time-sampled joint trajectories**. The crate reader is a
-> from-scratch TypeScript implementation (no OpenUSD/WASM dependency). Not yet:
-> time samples and variant *selection* stored inside binary crate.
+![A robot cell loaded in the browser](assets/threejs.png)
 
-```ts
-// .usda / .usdc / binary .usd / .usdz are all auto-detected:
-const robot = await new ThreeUsdRobotLoader().loadAsync("/assets/robot.usd");
-// or from bytes you already have:
-const robot = await new ThreeUsdRobotLoader().parseCrate(usdcBytes);
-```
+## Features
+
+- **Formats** — ASCII `.usda`, binary `.usdc` / `.usd`, and `.usdz`, auto-detected.
+  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 with `UsdShade` materials (UsdPreviewSurface / OmniPBR)
+  and textures; up-axis and units normalized automatically.
+- **Animation** — plays back time-sampled joint trajectories.
+- **Export** — write robots and whole cells back to `.usda` / `.usdz`,
+  simulation-ready for Isaac Sim.
+- **React** — declarative `<UsdRobot>` for React Three Fiber.
 
-![demo](assets/anim_demo.gif)
+Not yet supported: time samples and variant *selections* stored inside binary
+crate files, and full material/shader fidelity.
 
 ## Install
 
@@ -36,11 +36,12 @@ npm install three-usd-robot three
 
 `three` is a **peer dependency** (`>=0.160.0`).
 
-## Usage
+## Quick start
 
 ```ts
 import { ThreeUsdRobotLoader } from "three-usd-robot";
 
+// .usda / .usdc / binary .usd / .usdz are all auto-detected.
 const robot = await new ThreeUsdRobotLoader().loadAsync("/assets/arm.usda");
 scene.add(robot);
 
@@ -52,9 +53,12 @@ const handMatrix = robot.getLinkWorldMatrix("tool0"); // THREE.Matrix4
 const handPos = robot.getLinkWorldPosition("tool0"); // THREE.Vector3
 
 robot.getJointNames(); // controllable joints
-robot.getKinematicTree(); // root, ordering, loopJoints, ...
+robot.getKinematicTree(); // root, ordering, loop joints, ...
 ```
 
+Already have the bytes? Use `parse(usdaText)`, `parseCrate(usdcBytes)` or
+`parseUsdz(bytes)` instead of `loadAsync`.
+
 ### Viewer toggles & helpers
 
 ```ts
@@ -67,6 +71,10 @@ import { addJointLimitHelpers } from "three-usd-robot/helpers";
 addJointLimitHelpers(robot); // arc (revolute) / segment (prismatic) per joint
 ```
 
+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.
+
 ### Joint slider panel (lil-gui)
 
 ```ts
@@ -76,24 +84,107 @@ import { createJointSliderPanel } from "three-usd-robot/extras";
 createJointSliderPanel(robot, new GUI()); // one slider per articulated joint
 ```
 
-The `extras` panel takes the GUI instance from you, so the library never bundles
-`lil-gui`. See [`examples/`](./examples) for runnable Vite demos.
+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 (joint-state or drive-target
-time samples), the robot plays them back:
+If the asset has time-sampled joint trajectories, the robot plays them back:
 
 ```ts
-if (robot.hasAnimation()) {
-  const { start, end } = robot.getTimeRange()!;
-  const fps = robot.getTimeCodesPerSecond();
-  // in your render loop, advance a time code and sample:
+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
 }
 ```
 
-### Inspect without Three.js
+### 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>;
+```
+
+Also exported: `useUsdRobot(url)` (Suspense loader), `useRobotAnimation(robot)`,
+`preloadUsdRobot`, `clearUsdRobotCache`. Pass a `ref` to `<UsdRobot>` for the
+imperative API.
+
+## 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)
+
+```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.
+const builder = new RobotBuilder({ name: "my_robot" });
+builder.addLink({ name: "base", visuals: [baseMesh] });
+builder.addLink({ name: "arm", frame: armFrame, visuals: [armMesh] });
+builder.addFixedJoint({ name: "root_joint", child: "base" });
+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";
@@ -102,14 +193,24 @@ const desc = extractRobotDescription(Stage.OpenFromString(usdaText));
 console.log(desc.rootLink, Object.keys(desc.joints));
 ```
 
+Command line: `npx tsx scripts/usdc-to-usda.ts robot.usd` converts binary crate
+and `.usdz` packages to ASCII USDA.
+
+## Examples
+
+[`examples/`](./examples) holds runnable Vite demos, including a React Three
+Fiber viewer that loads any asset via `?asset=<url>` and exports it back to
+`.usda` / `.usdz`.
+
 ## Package entry points
 
 | Import | Contents |
 | --- | --- |
-| `three-usd-robot` | Three.js runtime — `ThreeUsdRobotLoader`, `ThreeUsdRobot` |
-| `three-usd-robot/core` | Three.js-independent USDA parser, robot IR, forward-kinematics math |
+| `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/extras` | Heavier convenience utilities (e.g. joint slider panel) |
+| `three-usd-robot/extras` | Joint slider panel (bring your own `lil-gui`) |
+| `three-usd-robot/react` | React Three Fiber `<UsdRobot>` component + hooks |
 
 ## Development
 

package/dist/AssetResolver-CpIJNgWZ.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Resolves USD asset paths (from references / payloads / sublayers) to URLs and
+ * fetches their text. Composition (`composition.ts`) is I/O-agnostic and goes
+ * through an {@link AssetResolver}, so the same engine works in the browser, in
+ * Node, or against an in-memory file map in tests.
+ */
+interface AssetResolver {
+    /** Resolve an authored asset path against the layer's base URL to an absolute key. */
+    resolve(assetPath: string, baseUrl: string): string;
+    /** Fetch the text of a resolved asset; rejects if it cannot be read. */
+    fetchText(url: string): Promise<string>;
+    /** Fetch the raw bytes of a resolved asset (for binary USDC / USDZ). Optional. */
+    fetchBytes?(url: string): Promise<Uint8Array>;
+}
+/** URL-based resolver using the global `fetch` (browser / Node 18+). */
+declare class DefaultAssetResolver implements AssetResolver {
+    resolve(assetPath: string, baseUrl: string): string;
+    fetchText(url: string): Promise<string>;
+    fetchBytes(url: string): Promise<Uint8Array>;
+}
+/**
+ * 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;
+
+export { type AssetResolver as A, DefaultAssetResolver as D, createMemoryResolver as c, joinPosix as j };

package/dist/{ThreeUsdRobot-Deoh7zam.d.ts → ThreeUsdRobot-CajXJqYU.d.ts}

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

package/dist/ThreeUsdRobotLoader-DrMMLzo-.d.ts

@@ -0,0 +1,67 @@
+import { R as RobotDescription } from './buildKinematicTree-wtZPzy0B.js';
+import { A as AssetResolver } from './AssetResolver-CpIJNgWZ.js';
+import { T as ThreeUsdRobot } from './ThreeUsdRobot-CajXJqYU.js';
+
+type ThreeUsdRobotLoaderOptions = {
+    /** Resolver for references / payloads / sublayers (default {@link DefaultAssetResolver}). */
+    assetResolver?: AssetResolver;
+    /** Render visual meshes (M6). */
+    loadVisuals?: boolean;
+    /** Render collision meshes (M6). */
+    loadCollisions?: boolean;
+    /**
+     * Also render Mesh prims that belong to no link — the static scenery of a
+     * cell that contains robots (floor, guarding, racking, …). Placed by their
+     * authored stage transform. Default `false`.
+     */
+    loadSceneGeometry?: 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). */
+    unitScale?: number;
+    /** Clamp `setJointValue` to authored limits (default `true`). */
+    clampJointLimits?: boolean;
+    /** Seed joints from drive targets / joint state (M9). */
+    applyDriveTargetsAsInitialPose?: boolean;
+    /** Override the robot name. */
+    robotName?: string;
+    /** Receives non-fatal load diagnostics. */
+    onWarn?: (message: string) => void;
+};
+/**
+ * Loads Isaac Sim / OpenUSD robot assets into a controllable {@link ThreeUsdRobot}.
+ *
+ * Composition (references / payloads / sublayers, M8) is resolved through an
+ * {@link AssetResolver}. Mesh rendering is M6; unit / up-axis / initial-pose
+ * handling is M9; USDC and variants are M10.
+ */
+declare class ThreeUsdRobotLoader {
+    readonly options: ThreeUsdRobotLoaderOptions;
+    constructor(options?: ThreeUsdRobotLoaderOptions);
+    private get resolver();
+    /**
+     * Fetch an asset by URL and build the robot. `.usdz` packages are unzipped and
+     * composed from their entries; everything else is sniffed for the crate magic
+     * and parsed as binary USDC or USDA text.
+     */
+    loadAsync(url: string): Promise<ThreeUsdRobot>;
+    private fetchRootBytes;
+    /** Build a robot (composed, with meshes) from USDA source text. */
+    parse(text: string, baseUrl?: string): Promise<ThreeUsdRobot>;
+    /** 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, baseUrl?: string): Promise<ThreeUsdRobot>;
+    /** Parse + compose USDA source into the Three.js-independent robot IR. */
+    parseRobotDescription(text: string, baseUrl?: string): Promise<RobotDescription>;
+    private buildFromStage;
+    private composeStage;
+    /** Compose a layer from raw bytes, sniffing binary crate vs USDA text. */
+    private composeStageFromBytes;
+    private robotOptions;
+    private extractOptions;
+}
+
+export { type ThreeUsdRobotLoaderOptions as T, ThreeUsdRobotLoader as a };

package/dist/{buildKinematicTree-CZjBMA1I.d.ts → buildKinematicTree-wtZPzy0B.d.ts}

@@ -125,6 +125,25 @@ type RelationshipSpec = {
     line: number;
 };
 
+/**
+ * Time-sample interpolation for animated values (e.g. joint trajectories).
+ *
+ * USD time samples are keyed by time code. We linearly interpolate between the
+ * two bracketing samples and hold the endpoints outside the authored range
+ * (matching USD's held extrapolation).
+ */
+/** A sorted time-sampled scalar channel. */
+type SampleChannel = {
+    /** Sample times, ascending. */
+    times: number[];
+    /** Sample values, parallel to {@link times} (SI units). */
+    values: number[];
+};
+/** Linearly sample `channel` at time `t` (held outside the range). */
+declare function interpolate(channel: SampleChannel, t: number): number;
+/** Build a sorted {@link SampleChannel} from `(time → value)` pairs via `map`. */
+declare function channelFromSamples(samples: Map<number, number>): SampleChannel;
+
 /**
  * Minimal 4×4 matrix math, Three.js-independent.
  *
@@ -176,25 +195,21 @@ declare function makeEuler(angles: Vec3, order: string): Mat4;
 declare function fromUsdMatrix(m: UsdMatrix): Mat4;
 /** Extract the translation component `[x, y, z]` from a {@link Mat4}. */
 declare function getTranslation(m: Mat4): Vec3;
-
+/** Copy a {@link Mat4} into a USD `matrix4d` — same flat layout (see module docs). */
+declare function toUsdMatrix(m: Mat4): UsdMatrix;
 /**
- * Time-sample interpolation for animated values (e.g. joint trajectories).
+ * Decompose a rigid transform into translation + orientation (M13 export).
  *
- * USD time samples are keyed by time code. We linearly interpolate between the
- * two bracketing samples and hold the endpoints outside the authored range
- * (matching USD's held extrapolation).
+ * The rotation basis is orthonormalized (Gram-Schmidt, right-handed) before
+ * quaternion extraction; `rigid` reports whether the input already was rigid
+ * within tolerance, so callers can warn that scale/shear/reflection was
+ * discarded.
  */
-/** A sorted time-sampled scalar channel. */
-type SampleChannel = {
-    /** Sample times, ascending. */
-    times: number[];
-    /** Sample values, parallel to {@link times} (SI units). */
-    values: number[];
+declare function decomposeRigid(m: Mat4): {
+    position: Vec3;
+    orientation: Quat;
+    rigid: boolean;
 };
-/** Linearly sample `channel` at time `t` (held outside the range). */
-declare function interpolate(channel: SampleChannel, t: number): number;
-/** Build a sorted {@link SampleChannel} from `(time → value)` pairs via `map`. */
-declare function channelFromSamples(samples: Map<number, number>): SampleChannel;
 
 /**
  * Robot intermediate representation (IR) — Three.js-independent.
@@ -240,6 +255,28 @@ type LinkDescription = {
     visualPrims: string[];
     /** Mesh prim paths flagged with a collision API. */
     collisionPrims?: string[];
+    /** Mass properties (`UsdPhysicsMassAPI`), if authored (M16). */
+    inertial?: LinkInertialDescription;
+    /**
+     * Authored stage (world) transform of the link prim, when not identity.
+     * Joint chains place tree links; this places floating roots and links that
+     * are isolated from the chosen tree (e.g. other machines / free bodies on a
+     * multi-articulation stage).
+     */
+    worldTransform?: Mat4;
+};
+/** Mass properties as authored by `UsdPhysicsMassAPI` (stage units). */
+type LinkInertialDescription = {
+    /** Mass in kilograms. */
+    mass?: number;
+    /** Center of mass in the link frame (stage linear units). */
+    centerOfMass?: Vec3;
+    /** Principal moments of inertia. */
+    diagonalInertia?: Vec3;
+    /** Orientation of the principal inertia axes in the link frame. */
+    principalAxes?: Quat;
+    /** Density — the physics engine derives mass from it when `mass` is absent. */
+    density?: number;
 };
 type JointDescription = {
     /** Display name (leaf prim name). */
@@ -319,4 +356,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, makeRotationFromQuat as E, makeRotationX as F, makeRotationY as G, makeRotationZ as H, makeScale as I, type JointType as J, type KinematicTree as K, type LinkDescription as L, type Mat4 as M, makeTranslation as N, multiply as O, type PrimSpec as P, Quat as Q, type RobotDescription as R, type SampleChannel as S, type TreeEdge as T, type UsdDictionary as U, type Vec3 as V, multiplyAll as W, 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 SdfPath as k, type Specifier as l, UsdMatrix as m, type UsdValue as n, type UsdaFile as o, type Variability as p, type Vec2 as q, type Vec4 as r, buildKinematicTree as s, channelFromSamples as t, fromUsdMatrix as u, getTranslation as v, identity4 as w, interpolate as x, invert as y, makeEuler as z };
+export { type Axis as A, type BuildTreeOptions as B, type CompositionArc as C, DEG2RAD as D, invert as E, makeEuler as F, makeRotationFromQuat as G, makeRotationX as H, makeRotationY as I, type JointType as J, type KinematicTree as K, type LinkDescription as L, type Mat4 as M, makeRotationZ as N, makeScale as O, type PrimSpec as P, Quat as Q, type RobotDescription as R, type SampleChannel as S, type TreeEdge as T, type UsdaFile as U, type Vec2 as V, makeTranslation as W, multiply as X, multiplyAll as Y, toUsdMatrix as Z, type JointDescription as a, type Vec3 as b, type JointDriveDescription as c, type LinkInertialDescription as d, AssetPath as e, type AttributeSpec as f, type KinematicNode as g, type ListOp as h, type MetadataMap as i, type PropertySpec as j, RAD2DEG as k, type RelationshipSpec as l, type SdfPath as m, type Specifier as n, type UsdDictionary as o, UsdMatrix as p, type UsdValue as q, type Variability as r, type Vec4 as s, buildKinematicTree as t, channelFromSamples as u, decomposeRigid as v, fromUsdMatrix as w, getTranslation as x, identity4 as y, interpolate as z };