@openusd-wasm/three-loader 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 KeJun <https://github.com/kejunmao>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# @openusd-wasm/three-loader
+
+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`.
+
+```ts
+import createOpenUsdPxrWasm from '@openusd-wasm/core'
+import { wasmURL, workerURL } from '@openusd-wasm/core/urls'
+import { USDLoader } from '@openusd-wasm/three-loader'
+
+const loader = new USDLoader({
+  pxrOptions: {
+    core: createOpenUsdPxrWasm,
+    wasmURL,
+    workerURL,
+  },
+})
+
+const { scene, metadata } = await loader.loadAsync('/models/robot.usda')
+threeScene.add(scene)
+
+console.log(metadata.joints)
+```
+
+## Returned Data
+
+`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.
+- `sourcePath` and `rootLayerIdentifier`: useful for diagnostics and texture resolution.
+
+The same metadata is attached to the scene:
+
+```ts
+scene.userData.usdMetadata
+scene.userData.usdJoints
+scene.userData.usdObjectsByPath
+```
+
+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.
+
+## USDZ
+
+For USDZ packages, OpenUSD can often open the package path directly. If the
+package requires an explicit root layer, pass it when constructing or parsing:
+
+```ts
+const loader = new USDLoader({
+  pxr,
+  usdzLayer: 'robot.usda',
+})
+```
+
+The loader will open `file.usdz[robot.usda]` before falling back to `file.usdz`.
+
+## References
+
+For URL-based loads, the loader resolves same-origin relative USD references
+automatically before opening the stage. It scans the entry asset for referenced
+USD, image, and material paths, fetches those files recursively, and mirrors
+them into the same virtual filesystem directory that OpenUSD opens from.
+
+This handles common exported asset layouts where files reference extensionless
+assets like `./resource/material` while the server stores `material.usd`.
+When the entry layer references a known asset root, such as `resource/` or
+`textures/`, sibling references are also searched under that root. Use
+`assetSearchRoots` to configure additional pipeline-specific root folders,
+pass `files` to `parseAsync` for explicit virtual filesystem entries, or set
+`autoResolveAssets: false` to disable this behavior.
+
+## Textures
+
+USD asset paths do not always map directly to browser URLs. The loader creates
+object URLs for image files it auto-resolves and for image entries inside stored
+USDZ packages. Pass `textureResolver` to override or extend that mapping for
+custom asset systems.
+
+```ts
+const loader = new USDLoader({
+  pxr,
+  textureResolver(asset, context) {
+    if (asset.path) return new URL(asset.path, context.sourcePath).href
+    return null
+  },
+})
+```

package/dist/openusd_three_loader.d.ts

