three-usd-robot 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,29 +1,114 @@
-import { AssetResolver, Stage, Prim } from './core.js';
-export { ARTICULATION_ROOT_API, Attribute, COLLISION_API, ComposeOptions, CrateReader, DEFAULT_METERS_PER_UNIT, DefaultAssetResolver, ExtractOptions, Layer, PACKAGE_NAME, ParseError, RIGID_BODY_API, Relationship, ResolvedXform, TokenizeError, UpAxis, UsdzPackage, VERSION, composeFile, composeLayer, computeLocalTransform, crateToUsdaFile, createMemoryResolver, driveKindFor, extractRobotDescription, gatherMeshDescendants, getJointAxis, getJointBodies, getJointDrive, getJointLimits, getJointLocalFrame, getJointStatePosition, getJointType, hasArticulationRootAPI, hasCollisionAPI, hasRigidBodyAPI, isMesh, isScope, isXform, iterDescendants, joinPosix, jointValueToSI, normalizeJointLimits, openUsdz, parseOpType, parseUsda, refineJointType, tokenize } from './core.js';
+import { Stage, Prim, CollisionApproximation, ExportPhysicsMaterial, RobotGeometryProvider, ExportRobotOptions, ExportMaterial, ExportMesh } from './core.js';
+export { ARTICULATION_ROOT_API, Attribute, COLLISION_API, ComposeOptions, CrateReader, DEFAULT_METERS_PER_UNIT, ExtractOptions, Layer, MASS_API, MESH_COLLISION_API, PACKAGE_NAME, PHYSICS_MATERIAL_API, ParseError, RIGID_BODY_API, Relationship, ResolvedXform, TextureChannel, TokenizeError, UpAxis, UsdzPackage, VERSION, ValidateRobotOptions, ValidationIssue, ValidationSeverity, composeFile, composeLayer, computeLocalTransform, computeWorldTransform, crateToUsdaFile, driveKindFor, exportRobotUsda, extractRobotDescription, gatherMeshDescendants, getJointAxis, getJointBodies, getJointDrive, getJointLimits, getJointLocalFrame, getJointStatePosition, getJointType, getMassProperties, hasArticulationRootAPI, hasCollisionAPI, hasRigidBodyAPI, isMesh, isScope, isXform, iterDescendants, jointValueFromSI, jointValueToSI, normalizeJointLimits, openUsdz, parseOpType, parseUsda, refineJointType, serializeUsda, stageGeometryProvider, tokenize, validateRobotDescription, writeUsdz } from './core.js';
 import * as THREE from 'three';
