three-usd-robot 0.5.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,26 +84,24 @@ 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
 }
 ```
 
 ### React Three Fiber
 
-`three-usd-robot/react` provides a declarative `<UsdRobot>` for R3F (`react` and
+`three-usd-robot/react` provides a declarative `<UsdRobot>` (`react` and
 `@react-three/fiber` are **optional** peer deps):
 
 ```tsx
@@ -117,11 +123,68 @@ import { UsdRobot } from "three-usd-robot/react";
 </Canvas>;
 ```
 
-Also exported: `useUsdRobot(url)` (Suspense loader), `useRobotAnimation(robot)`
-(per-frame playback), `preloadUsdRobot`, `clearUsdRobotCache`. Pass a `ref` to
-`<UsdRobot>` for the imperative `ThreeUsdRobot` API.
+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
 
-### Inspect 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";
@@ -130,15 +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/react` | React Three Fiber `<UsdRobot>` component + hooks (optional `react` / `@react-three/fiber` peers) |
+| `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/{ThreeUsdRobot-D9AOUaVh.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-3oKG00Sc.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-BgsnuJWd.d.ts → ThreeUsdRobotLoader-DrMMLzo-.d.ts}

@@ -1,6 +1,6 @@
-import { R as RobotDescription } from './buildKinematicTree-3oKG00Sc.js';
+import { R as RobotDescription } from './buildKinematicTree-wtZPzy0B.js';
 import { A as AssetResolver } from './AssetResolver-CpIJNgWZ.js';
-import { T as ThreeUsdRobot } from './ThreeUsdRobot-D9AOUaVh.js';
+import { T as ThreeUsdRobot } from './ThreeUsdRobot-CajXJqYU.js';
 
 type ThreeUsdRobotLoaderOptions = {
     /** Resolver for references / payloads / sublayers (default {@link DefaultAssetResolver}). */
@@ -9,6 +9,12 @@ type ThreeUsdRobotLoaderOptions = {
     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). */

package/dist/{buildKinematicTree-3oKG00Sc.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 Vec2 as V, multiplyAll as W, type JointDescription as a, type Vec3 as b, AssetPath as c, type AttributeSpec as d, type JointDriveDescription as e, type KinematicNode as f, type ListOp as g, type MetadataMap as h, type PropertySpec as i, RAD2DEG as j, type RelationshipSpec as k, type SdfPath as l, type Specifier as m, UsdMatrix as n, type UsdValue as o, type UsdaFile as p, type Variability 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 };