three-usd-robot 0.6.0 → 0.8.0

package/README.md

@@ -9,6 +9,11 @@ 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` assets
 and drives forward kinematics on a Three.js `Object3D` hierarchy.
 
+**[▶ Live demo](https://three-usd-robot.vercel.app)** — stock Isaac Sim robots
+streamed from NVIDIA's asset CDN, joints driven from a slider panel, and
+exported back to `.usda` / `.usdz` in the browser.
+
+![A franka panda loaded in the browser](assets/franka.png)
 ![A robot cell loaded in the browser](assets/threejs.png)
 
 ## Features
@@ -18,15 +23,35 @@ and drives forward kinematics on a Three.js `Object3D` hierarchy.
   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.
+- **Rendering** — meshes and solid gprims (`Cube` / `Sphere` / `Cylinder` /
+  `Capsule` / `Cone`) with `UsdShade` materials (UsdPreviewSurface / OmniPBR)
+  and textures; up-axis and units normalized automatically. Articulation-free
+  stages load as static scenes.
 - **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.
 
-Not yet supported: time samples and variant *selections* stored inside binary
-crate files, and full material/shader fidelity.
+Stock Isaac Sim robot assets load straight from their public CDN — Franka
+Panda, UR10e, Fanuc CRX-10iA/L, Kuka KR210, Shadow Hand, Unitree H1/Go2 and
+friends all compose from their variant-driven, multi-layer form:
+
+```ts
+const ROOT = "https://omniverse-content-production.s3-us-west-2.amazonaws.com/Assets/Isaac/5.1";
+const franka = await new ThreeUsdRobotLoader()
+  .loadAsync(`${ROOT}/Isaac/Robots/FrankaRobotics/FrankaPanda/franka.usd`);
+
+franka.setJointValues({ panda_joint2: -0.785, panda_joint4: -2.356, panda_joint6: 1.571 });
+franka.getLinkWorldPosition("panda_hand"); // (0.307, 0, 0.590) — the documented ready pose
+```
+
+The CDN is public and CORS-enabled, so this works in the browser too. Try
+`npx tsx scripts/demo-franka.ts` for a console walkthrough (articulation table,
+FK check, and a re-export to one self-contained file), or open the Vite example
+and pick a robot from the preset list.
+
+Not yet supported: time samples stored inside binary crate files, point/curve
+gprims (`Points`, `BasisCurves`, …), and full material/shader fidelity.
 
 ## Install
 
@@ -56,8 +81,38 @@ robot.getJointNames(); // controllable joints
 robot.getKinematicTree(); // root, ordering, loop joints, ...
 ```
 
-Already have the bytes? Use `parse(usdaText)`, `parseCrate(usdcBytes)` or
-`parseUsdz(bytes)` instead of `loadAsync`.
+No URL? `parse` also takes in-memory content: USDA source text, or an
+`ArrayBuffer` / typed array / `Blob` holding any supported format — the zip /
+crate magic is sniffed, so a dropped `File` or a response body works as-is:
+
+```ts
+const loader = new ThreeUsdRobotLoader();
+await loader.parse(usdaText); // USDA source string
+await loader.parse(file); // File / Blob from drag & drop or <input type="file">
+await loader.parse(await res.arrayBuffer()); // a fetch you did yourself
+```
+
+`parseUsdz(data)` / `parseCrate(data, baseUrl)` stay as explicit-format entries,
+and `parseRobotDescription(data)` returns the Three.js-independent IR. Pass a
+`baseUrl` as the second `parse` argument if the layer has relative references
+or texture paths to resolve.
+
+### Stable addressing (naming contract)
+
+Joints and links are keyed by their prim's **leaf name** while it is unique
+across the robot; on a collision (say, two arms each with a `seg` link) the
+colliding entries are keyed by their **full prim path** instead —
+deterministically. Every accessor also takes the full prim path directly, so
+tooling can pin exact prims no matter how the asset is named:
+
+```ts
+robot.setJointValue("/World/armL/j1", 0.4); // same joint as its key
+robot.getLinkWorldMatrix("/World/armL/seg");
+robot.getLinkObjectsByPath(); // Map<primPath, LinkObject>
+robot.getJointObjectsByPath(); // Map<primPath, JointObject>
+```
+
+`LinkObject.primPath` / `JointObject.primPath` carry the reverse direction.
 
 ### Viewer toggles & helpers
 
