@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.

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:

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:

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.

When generating USDA files that reference assets written next to the layer, use toLayerRelativeAssetPath before authoring the reference. OpenUSD treats @assets/model.usdz@ as a search-path asset, while @./assets/model.usdz@ is anchored to the current layer directory and packages without transient 0/model.usdz remap warnings.

import { toLayerRelativeAssetPath } from '@openusd-wasm/utils'

refs.AddReference(toLayerRelativeAssetPath('assets/gearbox.usdz'), '')

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.

const loader = new USDLoader({
  pxr,
  textureResolver(asset, context) {
    if (asset.path) return new URL(asset.path, context.sourcePath).href
    return null
  },
})