@@ -0,0 +1,243 @@
+import { Pxr } from "@openusd-wasm/pxr";
+import * as THREE from "three";
+import { Loader, LoadingManager } from "three";
+
+//#region src/types.d.ts
+type USDSourceInput = string | ArrayBuffer | ArrayBufferView | Blob;
+type USDFileExtension = 'usd' | 'usda' | 'usdc' | 'usdz';
+type USDVector2 = [number, number];
+type USDVector3 = [number, number, number];
+type USDVector4 = [number, number, number, number];
+interface USDStageInfo {
+  sourcePath: string;
+  rootLayerIdentifier: string;
+  defaultPrim: string | null;
+  upAxis: string;
+  startTimeCode?: number | null;
+  endTimeCode?: number | null;
+  timeCodesPerSecond?: number;
+}
+interface USDViewPrim {
+  path: string;
+  parentPath: string | null;
+  name: string;
+  typeName: string;
+  visibility: string;
+  localMatrix: number[] | null;
+  resetsXformStack: boolean;
+}
+interface USDMeshGeometryData {
+  positions: number[];
+  normals: number[];
+  uvs: number[];
+  displayColor: USDVector3 | null;
+  displayOpacity: number | null;
+}
+interface USDMeshElement {
+  path: string;
+  doubleSided: boolean;
+  material: string | null;
+  geometry: USDMeshGeometryData;
+}
+interface USDShaderInfo {
+  path: string;
+  id: string | null;
+  inputs: Record<string, unknown>;
+}
+interface USDMaterialInfo {
+  path: string;
+  inputs: Record<string, unknown>;
+  shaders: USDShaderInfo[];
+}
+interface USDJointDriveInfo {
+  targetPosition: number | null;
+  targetVelocity: number | null;
+  stiffness: number | null;
+  damping: number | null;
+  maxForce: number | null;
+}
+interface USDJointInfo {
+  path: string;
+  name: string;
+  typeName: string;
+  jointType: string;
+  body0: string | null;
+  body1: string | null;
+  axis: string | null;
+  localPos0: USDVector3;
+  localPos1: USDVector3;
+  localRot0: USDVector4 | null;
+  localRot1: USDVector4 | null;
+  lowerLimit: number | null;
+  upperLimit: number | null;
+  enabled: boolean;
+  drive: USDJointDriveInfo | null;
+  drives: Record<string, USDJointDriveInfo>;
+}
+interface USDTransformAnimationSample {
+  time: number;
+  localMatrix: number[];
+}
+interface USDTransformAnimation {
+  primPath: string;
+  samples: USDTransformAnimationSample[];
+}
+interface USDAnimationInfo {
+  startTimeCode: number;
+  endTimeCode: number;
+  timeCodesPerSecond: number;
+  transforms: USDTransformAnimation[];
+}
+interface USDModelData {
+  stage: USDStageInfo;
+  view: {
+    prims: USDViewPrim[];
+  };
+  elements: USDMeshElement[];
+  materials: USDMaterialInfo[];
+  joints: USDJointInfo[];
+  animations: USDAnimationInfo[];
+}
+interface USDLoadedModel {
+  scene: THREE.Group;
+  metadata: USDModelData;
+  stage?: unknown;
+  pxr: Pxr;
+  sourcePath: string;
+  rootLayerIdentifier: string;
+}
+interface ExtractUSDModelDataOptions {
+  sourcePath?: string;
+  rootLayerIdentifier?: string;
+}
+interface USDTextureResolverContext {
+  sourcePath: string;
+  material?: USDMaterialInfo;
+  shader?: USDShaderInfo;
+}
+interface USDAssetValue {
+  path?: string;
+  resolvedPath?: string;
+  url?: string;
+}
+type USDTextureResolver = (asset: USDAssetValue, context: USDTextureResolverContext) => string | null | undefined;
+interface BuildUSDObjectOptions {
+  sourcePath?: string;
+  convertZUp?: boolean;
+  loadTextures?: boolean;
+  textureResolver?: USDTextureResolver;
+  textureLoader?: THREE.TextureLoader;
+  textureCache?: Map<string, THREE.Texture>;
+}
+interface USDLoaderParseOptions extends BuildUSDObjectOptions {
+  sourcePath?: string;
+  fileName?: string;
+  files?: Record<string, USDSourceInput>;
+  autoResolveAssets?: boolean;
+  assetSearchExtensions?: string[];
+  assetSearchRoots?: string[];
+  maxAssetReferences?: number;
+  maxAssetReferenceDepth?: number;
+  workingDirectory?: string;
+  usdzLayer?: string;
+  preserveStage?: boolean;
+  cleanupAfterParse?: boolean;
+}
+interface USDLoaderOptions extends BuildUSDObjectOptions {
+  pxr?: Pxr | Promise<Pxr>;
+  pxrOptions?: Parameters<typeof import('@openusd-wasm/pxr').createPxr>[0];
+  workingDirectory?: string;
+  assetSearchRoots?: string[];
+  usdzLayer?: string;
+  preserveStage?: boolean;
+  cleanupAfterParse?: boolean;
+}
+type PxrObject = Record<string, any> & {
+  delete?: () => void;
+};
+//#endregion
+//#region src/loader.d.ts
+declare class USDLoader extends Loader<USDLoadedModel, string> {
+  private options;
+  private pxrPromise;
+  constructor(manager?: LoadingManager);
+  constructor(options?: USDLoaderOptions, manager?: LoadingManager);
+  setPxr(pxr: Pxr | Promise<Pxr>): this;
+  setUSDZLayer(layer: string): this;
+  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;
+  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;
+//#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;
+//#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 };