@@ -71,9 +126,38 @@ import { addJointLimitHelpers } from "three-usd-robot/helpers";
 addJointLimitHelpers(robot); // arc (revolute) / segment (prismatic) per joint
 ```
 
+### Link highlighting & ghosts
+
+Per-link appearance helpers cover the common viewer chores — flagging
+colliding links, material swaps, and translucent "ghost" pose previews:
+
+```ts
+import {
+  createGhostRobot,
+  highlightLink,
+  restoreLinkMaterials,
+  setLinkMaterial,
+} from "three-usd-robot/helpers";
+
+highlightLink(robot, "link1"); // emissive red tint; maps/colors kept
+highlightLink(robot, "/World/armL/seg", { color: 0xffaa00, opacity: 0.6 });
+setLinkMaterial(robot, "link2", new THREE.MeshBasicMaterial({ wireframe: true }));
+restoreLinkMaterials(robot, "link1"); // exact original materials back
+
+const ghost = createGhostRobot(robot, { jointValues: { joint1: 1.2 } });
+scene.add(ghost); // translucent copy previewing the target pose
+ghost.setJointValues(ikSolution); // a full ThreeUsdRobot, driveable like the source
+```
+
+Highlights never stack (each call re-tints from the originals), and ghosts
+share the source's geometry — cloning is cheap enough for onion-skinning.
+
 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.
+(floor, guarding, racking, …) around the machines. A stage with **no
+articulation at all** — a plain static USD scene — is detected and rendered as
+scene geometry automatically, with the same unit / up-axis normalization; pass
+`loadSceneGeometry: false` to opt out.
 
 ### Joint slider panel (lil-gui)
 
@@ -198,9 +282,16 @@ 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`.
+[`examples/`](./examples) holds runnable Vite demos:
+
+- **`vite-joint-slider`** — the [live demo](https://three-usd-robot.vercel.app):
+  vanilla Three.js + `lil-gui`, with a robot picker, joint sliders, animation
+  playback and USD export.
+- **`vite-basic-viewer`** — the same thing through React Three Fiber.
+
+Both take `?asset=<url>` for any asset, or `?isaac=<path under Isaac/>` to pull
+one straight from NVIDIA's CDN. `npm run demo:build` generates the factory cell
+and builds the deployable site.
 
 ## Package entry points
 

package/dist/{ThreeUsdRobot-CajXJqYU.d.ts → ThreeUsdRobot-CsjraHqP.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-wtZPzy0B.js';
+import { J as JointType, A as Axis, a as JointDescription, L as LinkDescription, R as RobotDescription, K as KinematicTree } from './buildKinematicTree-D4R0hEtN.js';
 
 /**
  * The articulated "motion" node of a joint, inserted between the joint's two
@@ -10,6 +10,8 @@ import { J as JointType, A as Axis, a as JointDescription, L as LinkDescription,
 declare class JointObject extends THREE.Object3D {
     readonly isJointObject = true;
     readonly jointName: string;
+    /** Full USD prim path of the joint — the collision-proof address. */
+    readonly primPath: string;
     readonly jointType: JointType;
     readonly axisToken: Axis;
     readonly axis: THREE.Vector3;
@@ -63,6 +65,12 @@ type ThreeUsdRobotOptions = {
  * `parentLink → jointFrame0 → jointMotion → jointFrame1⁻¹ → childLink`,
  * where only `jointMotion` (a {@link JointObject}) changes with the joint value;
  * world poses then fall out of Three.js's `updateMatrixWorld`.
+ *
+ * **Naming contract** — a link/joint's key is its prim's leaf name when that
+ * is unique across the robot, else its full prim path (deterministic; see the
+ * extractor). Every accessor taking a name equally accepts the full prim path,
+ * which is stable regardless of collisions; {@link getLinkObjectsByPath} /
+ * {@link getJointObjectsByPath} enumerate the path-keyed tables.
  */
 declare class ThreeUsdRobot extends THREE.Object3D {
     readonly isThreeUsdRobot = true;
@@ -71,6 +79,8 @@ declare class ThreeUsdRobot extends THREE.Object3D {
     readonly clampJointLimits: boolean;
     private readonly linkObjects;
     private readonly jointObjects;
+    private readonly linkKeyByPath;
+    private readonly jointKeyByPath;
     private dirty;
     private readonly helperSize;
     private _showVisual;
@@ -89,7 +99,14 @@ declare class ThreeUsdRobot extends THREE.Object3D {
     /** Build `parent → frame0 → motion → frame1⁻¹ → child` for one joint. */
     private attachJointChain;
     private attachIsolatedLinks;
-    /** Set one joint value. Unknown joints are ignored. Returns whether it applied. */
+    /** Resolve a link reference — key or full prim path — to the extractor key. */
+    private linkKey;
+    /** Resolve a joint reference — key or full prim path — to the extractor key. */
+    private jointKey;
+    /**
+     * Set one joint value, addressed by key or full prim path. Unknown joints
+     * are ignored. Returns whether it applied.
+     */
     setJointValue(name: string, value: number): boolean;
     /** Set several joint values at once (matrix update is coalesced). */
     setJointValues(values: Record<string, number>): void;
@@ -97,10 +114,23 @@ declare class ThreeUsdRobot extends THREE.Object3D {
     /** Recompute world matrices. Called lazily by the getters; safe to call directly. */
     updateKinematics(): void;
     private ensureUpdated;
+    /** World matrix of a link, addressed by key or full prim path. */
     getLinkWorldMatrix(name: string): THREE.Matrix4;
     getLinkWorldPosition(name: string): THREE.Vector3;
+    /** Link object by key or full prim path. */
     getLinkObject(name: string): LinkObject | undefined;
+    /** Joint object by key or full prim path. */
     getJointObject(name: string): JointObject | undefined;
+    /**
+     * Table of link prim path → {@link LinkObject}. Prim paths are the
+     * collision-proof way to pin a link (e.g. to attach tools or gizmos).
+     */
+    getLinkObjectsByPath(): Map<string, LinkObject>;
+    /**
+     * Table of joint prim path → {@link JointObject}, covering the joints
+     * realized in the kinematic tree (loop joints have no motion node).
+     */
+    getJointObjectsByPath(): Map<string, JointObject>;
     getJoints(): JointDescription[];
     getLinks(): LinkDescription[];
     /** Names of the articulated (controllable) joints. */

package/dist/{ThreeUsdRobotLoader-DrMMLzo-.d.ts → ThreeUsdRobotLoader-CxOGRLXH.d.ts}

@@ -1,6 +1,6 @@
-import { R as RobotDescription } from './buildKinematicTree-wtZPzy0B.js';
-import { A as AssetResolver } from './AssetResolver-CpIJNgWZ.js';
-import { T as ThreeUsdRobot } from './ThreeUsdRobot-CajXJqYU.js';
+import { R as RobotDescription } from './buildKinematicTree-D4R0hEtN.js';
+import { A as AssetResolver, U as UsdSource, B as BinarySource } from './bytes-MOJ2oN-u.js';
+import { T as ThreeUsdRobot } from './ThreeUsdRobot-CsjraHqP.js';
 
 type ThreeUsdRobotLoaderOptions = {
     /** Resolver for references / payloads / sublayers (default {@link DefaultAssetResolver}). */
@@ -10,9 +10,10 @@ type ThreeUsdRobotLoaderOptions = {
     /** 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`.
+     * Also render gprims 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`; a stage with no articulation at
+     * all (a pure static scene) defaults to `true` so it renders out of the box.
      */
     loadSceneGeometry?: boolean;
     /** Load diffuse textures referenced by materials (default `true`). */
@@ -33,6 +34,8 @@ type ThreeUsdRobotLoaderOptions = {
 /**
  * Loads Isaac Sim / OpenUSD robot assets into a controllable {@link ThreeUsdRobot}.
  *
+ * Assets load by URL ({@link loadAsync}) or from in-memory content
+ * ({@link parse} — USDA text, `ArrayBuffer`, typed array, or `Blob`/`File`).
  * 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.
@@ -43,19 +46,31 @@ declare class ThreeUsdRobotLoader {
     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.
+     * composed from their entries; everything else is sniffed for the zip / crate
+     * magic and parsed as USDZ, 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>;
+    /**
+     * Build a robot from in-memory content — no fetch involved. Accepts USDA
+     * source text, or an `ArrayBuffer` / typed array / `Blob` (e.g. a dropped
+     * `File`) holding USDA text, a binary crate, or a `.usdz` package; binary
+     * input is sniffed for the zip / crate magic. `baseUrl` anchors relative
+     * references, payloads, and texture paths of non-package input.
+     */
+    parse(data: UsdSource, baseUrl?: string): Promise<ThreeUsdRobot>;
+    /** Build a robot from a `.usdz` package (bytes, `ArrayBuffer`, or `Blob`). */
+    parseUsdz(data: BinarySource): Promise<ThreeUsdRobot>;
+    /** Build a robot from a binary crate (`.usdc` / binary `.usd`). */
+    parseCrate(data: BinarySource, baseUrl?: string): Promise<ThreeUsdRobot>;
+    /**
+     * Parse + compose in-memory content (same formats as {@link parse}) into the
+     * Three.js-independent robot IR.
+     */
+    parseRobotDescription(data: UsdSource, baseUrl?: string): Promise<RobotDescription>;
+    /** Sniff in-memory content (text / zip / crate) and compose it into a stage. */
+    private openSource;
+    private openUsdzStage;
     private buildFromStage;
     private composeStage;
     /** Compose a layer from raw bytes, sniffing binary crate vs USDA text. */

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

@@ -89,6 +89,11 @@ type PrimSpec = {
 type VariantContent = {
     properties: PropertySpec[];
     children: PrimSpec[];
+    /**
+     * Metadata authored on the variant itself. Composition arcs live here — the
+     * common "this variant references another layer" pattern in Isaac Sim assets.
+     */
+    metadata: MetadataMap;
 };
 /** `variantSetName → variantName → content`. */
 type VariantSetMap = {
@@ -251,9 +256,9 @@ type LinkDescription = {
     /** Display name (leaf prim name). */
     name: string;
     primPath: string;
-    /** Mesh prim paths to render. */
+    /** Renderable gprim paths (Mesh / Cube / Sphere / Cylinder / Capsule / Cone). */
     visualPrims: string[];
-    /** Mesh prim paths flagged with a collision API. */
+    /** Gprim paths flagged with a collision API (or a non-visual purpose). */
     collisionPrims?: string[];
     /** Mass properties (`UsdPhysicsMassAPI`), if authored (M16). */
     inertial?: LinkInertialDescription;

package/dist/{AssetResolver-CpIJNgWZ.d.ts → bytes-MOJ2oN-u.d.ts}

@@ -26,4 +26,17 @@ declare function createMemoryResolver(files: Record<string, string | Uint8Array>
 /** 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 };
+/**
+ * In-memory input normalization for the loader entry points. Callers hold USD
+ * content in many shapes — a `fetch` response's `ArrayBuffer`, a `Uint8Array`
+ * (or any typed-array view), a dropped `File` / `Blob` — and every byte-eating
+ * API here funnels through {@link toBytes} so all of them are accepted.
+ */
+/** Binary USD content: an `ArrayBuffer`, any typed-array view, or a `Blob`/`File`. */
+type BinarySource = ArrayBuffer | ArrayBufferView | Blob;
+/** In-memory USD content: USDA source text, or {@link BinarySource} bytes. */
+type UsdSource = string | BinarySource;
+/** Normalize a {@link BinarySource} to bytes, honoring a view's offset/length. */
+declare function toBytes(data: BinarySource): Promise<Uint8Array>;
+
+export { type AssetResolver as A, type BinarySource as B, DefaultAssetResolver as D, type UsdSource as U, createMemoryResolver as c, joinPosix as j, toBytes as t };