three-usd-robot 0.4.0 → 0.5.0

package/README.md

@@ -93,6 +93,34 @@ if (robot.hasAnimation()) {
 }
 ```
 
+### 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
@@ -110,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-Deoh7zam.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-CZjBMA1I.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

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-CZjBMA1I.d.ts → buildKinematicTree-3oKG00Sc.d.ts}

@@ -319,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, 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, 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 };