usd-gltf 0.2.0 → 0.3.0

package/README.md

@@ -37,7 +37,20 @@ USD to glTF composes the stage first (sublayers, references, payloads, inherits,
 
 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. Primitives of a mesh that share their vertex data become one USD Mesh with a GeomSubset per primitive, and each Mesh keeps only the vertices it uses, so vertex data is never repeated per primitive.
 
-glTF compression: meshopt (`EXT_meshopt_compression`, `KHR_meshopt_compression`) and `KHR_mesh_quantization` are decoded. Draco (`KHR_draco_mesh_compression`) and KTX2 textures (`KHR_texture_basisu`) are not: when an asset lists them in `extensionsRequired` the conversion fails with an error naming them, and when they are optional the uncompressed fallback data is used.
+glTF compression: meshopt (`EXT_meshopt_compression`, `KHR_meshopt_compression`), `KHR_mesh_quantization` and Draco (`KHR_draco_mesh_compression`, see below) are decoded. KTX2 textures (`KHR_texture_basisu`) are not: an asset that requires them fails with an error naming the extension, and when they are optional the PNG or JPEG fallback is used.
+
+### Draco
+
+usd-gltf doesn't bundle a Draco decoder; it loads Google's only when a file is Draco compressed, and uses the uncompressed fallback without loading anything when a file has one.
+
+- **Node:** install [`draco3d`](https://www.npmjs.com/package/draco3d) alongside, an optional peer dependency, and Draco files just work: `npm install draco3d`.
+- **Browsers:** the decoder (about 250 KB) is fetched from Google's CDN, `www.gstatic.com/draco/versioned/decoders/1.5.7/`, pinned to that version and checked against its SHA-256 before it runs. This needs a secure context, and a Content Security Policy that allows the fetch, `unsafe-eval` and WebAssembly.
+- **Your own:** pass a decoder module as `dracoDecoder` to use a self hosted copy, or where the CDN isn't allowed:
+
+```js
+import draco3d from 'draco3d';
+const usdz = await glbToUSD( glb, { dracoDecoder: await draco3d.createDecoderModule() } );
+```
 
 ## Limits
 
@@ -62,7 +75,7 @@ Going over a limit rejects with a `ConversionLimitError` whose `stage`, `resourc
 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. Each model is checked as `.gltf`, and also as `.glb` (120 models) and embedded `.gltf` (32 models) where the sample set has those versions: 302 conversions in all.
+- 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. Each model is checked as `.gltf`, and also as `.glb` (120 models), embedded `.gltf` (32 models) and Draco compressed (16 models) where the sample set has those versions: 318 conversions in all.
 
 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "usd-gltf",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Convert between USD (usda, usdc, usdz) and glTF / GLB, pure JavaScript with no dependencies",
   "type": "module",
   "main": "src/index.js",
@@ -35,7 +35,8 @@
     "gltf",
     "glb",
     "converter",
-    "3d"
+    "3d",
+    "draco"
   ],
   "author": "Richard Monette",
   "license": "MIT",
@@ -47,7 +48,16 @@
     "url": "https://github.com/richardmonette/usd-gltf/issues"
   },
   "homepage": "https://github.com/richardmonette/usd-gltf#readme",
+  "peerDependencies": {
+    "draco3d": "^1.5.7"
+  },
+  "peerDependenciesMeta": {
+    "draco3d": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "draco3d": "^1.5.7",
     "gltf-validator": "^2.0.0-dev.3.10",
     "meshoptimizer": "^1.3.0"
   },

package/src/gltf/document.js

@@ -2,6 +2,7 @@
 
 import { readGLB, writeGLB } from './glb.js';
 import { decodeMeshoptView } from './meshopt.js';
+import { decodeDracoPrimitive, loadDracoDecoder, needsDraco } from './draco.js';
 import { Budget, checkSize } from '../limits.js';
 
 const COMPONENT_ARRAYS = {
@@ -18,13 +19,13 @@ export const TYPE_SIZES = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT2: 4, MAT3:
 // Extensions an asset may require. Material extensions without a UsdPreviewSurface equivalent are
 // approximated and kept on the USD material for the way back, so every KHR_materials_* is accepted.
 const SUPPORTED_EXTENSIONS = new Set( [
-	'EXT_mesh_gpu_instancing', 'EXT_meshopt_compression', 'KHR_meshopt_compression', 'KHR_mesh_quantization',
+	'EXT_mesh_gpu_instancing', 'EXT_meshopt_compression', 'KHR_meshopt_compression', 'KHR_mesh_quantization', 'KHR_draco_mesh_compression',
 	'EXT_texture_webp', 'EXT_texture_avif', 'KHR_texture_transform', 'KHR_animation_pointer', 'KHR_lights_punctual',
 	'KHR_node_visibility', 'KHR_xmp_json_ld',
 ] );
 
 /**
- * The asset's required extensions that can't be converted (e.g. KHR_draco_mesh_compression, KHR_texture_basisu).
+ * The asset's required extensions that can't be converted (e.g. KHR_texture_basisu).
  * @param {object} json
  * @returns {string[]}
  */
@@ -34,24 +35,6 @@ export function unsupportedExtensions( json ) {
 
 }
 
-// Optional Draco needs uncompressed fallback data: without a bufferView or sparse values the
-// accessors would read as zeros.
-function checkDracoFallbacks( json ) {
-
-	( json.meshes || [] ).forEach( ( mesh, m ) => mesh.primitives.forEach( ( primitive, p ) => {
-
-		if ( ! primitive.extensions?.KHR_draco_mesh_compression ) return;
-		const used = [ ...Object.values( primitive.attributes ), primitive.indices ].filter( ( a ) => a !== undefined );
-		if ( used.some( ( a ) => json.accessors[ a ].bufferView === undefined && ! json.accessors[ a ].sparse ) ) {
-
-			throw new Error( `usd-gltf: mesh ${ m } primitive ${ p } is Draco compressed with no uncompressed fallback; KHR_draco_mesh_compression is not supported` );
-
-		}
-
-	} ) );
-
-}
-
 function decodeDataURI( uri ) {
 
 	const comma = uri.indexOf( ',' );
@@ -84,6 +67,7 @@ export class GLTFDocument {
 		this.budget = budget;
 		this.accessorCache = new Map();
 		this.decodedViews = new Map(); // bufferView index -> bytes, for compressed views
+		this.decodedAccessors = new Map(); // accessor index -> data, for Draco compressed primitives
 
 	}
 
@@ -139,8 +123,9 @@ export class GLTFDocument {
 
 		}
 
-		this.budget.decode( size, stage );
-		let array = new ArrayType( count * itemSize );
+		const decoded = accessor.bufferView === undefined ? this.decodedAccessors.get( index ) : undefined; // charged when decoded
+		if ( ! decoded ) this.budget.decode( size, stage );
+		let array = decoded || new ArrayType( count * itemSize );
 
 		if ( read ) {
 
@@ -230,9 +215,9 @@ export class GLTFDocument {
 /**
  * Loads a glTF or GLB.
  * @param {Uint8Array} bytes
- * @param {{ resolver?: ( uri: string ) => Promise<Uint8Array>|Uint8Array }} [options] loads external uris (already decoded from URI escaping)
+ * @param {{ resolver?: ( uri: string ) => Promise<Uint8Array>|Uint8Array, dracoDecoder?: object|Promise<object> }} [options] resolver loads external uris (already decoded from URI escaping); dracoDecoder is a Draco decoder module, loaded when needed if not given
  */
-export async function readGLTF( bytes, { resolver = null, budget = new Budget() } = {} ) {
+export async function readGLTF( bytes, { resolver = null, budget = new Budget(), dracoDecoder = null } = {} ) {
 
 	let json, bin = null;
 	bytes = plainBytes( bytes );
@@ -242,7 +227,6 @@ export async function readGLTF( bytes, { resolver = null, budget = new Budget()
 
 	const unsupported = unsupportedExtensions( json );
 	if ( unsupported.length ) throw new Error( `usd-gltf: required extension${ unsupported.length > 1 ? 's' : '' } ${ unsupported.join( ', ' ) } not supported` );
-	checkDracoFallbacks( json );
 
 	async function load( uri ) {
 
@@ -283,6 +267,23 @@ export async function readGLTF( bytes, { resolver = null, budget = new Budget()
 
 	} );
 
+	// Draco primitives without uncompressed fallback data
+	const draco = ( json.meshes || [] ).flatMap( ( mesh ) => mesh.primitives ).filter( ( p ) => needsDraco( json, p ) );
+
+	if ( draco.length ) {
+
+		const decoder = await ( dracoDecoder || loadDracoDecoder() );
+
+		for ( const primitive of draco ) {
+
+			budget.check();
+			const bytes = doc.bufferViewBytes( primitive.extensions.KHR_draco_mesh_compression.bufferView );
+			for ( const [ index, data ] of decodeDracoPrimitive( decoder, bytes, json, primitive, budget ) ) doc.decodedAccessors.set( index, data );
+
+		}
+
+	}
+
 	doc.images = await Promise.all( ( json.images || [] ).map( async ( image ) => {
 
 		if ( image.bufferView !== undefined ) return { bytes: doc.bufferViewBytes( image.bufferView ), mimeType: image.mimeType, name: image.name, uri: null };

package/src/gltf/draco.js

@@ -0,0 +1,191 @@
+// KHR_draco_mesh_compression, decoded with Google's Draco decoder, which usd-gltf doesn't bundle.
+// The decoder is the dracoDecoder option when given; otherwise the draco3d package in Node (an
+// optional peer dependency), or in browsers Google's CDN build, pinned to one version and checked
+// against its hash before it runs. Only loaded when a file needs it.
+// https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_draco_mesh_compression
+
+const CDN = 'https://www.gstatic.com/draco/versioned/decoders/1.5.7/';
+const CDN_FILES = {
+	'draco_wasm_wrapper_gltf.js': 'i7KVLSun1n4UFPjfgZQQywQ0pma+U/Zx//dfaIQ9dvY=',
+	'draco_decoder_gltf.wasm': 'cS2zRJriBB1uiiJMOVvabO20nlEyL644t9ub64s4GIk=',
+};
+
+const DATA_TYPES = { 5120: 'DT_INT8', 5121: 'DT_UINT8', 5122: 'DT_INT16', 5123: 'DT_UINT16', 5125: 'DT_UINT32', 5126: 'DT_FLOAT32' };
+const COMPONENT_ARRAYS = { 5120: Int8Array, 5121: Uint8Array, 5122: Int16Array, 5123: Uint16Array, 5125: Uint32Array, 5126: Float32Array };
+const TYPE_SIZES = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT2: 4, MAT3: 9, MAT4: 16 };
+
+let defaultDecoder = null;
+
+/**
+ * The default Draco decoder module: draco3d in Node, Google's CDN in browsers. Loaded once.
+ * @returns {Promise<object>}
+ */
+export function loadDracoDecoder() {
+
+	defaultDecoder ||= ( isNode() ? loadNode() : loadDracoFromCDN() ).catch( ( e ) => {
+
+		defaultDecoder = null; // let a later conversion try again
+		throw e;
+
+	} );
+
+	return defaultDecoder;
+
+}
+
+function isNode() {
+
+	return typeof process !== 'undefined' && !! process.versions?.node;
+
+}
+
+async function loadNode() {
+
+	const name = 'draco3d'; // not a literal, so bundlers don't try to include it
+	let draco3d;
+
+	try {
+
+		draco3d = await import( /* webpackIgnore: true */ /* @vite-ignore */ name );
+
+	} catch {
+
+		throw new Error( 'usd-gltf: this glTF is Draco compressed; install the decoder with npm install draco3d, or pass a dracoDecoder' );
+
+	}
+
+	return ( draco3d.default ?? draco3d ).createDecoderModule();
+
+}
+
+// Exported for tests; loadDracoDecoder picks the source.
+export async function loadDracoFromCDN() {
+
+	if ( ! globalThis.crypto?.subtle ) throw new Error( 'usd-gltf: loading the Draco decoder needs a secure context (https) to check it; pass a dracoDecoder instead' );
+	const [ wrapper, wasm ] = await Promise.all( Object.keys( CDN_FILES ).map( fetchVerified ) );
+	// the wrapper is a classic script defining DracoDecoderModule, so it can't be imported as a module
+	const factory = new Function( new TextDecoder().decode( wrapper ) + '\nreturn DracoDecoderModule;' )();
+	return factory( { wasmBinary: wasm.buffer } );
+
+}
+
+async function fetchVerified( name ) {
+
+	const response = await fetch( CDN + name );
+	if ( ! response.ok ) throw new Error( `usd-gltf: could not load the Draco decoder (${ response.status } for ${ CDN + name })` );
+	const bytes = new Uint8Array( await response.arrayBuffer() );
+	const digest = new Uint8Array( await crypto.subtle.digest( 'SHA-256', bytes ) );
+	if ( btoa( String.fromCharCode( ...digest ) ) !== CDN_FILES[ name ] ) throw new Error( `usd-gltf: ${ CDN + name } doesn't match its expected hash` );
+	return bytes;
+
+}
+
+/**
+ * Whether a primitive's data is only in its Draco extension: Draco is decoded only when the
+ * accessors have no uncompressed fallback.
+ */
+export function needsDraco( json, primitive ) {
+
+	if ( ! primitive.extensions?.KHR_draco_mesh_compression ) return false;
+	const used = [ ...Object.values( primitive.attributes ), primitive.indices ].filter( ( a ) => a !== undefined );
+	return used.some( ( a ) => json.accessors[ a ]?.bufferView === undefined && ! json.accessors[ a ]?.sparse );
+
+}
+
+/**
+ * Decodes one Draco compressed primitive into the data of the accessors it describes.
+ * @param {object} draco decoder module
+ * @param {Uint8Array} bytes the extension's bufferView
+ * @param {object} json
+ * @param {object} primitive
+ * @param {import('../limits.js').Budget} budget
+ * @returns {Map<number, ArrayLike<number>>} accessor index -> data, in the accessor's component type
+ */
+export function decodeDracoPrimitive( draco, bytes, json, primitive, budget ) {
+
+	const ext = primitive.extensions.KHR_draco_mesh_compression;
+	const decoder = new draco.Decoder();
+	const array = new Int8Array( bytes.buffer, bytes.byteOffset, bytes.byteLength );
+	const out = new Map();
+	let geometry = null;
+
+	try {
+
+		const type = decoder.GetEncodedGeometryType( array );
+		let status;
+
+		if ( type === draco.TRIANGULAR_MESH ) {
+
+			geometry = new draco.Mesh();
+			status = decoder.DecodeArrayToMesh( array, array.byteLength, geometry );
+
+		} else if ( type === draco.POINT_CLOUD ) {
+
+			geometry = new draco.PointCloud();
+			status = decoder.DecodeArrayToPointCloud( array, array.byteLength, geometry );
+
+		} else {
+
+			throw new Error( 'usd-gltf: Draco data is neither a mesh nor a point cloud' );
+
+		}
+
+		if ( ! status.ok() || geometry.ptr === 0 ) throw new Error( `usd-gltf: Draco decoding failed: ${ status.error_msg() }` );
+
+		const points = geometry.num_points();
+
+		for ( const [ name, id ] of Object.entries( ext.attributes ) ) {
+
+			const index = primitive.attributes[ name ];
+			const accessor = json.accessors[ index ];
+			if ( accessor === undefined ) continue;
+			const ArrayType = COMPONENT_ARRAYS[ accessor.componentType ];
+			const size = TYPE_SIZES[ accessor.type ];
+			const attribute = decoder.GetAttributeByUniqueId( geometry, id );
+			if ( ! ArrayType || ! size || ! attribute || attribute.ptr === 0 ) throw new Error( `usd-gltf: Draco data has no ${ name } attribute ${ id }` );
+			if ( points !== accessor.count || attribute.num_components() !== size ) throw new Error( `usd-gltf: Draco ${ name } doesn't match accessor ${ index }` );
+			out.set( index, read( draco, points * size, ArrayType, budget, ( length, ptr ) => decoder.GetAttributeDataArrayForAllPoints( geometry, attribute, draco[ DATA_TYPES[ accessor.componentType ] ], length, ptr ) ) );
+
+		}
+
+		if ( primitive.indices !== undefined && type === draco.TRIANGULAR_MESH ) {
+
+			const accessor = json.accessors[ primitive.indices ];
+			const count = geometry.num_faces() * 3;
+			if ( ! accessor || accessor.count !== count ) throw new Error( `usd-gltf: Draco indices don't match accessor ${ primitive.indices }` );
+			const indices = read( draco, count, Uint32Array, budget, ( length, ptr ) => decoder.GetTrianglesUInt32Array( geometry, length, ptr ) );
+			const IndexType = COMPONENT_ARRAYS[ accessor.componentType ] || Uint32Array;
+			out.set( primitive.indices, IndexType === Uint32Array ? indices : IndexType.from( indices ) );
+
+		}
+
+	} finally {
+
+		if ( geometry ) draco.destroy( geometry );
+		draco.destroy( decoder );
+
+	}
+
+	return out;
+
+}
+
+// Has the decoder fill a buffer on its heap, then copies it out.
+function read( draco, count, ArrayType, budget, fill ) {
+
+	const length = count * ArrayType.BYTES_PER_ELEMENT;
+	budget.decode( length, 'draco' );
+	const ptr = draco._malloc( length );
+
+	try {
+
+		if ( ! fill( length, ptr ) ) throw new Error( 'usd-gltf: Draco attribute could not be read' );
+		return new ArrayType( draco.HEAPF32.buffer, ptr, count ).slice();
+
+	} finally {
+
+		draco._free( ptr );
+
+	}
+
+}

package/src/index.d.ts

@@ -53,6 +53,11 @@ export interface GLBToUSDOptions extends ConversionLimits {
 	format?: 'usdz' | 'usda' | 'usdc';
 	/** Needed for .gltf files with external buffers or images. */
 	resolver?: Resolver;
+	/**
+	 * A Draco decoder module (from draco3d's createDecoderModule, or Google's decoder build), or a
+	 * promise of one. Without it, Draco files load draco3d in Node and Google's CDN build in browsers.
+	 */
+	dracoDecoder?: object | Promise<object>;
 	imageDecoder?: ImageDecoder;
 	log?: ( message: string ) => void;
 }

package/src/index.js

@@ -50,13 +50,13 @@ export async function usdToGLB( data, options = {} ) {
 /**
  * Converts GLB (or glTF JSON with embedded or resolvable buffers) to USD.
  * @param {ArrayBuffer|Uint8Array} data
- * @param {{ format?: 'usda'|'usdc'|'usdz', resolver?: ( uri: string ) => Promise<Uint8Array>, maxDecodedBytes?: number, maxOutputBytes?: number, signal?: AbortSignal }} [options]
+ * @param {{ format?: 'usda'|'usdc'|'usdz', resolver?: ( uri: string ) => Promise<Uint8Array>, dracoDecoder?: object, maxDecodedBytes?: number, maxOutputBytes?: number, signal?: AbortSignal }} [options]
  * @returns {Promise<Uint8Array>}
  */
-export async function glbToUSD( data, { format = 'usdz', resolver = null, log, imageDecoder, ...limits } = {} ) {
+export async function glbToUSD( data, { format = 'usdz', resolver = null, log, imageDecoder, dracoDecoder, ...limits } = {} ) {
 
 	const budget = budgetFor( limits );
-	const doc = await readGLTF( toBytes( data ), { resolver, budget } );
+	const doc = await readGLTF( toBytes( data ), { resolver, budget, dracoDecoder } );
 	const { layer, files } = await new GLTFToUSD( doc, { log, imageDecoder } ).convert();
 	let out;
 
@@ -73,10 +73,10 @@ export async function glbToUSD( data, { format = 'usdz', resolver = null, log, i
  * For usda / usdc output the textures are separate files; this returns them alongside the layer.
  * @returns {Promise<{ layer: Uint8Array, files: Array<{ name: string, data: Uint8Array }> }>}
  */
-export async function glbToUSDFiles( data, { format = 'usda', resolver = null, log, imageDecoder, ...limits } = {} ) {
+export async function glbToUSDFiles( data, { format = 'usda', resolver = null, log, imageDecoder, dracoDecoder, ...limits } = {} ) {
 
 	const budget = budgetFor( limits );
-	const doc = await readGLTF( toBytes( data ), { resolver, budget } );
+	const doc = await readGLTF( toBytes( data ), { resolver, budget, dracoDecoder } );
 	const { layer, files } = await new GLTFToUSD( doc, { log, imageDecoder } ).convert();
 	const bytes = format === 'usdc' ? writeUSDC( layer, { budget } ) : new TextEncoder().encode( writeUSDA( layer, { budget } ) );
 	budget.output( files.reduce( ( n, f ) => n + f.data.byteLength, bytes.byteLength ), 'usd files' );