-import { A as Axis, R as RobotDescription, V as Vec3 } from './buildKinematicTree-CZjBMA1I.js';
-export { b as AssetPath, c as AttributeSpec, B as BuildTreeOptions, C as CompositionArc, D as DEG2RAD, a as JointDescription, d as JointDriveDescription, J as JointType, e as KinematicNode, K as KinematicTree, L as LinkDescription, f as ListOp, M as Mat4, g as MetadataMap, P as PrimSpec, h as PropertySpec, Q as Quat, i as RAD2DEG, j as RelationshipSpec, S as SampleChannel, k as SdfPath, l as Specifier, T as TreeEdge, U as UsdDictionary, m as UsdMatrix, n as UsdValue, o as UsdaFile, p as Variability, q as Vec2, r as Vec4, s as buildKinematicTree, t as channelFromSamples, u as fromUsdMatrix, v as getTranslation, w as identity4, x as interpolate, y as invert, z as makeEuler, E as makeRotationFromQuat, F as makeRotationX, G as makeRotationY, H as makeRotationZ, I as makeScale, N as makeTranslation, O as multiply, W as multiplyAll } from './buildKinematicTree-CZjBMA1I.js';
-import { T as ThreeUsdRobot } from './ThreeUsdRobot-Deoh7zam.js';
-export { J as JointObject, L as LinkObject, a as ThreeUsdRobotOptions } from './ThreeUsdRobot-Deoh7zam.js';
+import { A as Axis, V as Vec2, b as Vec3, R as RobotDescription, c as JointDriveDescription, d as LinkInertialDescription, K as KinematicTree, U as UsdaFile, M as Mat4 } from './buildKinematicTree-wtZPzy0B.js';
+export { e as AssetPath, f as AttributeSpec, B as BuildTreeOptions, C as CompositionArc, D as DEG2RAD, a as JointDescription, J as JointType, g as KinematicNode, L as LinkDescription, h as ListOp, i as MetadataMap, P as PrimSpec, j as PropertySpec, Q as Quat, k as RAD2DEG, l as RelationshipSpec, S as SampleChannel, m as SdfPath, n as Specifier, T as TreeEdge, o as UsdDictionary, p as UsdMatrix, q as UsdValue, r as Variability, s as Vec4, t as buildKinematicTree, u as channelFromSamples, v as decomposeRigid, w as fromUsdMatrix, x as getTranslation, y as identity4, z as interpolate, E as invert, F as makeEuler, G as makeRotationFromQuat, H as makeRotationX, I as makeRotationY, N as makeRotationZ, O as makeScale, W as makeTranslation, X as multiply, Y as multiplyAll, Z as toUsdMatrix } from './buildKinematicTree-wtZPzy0B.js';
+import { T as ThreeUsdRobot } from './ThreeUsdRobot-CajXJqYU.js';
+export { J as JointObject, L as LinkObject, a as ThreeUsdRobotOptions } from './ThreeUsdRobot-CajXJqYU.js';
+import { A as AssetResolver } from './AssetResolver-CpIJNgWZ.js';
+export { D as DefaultAssetResolver, c as createMemoryResolver, j as joinPosix } from './AssetResolver-CpIJNgWZ.js';
+export { a as ThreeUsdRobotLoader, T as ThreeUsdRobotLoaderOptions } from './ThreeUsdRobotLoader-DrMMLzo-.js';
 
 /** Unit vector for a USD joint axis token. Returns a fresh vector each call. */
 declare function axisVector(axis: Axis): THREE.Vector3;
 
+/**
+ * Resolves `UsdShade` material bindings to flat PBR parameters.
+ *
+ * Follows a prim's (or an ancestor's) `material:binding` to a `Material`, finds
+ * its surface `Shader`, and reads constant color/metalness/roughness/opacity/
+ * emissive inputs plus the **texture** asset paths for the diffuse, normal,
+ * roughness, metallic, occlusion and emissive channels. Handles both
+ * `UsdPreviewSurface` (constant inputs or a connected `UsdUVTexture` network)
+ * and Omniverse `OmniPBR` MDL (direct asset-valued texture inputs such as
+ * `inputs:normalmap_texture`).
+ */
+
+/** `UsdUVTexture` wrap mode for one axis (`black` ≈ clamp; three has no border). */
+type TextureWrap = "repeat" | "clamp" | "mirror" | "black";
+/** `UsdTransform2d` applied to the `st` coords feeding a texture. */
+type TextureTransform = {
+    /** `inputs:translation` (UV offset). */
+    translation?: Vec2;
+    /** `inputs:rotation` in degrees (CCW about the origin). */
+    rotation?: number;
+    /** `inputs:scale` (UV tiling). */
+    scale?: Vec2;
+};
+/** A resolved texture reference plus its `UsdUVTexture` sampler/transform state. */
+type ResolvedTexture = {
+    /** Authored asset path of the image. */
+    path: string;
+    wrapS?: TextureWrap;
+    wrapT?: TextureWrap;
+    /** `UsdTransform2d` on the `st` input, if any. */
+    transform?: TextureTransform;
+    /** `inputs:scale` — multiplies the sampled value (folded into material factors). */
+    scale?: [number, number, number, number];
+    /** `inputs:bias` — added to the sampled value. */
+    bias?: [number, number, number, number];
+};
+type ResolvedMaterial = {
+    color?: Vec3;
+    opacity?: number;
+    metalness?: number;
+    roughness?: number;
+    emissiveColor?: Vec3;
+    /**
+     * `inputs:opacityThreshold`. When `> 0`, opacity is a binary mask (alpha
+     * clip / cutout); when `0`/absent, sub-unit opacity blends translucently.
+     */
+    opacityThreshold?: number;
+    /** Diffuse/albedo texture, if any. */
+    colorTexture?: ResolvedTexture;
+    /** Opacity / alpha texture (may be the same image as `colorTexture`). */
+    opacityTexture?: ResolvedTexture;
+    /** Tangent-space normal map, if any. */
+    normalTexture?: ResolvedTexture;
+    /** Roughness map, if any. */
+    roughnessTexture?: ResolvedTexture;
+    /** Metallic map, if any. */
+    metalnessTexture?: ResolvedTexture;
+    /** Ambient-occlusion map, if any. */
+    occlusionTexture?: ResolvedTexture;
+    /** Emissive map, if any. */
+    emissiveTexture?: ResolvedTexture;
+};
+/** Resolve the bound material's flat parameters for `prim`, or `undefined`. */
+declare function resolveBoundMaterial(stage: Stage, prim: Prim): ResolvedMaterial | undefined;
+
 /**
  * Loads texture image assets referenced by `UsdShade` materials.
  *
- * A {@link TextureProvider} maps an authored asset path to a `THREE.Texture`.
- * The default provider resolves the path against the layer base URL and loads it
- * with `THREE.TextureLoader` (so it works for textures served alongside the USD
- * on the web). Textures load asynchronously and update the material when ready.
+ * A {@link TextureProvider} maps an authored asset path (plus sampler/transform
+ * options) to a `THREE.Texture`. The default provider fetches the image **bytes**
+ * through the {@link AssetResolver} and decodes them via a blob URL — so it works
+ * uniformly for textures served over HTTP and for images embedded inside a
+ * `.usdz` package (whose resolver serves zip entries, not real URLs). Decoded
+ * images are cached per resolved URL and shared across every texture that uses
+ * them; each `THREE.Texture` carries its own color space / wrap / transform.
  */
 
