three-usd-robot 0.3.0 → 0.4.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,20 @@ 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
+}
+```
+
 ### Inspect without Three.js
 
 ```ts

package/dist/{ThreeUsdRobot-C6uqpNZA.d.ts → ThreeUsdRobot-Deoh7zam.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-CZjBMA1I.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/{buildKinematicTree-BJuC_-5_.d.ts → buildKinematicTree-CZjBMA1I.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 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 };