three-usd-robot 0.8.1 → 0.10.0

package/README.md

@@ -23,10 +23,13 @@ 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 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.
+- **Rendering** — meshes, solid gprims (`Cube` / `Sphere` / `Cylinder` /
+  `Capsule` / `Cone`), point clouds (`Points`) and curves (`BasisCurves`:
+  linear / bezier / bspline / catmullRom, periodic wrap, and an opt-in
+  `curveTubes` mode that turns authored widths into tube meshes) 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.
@@ -50,8 +53,15 @@ 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, point/curve
-gprims (`Points`, `BasisCurves`, …), and full material/shader fidelity.
+Materials target **UsdPreviewSurface fidelity plus an OmniPBR mapping**:
+constant and textured inputs, faceVarying / indexed UVs, multiple UV sets,
+per-vertex display colors, physical extensions (`ior` / `clearcoat` /
+specular workflow → `MeshPhysicalMaterial`), packed ORM maps,
+`sourceColorSpace`, and purpose/strength-aware bindings. Executing MDL or
+MaterialX shader graphs is out of scope. Not yet supported:
+collection-based material bindings, and the exotic curve schemas
+(`NurbsCurves`, `HermiteCurves`, `NurbsPatch`) which load with a warning and
+are skipped.
 
 ## Install
 
@@ -303,9 +313,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-B7Z4oORO.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-BCySuZZn.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-NdFAVN96.d.ts}

@@ -1,6 +1,6 @@
-import { R as RobotDescription } from './buildKinematicTree-D4R0hEtN.js';
+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-BZ_vlr1R.js';
+import { W as WorldUpAxis, T as ThreeUsdRobot } from './ThreeUsdRobot-B7Z4oORO.js';
 
 type ThreeUsdRobotLoaderOptions = {
     /** Resolver for references / payloads / sublayers (default {@link DefaultAssetResolver}). */
@@ -18,6 +18,11 @@ type ThreeUsdRobotLoaderOptions = {
     loadSceneGeometry?: boolean;
     /** Load diffuse textures referenced by materials (default `true`). */
     loadTextures?: boolean;
+    /**
+     * Render `BasisCurves` that author `widths` as tube meshes instead of
+     * 1-px lines (default `false`, M18).
+     */
+    curveTubes?: 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),
@@ -82,6 +87,8 @@ declare class ThreeUsdRobotLoader {
     private openSource;
     private openUsdzStage;
     private buildFromStage;
+    /** Surface recognized-but-unrenderable gprim schemas instead of silence (M18). */
+    private warnUnsupportedGprims;
     private composeStage;
     /** Compose a layer from raw bytes, sniffing binary crate vs USDA text. */
     private composeStageFromBytes;

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

@@ -317,6 +317,173 @@ 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[];
+    /** Authored attribute metadata (`interpolation`, `elementSize`, …). */
+    GetMetadata(key: string): UsdValue | undefined;
+}
+/** 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[];
+    /** Authored relationship metadata (`bindMaterialAs`, …). */
+    GetMetadata(key: string): UsdValue | undefined;
+}
+
+/**
+ * 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 +528,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 };