+/**
+ * Color space to interpret a texture in. Color/albedo and emissive maps are
+ * `"srgb"`; data maps (normal, roughness, metalness, occlusion) are `"linear"`.
+ */
+type TextureColorSpace = "srgb" | "linear";
+/** Per-use sampler state applied to the returned `THREE.Texture`. */
+type TextureOptions = {
+    /** Defaults to `"srgb"`. */
+    colorSpace?: TextureColorSpace;
+    wrapS?: TextureWrap;
+    wrapT?: TextureWrap;
+    transform?: TextureTransform;
+};
 /** Resolve an authored texture asset path to a `THREE.Texture` (or `null`). */
-type TextureProvider = (assetPath: string) => THREE.Texture | null;
+type TextureProvider = (assetPath: string, options?: TextureOptions) => THREE.Texture | null;
 /**
- * A {@link TextureProvider} backed by `THREE.TextureLoader`, resolving paths via
- * `resolver` against `baseUrl`. Results are cached per resolved URL and tagged
- * as sRGB color textures.
+ * A {@link TextureProvider} backed by the {@link AssetResolver}, resolving paths
+ * against `baseUrl`. Image bytes are fetched once per URL (works for HTTP and
+ * `.usdz` entries alike) and the decoded image is shared; each call returns a
+ * distinct `THREE.Texture` carrying the requested color space / wrap / transform.
  */
 declare function createTextureProvider(resolver: AssetResolver, baseUrl: string): TextureProvider;
 
