three-usd-robot 0.8.0 → 0.9.0

package/README.md

@@ -97,6 +97,25 @@ 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
@@ -284,9 +303,10 @@ and `.usdz` packages to ASCII USDA.
 
 [`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-usd-inspector`** — the [live demo](https://three-usd-robot.vercel.app):
+  vanilla Three.js + `lil-gui`, with a robot picker, a USD structure panel
+  (prim tree + attribute inspector), a transform gizmo, 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

package/dist/{ThreeUsdRobot-CsjraHqP.d.ts → ThreeUsdRobot-BAh-48DD.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-D4R0hEtN.js';
+import { J as JointType, A as Axis, a as JointDescription, L as LinkDescription, R as RobotDescription, K as KinematicTree, S as Stage } from './buildKinematicTree-DQ4Vr4sJ.js';
 
 /**
  * The articulated "motion" node of a joint, inserted between the joint's two
@@ -41,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`). */
@@ -77,6 +87,12 @@ declare class ThreeUsdRobot extends THREE.Object3D {
     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;
@@ -90,7 +106,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;
@@ -137,6 +153,10 @@ declare class ThreeUsdRobot extends THREE.Object3D {
     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. */
@@ -162,4 +182,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-CxOGRLXH.d.ts → ThreeUsdRobotLoader-DYtvelif.d.ts}

@@ -1,6 +1,6 @@
-import { R as RobotDescription } from './buildKinematicTree-D4R0hEtN.js';
+import { R as RobotDescription } from './buildKinematicTree-DQ4Vr4sJ.js';
 import { A as AssetResolver, U as UsdSource, B as BinarySource } from './bytes-MOJ2oN-u.js';
-import { T as ThreeUsdRobot } from './ThreeUsdRobot-CsjraHqP.js';
+import { W as WorldUpAxis, T as ThreeUsdRobot } from './ThreeUsdRobot-BAh-48DD.js';
 
 type ThreeUsdRobotLoaderOptions = {
     /** Resolver for references / payloads / sublayers (default {@link DefaultAssetResolver}). */
@@ -18,7 +18,17 @@ type ThreeUsdRobotLoaderOptions = {
     loadSceneGeometry?: boolean;
     /** Load diffuse textures referenced by materials (default `true`). */
     loadTextures?: boolean;
-    /** Up-axis correction strategy (M9). */
+    /**
+     * 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;

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

@@ -317,6 +317,169 @@ type JointDriveDescription = {
     maxForce?: number;
 };
 
+/** A parsed USDA layer (`SdfLayer`-like, read-only). */
+declare class Layer {
+    private readonly _file;
+    constructor(_file: UsdaFile);
+    /** Serialize this layer back to USDA text (`SdfLayer::ExportToString`-like). */
+    ExportToString(): string;
+    GetVersion(): string;
+    GetPseudoRootMetadata(): MetadataMap;
+    GetMetadata(key: string): UsdValue | undefined;
+    GetDefaultPrimName(): string | undefined;
+    GetRootPrimSpecs(): PrimSpec[];
+}
+
+/**
+ * A typed attribute on a prim (`UsdAttribute`-like).
+ *
+ * Mirrors the pxr USD API: `GetAttribute` always returns an `Attribute` object;
+ * call {@link Attribute.IsValid} to check whether the attribute is actually
+ * authored on the prim.
+ */
+declare class Attribute {
+    private readonly _prim;
+    private readonly _name;
+    private readonly _spec;
+    constructor(_prim: Prim, _name: string, _spec: AttributeSpec | null);
+    IsValid(): boolean;
+    GetPrim(): Prim;
+    GetName(): string;
+    GetBaseName(): string;
+    GetNamespace(): string;
+    /** Scalar type name (without the `[]` suffix); pair with {@link IsArray}. */
+    GetTypeName(): string;
+    IsArray(): boolean;
+    GetVariability(): Variability;
+    IsCustom(): boolean;
+    /** True if a default value or any time sample is authored. */
+    HasValue(): boolean;
+    HasAuthoredValue(): boolean;
+    /**
+     * Resolve the attribute value. With no `time`, returns the default value (or
+     * the earliest time sample if only samples are authored). With a `time`,
+     * returns the exact sample if present, else the default, else the earliest
+     * sample. Returns `undefined` when nothing is authored.
+     */
+    Get(time?: number): UsdValue | undefined;
+    GetTimeSamples(): Map<number, UsdValue>;
+    GetConnections(): SdfPath[];
+}
+/** A relationship on a prim (`UsdRelationship`-like). */
+declare class Relationship {
+    private readonly _prim;
+    private readonly _name;
+    private readonly _spec;
+    constructor(_prim: Prim, _name: string, _spec: RelationshipSpec | null);
+    IsValid(): boolean;
+    GetPrim(): Prim;
+    GetName(): string;
+    GetBaseName(): string;
+    GetNamespace(): string;
+    IsCustom(): boolean;
+    GetTargets(): SdfPath[];
+}
+
+/**
+ * A composed prim on a {@link Stage} (`UsdPrim`-like).
+ *
+ * The pseudo-root (path `/`) is represented by a Prim with a `null` spec; its
+ * children are the stage's root prims.
+ */
+declare class Prim {
+    private readonly _stage;
+    private readonly _spec;
+    private readonly _path;
+    private readonly _parent;
+    private readonly _children;
+    private _attributes?;
+    private _relationships?;
+    constructor(_stage: Stage, _spec: PrimSpec | null, _path: string, _parent: Prim | null);
+    /** @internal Used by {@link Stage} while building the prim tree. */
+    _addChild(child: Prim): void;
+    GetStage(): Stage;
+    IsValid(): boolean;
+    IsPseudoRoot(): boolean;
+    GetName(): string;
+    GetPath(): string;
+    GetTypeName(): string;
+    GetSpecifier(): Specifier | null;
+    GetParent(): Prim | null;
+    GetChildren(): Prim[];
+    GetChild(name: string): Prim | null;
+    private attrMap;
+    /** Always returns an Attribute; check {@link Attribute.IsValid}. */
+    GetAttribute(name: string): Attribute;
+    HasAttribute(name: string): boolean;
+    GetAttributes(): Attribute[];
+    private relMap;
+    /** Always returns a Relationship; check {@link Relationship.IsValid}. */
+    GetRelationship(name: string): Relationship;
+    HasRelationship(name: string): boolean;
+    GetRelationships(): Relationship[];
+    GetMetadata(key: string): UsdValue | undefined;
+    GetAllMetadata(): MetadataMap;
+    /**
+     * Model-hierarchy kind from the `kind` metadata — `"component"`, `"group"`,
+     * `"assembly"`, `"subcomponent"`, … — or `""` when unauthored. The standard
+     * signal for selection granularity (usdview's "select by kind").
+     */
+    GetKind(): string;
+    /** Applied API schema names from `apiSchemas` (e.g. `PhysicsArticulationRootAPI`). */
+    GetAppliedSchemas(): string[];
+    /**
+     * Whether the given API schema is applied. Matches the bare schema name as
+     * well as multi-apply instances (e.g. `HasAPI("PhysicsDriveAPI")` is true for
+     * an applied `PhysicsDriveAPI:angular`).
+     */
+    HasAPI(schemaName: string): boolean;
+}
+
+/** OpenUSD's fallback stage linear unit when `metersPerUnit` is unauthored. */
+declare const DEFAULT_METERS_PER_UNIT = 0.01;
+type UpAxis = "Y" | "Z";
+/**
+ * A composed USD stage (`UsdStage`-like) backed by a single in-memory USDA
+ * layer. Multi-layer composition (sublayers / references / payloads) arrives in
+ * M8; for now a stage wraps exactly one parsed layer.
+ */
+declare class Stage {
+    private readonly _layer;
+    private readonly _byPath;
+    private readonly _pseudoRoot;
+    private constructor();
+    /** Parse and open a stage from USDA source text. */
+    static OpenFromString(usda: string): Stage;
+    /** Open a stage from an already-parsed layer. */
+    static OpenFromFile(file: UsdaFile): Stage;
+    private buildPrim;
+    GetRootLayer(): Layer;
+    /**
+     * Serialize the stage's backing layer to USDA text. Loader-built stages wrap
+     * the fully composed layer, so this is a flattened (`usdcat --flatten`-like)
+     * export of everything that was read — including binary-crate sources.
+     */
+    ExportToString(): string;
+    GetPseudoRoot(): Prim;
+    /** Returns the prim at the absolute path, or `null` if none exists. */
+    GetPrimAtPath(path: string): Prim | null;
+    /** The stage's default prim (from layer `defaultPrim` metadata), if any. */
+    GetDefaultPrim(): Prim | null;
+    /** Depth-first traversal of all prims (excludes the pseudo-root). */
+    Traverse(): Prim[];
+    GetMetadata(key: string): UsdValue | undefined;
+    /** Stage up axis (`upAxis` metadata); defaults to `"Y"` per OpenUSD. */
+    GetUpAxis(): UpAxis;
+    /** Stage linear unit (`metersPerUnit` metadata); defaults to {@link DEFAULT_METERS_PER_UNIT}. */
+    GetMetersPerUnit(): number;
+    /** Animation start time code, if authored. */
+    GetStartTimeCode(): number | undefined;
+    /** Animation end time code, if authored. */
+    GetEndTimeCode(): number | undefined;
+    /** Time codes per second for playback; defaults to 24. */
+    GetTimeCodesPerSecond(): number;
+}
+
 /**
  * Builds a kinematic spanning tree from a {@link RobotDescription}.
  *
@@ -361,4 +524,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, invert as E, makeEuler as F, makeRotationFromQuat as G, makeRotationX as H, makeRotationY as I, type JointType as J, type KinematicTree as K, type LinkDescription as L, type Mat4 as M, makeRotationZ as N, makeScale as O, type PrimSpec as P, Quat as Q, type RobotDescription as R, type SampleChannel as S, type TreeEdge as T, type UsdaFile as U, type Vec2 as V, makeTranslation as W, multiply as X, multiplyAll as Y, toUsdMatrix as Z, type JointDescription as a, type Vec3 as b, type JointDriveDescription as c, type LinkInertialDescription as d, AssetPath as e, type AttributeSpec as f, type KinematicNode as g, type ListOp as h, type MetadataMap as i, type PropertySpec as j, RAD2DEG as k, type RelationshipSpec as l, type SdfPath as m, type Specifier as n, type UsdDictionary as o, UsdMatrix as p, type UsdValue as q, type Variability as r, type Vec4 as s, buildKinematicTree as t, channelFromSamples as u, decomposeRigid as v, fromUsdMatrix as w, getTranslation as x, identity4 as y, interpolate 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 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 };

package/dist/{chunk-PHHMWMCA.js → chunk-2UD32EGU.js}

@@ -1907,6 +1907,15 @@ var Prim = class {
   GetAllMetadata() {
     return this._spec?.metadata ?? {};
   }
+  /**
+   * Model-hierarchy kind from the `kind` metadata — `"component"`, `"group"`,
+   * `"assembly"`, `"subcomponent"`, … — or `""` when unauthored. The standard
+   * signal for selection granularity (usdview's "select by kind").
+   */
+  GetKind() {
+    const kind = this._spec?.metadata.kind;
+    return typeof kind === "string" ? kind : "";
+  }
   /** Applied API schema names from `apiSchemas` (e.g. `PhysicsArticulationRootAPI`). */
   GetAppliedSchemas() {
     const raw = this._spec?.metadata.apiSchemas;
@@ -3210,5 +3219,5 @@ function openUsdz(bytes) {
 }
 
 export { ARTICULATION_ROOT_API, Attribute, COLLISION_API, CrateReader, DEFAULT_METERS_PER_UNIT, DefaultAssetResolver, Layer, MASS_API, MESH_COLLISION_API, PHYSICS_MATERIAL_API, ParseError, Prim, RIGID_BODY_API, Relationship, Stage, TokenizeError, buildKinematicTree, composeFile, composeLayer, computeLocalTransform, computeWorldTransform, crateToUsdaFile, createMemoryResolver, driveKindFor, extractRobotDescription, gatherGprimDescendants, gatherMeshDescendants, getJointAxis, getJointBodies, getJointDrive, getJointLimits, getJointLocalFrame, getJointStatePosition, getJointType, getMassProperties, getMaterialSubsets, hasArticulationRootAPI, hasCollisionAPI, hasRigidBodyAPI, isMesh, isNonVisualPurpose, isRenderableGprim, isScope, isSolidGprim, isXform, isZip, iterDescendants, joinPosix, jointValueFromSI, jointValueToSI, normalizeJointLimits, openUsdz, parseOpType, parseUsda, refineJointType, resolveBoundMaterial, serializeUsda, toBytes, tokenize };
-//# sourceMappingURL=chunk-PHHMWMCA.js.map
-//# sourceMappingURL=chunk-PHHMWMCA.js.map
+//# sourceMappingURL=chunk-2UD32EGU.js.map
+//# sourceMappingURL=chunk-2UD32EGU.js.map