usd-gltf 0.0.1 → 0.2.0

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

@@ -0,0 +1,92 @@
+/** Loads a file referenced by a relative path or URI (glTF buffers and images, USD sublayers and references). */
+export type Resolver = ( path: string ) => Uint8Array | ArrayBuffer | Promise<Uint8Array | ArrayBuffer>;
+
+/** A decoded image: 8 or 16 bit samples, interleaved, top row first. */
+export interface DecodedImage {
+	width: number;
+	height: number;
+	channels: 1 | 2 | 3 | 4;
+	bitDepth: 8 | 16;
+	data: Uint8Array | Uint16Array;
+}
+
+/** 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>;
+
+/** 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. */
+	resolver?: Resolver;
+	/** Variant selections, by prim path: { '/Root': { shadingVariant: 'red' } }, or by set name for every prim. */
+	variants?: Record<string, string | Record<string, string>>;
+	/** Write material variant sets as KHR_materials_variants (default true). */
+	materialVariants?: boolean;
+	imageDecoder?: ImageDecoder;
+	/** Receives non fatal problems, such as textures that could not be read. */
+	log?: ( message: string ) => void;
+}
+
+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. */
+	resolver?: Resolver;
+	imageDecoder?: ImageDecoder;
+	log?: ( message: string ) => void;
+}
+
+/** Converts USD (usda, usdc or usdz, detected from the bytes) to GLB. */
+export function usdToGLB( data: Uint8Array | ArrayBuffer, options?: USDToGLBOptions ): Promise<Uint8Array>;
+
+/** Converts glTF (GLB, or .gltf JSON with a resolver for its files) to USD. */
+export function glbToUSD( data: Uint8Array | ArrayBuffer, options?: GLBToUSDOptions ): Promise<Uint8Array>;
+
+/** Like glbToUSD for usda / usdc output, also returning the texture files the layer references. */
+export function glbToUSDFiles( data: Uint8Array | ArrayBuffer, options?: Omit<GLBToUSDOptions, 'format'> & { format?: 'usda' | 'usdc' } ): Promise<{ layer: Uint8Array, files: Array<{ name: string, data: Uint8Array }> }>;
+
+/** Identifies a file from its leading bytes. */
+export function detectFormat( data: Uint8Array | ArrayBuffer ): 'glb' | 'gltf' | 'usda' | 'usdc' | 'usdz' | null;
+
+/** Splits a GLB into its JSON and binary chunk. */
+export function readGLB( data: Uint8Array | ArrayBuffer ): { json: any, bin: Uint8Array | null };
+
+/** 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 {
+	identifier: string;
+	metadata: Record<string, any>;
+	root: any;
+	getPrimAtPath( path: string ): any;
+}
+
+export function readUSDA( source: string | Uint8Array, identifier?: string ): Layer;
+export function writeUSDA( layer: Layer ): string;
+export function readUSDC( data: Uint8Array | ArrayBuffer, identifier?: string ): Layer;
+export function writeUSDC( layer: Layer ): Uint8Array;
+
+/** Opens and composes a USD stage (references, payloads, sublayers, inherits, variants). */
+export function openStage( data: Uint8Array, options?: { identifier?: string, resolver?: Resolver, variants?: USDToGLBOptions[ 'variants' ] } ): Promise<any>;

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 };
 
 }

package/src/limits.js

