three-usd-robot 0.3.0 → 0.5.0

package/README.md

@@ -8,15 +8,16 @@ Think of it as a **USD version of [`urdf-loader`](https://www.npmjs.com/package/
 it reads the link / joint / xform / mesh structure out of `UsdPhysics` robot assets
 and drives forward kinematics on a Three.js `Object3D` hierarchy.
 
-> 🚧 **Status: v0.2 + USDC.** Loads **ASCII `.usda`**, **binary `.usdc` / `.usd`
-> (crate)**, and **`.usdz`** robots — including multi-file assets via
-> references/payloads/sublayers, **variant selections**, and **instanceable**
-> prims (internal-reference prototypes) — drives forward kinematics with meshes,
-> applies flat **`UsdShade` material colors** (UsdPreviewSurface / OmniPBR
-> constants), normalizes up-axis & units, and seeds the initial pose. The
-> crate reader is a from-scratch TypeScript implementation (no OpenUSD/WASM
-> dependency). Not yet: variant resolution inside binary crate, and time-sampled
-> (animated) values.
+> 🚧 **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.
 
 ```ts
 // .usda / .usdc / binary .usd / .usdz are all auto-detected:
@@ -25,6 +26,8 @@ const robot = await new ThreeUsdRobotLoader().loadAsync("/assets/robot.usd");
 const robot = await new ThreeUsdRobotLoader().parseCrate(usdcBytes);
 ```
 
+![demo](assets/anim_demo.gif)
+
 ## Install
 
 ```sh
@@ -76,6 +79,48 @@ 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.
 
+### Animation playback
+
+If the asset has time-sampled joint trajectories (joint-state or drive-target
+time samples), 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:
+  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
+`@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)`
+(per-frame playback), `preloadUsdRobot`, `clearUsdRobotCache`. Pass a `ref` to
+`<UsdRobot>` for the imperative `ThreeUsdRobot` API.
+
 ### Inspect without Three.js
 
 ```ts
@@ -93,6 +138,7 @@ console.log(desc.rootLink, Object.keys(desc.joints));
 | `three-usd-robot/core` | Three.js-independent USDA parser, 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) |
 
 ## 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-C6uqpNZA.d.ts → ThreeUsdRobot-D9AOUaVh.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-BJuC_-5_.js';
+import { J as JointType, A as Axis, a as JointDescription, L as LinkDescription, R as RobotDescription, K as KinematicTree } from './buildKinematicTree-3oKG00Sc.js';
 
 /**
  * The articulated "motion" node of a joint, inserted between the joint's two
@@ -107,6 +107,20 @@ declare class ThreeUsdRobot extends THREE.Object3D {
     getJointNames(): string[];
     getLinkNames(): string[];
     getKinematicTree(): KinematicTree;
+    /** Playback rate in time codes per second (from the stage; default 24). */
+    getTimeCodesPerSecond(): number;
+    /** Whether any joint has a time-sampled trajectory. */
+    hasAnimation(): boolean;
+    /**
+     * Animation range in time codes: the union of authored joint sample ranges,
+     * falling back to the stage `startTimeCode`/`endTimeCode`. `null` if neither.
+     */
+    getTimeRange(): {
+        start: number;
+        end: number;
+    } | null;
+    /** Sample every animated joint at time code `t` and apply the values. */
+    setTime(t: number): void;
     get showVisual(): boolean;
     set showVisual(v: boolean);
     get showCollision(): boolean;

package/dist/ThreeUsdRobotLoader-BgsnuJWd.d.ts

@@ -0,0 +1,61 @@
+import { R as RobotDescription } from './buildKinematicTree-3oKG00Sc.js';
+import { A as AssetResolver } from './AssetResolver-CpIJNgWZ.js';
+import { T as ThreeUsdRobot } from './ThreeUsdRobot-D9AOUaVh.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;
+    /** 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-BJuC_-5_.d.ts → buildKinematicTree-3oKG00Sc.d.ts}

@@ -177,6 +177,25 @@ declare function fromUsdMatrix(m: UsdMatrix): Mat4;
 /** Extract the translation component `[x, y, z]` from a {@link Mat4}. */
 declare function getTranslation(m: Mat4): Vec3;
 
+/**
+ * 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;
+
 /**
  * Robot intermediate representation (IR) — Three.js-independent.
  *
@@ -205,6 +224,11 @@ type RobotDescription = {
     upAxis: "Y" | "Z";
     /** Stage linear unit, for the M9 scale normalization. */
     metersPerUnit: number;
+    /** Playback rate (time codes per second); defaults to 24 when unauthored. */
+    timeCodesPerSecond?: number;
+    /** Authored animation range (time codes), if any. */
+    startTimeCode?: number;
+    endTimeCode?: number;
     /** Non-fatal extraction diagnostics. */
     warnings?: string[];
 };
@@ -237,6 +261,8 @@ type JointDescription = {
     jointFrame1: Mat4;
     /** Initial joint value (SI) from JointStateAPI or a drive target, if authored. */
     initialValue?: number;
+    /** Time-sampled joint value trajectory (SI), if authored — drives playback. */
+    valueSamples?: SampleChannel;
     drive?: JointDriveDescription;
 };
 /** Authored joint drive parameters (`UsdPhysicsDriveAPI`), as read in M3. */
@@ -293,4 +319,4 @@ type BuildTreeOptions = {
 };
 declare function buildKinematicTree(robot: RobotDescription, options?: BuildTreeOptions): KinematicTree;
 
-export { type Axis as A, type BuildTreeOptions as B, type CompositionArc as C, DEG2RAD as D, makeRotationZ as E, makeScale as F, makeTranslation as G, multiply as H, multiplyAll as I, type JointType as J, type KinematicTree as K, type LinkDescription as L, type Mat4 as M, type PrimSpec as P, Quat as Q, type RobotDescription as R, type SdfPath as S, type TreeEdge as T, type UsdDictionary as U, type Vec3 as V, type JointDescription as a, AssetPath as b, type AttributeSpec as c, type JointDriveDescription as d, type KinematicNode as e, type ListOp as f, type MetadataMap as g, type PropertySpec as h, RAD2DEG as i, type RelationshipSpec as j, type Specifier as k, UsdMatrix as l, type UsdValue as m, type UsdaFile as n, type Variability as o, type Vec2 as p, type Vec4 as q, buildKinematicTree as r, fromUsdMatrix as s, getTranslation as t, identity4 as u, invert as v, makeEuler as w, makeRotationFromQuat as x, makeRotationX as y, makeRotationY as z };
+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 };