@openusd-wasm/three-loader 0.0.4 → 0.0.5

package/README.md

@@ -2,8 +2,8 @@
 
 Three.js loader for OpenUSD `.usd`, `.usda`, `.usdc`, and `.usdz` assets.
 Parsing runs through `@openusd-wasm/pxr`; this package converts the opened USD
-stage into a Three.js object tree and keeps OpenUSD metadata available in
-`Object3D.userData`.
+stage into a Three.js object tree, returns extracted USD scene data, and keeps
+runtime lookup state separate from Three.js `userData`.
 
 ```ts
 import createOpenUsdPxrWasm from '@openusd-wasm/core'
@@ -18,10 +18,13 @@ const loader = new USDLoader({
   },
 })
 
-const { scene, metadata } = await loader.loadAsync('/models/robot.usda')
+const model = await loader.loadAsync('/models/robot.usda')
+const { scene, data, index } = model
 threeScene.add(scene)
 
-console.log(metadata.joints)
+console.log(data.physics)
+console.log(data.joints)
+console.log(index.objectsByPath.get('/World/Robot'))
 ```
 
 ## Returned Data
@@ -29,21 +32,58 @@ console.log(metadata.joints)
 `USDLoader` returns:
 
 - `scene`: a `THREE.Group` containing mesh/group objects that mirror the USD prim hierarchy.
-- `metadata`: stage info, view prims, mesh geometry summaries, material/shader inputs, and physics joint info.
+- `data`: extracted stage info, view prims, mesh geometry summaries, material/shader inputs, animation data, variants, and USD physics info.
+- `index`: runtime lookup maps such as `objectsByPath`, `meshesByPath`, `materialsByPath`, `rigidBodiesByPath`, `jointsByBodyPath`, and `bonesBySkeletonPath`.
+- `resources`: object URL maps for images discovered in USDZ packages or auto-resolved next to the root layer.
 - `sourcePath` and `rootLayerIdentifier`: useful for diagnostics and texture resolution.
 
-The same metadata is attached to the scene:
+Generated prim objects only store a lightweight USD bridge in `userData`:
 
 ```ts
-scene.userData.usdMetadata
-scene.userData.usdJoints
-scene.userData.usdObjectsByPath
+object.userData.usd
+// { kind: 'prim', path: '/World/Mesh', typeName: 'Mesh' }
 ```
 
-Each generated object gets `userData.usdPath` and `userData.usdTypeName`.
-Joint prim objects get `userData.usdJoint`; body objects referenced by joints
-get a `userData.usdJoints` array. This mirrors the URDFLoader pattern where
-clients can restore articulation controls from exported joint metadata.
+Use `model.index` to look up heavy USD data or Three.js runtime objects. The
+loader does not mirror scene data, physics summaries, texture URL maps, or
+object indexes into `Object3D.userData`.
+
+Skeleton bones and animation clips use the same lightweight bridge:
+
+```ts
+bone.userData.usd
+// { kind: 'skelJoint', skeletonPath: '/World/Skeleton', jointPath: 'root', jointIndex: 0 }
+
+clip.userData.usd
+// { kind: 'animation', id: 'skel:/World/Skeleton/Animation', source: 'skel', variant: null }
+```
+
+Call `model.dispose()` or `disposeUSDLoadedModel(model)` when a loaded model is
+removed. This releases generated Three.js resources, preserved USD stages, and
+object URLs created for auto-resolved or USDZ textures stored in
+`model.resources`.
+
+## Lower-Level APIs
+
+Use `parseDataAsync()` when an application needs the OpenUSD scene facts before
+creating Three.js objects:
+
+```ts
+const parsed = await loader.parseDataAsync(file, { sourcePath: 'robot.usda' })
+console.log(parsed.data.stage)
+console.log(parsed.data.materials)
+```
+
+Use `extractUSDSceneData()` when you already opened a `Usd.Stage` through
+`@openusd-wasm/pxr`, and `buildUSDScene()` when you want to convert extracted
+data into Three.js manually:
+
+```ts
+import { buildUSDScene, extractUSDSceneData } from '@openusd-wasm/three-loader'
+
+const data = extractUSDSceneData(pxr, stage, { sourcePath: 'robot.usda' })
+const { scene, index } = buildUSDScene(data, { loadTextures: false })
+```
 
 ## USDZ
 

package/dist/openusd_three_loader.d.ts

