usd-gltf 0.1.0 → 0.2.0

package/src/gltf/document.js

@@ -2,6 +2,7 @@
 
 import { readGLB, writeGLB } from './glb.js';
 import { decodeMeshoptView } from './meshopt.js';
+import { Budget, checkSize } from '../limits.js';
 
 const COMPONENT_ARRAYS = {
 	5120: Int8Array,
@@ -14,6 +15,43 @@ const COMPONENT_ARRAYS = {
 
 export const TYPE_SIZES = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT2: 4, MAT3: 9, MAT4: 16 };
 
+// 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_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).
+ * @param {object} json
+ * @returns {string[]}
+ */
+export function unsupportedExtensions( json ) {
+
+	return ( json.extensionsRequired || [] ).filter( ( name ) => ! SUPPORTED_EXTENSIONS.has( name ) && ! name.startsWith( 'KHR_materials_' ) );
+
+}
+
+// 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( ',' );
@@ -38,11 +76,12 @@ function decodeDataURI( uri ) {
  */
 export class GLTFDocument {
 
-	constructor( json, buffers, images ) {
+	constructor( json, buffers, images, budget = new Budget() ) {
 
 		this.json = json;
 		this.buffers = buffers; // Uint8Array per json.buffers entry
 		this.images = images; // { bytes, mimeType, name } per json.images entry
+		this.budget = budget;
 		this.accessorCache = new Map();
 		this.decodedViews = new Map(); // bufferView index -> bytes, for compressed views
 
@@ -52,9 +91,11 @@ export class GLTFDocument {
 
 		const decoded = this.decodedViews.get( index );
 		if ( decoded ) return decoded;
-		const view = this.json.bufferViews[ index ];
-		const buffer = this.buffers[ view.buffer ];
-		return buffer.subarray( view.byteOffset || 0, ( view.byteOffset || 0 ) + view.byteLength );
+		const view = this.json.bufferViews?.[ index ];
+		const buffer = view && this.buffers[ view.buffer ];
+		const start = view?.byteOffset || 0;
+		if ( ! buffer || ! ( start + view.byteLength <= buffer.length ) ) throw new Error( `usd-gltf: bufferView ${ index } is outside its buffer` );
+		return buffer.subarray( start, start + view.byteLength );
 
 	}
 
@@ -68,11 +109,16 @@ export class GLTFDocument {
 		const key = index + ( normalize ? 'n' : '' );
 		if ( this.accessorCache.has( key ) ) return this.accessorCache.get( key );
 
-		const accessor = this.json.accessors[ index ];
-		const ArrayType = COMPONENT_ARRAYS[ accessor.componentType ];
-		const itemSize = TYPE_SIZES[ accessor.type ];
+		const accessor = this.json.accessors?.[ index ];
+		const ArrayType = COMPONENT_ARRAYS[ accessor?.componentType ];
+		const itemSize = TYPE_SIZES[ accessor?.type ];
+		if ( ! ArrayType || ! itemSize ) throw new Error( `usd-gltf: accessor ${ index } is missing or has an invalid type` );
 		const count = accessor.count;
-		let array = new ArrayType( count * itemSize );
+		const stage = `accessor ${ index }`;
+		const size = count * itemSize * ArrayType.BYTES_PER_ELEMENT;
+		checkSize( size, stage );
+
+		let read = null;
 
 		if ( accessor.bufferView !== undefined ) {
 
@@ -88,6 +134,17 @@ export class GLTFDocument {
 			const columnStride = Math.ceil( rows * elementBytes / 4 ) * 4;
 			const packed = columns === 1 ? itemSize * elementBytes : columnStride * columns;
 			const stride = view.byteStride || packed;
+			if ( count > 0 && ! ( offset + stride * ( count - 1 ) + packed <= bytes.length ) ) throw new Error( `usd-gltf: ${ stage } reads past the end of its bufferView` );
+			read = { view, bytes, elementBytes, offset, columns, rows, columnStride, stride };
+
+		}
+
+		this.budget.decode( size, stage );
+		let array = new ArrayType( count * itemSize );
+
+		if ( read ) {
+
+			const { bytes, elementBytes, offset, columns, rows, columnStride, stride } = read;
 
 			const dv = new DataView( bytes.buffer, bytes.byteOffset, bytes.byteLength );
 			const getters = { 5120: 'getInt8', 5121: 'getUint8', 5122: 'getInt16', 5123: 'getUint16', 5125: 'getUint32', 5126: 'getFloat32' };
@@ -120,9 +177,16 @@ export class GLTFDocument {
 			const IndexType = COMPONENT_ARRAYS[ indices.componentType ];
 			const ib = this.bufferViewBytes( indices.bufferView );
 			const vb = this.bufferViewBytes( values.bufferView );
+			if ( ! IndexType || ! Number.isSafeInteger( n ) || n < 0 || n > count ) throw new Error( `usd-gltf: ${ stage } has an invalid sparse count` );
+			if ( ! ( ( indices.byteOffset || 0 ) + n * IndexType.BYTES_PER_ELEMENT <= ib.length && ( values.byteOffset || 0 ) + n * itemSize * ArrayType.BYTES_PER_ELEMENT <= vb.length ) ) throw new Error( `usd-gltf: ${ stage } sparse data is outside its bufferViews` );
 			const idx = new IndexType( ib.slice( indices.byteOffset || 0, ( indices.byteOffset || 0 ) + n * IndexType.BYTES_PER_ELEMENT ).buffer );
 			const vals = new ArrayType( vb.slice( values.byteOffset || 0, ( values.byteOffset || 0 ) + n * itemSize * ArrayType.BYTES_PER_ELEMENT ).buffer );
-			for ( let i = 0; i < n; i ++ ) for ( let c = 0; c < itemSize; c ++ ) array[ idx[ i ] * itemSize + c ] = vals[ i * itemSize + c ];
+			for ( let i = 0; i < n; i ++ ) {
+
+				if ( idx[ i ] >= count ) throw new Error( `usd-gltf: ${ stage } sparse index is out of range` );
+				for ( let c = 0; c < itemSize; c ++ ) array[ idx[ i ] * itemSize + c ] = vals[ i * itemSize + c ];
+
+			}
 
 		}
 
@@ -130,6 +194,7 @@ export class GLTFDocument {
 
 		if ( normalize && normalized ) {
 
+			this.budget.decode( array.length * 4, stage );
 			const out = new Float32Array( array.length );
 			const ct = accessor.componentType;
 			for ( let i = 0; i < array.length; i ++ ) {
@@ -154,7 +219,9 @@ export class GLTFDocument {
 	getFloats( index ) {
 
 		const { array, itemSize, count } = this.getAccessor( index );
-		return { array: array instanceof Float32Array ? array : Float32Array.from( array ), itemSize, count };
+		if ( array instanceof Float32Array ) return { array, itemSize, count };
+		this.budget.decode( array.length * 4, `accessor ${ index }` );
+		return { array: Float32Array.from( array ), itemSize, count };
 
 	}
 
@@ -165,13 +232,18 @@ export class GLTFDocument {
  * @param {Uint8Array} bytes
  * @param {{ resolver?: ( uri: string ) => Promise<Uint8Array>|Uint8Array }} [options] loads external uris (already decoded from URI escaping)
  */
-export async function readGLTF( bytes, { resolver = null } = {} ) {
+export async function readGLTF( bytes, { resolver = null, budget = new Budget() } = {} ) {
 
 	let json, bin = null;
+	bytes = plainBytes( bytes );
 
 	if ( bytes[ 0 ] === 0x67 && bytes[ 1 ] === 0x6C && bytes[ 2 ] === 0x54 && bytes[ 3 ] === 0x46 ) ( { json, bin } = readGLB( bytes ) );
 	else json = JSON.parse( new TextDecoder().decode( bytes ).replace( /^/, '' ) );
 
+	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 ) {
 
 		if ( uri.startsWith( 'data:' ) ) return decodeDataURI( uri ).bytes;
@@ -179,7 +251,7 @@ export async function readGLTF( bytes, { resolver = null } = {} ) {
 		let path = uri;
 		try { path = decodeURIComponent( uri ); } catch { /* keep as is */ }
 		const data = await resolver( path );
-		return data instanceof Uint8Array ? data : new Uint8Array( data );
+		return plainBytes( data );
 
 	}
 
@@ -188,8 +260,9 @@ export async function readGLTF( bytes, { resolver = null } = {} ) {
 		if ( buffer.uri === undefined ) {
 
 			if ( i === 0 && bin ) return bin;
-			// e.g. EXT_meshopt_compression fallback buffers have no data
-			return new Uint8Array( buffer.byteLength );
+			// e.g. EXT_meshopt_compression fallback buffers: only read through decoded views, so they
+			// need no storage, and any other view into one fails its bounds check
+			return new Uint8Array( 0 );
 
 		}
 
@@ -197,12 +270,16 @@ export async function readGLTF( bytes, { resolver = null } = {} ) {
 
 	} ) );
 
-	const doc = new GLTFDocument( json, buffers, [] );
+	const doc = new GLTFDocument( json, buffers, [], budget );
 
 	( json.bufferViews || [] ).forEach( ( view, i ) => {
 
 		const ext = view.extensions?.KHR_meshopt_compression || view.extensions?.EXT_meshopt_compression;
-		if ( ext ) doc.decodedViews.set( i, decodeMeshoptView( ext, buffers ) );
+		if ( ! ext ) return;
+		const start = ext.byteOffset || 0;
+		if ( ! buffers[ ext.buffer ] || ! ( start + ext.byteLength <= buffers[ ext.buffer ].length ) ) throw new Error( `usd-gltf: bufferView ${ i } compressed data is outside its buffer` );
+		budget.decode( ext.count * ext.byteStride, `bufferView ${ i }` );
+		doc.decodedViews.set( i, decodeMeshoptView( ext, buffers ) );
 
 	} );
 
@@ -228,6 +305,14 @@ export async function readGLTF( bytes, { resolver = null } = {} ) {
 
 }
 
+// A plain Uint8Array view: a Node Buffer's slice() aliases its memory instead of copying, so data
+// read through .slice().buffer would be the wrong bytes.
+function plainBytes( data ) {
+
+	return ArrayBuffer.isView( data ) ? new Uint8Array( data.buffer, data.byteOffset, data.byteLength ) : new Uint8Array( data );
+
+}
+
 function guessMime( uri ) {
 
 	const ext = uri.split( '?' )[ 0 ].split( '.' ).pop().toLowerCase();
@@ -240,8 +325,9 @@ function guessMime( uri ) {
  */
 export class GLTFBuilder {
 
-	constructor( generator = 'usd-gltf' ) {
+	constructor( generator = 'usd-gltf', budget = new Budget() ) {
 
+		this.budget = budget;
 		this.json = { asset: { version: '2.0', generator }, scenes: [], nodes: [], meshes: [], materials: [], textures: [], images: [], samplers: [], accessors: [], bufferViews: [], buffers: [] };
 		this.chunks = [];
 		this.byteLength = 0;
@@ -262,6 +348,7 @@ export class GLTFBuilder {
 		const pad = ( 4 - ( this.byteLength % 4 ) ) % 4;
 		if ( pad ) { this.chunks.push( new Uint8Array( pad ) ); this.byteLength += pad; }
 
+		this.budget.output( this.byteLength + bytes.byteLength, 'glb buffer' );
 		const view = { buffer: 0, byteOffset: this.byteLength, byteLength: bytes.byteLength };
 		if ( target ) view.target = target;
 		this.chunks.push( bytes instanceof Uint8Array ? bytes : new Uint8Array( bytes.buffer, bytes.byteOffset, bytes.byteLength ) );
@@ -323,7 +410,9 @@ export class GLTFBuilder {
 
 	toGLB() {
 
-		const json = this.finalize();
+		const json = new TextEncoder().encode( JSON.stringify( this.finalize() ) );
+		const pad4 = ( n ) => Math.ceil( n / 4 ) * 4;
+		this.budget.output( 20 + pad4( json.byteLength ) + ( this.byteLength ? 8 + pad4( this.byteLength ) : 0 ), 'glb' );
 		const bin = new Uint8Array( this.byteLength );
 		let offset = 0;
 		for ( const chunk of this.chunks ) {

package/src/gltf/glb.js

@@ -68,13 +68,13 @@ export function readGLB( data ) {
 
 /**
  * Packs glTF JSON and an optional binary buffer into a GLB.
- * @param {object} json
+ * @param {object|Uint8Array} json the glTF JSON, or it already encoded as UTF-8
  * @param {Uint8Array|null} [bin]
  * @returns {Uint8Array}
  */
 export function writeGLB( json, bin = null ) {
 
-	const jsonBytes = encoder.encode( JSON.stringify( json ) );
+	const jsonBytes = json instanceof Uint8Array ? json : encoder.encode( JSON.stringify( json ) );
 	const jsonLength = pad4( jsonBytes.byteLength );
 	const binLength = bin ? pad4( bin.byteLength ) : 0;
 

package/src/image/index.js

@@ -65,6 +65,54 @@ export function isGreyscaleImage( bytes ) {
 
 }
 
+/**
+ * Width, height and bytes per pixel of a PNG, JPEG or WebP from its header, or null.
+ * @param {Uint8Array} bytes
+ * @returns {{ width: number, height: number, pixelBytes: number }|null}
+ */
+export function imageSize( bytes ) {
+
+	bytes = toBytes( bytes );
+	const type = imageMimeType( bytes );
+	const be16 = ( o ) => ( bytes[ o ] << 8 ) | bytes[ o + 1 ];
+	const le16 = ( o ) => bytes[ o ] | ( bytes[ o + 1 ] << 8 );
+	const le24 = ( o ) => le16( o ) | ( bytes[ o + 2 ] << 16 );
+
+	if ( type === 'image/png' && bytes.length >= 26 ) {
+
+		const width = ( be16( 16 ) * 65536 ) + be16( 18 ), height = ( be16( 20 ) * 65536 ) + be16( 22 );
+		return { width, height, pixelBytes: bytes[ 24 ] === 16 ? 8 : 4 };
+
+	}
+
+	if ( type === 'image/jpeg' ) {
+
+		for ( let o = 2; o + 9 < bytes.length; ) {
+
+			if ( bytes[ o ] !== 0xFF ) return null;
+			const marker = bytes[ o + 1 ];
+			if ( marker >= 0xC0 && marker <= 0xCF && marker !== 0xC4 && marker !== 0xC8 && marker !== 0xCC ) return { width: be16( o + 7 ), height: be16( o + 5 ), pixelBytes: 4 };
+			o += 2 + be16( o + 2 );
+
+		}
+
+		return null;
+
+	}
+
+	if ( type === 'image/webp' && bytes.length >= 30 ) {
+
+		const chunk = String.fromCharCode( bytes[ 12 ], bytes[ 13 ], bytes[ 14 ], bytes[ 15 ] );
+		if ( chunk === 'VP8X' ) return { width: le24( 24 ) + 1, height: le24( 27 ) + 1, pixelBytes: 4 };
+		if ( chunk === 'VP8 ' ) return { width: le16( 26 ) & 0x3FFF, height: le16( 28 ) & 0x3FFF, pixelBytes: 4 };
+		if ( chunk === 'VP8L' ) { const b = bytes[ 21 ] | ( bytes[ 22 ] << 8 ) | ( bytes[ 23 ] << 16 ) | ( bytes[ 24 ] << 24 ); return { width: ( b & 0x3FFF ) + 1, height: ( ( b >>> 14 ) & 0x3FFF ) + 1, pixelBytes: 4 }; }
+
+	}
+
+	return null;
+
+}
+
 /**
  * Decodes a PNG, JPEG or WebP. The format is sniffed from the bytes; mimeType is only a fallback.
  * @param {Uint8Array|ArrayBuffer} bytes
@@ -141,10 +189,13 @@ export async function encodePNGAsync( image ) {
  * @param {Uint8Array} bytes
  * @param {string} [mimeType]
  * @param {( bytes: Uint8Array, mimeType?: string ) => Promise<object>|object} [decoder] overrides both
+ * @param {import('../limits.js').Budget} [budget] charged with the decoded size, from the header, before decoding
  */
-export async function decodeImageAsync( bytes, mimeType, decoder = null ) {
+export async function decodeImageAsync( bytes, mimeType, decoder = null, budget = null ) {
 
 	bytes = toBytes( bytes );
+	const size = budget && imageSize( bytes );
+	if ( size ) budget.decode( size.width * size.height * size.pixelBytes, 'image' );
 	if ( decoder ) return decoder( bytes, mimeType );
 	const type = imageMimeType( bytes ) || mimeType;
 

package/src/image/inflate.js

@@ -137,12 +137,12 @@ function corrupt( what ) {
 }
 
 // Inflates the raw DEFLATE stream starting at src[ pos ]. Returns the output and the byte offset just past the stream.
-function inflateStream( src, pos, sizeHint ) {
+function inflateStream( src, pos, sizeHint, maxSize ) {
 
 	const srcLen = src.length;
 	const overrun = srcLen + 8;
 
-	let out = new Uint8Array( sizeHint > 0 ? sizeHint : Math.max( 1 << 15, srcLen * 4 ) );
+	let out = new Uint8Array( Math.min( sizeHint > 0 ? sizeHint : Math.max( 1 << 15, srcLen * 4 ), maxSize ) );
 	let op = 0;
 
 	let bitBuf = 0;
@@ -154,7 +154,7 @@ function inflateStream( src, pos, sizeHint ) {
 	let clTable = null;
 
 	let final = 0;
-	const state = { src, overrun, pos, bitBuf, bitCnt, out, op };
+	const state = { src, overrun, pos, bitBuf, bitCnt, out, op, maxSize };
 
 	do {
 
@@ -188,7 +188,7 @@ function inflateStream( src, pos, sizeHint ) {
 			pos += 4;
 			if ( pos + len > srcLen ) throw corrupt( 'unexpected end' );
 
-			if ( op + len > out.length ) out = grow( out, op + len );
+			if ( op + len > out.length ) out = grow( out, op + len, maxSize );
 			out.set( src.subarray( pos, pos + len ), op );
 			op += len;
 			pos += len;
@@ -371,7 +371,7 @@ function decodeSymbols( state, litTable, litMask, distTable, distMask ) {
 
 			if ( op === outLen ) {
 
-				out = grow( out, op + 1 );
+				out = grow( out, op + 1, state.maxSize );
 				outLen = out.length;
 
 			}
@@ -435,7 +435,7 @@ function decodeSymbols( state, litTable, litMask, distTable, distMask ) {
 
 		if ( op + len > outLen ) {
 
-			out = grow( out, op + len );
+			out = grow( out, op + len, state.maxSize );
 			outLen = out.length;
 
 		}
@@ -464,9 +464,10 @@ function decodeSymbols( state, litTable, litMask, distTable, distMask ) {
 
 }
 
-function grow( out, need ) {
+function grow( out, need, maxSize ) {
 
-	const next = new Uint8Array( Math.max( need, out.length * 2 ) );
+	if ( need > maxSize ) throw corrupt( `more than the expected ${ maxSize } bytes` );
+	const next = new Uint8Array( Math.min( Math.max( need, out.length * 2 ), maxSize ) );
 	next.set( out );
 	return next;
 
@@ -482,11 +483,12 @@ function toBytes( data ) {
  * Decompresses raw DEFLATE data.
  * @param {Uint8Array} bytes
  * @param {number} [sizeHint] expected output size, avoids reallocation when known
+ * @param {number} [maxSize] fails rather than produce more than this
  * @returns {Uint8Array}
  */
-export function inflate( bytes, sizeHint = 0 ) {
+export function inflate( bytes, sizeHint = 0, maxSize = Infinity ) {
 
-	return inflateStream( toBytes( bytes ), 0, sizeHint ).data;
+	return inflateStream( toBytes( bytes ), 0, sizeHint, maxSize ).data;
 
 }
 
@@ -496,7 +498,7 @@ export function inflate( bytes, sizeHint = 0 ) {
  * @param {number} [sizeHint]
  * @returns {Uint8Array}
  */
-export function inflateZlib( bytes, sizeHint = 0 ) {
+export function inflateZlib( bytes, sizeHint = 0, maxSize = Infinity ) {
 
 	bytes = toBytes( bytes );
 	if ( bytes.length < 2 ) throw corrupt( 'missing zlib header' );
@@ -506,7 +508,7 @@ export function inflateZlib( bytes, sizeHint = 0 ) {
 	if ( ( cmf & 15 ) !== 8 || ( cmf >> 4 ) > 7 || ( ( cmf << 8 ) | flg ) % 31 !== 0 ) throw corrupt( 'bad zlib header' );
 	if ( flg & 32 ) throw corrupt( 'zlib preset dictionary not supported' );
 
-	const { data, end } = inflateStream( bytes, 2, sizeHint );
+	const { data, end } = inflateStream( bytes, 2, sizeHint, maxSize );
 
 	if ( end + 4 <= bytes.length ) {
 

package/src/image/png.js

@@ -219,7 +219,7 @@ export function decodePNG( bytes ) {
 
 	}
 
-	const raw = inflateZlib( zdata, expected );
+	const raw = inflateZlib( zdata, expected, expected * 2 + 1024 ); // tolerates trailing data, not a decompression bomb
 	if ( raw.length < expected ) throw new Error( 'usd-gltf: PNG image data is truncated' );
 
 	const channels = colorType === 3 ? ( trns !== null ? 4 : 3 ) : samples + ( trns !== null ? 1 : 0 );

package/src/index.d.ts

@@ -13,7 +13,28 @@ export interface DecodedImage {
 /** Replaces the built in image decoding (the platform decoder in browsers, JavaScript decoders in Node). */
 export type ImageDecoder = ( bytes: Uint8Array, mimeType?: string ) => DecodedImage | Promise<DecodedImage>;
 
-export interface USDToGLBOptions {
+/** Opt-in resource limits, for both directions. See README "Limits". */
+export interface ConversionLimits {
+	/** Decoded data held during the conversion: accessors, USD arrays, decompressed data, images, arrays written to the output layer. */
+	maxDecodedBytes?: number;
+	/** Largest output buffer: checked as writers grow and before the final usdz or glb is allocated. */
+	maxOutputBytes?: number;
+	/** Cancels the conversion, which then rejects with the signal's reason. */
+	signal?: AbortSignal;
+}
+
+/** Thrown when a conversion would go over one of its limits. Carries sizes only, never input data or file names. */
+export class ConversionLimitError extends Error {
+	name: 'ConversionLimitError';
+	code: 'USD_GLTF_LIMIT';
+	/** Where the limit was reached, e.g. 'accessor 3', 'usdc', 'image', 'glb'. */
+	stage: string;
+	resource: 'decoded' | 'output';
+	limit: number;
+	attempted: number;
+}
+
+export interface USDToGLBOptions extends ConversionLimits {
 	/** Name of the input file, used to resolve relative paths. */
 	identifier?: string;
 	/** Needed when the USD references files outside a usdz package. */
@@ -27,7 +48,7 @@ export interface USDToGLBOptions {
 	log?: ( message: string ) => void;
 }
 
-export interface GLBToUSDOptions {
+export interface GLBToUSDOptions extends ConversionLimits {
 	/** Output encoding: a usdz package (default), or a single usda / usdc layer without its textures. */
 	format?: 'usdz' | 'usda' | 'usdc';
 	/** Needed for .gltf files with external buffers or images. */
@@ -51,8 +72,8 @@ export function detectFormat( data: Uint8Array | ArrayBuffer ): 'glb' | 'gltf' |
 /** Splits a GLB into its JSON and binary chunk. */
 export function readGLB( data: Uint8Array | ArrayBuffer ): { json: any, bin: Uint8Array | null };
 
-/** Packs glTF JSON and a binary buffer into a GLB. */
-export function writeGLB( json: object, bin?: Uint8Array | null ): Uint8Array;
+/** Packs glTF JSON (an object, or already UTF-8 encoded) and a binary buffer into a GLB. */
+export function writeGLB( json: object | Uint8Array, bin?: Uint8Array | null ): Uint8Array;
 
 /** The uncomposed contents of one USD layer; see src/usd/model.js for the value representation. */
 export interface Layer {

package/src/index.js

@@ -5,6 +5,7 @@ import { readGLTF } from './gltf/document.js';
 import { writeUSDA } from './usd/usda/writer.js';
 import { writeUSDC } from './usd/usdc/writer.js';
 import { writeUSDZ } from './usd/usdz.js';
+import { Budget } from './limits.js';
 
 export { readGLB, writeGLB } from './gltf/glb.js';
 export { detectFormat } from './detect.js';
@@ -13,6 +14,7 @@ export { readUSDA } from './usd/usda/reader.js';
 export { writeUSDA } from './usd/usda/writer.js';
 export { readUSDC } from './usd/usdc/reader.js';
 export { writeUSDC } from './usd/usdc/writer.js';
+export { ConversionLimitError } from './limits.js';
 
 function toBytes( data ) {
 
@@ -20,37 +22,50 @@ function toBytes( data ) {
 
 }
 
+// Limits shared by both directions; see README "Limits".
+function budgetFor( { maxDecodedBytes, maxOutputBytes, signal } ) {
+
+	return new Budget( { maxDecodedBytes, maxOutputBytes, signal } );
+
+}
+
 /**
  * Converts USD (usda, usdc or usdz, detected from the bytes) to GLB.
  * @param {ArrayBuffer|Uint8Array} data
- * @param {{ identifier?: string, resolver?: ( path: string ) => Promise<Uint8Array>, variants?: object, log?: ( message: string ) => void }} [options]
+ * @param {{ identifier?: string, resolver?: ( path: string ) => Promise<Uint8Array>, variants?: object, log?: ( message: string ) => void, maxDecodedBytes?: number, maxOutputBytes?: number, signal?: AbortSignal }} [options]
  *   resolver loads files referenced by relative paths (not needed for self-contained usdz)
  * @returns {Promise<Uint8Array>}
  */
 export async function usdToGLB( data, options = {} ) {
 
-	const stage = await openStage( toBytes( data ), options );
-	const builder = await new USDToGLTF( stage, options ).convert();
-	return builder.toGLB();
+	const budget = budgetFor( options );
+	const stage = await openStage( toBytes( data ), { ...options, budget } );
+	const builder = await new USDToGLTF( stage, { ...options, budget } ).convert();
+	const glb = builder.toGLB();
+	budget.check();
+	return glb;
 
 }
 
 /**
  * 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> }} [options]
+ * @param {{ format?: 'usda'|'usdc'|'usdz', resolver?: ( uri: string ) => Promise<Uint8Array>, maxDecodedBytes?: number, maxOutputBytes?: number, signal?: AbortSignal }} [options]
  * @returns {Promise<Uint8Array>}
  */
-export async function glbToUSD( data, { format = 'usdz', resolver = null, log, imageDecoder } = {} ) {
+export async function glbToUSD( data, { format = 'usdz', resolver = null, log, imageDecoder, ...limits } = {} ) {
 
-	const doc = await readGLTF( toBytes( data ), { resolver } );
+	const budget = budgetFor( limits );
+	const doc = await readGLTF( toBytes( data ), { resolver, budget } );
 	const { layer, files } = await new GLTFToUSD( doc, { log, imageDecoder } ).convert();
+	let out;
 
-	if ( format === 'usda' ) return new TextEncoder().encode( writeUSDA( layer ) );
-	if ( format === 'usdc' ) return writeUSDC( layer );
+	if ( format === 'usda' ) out = new TextEncoder().encode( writeUSDA( layer, { budget } ) );
+	else if ( format === 'usdc' ) out = writeUSDC( layer, { budget } );
+	else out = writeUSDZ( [ { name: 'root.usdc', data: writeUSDC( layer, { budget } ) }, ...files ], { budget } ); // the root layer must come first
 
-	// the root layer must be the first file in the package
-	return writeUSDZ( [ { name: 'root.usdc', data: writeUSDC( layer ) }, ...files ] );
+	budget.check();
+	return out;
 
 }
 
@@ -58,10 +73,14 @@ 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 } = {} ) {
+export async function glbToUSDFiles( data, { format = 'usda', resolver = null, log, imageDecoder, ...limits } = {} ) {
 
-	const doc = await readGLTF( toBytes( data ), { resolver } );
+	const budget = budgetFor( limits );
+	const doc = await readGLTF( toBytes( data ), { resolver, budget } );
 	const { layer, files } = await new GLTFToUSD( doc, { log, imageDecoder } ).convert();
-	return { layer: format === 'usdc' ? writeUSDC( layer ) : new TextEncoder().encode( writeUSDA( layer ) ), files };
+	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' );
+	budget.check();
+	return { layer: bytes, files };
 
 }