@@ -0,0 +1,101 @@
+// Opt-in resource limits for a conversion: decoded data, serialized output and cancellation.
+
+/**
+ * Thrown when a conversion would go over one of its limits. The message and fields describe sizes
+ * only, never input data or file names.
+ */
+export class ConversionLimitError extends Error {
+
+	/**
+	 * @param {{ stage: string, resource: 'decoded'|'output', limit: number, attempted: number }} info
+	 */
+	constructor( { stage, resource, limit, attempted } ) {
+
+		super( `usd-gltf: ${ stage } needs ${ attempted } ${ resource } bytes, over the limit of ${ limit }` );
+		this.name = 'ConversionLimitError';
+		this.code = 'USD_GLTF_LIMIT';
+		this.stage = stage;
+		this.resource = resource;
+		this.limit = limit;
+		this.attempted = attempted;
+
+	}
+
+}
+
+/**
+ * Tracks one conversion against its limits. Readers and converters charge decoded bytes before
+ * allocating them; writers report their size before growing.
+ */
+export class Budget {
+
+	/**
+	 * @param {{ maxDecodedBytes?: number, maxOutputBytes?: number, signal?: AbortSignal }} [options]
+	 */
+	constructor( { maxDecodedBytes = Infinity, maxOutputBytes = Infinity, signal = null } = {} ) {
+
+		this.maxDecodedBytes = maxDecodedBytes;
+		this.maxOutputBytes = maxOutputBytes;
+		this.signal = signal;
+		this.decodedBytes = 0;
+
+	}
+
+	/**
+	 * Adds to the running total of decoded data: accessors, arrays, decompressed sections and images.
+	 * @param {number} bytes
+	 * @param {string} stage
+	 */
+	decode( bytes, stage ) {
+
+		checkSize( bytes, stage );
+		this.check();
+		this.decodedBytes += bytes;
+		if ( this.decodedBytes > this.maxDecodedBytes ) throw new ConversionLimitError( { stage, resource: 'decoded', limit: this.maxDecodedBytes, attempted: this.decodedBytes } );
+
+	}
+
+	/**
+	 * Checks the size an output buffer is about to reach.
+	 * @param {number} bytes
+	 * @param {string} stage
+	 */
+	output( bytes, stage ) {
+
+		checkSize( bytes, stage );
+		if ( bytes > this.maxOutputBytes ) throw new ConversionLimitError( { stage, resource: 'output', limit: this.maxOutputBytes, attempted: bytes } );
+
+	}
+
+	// Throws the signal's reason once the conversion is cancelled.
+	check() {
+
+		this.signal?.throwIfAborted();
+
+	}
+
+}
+
+/**
+ * A size computed from counts in a file must be a whole number of bytes that fits in an array.
+ * @param {number} bytes
+ * @param {string} stage
+ */
+export function checkSize( bytes, stage ) {
+
+	if ( ! Number.isSafeInteger( bytes ) || bytes < 0 ) throw new Error( `usd-gltf: invalid size in ${ stage }` );
+
+}
+
+/**
+ * For catch blocks that skip one failed asset and carry on: rethrows what must end the whole
+ * conversion instead, a limit error or cancellation.
+ * @param {unknown} error
+ * @param {Budget} [budget]
+ */
+export function rethrowFatal( error, budget ) {
+
+	budget?.check();
+	if ( error instanceof ConversionLimitError ) throw error;
+
+}

package/src/usd/stage.js

@@ -5,6 +5,7 @@
 import { AssetPath, ListOp } from './model.js';
 import { readUSDA } from './usda/reader.js';
 import { readZip } from './usdz.js';
+import { Budget, rethrowFatal } from '../limits.js';
 
 const decoder = new TextDecoder();
 
