three-usd-robot 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fabcowork
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# three-usd-robot
+
+> **Kinematic OpenUSD robot loader for Three.js.**
+> Load Isaac Sim / OpenUSD robot assets, extract joints and links, and control
+> articulations directly in the browser — no physics engine required.
+
+Think of it as a **USD version of [`urdf-loader`](https://www.npmjs.com/package/urdf-loader)**:
+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 — drives forward kinematics with meshes,
+> normalizes up-axis & units, and seeds the initial pose from joint drives. The
+> crate reader is a from-scratch TypeScript implementation (no OpenUSD/WASM
+> dependency). Not yet: variants, instancing, and time-sampled (animated)
+> values (see [`MILESTONES.md`](./MILESTONES.md), M10–M11).
+
+```ts
+// .usda / .usdc / binary .usd / .usdz are all auto-detected:
+const robot = await new ThreeUsdRobotLoader().loadAsync("/assets/robot.usd");
+// or from bytes you already have:
+const robot = await new ThreeUsdRobotLoader().parseCrate(usdcBytes);
+```
+
+## Install
+
+```sh
+npm install three-usd-robot three
+```
+
+`three` is a **peer dependency** (`>=0.160.0`).
+
+## Usage
+
+```ts
+import { ThreeUsdRobotLoader } from "three-usd-robot";
+
+const robot = await new ThreeUsdRobotLoader().loadAsync("/assets/arm.usda");
+scene.add(robot);
+
+// Drive joints (revolute/continuous in radians, prismatic in stage units).
+robot.setJointValues({ joint1: 0.4, joint2: -0.2 });
+
+// Forward kinematics falls out of the Three.js scene graph.
+const handMatrix = robot.getLinkWorldMatrix("tool0"); // THREE.Matrix4
+const handPos = robot.getLinkWorldPosition("tool0"); // THREE.Vector3
+
+robot.getJointNames(); // controllable joints
+robot.getKinematicTree(); // root, ordering, loopJoints, ...
+```
+
+### Viewer toggles & helpers
+
+```ts
+robot.showVisual = true;
+robot.showCollision = false;
+robot.showJointAxes = true; // built-in axes gizmos on each joint
+robot.showLinkFrames = false;
+
+import { addJointLimitHelpers } from "three-usd-robot/helpers";
+addJointLimitHelpers(robot); // arc (revolute) / segment (prismatic) per joint
+```
+
+### Joint slider panel (lil-gui)
+
+```ts
+import GUI from "lil-gui";
+import { createJointSliderPanel } from "three-usd-robot/extras";
+
+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.
+
+### Inspect without Three.js
+
+```ts
+import { parseUsda, Stage, extractRobotDescription } from "three-usd-robot/core";
+
+const desc = extractRobotDescription(Stage.OpenFromString(usdaText));
+console.log(desc.rootLink, Object.keys(desc.joints));
+```
+
+## Package entry points
+
+| Import | Contents |
+| --- | --- |
+| `three-usd-robot` | Three.js runtime — `ThreeUsdRobotLoader`, `ThreeUsdRobot` |
+| `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) |
+
+## Development
+
+```sh
+npm install
+npm run typecheck   # tsc --noEmit
+npm test            # vitest
+npm run build       # tsup -> dist/
+npm run check       # biome lint + format (autofix)
+```
+
+## License
+
+MIT

package/dist/ThreeUsdRobot-lMZHW-it.d.ts

