three-usd-robot 0.8.1 → 0.9.0

package/README.md

@@ -303,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-BZ_vlr1R.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
@@ -87,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;

package/dist/{ThreeUsdRobotLoader-HteyMZf1.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 { W as WorldUpAxis, T as ThreeUsdRobot } from './ThreeUsdRobot-BZ_vlr1R.js';
+import { W as WorldUpAxis, T as ThreeUsdRobot } from './ThreeUsdRobot-BAh-48DD.js';
 
 type ThreeUsdRobotLoaderOptions = {
     /** Resolver for references / payloads / sublayers (default {@link DefaultAssetResolver}). */

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