@@ -80,9 +81,10 @@ export function resolveAssetPath( anchor, assetPath ) {
 // Reads bytes for identifiers, opening packages (including nested ones) through the user resolver.
 export class AssetReader {
 
-	constructor( resolver ) {
+	constructor( resolver, budget = new Budget() ) {
 
 		this.resolver = resolver;
+		this.budget = budget;
 		this.packages = new Map();
 		this.files = new Map();
 
@@ -123,7 +125,7 @@ export class AssetReader {
 
 	async openPackage( identifier ) {
 
-		if ( ! this.packages.has( identifier ) ) this.packages.set( identifier, readZip( await this.read( identifier ) ) );
+		if ( ! this.packages.has( identifier ) ) this.packages.set( identifier, readZip( await this.read( identifier ), { budget: this.budget } ) );
 		return this.packages.get( identifier );
 
 	}
@@ -140,7 +142,7 @@ export class AssetReader {
 
 }
 
-async function parseLayer( bytes, identifier ) {
+async function parseLayer( bytes, identifier, budget ) {
 
 	const format = detectLayerFormat( bytes );
 	if ( format === 'usda' ) return readUSDA( bytes, identifier );
@@ -148,7 +150,7 @@ async function parseLayer( bytes, identifier ) {
 	if ( format === 'usdc' ) {
 
 		const { readUSDC } = await import( './usdc/reader.js' );
-		return readUSDC( bytes, identifier );
+		return readUSDC( bytes, identifier, { budget } );
 
 	}
 
@@ -185,14 +187,15 @@ async function loadLayers( reader, rootIdentifier ) {
 
 		if ( detectLayerFormat( bytes ) === 'usdz' ) {
 
-			reader.addPackage( identifier, readZip( bytes ) );
+			reader.addPackage( identifier, readZip( bytes, { budget: reader.budget } ) );
 			const root = await load( await reader.packageRoot( identifier ) );
 			layers.set( identifier, root );
 			return root;
 
 		}
 
-		const layer = await parseLayer( bytes, identifier );
+		reader.budget.check();
+		const layer = await parseLayer( bytes, identifier, reader.budget );
 		layers.set( identifier, layer );
 
 		const pending = [];
@@ -216,6 +219,7 @@ async function loadLayers( reader, rootIdentifier ) {
 
 			} catch ( e ) {
 
+				rethrowFatal( e, reader.budget );
 				console.warn( `usd-gltf: ${ e.message }` );
 
 			}
@@ -862,16 +866,16 @@ export class Stage {
 /**
  * Opens and composes a stage.
  * @param {Uint8Array} bytes usda, usdc or usdz
- * @param {{ identifier?: string, resolver?: ( identifier: string ) => Promise<Uint8Array>|Uint8Array, variants?: object }} [options]
+ * @param {{ identifier?: string, resolver?: ( identifier: string ) => Promise<Uint8Array>|Uint8Array, variants?: object, budget?: import('../limits.js').Budget }} [options]
  * @returns {Promise<Stage>}
  */
-export async function openStage( bytes, { identifier, resolver = null, variants = {} } = {} ) {
+export async function openStage( bytes, { identifier, resolver = null, variants = {}, budget = new Budget() } = {} ) {
 
 	const format = detectLayerFormat( bytes );
 	if ( ! format ) throw new Error( 'usd-gltf: input is not usda, usdc or usdz' );
 
 	identifier ??= 'root.' + format;
-	const reader = new AssetReader( resolver );
+	const reader = new AssetReader( resolver, budget );
 	reader.files.set( identifier, bytes );
 
 	const { root, layers } = await loadLayers( reader, identifier );

package/src/usd/usda/reader.js

@@ -358,7 +358,7 @@ function typeValue( raw, typeName ) {
 
 	if ( typeName === 'asset' ) return new AssetPath( raw instanceof AssetRef ? raw.path : String( raw ) );
 	if ( typeName === 'bool' ) return raw === true || raw === 1;
-	if ( typeName === 'string' || typeName === 'token' ) return raw instanceof Ident ? raw.name : raw;
+	if ( typeName === 'string' || typeName === 'token' || typeName === 'pathExpression' ) return raw instanceof Ident ? raw.name : raw;
 	if ( /^quat[hfd]$/.test( typeName ) ) return [ raw[ 1 ], raw[ 2 ], raw[ 3 ], raw[ 0 ] ];
 	if ( /^matrix[234]d$|^frame4d$/.test( typeName ) ) return raw.flat();
 	if ( raw instanceof Tuple ) return Array.from( raw );
@@ -524,6 +524,22 @@ function parseMetadata( lx, metadata, kind ) {
 			metadata.subLayers = layers.map( ( r ) => r.assetPath );
 			metadata.subLayerOffsets = layers.map( ( r ) => r.layerOffset );
 
+		} else if ( key === 'relocates' ) {
+
+			// { <source>: <target>, ... }; layer relocates use the layerRelocates field, as in usdc
+			const pairs = [];
+			lx.expect( '{' );
+			while ( ! lx.eat( '}' ) ) {
+
+				const from = lx.path();
+				lx.expect( ':' );
+				pairs.push( [ from, lx.path() ] );
+				lx.eat( ',' );
+
+			}
+
+			metadata[ kind === 'layer' ? 'layerRelocates' : 'relocates' ] = pairs;
+
 		} else if ( key === 'variants' ) {
 
 			metadata.variants = parseDictionary( lx );

package/src/usd/usda/writer.js

@@ -56,7 +56,7 @@ function formatScalar( v, base ) {
 
 	if ( v === null || v === undefined ) return 'None';
 	if ( base === 'bool' ) return v ? 'true' : 'false';
-	if ( base === 'string' || base === 'token' ) return quote( String( v ) );
+	if ( base === 'string' || base === 'token' || base === 'pathExpression' ) return quote( String( v ) );
 	if ( base === 'asset' ) return formatAsset( v );
 	if ( base === 'dictionary' ) return formatDictionary( v, '' );
 
@@ -142,12 +142,12 @@ function formatDictionary( dict, indent ) {
 
 }
 
-function formatLayerOffset( offset ) {
+function formatLayerOffset( offset, customData = null, indent = '' ) {
 
-	if ( ! offset ) return '';
 	const parts = [];
-	if ( offset.offset ) parts.push( `offset = ${ offset.offset }` );
-	if ( offset.scale !== undefined && offset.scale !== 1 ) parts.push( `scale = ${ offset.scale }` );
+	if ( offset?.offset ) parts.push( `offset = ${ offset.offset }` );
+	if ( offset?.scale !== undefined && offset.scale !== 1 ) parts.push( `scale = ${ offset.scale }` );
+	if ( customData && Object.keys( customData ).length ) parts.push( `customData = ${ formatDictionary( customData, indent ) }` );
 	return parts.length ? ` (${ parts.join( '; ' ) })` : '';
 
 }
@@ -157,7 +157,7 @@ function formatReference( r ) {
 	let s = '';
 	if ( r.assetPath ) s += formatAsset( r.assetPath );
 	if ( r.primPath ) s += `<${ r.primPath }>`;
-	return s + formatLayerOffset( r.layerOffset );
+	return s + formatLayerOffset( r.layerOffset, r.customData );
 
 }
 
@@ -218,6 +218,11 @@ function formatMetadataEntries( metadata, indent, kind ) {
 			const offsets = metadata.subLayerOffsets || [];
 			lines.push( `${ indent }subLayers = [\n${ value.map( ( p, i ) => `${ indent }    ${ formatAsset( p ) }${ formatLayerOffset( offsets[ i ] ) }` ).join( ',\n' ) }\n${ indent }]` );
 
+		} else if ( key === 'layerRelocates' || key === 'relocates' ) {
+
+			const pairs = value.map( ( [ a, b ] ) => `${ indent }    <${ a }>: <${ b }>` );
+			lines.push( `${ indent }relocates = {\n${ pairs.join( ',\n' ) }\n${ indent }}` );
+
 		} else if ( key === 'subLayerOffsets' ) {
 
 			continue;
@@ -309,6 +314,7 @@ function writePrimContents( out, spec, indent ) {
 
 	for ( const prop of spec.properties.values() ) writeProperty( out, prop, indent );
 
+	if ( spec.metadata.propertyOrder ) out.push( `${ indent }reorder properties = [${ spec.metadata.propertyOrder.map( quote ).join( ', ' ) }]` );
 	if ( spec.metadata.primOrder ) out.push( `${ indent }reorder nameChildren = [${ spec.metadata.primOrder.map( quote ).join( ', ' ) }]` );
 
 	for ( const child of spec.children.values() ) {
@@ -351,11 +357,26 @@ function writePrim( out, spec, indent ) {
 
 /**
  * @param {import('../model.js').Layer} layer
+ * @param {{ budget?: import('../../limits.js').Budget }} [options] its output limit is checked as lines are written
  * @returns {string}
  */
-export function writeUSDA( layer ) {
+export function writeUSDA( layer, { budget = null } = {} ) {
 
 	const out = [ '#usda 1.0' ];
+
+	if ( budget ) {
+
+		let size = 0;
+		const push = out.push;
+		out.push = function ( ...lines ) {
+
+			for ( const line of lines ) size += line.length + 1;
+			budget.output( size, 'usda' );
+			return push.apply( this, lines );
+
+		};
+
+	}
 	const meta = formatMetadataEntries( layer.metadata, '    ', 'layer' );
 	if ( meta.length ) out.push( '(', ...meta, ')' );
 	out.push( '' );