@@ -28,9 +28,10 @@ interface USDViewPrim {
   resetsXformStack: boolean;
 }
 interface USDMeshGeometryData {
-  positions: number[];
-  normals: number[];
-  uvs: number[];
+  positions: number[] | Float32Array;
+  pointIndices?: number[] | Int32Array;
+  normals: number[] | Float32Array;
+  uvs: number[] | Float32Array;
   displayColor: USDVector3 | null;
   displayOpacity: number | null;
 }
@@ -51,12 +52,19 @@ interface USDMaterialInfo {
   shaders: USDShaderInfo[];
 }
 interface USDJointDriveInfo {
+  dof?: string;
+  type?: string | null;
   targetPosition: number | null;
   targetVelocity: number | null;
   stiffness: number | null;
   damping: number | null;
   maxForce: number | null;
 }
+interface USDJointLimitInfo {
+  dof: string;
+  low: number | null;
+  high: number | null;
+}
 interface USDJointInfo {
   path: string;
   name: string;
@@ -72,9 +80,77 @@ interface USDJointInfo {
   lowerLimit: number | null;
   upperLimit: number | null;
   enabled: boolean;
+  collisionEnabled: boolean;
+  excludeFromArticulation: boolean;
+  breakForce: number | null;
+  breakTorque: number | null;
+  limits: USDJointLimitInfo[];
   drive: USDJointDriveInfo | null;
   drives: Record<string, USDJointDriveInfo>;
 }
+interface USDPhysicsMassInfo {
+  mass: number | null;
+  density: number | null;
+  centerOfMass: USDVector3 | null;
+  diagonalInertia: USDVector3 | null;
+  principalAxes: USDVector4 | null;
+}
+interface USDPhysicsRigidBodyInfo {
+  path: string;
+  name: string;
+  typeName: string;
+  enabled: boolean;
+  kinematicEnabled: boolean;
+  startsAsleep: boolean | null;
+  velocity: USDVector3 | null;
+  angularVelocity: USDVector3 | null;
+  mass: USDPhysicsMassInfo | null;
+}
+interface USDPhysicsColliderInfo {
+  path: string;
+  name: string;
+  typeName: string;
+  bodyPath: string | null;
+  enabled: boolean;
+  approximation: string | null;
+  material: string | null;
+}
+interface USDPhysicsMaterialInfo {
+  path: string;
+  name: string;
+  staticFriction: number | null;
+  dynamicFriction: number | null;
+  restitution: number | null;
+  density: number | null;
+}
+interface USDPhysicsSceneInfo {
+  path: string;
+  name: string;
+  gravityDirection: USDVector3 | null;
+  gravityMagnitude: number | null;
+}
+interface USDPhysicsArticulationRootInfo {
+  path: string;
+  name: string;
+  joints: string[];
+}
+interface USDPhysicsInfo {
+  scenes: USDPhysicsSceneInfo[];
+  rigidBodies: USDPhysicsRigidBodyInfo[];
+  colliders: USDPhysicsColliderInfo[];
+  materials: USDPhysicsMaterialInfo[];
+  articulationRoots: USDPhysicsArticulationRootInfo[];
+}
+interface USDStageCameraInfo {
+  path: string;
+  name: string;
+  projection: 'perspective' | 'orthographic';
+  horizontalAperture: number | null;
+  verticalAperture: number | null;
+  focalLength: number | null;
+  clippingRange: [number, number] | null;
+  localMatrix: number[] | null;
+}
 interface USDTransformAnimationSample {
   time: number;
   localMatrix: number[];
@@ -83,37 +159,173 @@ interface USDTransformAnimation {
   primPath: string;
   samples: USDTransformAnimationSample[];
 }
+interface USDSkelBindingInfo {
+  primPath: string;
+  skeletonPath: string | null;
+  animationSource: string | null;
+  joints: string[];
+  jointIndices: number[];
+  jointWeights: number[];
+  elementSize: number;
+  geomBindTransform: number[] | null;
+}
+interface USDSkeletonInfo {
+  path: string;
+  joints: string[];
+  bindTransforms: number[][];
+  restTransforms: number[][];
+  restSkelTransforms?: number[][];
+}
+interface USDSkelJointVec3Sample {
+  time: number;
+  values: USDVector3[];
+}
+interface USDSkelJointQuatSample {
+  time: number;
+  values: USDVector4[];
+}
+interface USDSkelJointMatrixSample {
+  time: number;
+  values: number[][];
+}
+interface USDSkelAnimationSkeletonSamples {
+  skeletonPath: string;
+  samples: USDSkelJointMatrixSample[];
+}
+interface USDSkelAnimationInfo {
+  path: string;
+  name: string;
+  joints: string[];
+  translations: USDSkelJointVec3Sample[];
+  rotations: USDSkelJointQuatSample[];
+  scales: USDSkelJointVec3Sample[];
+  jointSkelTransformSamples?: USDSkelAnimationSkeletonSamples[];
+}
+interface USDSkelAnimationTrack {
+  skeletonPath: string;
+  animationPath: string;
+  samplesStartTimeCode: number;
+  samplesEndTimeCode: number;
+}
+type USDAnimationClipSource = 'stage' | 'skel' | 'variant' | 'clipsApi';
+interface USDAnimationVariantRef {
+  primPath: string;
+  setName: string;
+  selection: string;
+}
 interface USDAnimationInfo {
+  id: string;
+  name: string;
+  source: USDAnimationClipSource;
+  variant: USDAnimationVariantRef | null;
   startTimeCode: number;
   endTimeCode: number;
   timeCodesPerSecond: number;
   transforms: USDTransformAnimation[];
+  skelAnimations: USDSkelAnimationTrack[];
+}
+interface USDVariantSetInfo {
+  primPath: string;
+  primName: string;
+  setName: string;
+  variantNames: string[];
+  selection: string | null;
 }
-interface USDModelData {
+interface USDVariantSelection {
+  primPath: string;
+  setName: string;
+  selection: string | null;
+}
+interface USDSkelInfo {
+  skeletons: USDSkeletonInfo[];
+  bindings: USDSkelBindingInfo[];
+  animations: USDSkelAnimationInfo[];
+}
+interface USDSceneData {
   stage: USDStageInfo;
   view: {
     prims: USDViewPrim[];
   };
   elements: USDMeshElement[];
   materials: USDMaterialInfo[];
+  physics: USDPhysicsInfo;
   joints: USDJointInfo[];
+  cameras: USDStageCameraInfo[];
+  skels: USDSkelInfo;
   animations: USDAnimationInfo[];
+  variants: USDVariantSetInfo[];
+}
+type USDUserDataValue = {
+  kind: 'prim';
+  path: string;
+  typeName: string;
+} | {
+  kind: 'skelJoint';
+  skeletonPath: string;
+  jointPath: string;
+  jointIndex: number;
+} | {
+  kind: 'animation';
+  id: string;
+  source: USDAnimationClipSource;
+  variant: USDAnimationVariantRef | null;
+};
+interface USDUserData {
+  usd?: USDUserDataValue;
+}
+interface USDSceneIndex {
+  objectsByPath: Map<string, THREE.Object3D>;
+  bonesBySkeletonPath: Map<string, THREE.Bone[]>;
+  boneHostsBySkeletonPath: Map<string, THREE.Object3D>;
+  primsByPath: Map<string, USDViewPrim>;
+  meshesByPath: Map<string, USDMeshElement>;
+  materialsByPath: Map<string, USDMaterialInfo>;
+  rigidBodiesByPath: Map<string, USDPhysicsRigidBodyInfo>;
+  collidersByPath: Map<string, USDPhysicsColliderInfo>;
+  jointsByPath: Map<string, USDJointInfo>;
+  jointsByBodyPath: Map<string, USDJointInfo[]>;
+  skelBindingsByPrimPath: Map<string, USDSkelBindingInfo>;
+  skeletonsByPath: Map<string, USDSkeletonInfo>;
+  camerasByPath: Map<string, USDStageCameraInfo>;
+  variantsByPrimPath: Map<string, USDVariantSetInfo[]>;
+  animationsById: Map<string, USDAnimationInfo>;
+}
+interface USDSceneBuildResult {
+  scene: THREE.Group;
+  index: USDSceneIndex;
+}
+interface USDLoadedModelResources {
+  usdzTextureURLs: Map<string, string>;
+  autoTextureURLs: Map<string, string>;
 }
 interface USDLoadedModel {
   scene: THREE.Group;
-  metadata: USDModelData;
+  data: USDSceneData;
+  index: USDSceneIndex;
+  resources: USDLoadedModelResources;
   stage?: unknown;
   pxr: Pxr;
   sourcePath: string;
   rootLayerIdentifier: string;
+  dispose(): void;
 }
-interface ExtractUSDModelDataOptions {
+interface USDParsedStageData {
+  data: USDSceneData;
+  stage?: unknown;
+  pxr: Pxr;
+  sourcePath: string;
+  rootLayerIdentifier: string;
+  textureResolver?: USDTextureResolver;
+  usdzTextureURLs?: Map<string, string>;
+  autoTextureURLs?: Map<string, string>;
+}
+interface ExtractUSDSceneDataOptions {
   sourcePath?: string;
   rootLayerIdentifier?: string;
 }
 type USDTextureResolverContext = USDTextureResolverContext$1<USDMaterialInfo, USDShaderInfo>;
 type USDTextureResolver = USDTextureResolver$1<USDMaterialInfo, USDShaderInfo>;
-interface BuildUSDObjectOptions {
+interface BuildUSDSceneOptions {
   sourcePath?: string;
   convertZUp?: boolean;
   loadTextures?: boolean;
@@ -121,7 +333,7 @@ interface BuildUSDObjectOptions {
   textureLoader?: THREE.TextureLoader;
   textureCache?: Map<string, THREE.Texture>;
 }
-interface USDLoaderParseOptions extends BuildUSDObjectOptions {
+interface USDLoaderParseOptions extends BuildUSDSceneOptions {
   sourcePath?: string;
   fileName?: string;
   files?: Record<string, USDSourceInput>;
@@ -134,8 +346,9 @@ interface USDLoaderParseOptions extends BuildUSDObjectOptions {
   usdzLayer?: string;
   preserveStage?: boolean;
   cleanupAfterParse?: boolean;
+  variantSelections?: USDVariantSelection[];
 }
-interface USDLoaderOptions extends BuildUSDObjectOptions {
+interface USDLoaderOptions extends BuildUSDSceneOptions {
   pxr?: Pxr | Promise<Pxr>;
   pxrOptions?: Parameters<typeof import('@openusd-wasm/pxr').createPxr>[0];
   workingDirectory?: string;
@@ -143,6 +356,7 @@ interface USDLoaderOptions extends BuildUSDObjectOptions {
   usdzLayer?: string;
   preserveStage?: boolean;
   cleanupAfterParse?: boolean;
+  variantSelections?: USDVariantSelection[];
 }
 type PxrObject = Record<string, any> & {
   delete?: () => void;
@@ -159,77 +373,17 @@ declare class USDLoader extends Loader<USDLoadedModel, string> {
   setWorkingDirectory(path: string): this;
   load(url: string, onLoad: (data: USDLoadedModel) => void, onProgress?: (event: ProgressEvent) => void, onError?: (err: unknown) => void): void;
   parse(input: USDSourceInput, onLoad: (data: USDLoadedModel) => void, onError?: (err: unknown) => void, options?: USDLoaderParseOptions): void;
+  parseDataAsync(input: USDSourceInput, options?: USDLoaderParseOptions): Promise<USDParsedStageData>;
   parseAsync(input: USDSourceInput, options?: USDLoaderParseOptions): Promise<USDLoadedModel>;
   private getPxr;
 }
 //#endregion
-//#region src/manipulation-controls.d.ts
-interface USDManipulationControlsOptions {
-  scene: THREE.Scene;
-  camera: THREE.Camera;
-  domElement: HTMLElement;
-  controls?: {
-    enabled: boolean;
-  } | null;
-  highlightColor?: THREE.ColorRepresentation;
-  enabled?: boolean;
-  onChange?: (event: USDManipulationChangeEvent) => void;
-  onHoverChange?: (event: USDManipulationHoverEvent) => void;
-}
-interface USDManipulationChangeEvent {
-  joint: USDJointInfo;
-  object: THREE.Object3D;
-  body0: THREE.Object3D | null;
-  value: number;
-  previousValue: number;
-}
-interface USDManipulationHoverEvent {
-  joint: USDJointInfo | null;
-  object: THREE.Object3D | null;
-}
-declare class USDManipulationControls {
-  private readonly raycaster;
-  private readonly pointer;
-  private readonly jointValues;
-  private readonly highlighted;
-  private activeDrag;
-  private hovered;
-  private modelStateSignature;
-  private _enabled;
-  private disposed;
-  scene: THREE.Scene;
-  camera: THREE.Camera;
-  domElement: HTMLElement;
-  controls: {
-    enabled: boolean;
-  } | null;
-  highlightColor: THREE.Color;
-  onChange?: (event: USDManipulationChangeEvent) => void;
-  onHoverChange?: (event: USDManipulationHoverEvent) => void;
-  constructor(options: USDManipulationControlsOptions);
-  get enabled(): boolean;
-  set enabled(value: boolean);
-  dispose(): void;
-  update(): void;
-  clearSelection(): void;
-  getJointValue(joint: USDJointInfo, root?: THREE.Object3D): number | undefined;
-  setJointValue(joint: USDJointInfo, value: number, root?: THREE.Object3D): boolean;
-  private readonly onPointerMove;
-  private readonly onPointerDown;
-  private readonly onPointerUp;
-  private pickJoint;
-  private updatePointer;
-  private syncModelState;
-  private endDrag;
-  private applyHighlight;
-  private restoreHighlight;
-}
-//#endregion
-//#region src/metadata.d.ts
-declare function extractUSDModelData(pxr: Pxr, stage: PxrObject, options?: ExtractUSDModelDataOptions): USDModelData;
+//#region src/scene-data.d.ts
+declare function extractUSDSceneData(pxr: Pxr, stage: PxrObject, options?: ExtractUSDSceneDataOptions): USDSceneData;
 //#endregion
-//#region src/three.d.ts
-declare function buildUSDObject(data: USDModelData, options?: BuildUSDObjectOptions): THREE.Group;
-declare function createUSDLoadedModel(data: USDModelData, pxr: USDLoadedModel['pxr'], rootLayerIdentifier: string, options?: BuildUSDObjectOptions, stage?: unknown): USDLoadedModel;
+//#region src/three/scene.d.ts
+declare function buildUSDScene(data: USDSceneData, options?: BuildUSDSceneOptions): USDSceneBuildResult;
+declare function createUSDLoadedModel(data: USDSceneData, pxr: USDLoadedModel['pxr'], rootLayerIdentifier: string, options?: BuildUSDSceneOptions, stage?: unknown, resources?: Partial<USDLoadedModelResources>): USDLoadedModel;
+declare function disposeUSDLoadedModel(model: USDLoadedModel): void;
 //#endregion
-export { type BuildUSDObjectOptions, type ExtractUSDModelDataOptions, type PxrObject, type USDAnimationInfo, type USDAssetValue, type USDFileExtension, type USDJointDriveInfo, type USDJointInfo, type USDLoadedModel, USDLoader, type USDLoaderOptions, type USDLoaderParseOptions, type USDManipulationChangeEvent, USDManipulationControls, type USDManipulationControlsOptions, type USDManipulationHoverEvent, type USDMaterialInfo, type USDMeshElement, type USDMeshGeometryData, type USDModelData, type USDShaderInfo, type USDSourceInput, type USDStageInfo, type USDTextureResolver, type USDTextureResolverContext, type USDTransformAnimation, type USDTransformAnimationSample, type USDVector2, type USDVector3, type USDVector4, type USDViewPrim, buildUSDObject, createUSDLoadedModel, extractUSDModelData };
+export { type BuildUSDSceneOptions, type ExtractUSDSceneDataOptions, type PxrObject, type USDAnimationInfo, type USDAssetValue, type USDFileExtension, type USDJointDriveInfo, type USDJointInfo, type USDJointLimitInfo, type USDLoadedModel, type USDLoadedModelResources, USDLoader, type USDLoaderOptions, type USDLoaderParseOptions, type USDMaterialInfo, type USDMeshElement, type USDMeshGeometryData, type USDParsedStageData, type USDPhysicsArticulationRootInfo, type USDPhysicsColliderInfo, type USDPhysicsInfo, type USDPhysicsMassInfo, type USDPhysicsMaterialInfo, type USDPhysicsRigidBodyInfo, type USDPhysicsSceneInfo, type USDSceneBuildResult, type USDSceneData, type USDSceneIndex, type USDShaderInfo, type USDSourceInput, type USDStageCameraInfo, type USDStageInfo, type USDTextureResolver, type USDTextureResolverContext, type USDTransformAnimation, type USDTransformAnimationSample, type USDUserData, type USDUserDataValue, type USDVariantSelection, type USDVariantSetInfo, type USDVector2, type USDVector3, type USDVector4, type USDViewPrim, buildUSDScene, createUSDLoadedModel, disposeUSDLoadedModel, extractUSDSceneData };