three-usd-robot 0.10.0 → 0.12.0

package/dist/ThreeUsdRobot-C3N6-XBJ.d.ts

@@ -0,0 +1,347 @@
+import * as THREE from 'three';
+import { f as JointType, A as Axis, e as JointDescription, i as LinkDescription, R as RobotDescription, K as KinematicTree, S as Stage } from './buildKinematicTree-iFqaw0Jl.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;
+    /** Full USD prim path of the joint — the collision-proof address. */
+    readonly primPath: 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);
+}
+
+/** 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;
+    /**
+     * 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`). */
+    unitScale?: number;
+    /** Seed joints from their authored initial value (drive target / joint state). Default `true`. */
+    applyInitialPose?: boolean;
+    /**
+     * Diagnose {@link ThreeUsdRobot.setLinkTransforms} poses against the joint
+     * constraints and `console.warn` once per baked session when one deviates
+     * beyond tolerance (default 1 mm anchor / 0.01 rad axis). `true` uses the
+     * defaults; pass an object to tune them.
+     */
+    debugBakedTransforms?: boolean | {
+        anchorTolerance?: number;
+        axisTolerance?: number;
+    };
+};
+/**
+ * A rigid world pose for {@link ThreeUsdRobot.setLinkTransforms} —
+ * `quaternion` in Three.js `[x, y, z, w]` order (USD authors quatf as
+ * `(w, x, y, z)`; reorder when reading recorded USD by hand).
+ */
+type LinkPose = {
+    position: [number, number, number];
+    quaternion: [number, number, number, number];
+};
+/**
+ * Coordinate space of {@link LinkPose} batches. `"world"` (default) is the
+ * Three.js scene world *after* `worldUp` / unit normalization — with
+ * `worldUp: "Z"` you hand in Z-up poses — including any transform on the
+ * robot object itself (which must stay a similarity: uniform scale, no
+ * shear). `"stage"` is the authored USD stage space (before up-axis rotation
+ * and `metersPerUnit` scaling), as prim world transforms are written in the
+ * file.
+ */
+type LinkPoseSpace = "world" | "stage";
+type LinkPosesOptions = {
+    /** Interpretation of the poses (default `"world"`). */
+    space?: LinkPoseSpace;
+};
+type JointValuesFromLinkTransformsOptions = LinkPosesOptions & {
+    /**
+     * Previous joint values (keyed like the returned `values`): each
+     * revolute/continuous joint picks the 2πk branch of its projection nearest
+     * this, for frame-to-frame continuity past ±π.
+     */
+    previous?: Record<string, number>;
+    /** Clamp `values` to authored limits (default `false` — deviations are reported, not hidden). */
+    clampLimits?: boolean;
+};
+/**
+ * Per-joint constraint residual of a link-pose batch, keyed by joint prim
+ * path. The ideal parent→child transform of a joint is a pure motion along
+ * its DOF; whatever the poses leave over splits into `anchorError` /
+ * `axisError` (see {@link ThreeUsdRobot.validateLinkTransforms}).
+ */
+type JointResidual = {
+    /** Translation residual at the joint anchor, in meters (`metersPerUnit` applied). */
+    anchorError: number;
+    /** Rotation residual off the joint DOF, in radians. */
+    axisError: number;
+    /** Projected joint value (SI: radians / stage length units; `0` for fixed joints). */
+    q: number;
+    /** Whether `q` lies outside the authored limits. */
+    limitExceeded: 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`.
+ *
+ * **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;
+    readonly robot: RobotDescription;
+    readonly tree: KinematicTree;
+    readonly clampJointLimits: boolean;
+    /**
+     * The composed USD stage this robot was built from — the full prim tree, for
+     * inspection tooling (structure panels, attribute browsers). Attached by
+     * {@link ThreeUsdRobotLoader}; `undefined` for programmatically-built robots.
+     */
+    stage?: Stage;
+    private readonly linkObjects;
+    private readonly jointObjects;
+    private readonly linkKeyByPath;
+    private readonly jointKeyByPath;
+    private dirty;
+    /** Constructed (fk rest) local matrix of every link, for baked→fk restore. */
+    private readonly restLocal;
+    private _displayMode;
+    /** Stage-space link worlds while baked (`null` in fk mode). */
+    private bakedStageWorld;
+    /** Frozen `frame0 · motion · frame1⁻¹` per tree joint while baked. */
+    private bakedChainRel;
+    private readonly debugBaked;
+    private bakedDebugWarned;
+    private readonly warnedPoseKeys;
+    private warnedNonUniformScale;
+    private readonly helperSize;
+    private _showVisual;
+    private _showCollision;
+    private _showJointAxes;
+    private _showLinkFrames;
+    private jointAxesHelpers;
+    private linkFrameHelpers;
+    constructor(robot: RobotDescription, tree: KinematicTree, options?: ThreeUsdRobotOptions);
+    /** 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;
+    private attachRoot;
+    private attachTreeEdges;
+    /** Build `parent → frame0 → motion → frame1⁻¹ → child` for one joint. */
+    private attachJointChain;
+    private attachIsolatedLinks;
+    /** 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. Always restores `"fk"` display
+     * mode first (see {@link setLinkTransforms}).
+     */
+    setJointValue(name: string, value: number): boolean;
+    /**
+     * Set several joint values at once (matrix update is coalesced). Always
+     * restores `"fk"` display mode first, recomputing every link purely from
+     * joint values — even an empty batch returns from baked playback (see
+     * {@link setLinkTransforms}).
+     */
+    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;
+    /**
+     * `"fk"` (default): link placements derive from joint values. `"baked"`:
+     * {@link setLinkTransforms} wrote link poses directly and the joints no
+     * longer constrain the display; any `setJointValue`-family call restores fk.
+     */
+    get displayMode(): "fk" | "baked";
+    /**
+     * Drive link world poses directly — the display path for baked recordings
+     * (Isaac Sim body-transform time samples, maximal-coordinate playback).
+     * usdview-like semantics: constraint deviations are shown, never corrected —
+     * {@link validateLinkTransforms} measures them,
+     * {@link jointValuesFromLinkTransforms} projects onto the joints instead.
+     *
+     * Enters `"baked"` display mode; joint values stay untouched. Return to fk
+     * with {@link setJointValues} (any batch, even `{}`), which recomputes
+     * every link purely from joint values.
+     *
+     * Keys are link keys or full prim paths; unknown keys warn once and are
+     * skipped. Unspecified links KEEP their current world pose — a track that
+     * omits a link means "it did not move". Poses are rigid, `quaternion` in
+     * `[x, y, z, w]` order, interpreted per `opts.space` (default `"world"`:
+     * the Three.js scene world after `worldUp` normalization — pair a Z-up
+     * meter track with `worldUp: "Z"`). Matrix updates are coalesced into the
+     * next render / world query. Returns the number of poses applied.
+     */
+    setLinkTransforms(poses: Record<string, LinkPose>, opts?: LinkPosesOptions): number;
+    /**
+     * Measure how far a link-pose batch deviates from the joint constraints,
+     * without touching the display. Unspecified links resolve to their current
+     * displayed pose, so the report predicts exactly what
+     * {@link setLinkTransforms} with the same batch would show.
+     *
+     * Keyed by joint prim path; covers every joint — fixed joints (`q` = 0
+     * check), loop joints dropped from the fk tree (closure error) and the
+     * world-fixed root attachment (a moved base against a fixed-base model).
+     * Typical signatures: a constant `anchorError` offset on every joint —
+     * recording/model mismatch (wrong version or scale); growth over time —
+     * maximal-coordinate solver drift; large uniform `axisError` — a
+     * coordinate-convention bug (Y/Z-up or quaternion order).
+     */
+    validateLinkTransforms(poses: Record<string, LinkPose>, opts?: LinkPosesOptions): Record<string, JointResidual>;
+    /**
+     * Project a link-pose batch onto the joint manifold: the closed-form 1-DOF
+     * joint values that best reproduce it, plus the same residuals as
+     * {@link validateLinkTransforms}. `values` covers the articulated tree
+     * joints, keyed by joint prim path, and feeds {@link setJointValues}
+     * directly — the constraint-respecting playback of the same track:
+     *
+     * ```ts
+     * robot.setJointValues(robot.jointValuesFromLinkTransforms(poses, { previous }).values);
+     * ```
+     *
+     * Residual `q` / `limitExceeded` always report the unclamped projection,
+     * also when `clampLimits` clamps `values`.
+     */
+    jointValuesFromLinkTransforms(poses: Record<string, LinkPose>, opts?: JointValuesFromLinkTransformsOptions): {
+        values: Record<string, number>;
+        residuals: Record<string, JointResidual>;
+    };
+    /** Restore the constructed fk link placements (no-op when already `"fk"`). */
+    private exitBakedMode;
+    /** Freeze the fk state a baked session builds on (joints cannot move while baked). */
+    private enterBakedMode;
+    /** `frame0 · motion(q) · frame1⁻¹` of every tree joint, from live joint values. */
+    private computeChainRels;
+    /** Stage-space world transform of every link under the current display state. */
+    private computeStageWorlds;
+    private currentStageWorlds;
+    /** Resolve pose keys to link keys and convert each pose to a rigid stage-space matrix. */
+    private resolvePoseTargets;
+    /**
+     * Scene world → stage space, undoing the robot's own world transform
+     * (up-axis rotation, unit scale, any user placement) as a similarity — so
+     * link locals stay rigid and the root keeps carrying the scale.
+     */
+    private sceneToStageConverter;
+    /**
+     * Decompose every joint's parent→child transform under a pose batch
+     * (unspecified links resolve to their current displayed pose, mirroring
+     * {@link setLinkTransforms}). Pure — the display is untouched.
+     */
+    private decomposeJoints;
+    private buildResidual;
+    private warnUnknownPoseKey;
+    /** `debugBakedTransforms`: warn once per baked session when poses break the constraints. */
+    private warnBakedDeviationOnce;
+    /** 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. */
+    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 (an fk drive — leaves baked mode). */
+    setTime(t: number): void;
+    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 WorldUpAxis as W, type ThreeUsdRobotOptions as a, type JointResidual as b, type JointValuesFromLinkTransformsOptions as c, type LinkPose as d, type LinkPoseSpace as e, type LinkPosesOptions as f };

package/dist/{ThreeUsdRobotLoader-NdFAVN96.d.ts → ThreeUsdRobotLoader-D2fEo9_p.d.ts}

@@ -1,6 +1,8 @@
-import { R as RobotDescription } from './buildKinematicTree-BCySuZZn.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-B7Z4oORO.js';
+import { R as RobotDescription } from './buildKinematicTree-iFqaw0Jl.js';
+import { A as AssetResolver } from './parseMdl-vfzBGoMr.js';
+import { U as UsdSource, B as BinarySource } from './bytes-CxGRGry_.js';
+import { M as MaterialFactory } from './MeshBinding-DQKXuYNr.js';
+import { W as WorldUpAxis, a as ThreeUsdRobotOptions, T as ThreeUsdRobot } from './ThreeUsdRobot-C3N6-XBJ.js';
 
 type ThreeUsdRobotLoaderOptions = {
     /** Resolver for references / payloads / sublayers (default {@link DefaultAssetResolver}). */
@@ -41,10 +43,22 @@ type ThreeUsdRobotLoaderOptions = {
     clampJointLimits?: boolean;
     /** Seed joints from drive targets / joint state (M9). */
     applyDriveTargetsAsInitialPose?: boolean;
+    /**
+     * Diagnose {@link ThreeUsdRobot.setLinkTransforms} poses against the joint
+     * constraints and warn once per baked session past tolerance (default
+     * 1 mm anchor / 0.01 rad axis).
+     */
+    debugBakedTransforms?: ThreeUsdRobotOptions["debugBakedTransforms"];
     /** Override the robot name. */
     robotName?: string;
     /** Receives non-fatal load diagnostics. */
     onWarn?: (message: string) => void;
+    /**
+     * Overrides material creation for mesh-like gprims (M22) — e.g. the TSL
+     * MaterialX factory from `three-usd-robot/nodes`. Return `null` per prim to
+     * keep the default `UsdShade` resolution.
+     */
+    materialFactory?: MaterialFactory;
 };
 /**
  * Loads Isaac Sim / OpenUSD robot assets into a controllable {@link ThreeUsdRobot}.

package/dist/{buildKinematicTree-BCySuZZn.d.ts → buildKinematicTree-iFqaw0Jl.d.ts}

@@ -528,4 +528,4 @@ type BuildTreeOptions = {
 };
 declare function buildKinematicTree(robot: RobotDescription, options?: BuildTreeOptions): KinematicTree;
 
-export { makeRotationZ as $, type Axis as A, type BuildTreeOptions as B, type CompositionArc as C, DEFAULT_METERS_PER_UNIT as D, buildKinematicTree as E, channelFromSamples as F, decomposeRigid as G, fromUsdMatrix as H, getTranslation as I, type JointType as J, type KinematicTree as K, type LinkDescription as L, type Mat4 as M, identity4 as N, interpolate as O, Prim as P, Quat as Q, type RobotDescription as R, Stage as S, type TreeEdge as T, type UsdaFile as U, type Vec2 as V, invert as W, makeEuler as X, makeRotationFromQuat as Y, makeRotationX as Z, makeRotationY as _, type JointDescription as a, makeScale as a0, makeTranslation as a1, multiply as a2, multiplyAll as a3, toUsdMatrix as a4, type Vec3 as b, type JointDriveDescription as c, type LinkInertialDescription as d, AssetPath as e, Attribute as f, type AttributeSpec as g, DEG2RAD as h, type KinematicNode as i, Layer as j, type ListOp as k, type MetadataMap as l, type PrimSpec as m, type PropertySpec as n, RAD2DEG as o, Relationship as p, type RelationshipSpec as q, type SampleChannel as r, type SdfPath as s, type Specifier as t, type UpAxis as u, type UsdDictionary as v, UsdMatrix as w, type UsdValue as x, type Variability as y, type Vec4 as z };
+export { makeRotationZ as $, type Axis as A, type BuildTreeOptions as B, type CompositionArc as C, DEFAULT_METERS_PER_UNIT as D, buildKinematicTree as E, channelFromSamples as F, decomposeRigid as G, fromUsdMatrix as H, getTranslation as I, type JointDriveDescription as J, type KinematicTree as K, type LinkInertialDescription as L, type Mat4 as M, identity4 as N, interpolate as O, Prim as P, Quat as Q, type RobotDescription as R, Stage as S, type TreeEdge as T, type UsdaFile as U, type Variability as V, invert as W, makeEuler as X, makeRotationFromQuat as Y, makeRotationX as Z, makeRotationY as _, AssetPath as a, makeScale as a0, makeTranslation as a1, multiply as a2, multiplyAll as a3, toUsdMatrix as a4, Attribute as b, type AttributeSpec as c, DEG2RAD as d, type JointDescription as e, type JointType as f, type KinematicNode as g, Layer as h, type LinkDescription as i, type ListOp as j, type MetadataMap as k, type PrimSpec as l, type PropertySpec as m, RAD2DEG as n, Relationship as o, type RelationshipSpec as p, type SampleChannel as q, type SdfPath as r, type Specifier as s, type UpAxis as t, type UsdDictionary as u, UsdMatrix as v, type UsdValue as w, type Vec2 as x, type Vec3 as y, type Vec4 as z };

package/dist/bytes-CxGRGry_.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 BinarySource as B, type UsdSource as U, toBytes as t };