@openusd-wasm/pxr

Community ESM facade for OpenUSD pxr WebAssembly bindings.

This package is the high-level facade. It follows the ffmpeg.wasm loading style: create an instance, then load the WebAssembly runtime.

Use PXR.load():

import { PXR } from '@openusd-wasm/pxr'

const pxr = new PXR()
await pxr.load()

The default package resolves its own WebAssembly JavaScript, .wasm, and worker assets. No core object or URL is needed for normal usage.

For advanced custom hosting or CDN usage only, pass the directory that contains openusd_pxr_wasm.js and openusd_pxr_wasm.wasm:

const pxr = new PXR()
await pxr.load({
  baseURL: 'https://cdn.example.com/@openusd-wasm/core/dist/',
})

In a Next.js Client Component, keep initialization behind a client-only module and reuse one instance:

'use client'

import { PXR, type Pxr } from '@openusd-wasm/pxr'

let pxrPromise: Promise<Pxr> | null = null

export function getClientPxr(): Promise<Pxr> {
  pxrPromise ??= new PXR().load()
  return pxrPromise
}

Some Next.js/Turbopack builds expose package asset URLs as internal file:///_next/... URLs. @openusd-wasm/core/urls normalizes those values back to browser-loadable /_next/... URLs before PXR.load() uses them.

The published core is built with WebAssembly pthreads, so browser usage also requires a cross-origin isolated page. Configure these headers in next.config.js:

const nextConfig = {
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          { key: 'Cross-Origin-Opener-Policy', value: 'same-origin' },
          { key: 'Cross-Origin-Embedder-Policy', value: 'require-corp' },
          { key: 'Cross-Origin-Resource-Policy', value: 'same-origin' },
        ],
      },
    ]
  },
}

export default nextConfig

Restart the Next.js dev server after changing these headers. Without them, worker startup can fail with browser-reported errors such as worker sent an error! undefined:undefined: undefined.

The returned namespace exposes Gf, Sdf, Usd, UsdGeom, UsdPhysics, UsdSkel, UsdShade, UsdUtils, and FS helpers for the virtual filesystem.

API shape

The facade is an OpenUSD pxr binding, so exposed APIs keep pxr-style module, class, and method names where possible. For example:

const stage = pxr.Usd.Stage.CreateInMemory('scene.usda')
const path = new pxr.Sdf.Path('/World/Joint')
const prim = stage.DefinePrim(path, 'PhysicsRevoluteJoint')

const joint = new pxr.UsdPhysics.RevoluteJoint(prim)
const axisAttr = joint.GetAxisAttr()

Wrapped objects own Wasm-side handles. Call delete() when you are done with objects, or use the installed using() helper for short scopes.

Current binding surface

This package is actively expanding toward broader pxr coverage. The current surface includes:

• Gf: vectors, matrices, quaternions, ranges, and bounding boxes used by the existing USD bindings.
• Sdf: paths, asset paths, layers, prim specs, value type names, and common layer dependency helpers.
• Usd: stages, prims, attributes, relationships, references, payloads, and time codes.
• UsdGeom: xforms, meshes, analytic Gprims (Cube, Sphere, Cylinder, Cylinder_1, Cone, Capsule, Capsule_1, and Plane), native triangulation, xform ops, primvars, PrimvarsAPI, cameras, stage metrics/up-axis helpers, tokens, and BBoxCache.
• UsdShade: materials, shaders, inputs, outputs, connectable APIs, material binding, source asset helpers, shader IDs, and tokens.
• UsdPhysics: collision, mesh collision, rigid-body, mass, and material APIs, joint schemas, fixed/revolute/prismatic/spherical/distance joints, limits, body relationships, local joint frames, and DriveAPI.
• UsdSkel: skeleton roots, skeletons, skel animations, binding API accessors, joint transforms, and skinning primvars.
• UsdUtils: external reference/dependency extraction, USDZ packaging, localization, and asset path modification helpers.

Not wrapped yet

The following areas still need JS-safe wrappers or schema-driven expansion.

Gf

• Camera, Rotation, and non-4d matrix variants need value conversion coverage before exposing.
• Line, plane, frustum, interval, and dual quaternion helpers are deferred until their dependent value types are bound.

Sdf

• AttributeSpec and RelationshipSpec mutation proxies are deferred because list/proxy lifetimes need JS-safe wrappers.
• ChangeBlock, LayerOffset, Reference/Payload value classes, VariantSpec, and VariantSetSpec APIs are deferred to the next Sdf expansion.

Usd

• EditTarget/EditContext, StageCache, StagePopulationMask, StageLoadRules, VariantSets, and PrimRange iterator objects are not wrapped yet.
• Generated Usd schema class coverage beyond concrete schema registration is deferred to schema-driven generation.

UsdGeom

• PointInstancer, curves, points, Imageable, additional BBoxCache overrides, and typed-array zero-copy bridges are deferred.

UsdPhysics

• Physics schema coverage beyond the exposed API/joint classes is deferred to schema-driven generation.
• Parsing utilities and metrics helpers are deferred to the next physics expansion.

UsdShade

• NodeGraph, shader registry, shader definition parsing, and deeper connectable-interface utilities are deferred to the next shading expansion.

UsdLux, UsdRender, UsdVol, and related modules

• These modules are not exposed yet. They need module resources, schema type registration, C++ wrappers, and TypeScript namespace mappings.

UsdUtils

• StageCache, SparseValueWriter, Stitch, StitchClips, FlattenLayerStack, TimeCodeRange, and compliance helpers are deferred.