@@ -0,0 +1,121 @@
+import * as THREE from 'three';
+import { d as JointType, A as Axis, J as JointDescription, L as LinkDescription, R as RobotDescription, e as KinematicTree } from './buildKinematicTree-2fg6ZN8m.js';
+
+/**
+ * The articulated "motion" node of a joint, inserted between the joint's two
+ * fixed frames (`jointFrame0` and `inverse(jointFrame1)`). {@link setValue}
+ * rotates it about the axis (revolute/continuous) or slides it along the axis
+ * (prismatic); fixed joints are inert.
+ */
+declare class JointObject extends THREE.Object3D {
+    readonly isJointObject = true;
+    readonly jointName: string;
+    readonly jointType: JointType;
+    readonly axisToken: Axis;
+    readonly axis: THREE.Vector3;
+    readonly lower: number | undefined;
+    readonly upper: number | undefined;
+    private _value;
+    constructor(joint: JointDescription);
+    get value(): number;
+    get articulated(): boolean;
+    /**
+     * Set the joint value (radians for revolute/continuous, length for prismatic).
+     * Optionally clamps to authored limits. Returns the value actually applied.
+     */
+    setValue(value: number, clampToLimits?: boolean): number;
+}
+
+/**
+ * Three.js node for a robot link. Its frame is the USD link prim's frame;
+ * visual/collision meshes (M6) attach as children relative to it. Placement
+ * relative to the parent is supplied by the joint chain, so a link's own local
+ * matrix is identity (except the root, which carries the world-fixed placement).
+ */
+declare class LinkObject extends THREE.Object3D {
+    readonly isLinkObject = true;
+    readonly linkName: string;
+    readonly primPath: string;
+    constructor(link: LinkDescription);
+}
+
+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"`).
+     */
+    upAxisConversion?: "auto" | "Y" | "Z" | "none";
+    /** Extra uniform scale multiplied with the stage `metersPerUnit` (default `1`). */
+    unitScale?: number;
+    /** Seed joints from their authored initial value (drive target / joint state). Default `true`. */
+    applyInitialPose?: boolean;
+};
+/**
+ * A Three.js `Object3D` that realizes a {@link RobotDescription} as a kinematic
+ * hierarchy and drives forward kinematics via {@link setJointValue}.
+ *
+ * Per joint the hierarchy is
+ * `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`.
+ */
+declare class ThreeUsdRobot extends THREE.Object3D {
+    readonly isThreeUsdRobot = true;
+    readonly robot: RobotDescription;
+    readonly tree: KinematicTree;
+    readonly clampJointLimits: boolean;
+    private readonly linkObjects;
+    private readonly jointObjects;
+    private dirty;
+    private readonly helperSize;
+    private _showVisual;
+    private _showCollision;
+    private _showJointAxes;
+    private _showLinkFrames;
+    private jointAxesHelpers;
+    private linkFrameHelpers;
+    constructor(robot: RobotDescription, tree: KinematicTree, options?: ThreeUsdRobotOptions);
+    /** Orient (Z-up → Y-up) and scale (metersPerUnit × unitScale) the robot root. */
+    private applyStageNormalization;
+    /** Apply each joint's authored initial value, if any. */
+    private applyInitialPose;
+    private attachRoot;
+    private attachTreeEdges;
+    /** 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. */
+    setJointValue(name: string, value: number): boolean;
+    /** Set several joint values at once (matrix update is coalesced). */
+    setJointValues(values: Record<string, number>): void;
+    getJointValue(name: string): number | undefined;
+    /** Recompute world matrices. Called lazily by the getters; safe to call directly. */
+    updateKinematics(): void;
+    private ensureUpdated;
+    getLinkWorldMatrix(name: string): THREE.Matrix4;
+    getLinkWorldPosition(name: string): THREE.Vector3;
+    getLinkObject(name: string): LinkObject | undefined;
+    getJointObject(name: string): JointObject | undefined;
+    getJoints(): JointDescription[];
+    getLinks(): LinkDescription[];
+    /** Names of the articulated (controllable) joints. */
+    getJointNames(): string[];
+    getLinkNames(): string[];
+    getKinematicTree(): KinematicTree;
+    get showVisual(): boolean;
+    set showVisual(v: boolean);
+    get showCollision(): boolean;
+    set showCollision(v: boolean);
+    get showJointAxes(): boolean;
+    set showJointAxes(v: boolean);
+    get showLinkFrames(): boolean;
+    set showLinkFrames(v: boolean);
+    private setKindVisibility;
+}
+
+export { JointObject as J, LinkObject as L, ThreeUsdRobot as T, type ThreeUsdRobotOptions as a };

package/dist/buildKinematicTree-2fg6ZN8m.d.ts

