three-usd-robot 0.7.0 → 0.8.1

package/README.md

@@ -23,8 +23,10 @@ exported back to `.usda` / `.usdz` in the browser.
   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.
@@ -48,8 +50,8 @@ The CDN is public and CORS-enabled, so this works in the browser too. Try
 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, non-mesh
-gprims (`Cube`, `Sphere`, …), and full material/shader fidelity.
+Not yet supported: time samples stored inside binary crate files, point/curve
+gprims (`Points`, `BasisCurves`, …), and full material/shader fidelity.
 
 ## Install
 
@@ -79,8 +81,57 @@ 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.
+
+### World up-axis & units
+
+Stages load normalized: `metersPerUnit` scales the root, and the authored
+`upAxis` (`"Y"` or `"Z"`) is rotated into your world convention via `worldUp`:
+
+```ts
+new ThreeUsdRobotLoader(); // default: "Y" — upright in a stock three.js scene
+new ThreeUsdRobotLoader({ worldUp: "Z" }); // robotics-style Z-up world
+new ThreeUsdRobotLoader({ worldUp: "keep" }); // leave the authored orientation
+
+robot.upAxis; // authored stage value ("Y" | "Z"), independent of normalization
+robot.metersPerUnit; // authored stage scale (already applied to the root)
+```
+
+Isaac Sim assets are Z-up, so the default makes them stand upright in a plain
+three.js scene; a Z-up app (ROS-style) passes `worldUp: "Z"` once instead of
+counter-rotating per asset. The M9 option `upAxisConversion` remains as a
+deprecated alias (`"auto"` ≡ `worldUp: "Y"`, `"none"` ≡ `"keep"`).
+
+### 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
 
@@ -94,9 +145,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)
 

package/dist/{ThreeUsdRobot-Ljh4PDVD.d.ts → ThreeUsdRobot-BZ_vlr1R.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-Ccd2DIKH.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;
@@ -39,15 +41,25 @@ declare class LinkObject extends THREE.Object3D {
     constructor(link: LinkDescription);
 }
 
+/** Target world up-axis: normalize to Y-up / Z-up, or keep the authored orientation. */
+type WorldUpAxis = "Y" | "Z" | "keep";
 type ThreeUsdRobotOptions = {
     /** Clamp `setJointValue` to authored limits (default `true`). */
     clampJointLimits?: boolean;
     /** Size of the built-in joint-axis / link-frame helpers (stage units, default `0.15`). */
     helperSize?: number;
     /**
-     * Up-axis correction applied at the robot root. `"auto"` rotates Z-up assets
-     * into the Three.js Y-up scene; `"Z"` forces it, `"Y"`/`"none"` leave the
-     * orientation as authored. Default `"none"` (the loader defaults to `"auto"`).
+     * Target world up-axis. The root is rotated so the stage's authored `upAxis`
+     * lands in that convention: `"Y"` for a standard three.js scene, `"Z"` for a
+     * robotics-style Z-up world, `"keep"` for no correction. Takes precedence
+     * over the deprecated {@link ThreeUsdRobotOptions.upAxisConversion}.
+     */
+    worldUp?: WorldUpAxis;
+    /**
+     * Legacy up-axis correction: `"auto"` ≡ `worldUp: "Y"`, `"Y"` / `"none"` ≡
+     * `worldUp: "keep"`, and `"Z"` forces the Z-up→Y-up rotation regardless of
+     * stage metadata. Default `"none"` (the loader defaults to `"auto"`).
+     * @deprecated Use {@link ThreeUsdRobotOptions.worldUp}.
      */
     upAxisConversion?: "auto" | "Y" | "Z" | "none";
     /** Extra uniform scale multiplied with the stage `metersPerUnit` (default `1`). */
@@ -63,6 +75,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 +89,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;
@@ -80,7 +100,7 @@ declare class ThreeUsdRobot extends THREE.Object3D {
     private jointAxesHelpers;
     private linkFrameHelpers;
     constructor(robot: RobotDescription, tree: KinematicTree, options?: ThreeUsdRobotOptions);
-    /** Orient (Z-up → Y-up) and scale (metersPerUnit × unitScale) the robot root. */
+    /** Orient (authored upAxis → target world up) and scale (metersPerUnit × unitScale) the root. */
     private applyStageNormalization;
     /** Apply each joint's authored initial value, if any. */
     private applyInitialPose;
@@ -89,7 +109,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,16 +124,33 @@ 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. */
     getJointNames(): string[];
     getLinkNames(): string[];
     getKinematicTree(): KinematicTree;
+    /** Authored stage up-axis (`"Y"` or `"Z"`) — unaffected by `worldUp` normalization. */
+    get upAxis(): "Y" | "Z";
+    /** Authored stage scale in meters per unit (already applied to the root). */
+    get metersPerUnit(): number;
     /** Playback rate in time codes per second (from the stage; default 24). */
     getTimeCodesPerSecond(): number;
     /** Whether any joint has a time-sampled trajectory. */
@@ -132,4 +176,4 @@ declare class ThreeUsdRobot extends THREE.Object3D {
     private setKindVisibility;
 }
 
-export { JointObject as J, LinkObject as L, ThreeUsdRobot as T, type ThreeUsdRobotOptions as a };
+export { JointObject as J, LinkObject as L, ThreeUsdRobot as T, type WorldUpAxis as W, type ThreeUsdRobotOptions as a };

package/dist/ThreeUsdRobotLoader-HteyMZf1.d.ts

@@ -0,0 +1,92 @@
+import { R as RobotDescription } from './buildKinematicTree-D4R0hEtN.js';
+import { A as AssetResolver, U as UsdSource, B as BinarySource } from './bytes-MOJ2oN-u.js';
+import { W as WorldUpAxis, T as ThreeUsdRobot } from './ThreeUsdRobot-BZ_vlr1R.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;
+    /**
+     * 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`). */
+    loadTextures?: boolean;
+    /**
+     * Target world up-axis. Any stage (Y-up or Z-up) is normalized into this
+     * convention: `"Y"` for a standard three.js scene (the default behavior),
+     * `"Z"` for a robotics-style Z-up world, `"keep"` to leave the authored
+     * orientation. Takes precedence over {@link upAxisConversion}.
+     */
+    worldUp?: WorldUpAxis;
+    /**
+     * Legacy up-axis correction (M9). Default `"auto"` ≡ `worldUp: "Y"`.
+     * @deprecated Use {@link worldUp}.
+     */
+    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}.
+ *
+ * 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.
+ */
+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 zip / crate
+     * magic and parsed as USDZ, binary USDC, or USDA text.
+     */
+    loadAsync(url: string): Promise<ThreeUsdRobot>;
+    private fetchRootBytes;
+    /**
+     * 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. */
+    private composeStageFromBytes;
+    private robotOptions;
+    private extractOptions;
+}
+
+export { type ThreeUsdRobotLoaderOptions as T, ThreeUsdRobotLoader as a };

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

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