usd-gltf 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard Monette
+
+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

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# usd-gltf
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Convert between [OpenUSD](https://openusd.org/) and [glTF](https://www.khronos.org/gltf/) in both directions, in pure JavaScript with no dependencies. Runs in Node and the browser, [live demo](https://richardmonette.github.io/usd-gltf/examples/). Reads and writes all three USD encodings: text `.usda`, binary crate `.usdc`, and the `.usdz` package.
+
+```
+npm install usd-gltf
+```
+
+```js
+import { usdToGLB, glbToUSD } from 'usd-gltf';
+
+const glb = await usdToGLB( usdzBytes );
+const usdz = await glbToUSD( glbBytes ); // or { format: 'usda' } / { format: 'usdc' }
+```
+
+Files that reference other files (a `.gltf` with `.bin` and textures, or a `.usda` with sublayers and references) need a `resolver` that returns the bytes for a relative path:
+
+```js
+const usdz = await glbToUSD( gltfBytes, { resolver: ( uri ) => readFile( join( dir, uri ) ) } );
+```
+
+```
+npx usd-gltf model.usdz model.glb
+npx usd-gltf model.glb model.usdz
+```
+
+## What converts
+
+USD to glTF composes the stage first (sublayers, references, payloads, inherits, specializes, variant sets) and then converts:
+
+- Xform hierarchies, every xformOp type, animated transforms, up axis and `metersPerUnit`
+- Meshes with any primvar interpolation, indexed primvars, GeomSubsets, holes and left handed orientation; Points, BasisCurves and the intrinsic shapes
+- `UsdPreviewSurface` networks and MaterialX graphs built from `ND_UsdPreviewSurface`, `ND_standard_surface` and `ND_open_pbr_surface`, with textures repacked when glTF needs a different channel layout
+- UsdSkel skeletons, skinning and blend shapes
+- Material variant sets as `KHR_materials_variants`, animation variant sets as separate glTF animations
+- Cameras, UsdLux lights as `KHR_lights_punctual`, PointInstancers
+
+glTF to USD writes `UsdPreviewSurface` materials, UsdSkel skins and blend shapes, time sampled animation, variant sets for material variants and multiple animations, cameras and lights. glTF features that `UsdPreviewSurface` can't express (transmission, sheen, iridescence, ...) are kept in the material's `customData`, so converting back to glTF is lossless.
+
+## Conformance
+
+Current status:
+
+- All 18 USD files in Apple's AR Quick Look gallery convert to GLB. Per mesh triangle counts and world space bounds at the start, middle and end of each animation match OpenUSD with skinning baked, and the Khronos glTF Validator reports no errors. (The gallery's three `.reality` files are RealityKit's format, not USD.)
+- All 150 Khronos glTF sample models convert to USDZ that OpenUSD's validators accept with no errors or warnings, with geometry matching the source at several animation times, and convert back to glTF with identical materials, material variants and animations.
+
+The acceptance corpora are every model in [Apple's AR Quick Look gallery](https://developer.apple.com/augmented-reality/quick-look/) and every model in the [Khronos glTF Sample Assets](https://github.com/KhronosGroup/glTF-Sample-Assets). Conversions are checked against Pixar's OpenUSD (`usd-core`) and the Khronos glTF Validator: per mesh triangle counts and world space bounds at several animation times, with skinning baked by OpenUSD, must match.
+
+To run it locally (needs Python with `pip install usd-core`, in a `.venv` here or on `PATH`):
+
+```
+npm run fetch-corpus
+npm run conformance
+```
+
+The [Conformance workflow](.github/workflows/conformance.yml) runs the same check in CI.
+
+## License
+
+MIT

package/bin/usd-gltf.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, extname, resolve } from 'node:path';
+import { detectFormat, usdToGLB, glbToUSD } from '../src/index.js';
+
+const [ input, output ] = process.argv.slice( 2 );
+
+if ( ! input || ! output ) {
+
+	console.error( 'usage: usd-gltf <input.usd[a|c|z]|input.glb|input.gltf> <output.glb|output.usd[a|c|z]>' );
+	process.exit( 1 );
+
+}
+
+const data = await readFile( input );
+const from = detectFormat( data );
+const to = extname( output ).slice( 1 ).toLowerCase();
+
+// files referenced by relative paths (gltf buffers and textures, usd sublayers and references)
+const dir = dirname( resolve( input ) );
+const resolver = ( path ) => readFile( resolve( dir, path ) );
+const log = ( message ) => console.warn( `warning: ${ message }` );
+
+let result;
+
+try {
+
+	if ( from === 'usda' || from === 'usdc' || from === 'usdz' ) {
+
+		if ( to !== 'glb' ) throw new Error( `cannot write .${ to } from USD, use .glb` );
+		result = await usdToGLB( data, { identifier: resolve( input ).replace( /\\/g, '/' ), resolver, log } );
+
+	} else if ( from === 'glb' || from === 'gltf' ) {
+
+		const format = to === 'usd' ? 'usdc' : to;
+		if ( format !== 'usda' && format !== 'usdc' && format !== 'usdz' ) throw new Error( `cannot write .${ to } from glTF, use .usda, .usdc or .usdz` );
+		result = await glbToUSD( data, { format, resolver, log } );
+
+	} else {
+
+		throw new Error( `${ basename( input ) } is not a USD or glTF file` );
+
+	}
+
+} catch ( e ) {
+
+	console.error( `usd-gltf: ${ e.message.replace( /^usd-gltf: /, '' ) }` );
+	process.exit( 1 );
+
+}
+
+await writeFile( output, result );

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "usd-gltf",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Convert between USD (usda, usdc, usdz) and glTF / GLB, pure JavaScript with no dependencies",
+  "type": "module",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "bin": {
+    "usd-gltf": "bin/usd-gltf.js"
+  },
+  "files": [
+    "src",
+    "bin"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "conformance": "node scripts/conformance.js",
+    "fetch-corpus": "node scripts/fetch-corpus.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "usd",
+    "usda",
+    "usdc",
+    "usdz",
+    "openusd",
+    "gltf",
+    "glb",
+    "converter",
+    "3d"
+  ],
+  "author": "Richard Monette",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/richardmonette/usd-gltf.git"
+  },
+  "bugs": {
+    "url": "https://github.com/richardmonette/usd-gltf/issues"
+  },
+  "homepage": "https://github.com/richardmonette/usd-gltf#readme",
+  "devDependencies": {
+    "gltf-validator": "^2.0.0-dev.3.10",
+    "meshoptimizer": "^1.3.0"
+  },
+  "types": "src/index.d.ts"
+}