@@ -0,0 +1,283 @@
+/**
+ * AST and value types for the USDA (ASCII USD) format.
+ *
+ * The parser (`parseUsda`) produces a {@link UsdaFile}. The USD-conformant
+ * runtime layer (`usd/Stage.ts` etc.) wraps this AST to expose a pxr-USD-style
+ * API (`GetPrimAtPath`, `GetAttribute`, `Get`, `GetTargets`, ...).
+ */
+/** Fixed-length numeric tuples, mirroring `GfVec2/3/4`. */
+type Vec2 = [number, number];
+type Vec3 = [number, number, number];
+type Vec4 = [number, number, number, number];
+/**
+ * A quaternion, mirroring `GfQuatf/d/h`.
+ *
+ * USDA authors quats as `(w, x, y, z)` — real part first. We keep the real and
+ * imaginary parts explicit so downstream code never has to guess the component
+ * order (Three.js, by contrast, uses `(x, y, z, w)`).
+ */
+declare class Quat {
+    readonly real: number;
+    readonly imaginary: Vec3;
+    constructor(real: number, imaginary: Vec3);
+    /** Components in Three.js order `[x, y, z, w]`. */
+    toXYZW(): Vec4;
+    static identity(): Quat;
+}
+/**
+ * A square matrix (`GfMatrix3d`/`GfMatrix4d`), stored flat in **row-major**
+ * order exactly as authored in USD (USD matrices are row-major).
+ */
+declare class UsdMatrix {
+    readonly values: number[];
+    readonly dim: 3 | 4;
+    constructor(values: number[], dim: 3 | 4);
+    static identity4(): UsdMatrix;
+}
+/** An asset reference (`SdfAssetPath`), e.g. `@./meshes/link0.usd@`. */
+declare class AssetPath {
+    readonly path: string;
+    constructor(path: string);
+}
+/**
+ * A namespace path into a stage (`SdfPath`), e.g. `/World/robot/link0` or a
+ * property path `/World/robot.xformOp:translate`. Stored as the authored
+ * string; relationship/connection resolution happens in the runtime layer.
+ */
+type SdfPath = string;
+/** A reference / payload composition arc as authored (resolved in M8). */
+type CompositionArc = {
+    assetPath?: AssetPath;
+    primPath?: SdfPath;
+};
+/** Any value an attribute or metadatum can hold. */
+type UsdValue = number | boolean | string | null | Vec2 | Vec3 | Vec4 | Quat | UsdMatrix | AssetPath | SdfPath | CompositionArc | UsdValue[] | UsdDictionary;
+/** A nested metadata dictionary (`customData`, `assetInfo`, ...). */
+type UsdDictionary = {
+    [key: string]: UsdValue;
+};
+type Specifier = "def" | "over" | "class";
+type Variability = "varying" | "uniform";
+/** List-editing qualifier on relationships and list-op metadata. */
+type ListOp = "explicit" | "prepend" | "append" | "add" | "delete" | "reorder";
+type MetadataMap = {
+    [key: string]: UsdValue;
+};
+/** A parsed `.usda` layer. */
+type UsdaFile = {
+    /** Version from the `#usda X.Y` magic line. */
+    version: string;
+    /** Layer-level metadata (`defaultPrim`, `upAxis`, `metersPerUnit`, ...). */
+    metadata: MetadataMap;
+    /** Root prims, in authored order. */
+    prims: PrimSpec[];
+};
+type PrimSpec = {
+    specifier: Specifier;
+    /** Schema type, e.g. `Xform`, `Mesh`, `PhysicsRevoluteJoint`. Empty if typeless. */
+    typeName: string;
+    name: string;
+    metadata: MetadataMap;
+    properties: PropertySpec[];
+    children: PrimSpec[];
+    /** 1-based source line of the prim declaration (for diagnostics). */
+    line: number;
+};
+type PropertySpec = AttributeSpec | RelationshipSpec;
+type AttributeSpec = {
+    kind: "attribute";
+    name: string;
+    /** USD type name without the `[]` suffix, e.g. `float3`, `token`, `quatf`. */
+    typeName: string;
+    isArray: boolean;
+    variability: Variability;
+    custom: boolean;
+    /** Default (time-independent) value, if authored. */
+    value?: UsdValue;
+    /** Time samples keyed by time code, if authored as `{ t: v, ... }`. */
+    timeSamples?: Map<number, UsdValue>;
+    /** Connection target paths (`attr.connect = <path>`), if authored. */
+    connections?: SdfPath[];
+    metadata: MetadataMap;
+    line: number;
+};
+type RelationshipSpec = {
+    kind: "relationship";
+    name: string;
+    custom: boolean;
+    listOp: ListOp;
+    /** Target paths; empty when authored as `None`. */
+    targets: SdfPath[];
+    metadata: MetadataMap;
+    line: number;
+};
+
+/**
+ * Minimal 4×4 matrix math, Three.js-independent.
+ *
+ * ## Convention
+ *
+ * A {@link Mat4} is a flat 16-element array in **column-major** order — the
+ * exact layout of `THREE.Matrix4.elements`, so a `Mat4` can be handed to
+ * `matrix4.fromArray(m)` with no transposition. Transforms use the
+ * column-vector convention `v' = M · v`; the translation lives at indices
+ * `[12, 13, 14]`.
+ *
+ * Conveniently, OpenUSD stores `GfMatrix4d` **row-major** with a row-vector
+ * convention (`v' = v · M`). The two raw 16-number arrays for the *same*
+ * transform are therefore bit-identical, which is why {@link fromUsdMatrix} is
+ * a plain copy. See the module test for a worked example.
+ */
+
+/** Column-major 4×4 matrix (Three.js `elements` layout). */
+type Mat4 = number[];
+declare const DEG2RAD: number;
+declare const RAD2DEG: number;
+declare function identity4(): Mat4;
+/** Matrix product `a · b` (column-major), matching `THREE.Matrix4.multiplyMatrices`. */
+declare function multiply(a: Mat4, b: Mat4): Mat4;
+/** Product of a list of matrices, left-to-right (`m[0] · m[1] · …`). */
+declare function multiplyAll(matrices: Mat4[]): Mat4;
+/** Inverse (column-major), matching `THREE.Matrix4.invert`. Throws if singular. */
+declare function invert(m: Mat4): Mat4;
+declare function makeTranslation([x, y, z]: Vec3): Mat4;
+declare function makeScale([x, y, z]: Vec3): Mat4;
+declare function makeRotationX(rad: number): Mat4;
+declare function makeRotationY(rad: number): Mat4;
+declare function makeRotationZ(rad: number): Mat4;
+/** Rotation matrix from a (normalized) quaternion, matching `THREE.Matrix4.compose`. */
+declare function makeRotationFromQuat(q: Quat): Mat4;
+/**
+ * Euler rotation matrix for the given axis order (e.g. `"XYZ"`), with per-axis
+ * angles in **radians** indexed by axis (`angles[0]`=X, `[1]`=Y, `[2]`=Z).
+ *
+ * Follows OpenUSD's `rotate<ORDER>` semantics: the first listed axis is applied
+ * first to the geometry, so `"XYZ"` yields `Rz · Ry · Rx` in column-vector form.
+ */
+declare function makeEuler(angles: Vec3, order: string): Mat4;
+/**
+ * Copy a USD matrix into a {@link Mat4}. USD's row-major storage is identical to
+ * Three.js column-major elements for the same transform (see module docs), so
+ * this is a straight copy after a dimension check.
+ */
+declare function fromUsdMatrix(m: UsdMatrix): Mat4;
+/** Extract the translation component `[x, y, z]` from a {@link Mat4}. */
+declare function getTranslation(m: Mat4): Vec3;
+
+/**
+ * Robot intermediate representation (IR) — Three.js-independent.
+ *
+ * The extractor (`RobotExtractor`) turns a USD {@link Stage} into a
+ * {@link RobotDescription}; the kinematics builder (M4) trees it; the Three.js
+ * runtime (M5) realizes it as an `Object3D` hierarchy. Keeping the IR free of
+ * Three.js lets the same data drive tooling, validation, and (later) IK.
+ *
+ * See concept.md §9 for the rationale behind each field.
+ */
+
+type JointType = "fixed" | "revolute" | "continuous" | "prismatic";
+/** Joint axis token as authored in USD (`physics:axis`); never a vector here. */
+type Axis = "X" | "Y" | "Z";
+type RobotDescription = {
+    name: string;
+    /** Key of the root link (see {@link LinkDescription} keys). */
+    rootLink: string;
+    links: Record<string, LinkDescription>;
+    joints: Record<string, JointDescription>;
+    /** Link keys whose prim carries `PhysicsArticulationRootAPI` (root hint for M4). */
+    articulationRoots?: string[];
+    /** Joints dropped from the spanning tree to break closed loops (filled in M4). */
+    loopJoints?: string[];
+    /** Stage up axis, for the M9 up-axis correction. */
+    upAxis: "Y" | "Z";
+    /** Stage linear unit, for the M9 scale normalization. */
+    metersPerUnit: number;
+    /** Non-fatal extraction diagnostics. */
+    warnings?: string[];
+};
+type LinkDescription = {
+    /** Display name (leaf prim name). */
+    name: string;
+    primPath: string;
+    /** Mesh prim paths to render. */
+    visualPrims: string[];
+    /** Mesh prim paths flagged with a collision API. */
+    collisionPrims?: string[];
+};
+type JointDescription = {
+    /** Display name (leaf prim name). */
+    name: string;
+    primPath: string;
+    type: JointType;
+    /** Parent link key (body0). Empty string `""` means fixed to the world. */
+    parent: string;
+    /** Child link key (body1). */
+    child: string;
+    axis: Axis;
+    lower?: number;
+    upper?: number;
+    effort?: number;
+    velocity?: number;
+    /** Joint frame in the parent (body0) local space: `(localPos0, localRot0)`. */
+    jointFrame0: Mat4;
+    /** Joint frame in the child (body1) local space: `(localPos1, localRot1)`. */
+    jointFrame1: Mat4;
+    /** Initial joint value (SI) from JointStateAPI or a drive target, if authored. */
+    initialValue?: number;
+    drive?: JointDriveDescription;
+};
+/** Authored joint drive parameters (`UsdPhysicsDriveAPI`), as read in M3. */
+type JointDriveDescription = {
+    /** Target position in SI (radians for angular, linear units for linear). */
+    targetPosition?: number;
+    /** Gains/limits as authored (not unit-normalized). */
+    stiffness?: number;
+    damping?: number;
+    maxForce?: number;
+};
+
+/**
+ * Builds a kinematic spanning tree from a {@link RobotDescription}.
+ *
+ * USD physics joints form a directed graph (parent `body0` → child `body1`,
+ * with an empty `body0` meaning "fixed to world"). Three.js needs a tree, so we
+ * pick a root, breadth-first walk the real (link→link) edges, and drop any edge
+ * that would revisit a link — those are recorded as {@link KinematicTree.loopJoints}
+ * (closed chains / parallel mechanisms) rather than silently corrupting the tree.
+ */
+
+type TreeEdge = {
+    /** Joint key connecting this node to the child. */
+    joint: string;
+    /** Child link key. */
+    child: string;
+};
+type KinematicNode = {
+    link: string;
+    /** Parent link key, or `null` for the root. */
+    parent: string | null;
+    /** Joint key to the parent, or `null` for the root. */
+    jointToParent: string | null;
+    children: TreeEdge[];
+    /** Distance from the root (root = 0). */
+    depth: number;
+};
+type KinematicTree = {
+    root: string;
+    /** World-fixed joint attaching the root to the world frame, if any. */
+    rootJoint: string | null;
+    nodes: Record<string, KinematicNode>;
+    /** Link keys in breadth-first order (parents before children). */
+    order: string[];
+    /** Joints dropped from the tree to break closed loops. */
+    loopJoints: string[];
+    /** Links not reachable from the root. */
+    isolatedLinks: string[];
+    warnings: string[];
+};
+type BuildTreeOptions = {
+    onWarn?: (message: string) => void;
+};
+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 JointDescription as J, type KinematicNode 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 Variability as V, AssetPath as a, type AttributeSpec as b, type JointDriveDescription as c, type JointType as d, type KinematicTree 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 Vec2 as o, type Vec3 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 };