@@ -48,9 +133,11 @@ type BindMeshesOptions = {
 declare function buildMeshGeometry(meshPrim: Prim): THREE.BufferGeometry | null;
 /**
  * Build a material for a Mesh prim. Color priority: bound `UsdShade` material
- * (when `stage` is given) → `primvars:displayColor` → default gray. A diffuse
- * texture (via `textures`) becomes `material.map`; metalness / roughness /
- * opacity come from the bound material when present.
+ * (when `stage` is given) → `primvars:displayColor` → default gray. Textures
+ * (via `textures`) become the matching `MeshStandardMaterial` maps — diffuse →
+ * `map` (sRGB), plus `normalMap` / `roughnessMap` / `metalnessMap` / `aoMap`
+ * (linear data) and emissive `emissiveMap`. Metalness / roughness / opacity /
+ * emissive constants come from the bound material when present.
  */
 declare function buildMeshMaterial(meshPrim: Prim, stage?: Stage, textures?: TextureProvider): THREE.Material;
 /**
@@ -59,80 +146,139 @@ declare function buildMeshMaterial(meshPrim: Prim, stage?: Stage, textures?: Tex
  * the owning link prim.
  */
 declare function bindRobotMeshes(stage: Stage, robot3d: ThreeUsdRobot, desc: RobotDescription, options?: BindMeshesOptions): void;
+/**
+ * Attach the Mesh prims that belong to no link — the static scenery of a cell
+ * that also contains robots. They are placed by their authored stage transform
+ * under the robot root, so the loader's up-axis and unit normalization applies
+ * to them too. Collision-only and guide/proxy prims are skipped.
+ */
+declare function bindSceneMeshes(stage: Stage, robot3d: ThreeUsdRobot, desc: RobotDescription, options?: {
+    textureProvider?: TextureProvider;
+}): number;
 
 /**
- * Resolves `UsdShade` material bindings to flat PBR parameters.
+ * Authoring API (M14): assemble a robot from Three.js objects and export it.
  *
- * Follows a prim's (or an ancestor's) `material:binding` to a `Material`, finds
- * its surface `Shader`, and reads constant color/metalness/roughness/opacity
- * inputs plus the diffuse **texture** asset path. Handles both
- * `UsdPreviewSurface` (`inputs:diffuseColor` constant or a `UsdUVTexture`
- * network) and Omniverse `OmniPBR` MDL (`inputs:diffuse_color_constant`,
- * `inputs:diffuse_texture`). Only the diffuse channel and constants are read.
+ * Links and joints are declared by name. Every joint takes **one** world-space
+ * frame; both body-local joint frames derive from it —
+ * `frame0 = linkWorld(parent)⁻¹ · frame`, `frame1 = linkWorld(child)⁻¹ · frame`
+ * — so the arrangement at build time is the robot's zero pose. Values are SI
+ * (radians / stage linear units); the exporter converts to authored units on
+ * write. World matrices are captured at `addLink`/`add*Joint` time.
  */
 
-type ResolvedMaterial = {
-    color?: Vec3;
-    opacity?: number;
-    metalness?: number;
-    roughness?: number;
-    /** Authored asset path of the diffuse/albedo texture, if any. */
-    colorTexture?: string;
-};
-/** Resolve the bound material's flat parameters for `prim`, or `undefined`. */
-declare function resolveBoundMaterial(stage: Stage, prim: Prim): ResolvedMaterial | undefined;
-
-type ThreeUsdRobotLoaderOptions = {
-    /** Resolver for references / payloads / sublayers (default {@link DefaultAssetResolver}). */
-    assetResolver?: AssetResolver;
-    /** Render visual meshes (M6). */
-    loadVisuals?: boolean;
-    /** Render collision meshes (M6). */
-    loadCollisions?: boolean;
-    /** Load diffuse textures referenced by materials (default `true`). */
-    loadTextures?: boolean;
-    /** Up-axis correction strategy (M9). */
-    upAxisConversion?: "auto" | "Y" | "Z" | "none";
-    /** Extra uniform scale multiplied with `metersPerUnit` (M9). */
-    unitScale?: number;
-    /** Clamp `setJointValue` to authored limits (default `true`). */
-    clampJointLimits?: boolean;
-    /** Seed joints from drive targets / joint state (M9). */
-    applyDriveTargetsAsInitialPose?: boolean;
-    /** Override the robot name. */
-    robotName?: string;
-    /** Receives non-fatal load diagnostics. */
+/** A world-space frame: a matrix, or an object whose `matrixWorld` is used. */
+type WorldFrame = THREE.Matrix4 | THREE.Object3D;
+type RobotBuilderOptions = {
+    name: string;
+    /** Stage up axis; defaults to `"Z"` (Isaac Sim convention). */
+    upAxis?: "Y" | "Z";
+    /** Stage linear unit; defaults to `1` (meters). */
+    metersPerUnit?: number;
+    /** Link to flag with `PhysicsArticulationRootAPI` (default: the container prim). */
+    articulationRoot?: string;
     onWarn?: (message: string) => void;
 };
+type AddLinkOptions = {
+    name: string;
+    /** Link frame in world space at build pose (default identity). */
+    frame?: WorldFrame;
+    /** Objects whose `THREE.Mesh` descendants become the link's visual meshes. */
+    visuals?: THREE.Object3D[];
+    /** Objects whose `THREE.Mesh` descendants become collision meshes. */
+    collisions?: THREE.Object3D[];
+    /** Mass properties, exported as `PhysicsMassAPI` (M16). */
+    inertial?: LinkInertialDescription;
+    /** `physics:approximation` applied to this link's collision meshes (M16). */
+    collisionApproximation?: CollisionApproximation;
+    /** Physics material bound to this link's collision meshes (M16). */
+    physicsMaterial?: ExportPhysicsMaterial;
+};
+type AddJointOptions = {
+    name: string;
+    /** Parent link name; omit to fix the child to the world. */
+    parent?: string;
+    child: string;
+    /** Joint frame in world space (default: the child link's frame). */
+    frame?: WorldFrame;
+    /** Rotation / sliding axis token in the joint frame (default `"X"`). */
+    axis?: Axis;
+    /** Limits in SI: radians (revolute) or stage linear units (prismatic). */
+    lower?: number;
+    upper?: number;
+    /** Initial joint value in SI, exported as `PhysicsJointStateAPI`. */
+    initialValue?: number;
+    drive?: JointDriveDescription;
+};
+declare class RobotBuilder {
+    private readonly robotName;
+    private readonly upAxis;
+    private readonly metersPerUnit;
+    private readonly articulationRoot?;
+    private readonly warn;
+    private readonly links;
+    private readonly joints;
+    private readonly materialCache;
+    private materialAutoId;
+    constructor(options: RobotBuilderOptions);
+    addLink(options: AddLinkOptions): this;
+    addFixedJoint(options: Omit<AddJointOptions, "axis" | "lower" | "upper">): this;
+    addRevoluteJoint(options: AddJointOptions): this;
+    addPrismaticJoint(options: AddJointOptions): this;
+    private addJoint;
+    /** Assemble the IR + geometry provider (validates the kinematic graph). */
+    build(): {
+        desc: RobotDescription;
+        geometry: RobotGeometryProvider;
+        tree: KinematicTree;
+    };
+    /** Build and export in one step (pass the result to `serializeUsda`). */
+    toUsda(options?: Omit<ExportRobotOptions, "geometry">): UsdaFile;
+    /** Collect `THREE.Mesh` descendants of `roots` as link-relative export meshes. */
+    private gatherMeshes;
+    private convertMaterial;
+}
+
 /**
- * Loads Isaac Sim / OpenUSD robot assets into a controllable {@link ThreeUsdRobot}.
+ * Three.js-side export (M14).
  *
- * Composition (references / payloads / sublayers, M8) is resolved through an
- * {@link AssetResolver}. Mesh rendering is M6; unit / up-axis / initial-pose
- * handling is M9; USDC and variants are M10.
+ * Converts `BufferGeometry` / `MeshStandardMaterial` into the plain
+ * {@link ExportMesh} data the exporter consumes, harvests the meshes attached
+ * under a loaded robot's links, and re-exports a {@link ThreeUsdRobot} as a
+ * USDA AST. Texture maps are not carried yet (M15) — constants only.
  */
-declare class ThreeUsdRobotLoader {
-    readonly options: ThreeUsdRobotLoaderOptions;
-    constructor(options?: ThreeUsdRobotLoaderOptions);
-    private get resolver();
-    /**
-     * Fetch an asset by URL and build the robot. `.usdz` packages are unzipped and
-     * composed from their entries; everything else is treated as USDA text.
-     */
-    loadAsync(url: string): Promise<ThreeUsdRobot>;
-    private fetchRootBytes;
-    /** Build a robot (composed, with meshes) from USDA source text. */
-    parse(text: string, baseUrl?: string): Promise<ThreeUsdRobot>;
-    /** Build a robot from the bytes of a `.usdz` package. */
-    parseUsdz(bytes: Uint8Array): Promise<ThreeUsdRobot>;
-    /** Build a robot from the bytes of a binary crate (`.usdc` / binary `.usd`). */
-    parseCrate(bytes: Uint8Array, baseUrl?: string): Promise<ThreeUsdRobot>;
-    /** Parse + compose USDA source into the Three.js-independent robot IR. */
-    parseRobotDescription(text: string, baseUrl?: string): Promise<RobotDescription>;
-    private buildFromStage;
-    private composeStage;
-    private robotOptions;
-    private extractOptions;
-}
 
-export { AssetResolver, Axis, type BindMeshesOptions, type MeshKind, Prim, type ResolvedMaterial, RobotDescription, Stage, type TextureProvider, ThreeUsdRobot, ThreeUsdRobotLoader, type ThreeUsdRobotLoaderOptions, Vec3, axisVector, bindRobotMeshes, buildMeshGeometry, buildMeshMaterial, createTextureProvider, resolveBoundMaterial };
+type GeometryToExportMeshOptions = {
+    name: string;
+    kind?: "visual" | "collision";
+    /** Transform relative to the link frame (column-major); identity when omitted. */
+    transform?: Mat4;
+    material?: ExportMaterial;
+    doubleSided?: boolean;
+};
+/**
+ * Convert a triangle `BufferGeometry` into exportable mesh data. Non-indexed
+ * geometry becomes sequential triangles; a trailing partial triangle (or the
+ * absence of a position attribute) returns `null`.
+ */
+declare function geometryToExportMesh(geometry: THREE.BufferGeometry, options: GeometryToExportMeshOptions): ExportMesh | null;
+/**
+ * Extract constant PBR parameters from a Three.js material. Only
+ * `MeshStandardMaterial` maps onto `UsdPreviewSurface`; anything else returns
+ * `undefined` (with a warning). Texture maps are reported but not carried.
+ */
+declare function materialToExportMaterial(material: THREE.Material, name: string, onWarn?: (message: string) => void): ExportMaterial | undefined;
+/**
+ * Provider over the meshes `bindRobotMeshes` attached under each link of a
+ * loaded robot (direct children tagged `userData.kind`), with their link-local
+ * transforms and materials.
+ */
+declare function threeGeometryProvider(robot: ThreeUsdRobot, onWarn?: (message: string) => void): RobotGeometryProvider;
+type ExportThreeUsdRobotOptions = Omit<ExportRobotOptions, "geometry"> & {
+    /** Re-read mesh data from the source stage instead of the Three.js scene. */
+    stage?: Stage;
+};
+/** Export a loaded robot back to a USDA AST (pass the result to `serializeUsda`). */
+declare function exportThreeUsdRobot(robot: ThreeUsdRobot, options?: ExportThreeUsdRobotOptions): UsdaFile;
+
+export { type AddJointOptions, type AddLinkOptions, AssetResolver, Axis, type BindMeshesOptions, CollisionApproximation, ExportMaterial, ExportMesh, ExportPhysicsMaterial, ExportRobotOptions, type ExportThreeUsdRobotOptions, type GeometryToExportMeshOptions, JointDriveDescription, KinematicTree, LinkInertialDescription, Mat4, type MeshKind, Prim, type ResolvedMaterial, type ResolvedTexture, RobotBuilder, type RobotBuilderOptions, RobotDescription, RobotGeometryProvider, Stage, type TextureColorSpace, type TextureOptions, type TextureProvider, type TextureTransform, type TextureWrap, ThreeUsdRobot, UsdaFile, Vec2, Vec3, type WorldFrame, axisVector, bindRobotMeshes, bindSceneMeshes, buildMeshGeometry, buildMeshMaterial, createTextureProvider, exportThreeUsdRobot, geometryToExportMesh, materialToExportMaterial, resolveBoundMaterial, threeGeometryProvider };