usd-gltf 0.0.1 → 0.1.0

package/README.md

@@ -2,8 +2,6 @@
 
 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.
 
-> Work in progress, not yet published to npm.
-
 ```
 npm install usd-gltf
 ```
@@ -48,10 +46,15 @@ Current status:
 
 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`):
+
 ```
-node scripts/fetch-corpus.js
+npm run fetch-corpus
+npm run conformance
 ```
 
+The [Conformance workflow](.github/workflows/conformance.yml) runs the same check in CI.
+
 ## License
 
 MIT

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "usd-gltf",
-  "version": "0.0.1",
+  "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": {
-    ".": "./src/index.js"
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
   },
   "bin": {
     "usd-gltf": "bin/usd-gltf.js"
@@ -16,7 +19,9 @@
     "bin"
   ],
   "scripts": {
-    "test": "node --test test/*.test.js"
+    "test": "node --test test/*.test.js",
+    "conformance": "node scripts/conformance.js",
+    "fetch-corpus": "node scripts/fetch-corpus.js"
   },
   "engines": {
     "node": ">=18"
@@ -45,5 +50,6 @@
   "devDependencies": {
     "gltf-validator": "^2.0.0-dev.3.10",
     "meshoptimizer": "^1.3.0"
-  }
+  },
+  "types": "src/index.d.ts"
 }

package/src/convert/usd-material.js

@@ -6,7 +6,7 @@
 // and lets textures be referenced directly when glTF can express the result, or be repacked
 // (baked) into a new image when it can't, e.g. separate roughness and metallic maps.
 
-import { decodeImageAsync, encodePNG, imageMimeType } from '../image/index.js';
+import { decodeImageAsync, encodePNG, encodePNGAsync, imageMimeType, isGreyscaleImage } from '../image/index.js';
 import { multiply } from '../util/math.js';
 import { resolveAssetPath } from '../usd/stage.js';
 
@@ -476,6 +476,20 @@ export class MaterialConverter {
 
 	}
 
+	async isGrey( file ) {
+
+		try {
+
+			return isGreyscaleImage( await this.stage.readAsset( file ) );
+
+		} catch {
+
+			return false;
+
+		}
+
+	}
+
 	decode( file ) {
 
 		if ( ! this.decoded.has( file ) ) {
@@ -562,8 +576,10 @@ export class MaterialConverter {
 		const tex = textured[ 0 ].term.tex;
 		const sameTexture = textured.every( ( s ) => s.term.tex.file === tex.file && s.term.tex.uv.name === tex.uv.name && JSON.stringify( s.term.tex.uv.transform ) === JSON.stringify( tex.uv.transform ) );
 
-		// direct use: each textured slot reads its own channel, no bias, scale expressible as a factor
-		const direct = sameTexture && textured.every( ( s ) => s.term.channel === s.out && Math.abs( s.term.bias ) < 1e-6 && ( allowFactor || Math.abs( s.term.scale - 1 ) < 1e-6 ) ) &&
+		// direct use: each textured slot reads its own channel (any colour channel of a grey image
+		// reads the same value), no bias, and a scale expressible as a factor
+		const grey = sameTexture && textured.some( ( s ) => s.term.channel !== s.out ) && await this.isGrey( tex.file );
+		const direct = sameTexture && textured.every( ( s ) => ( s.term.channel === s.out || ( grey && s.term.channel < 3 && s.out < 3 ) ) && Math.abs( s.term.bias ) < 1e-6 && ( allowFactor || Math.abs( s.term.scale - 1 ) < 1e-6 ) ) &&
 			slots.every( ( s ) => ! s || s.term.tex || s.ignoreConst || ( allowFactor && s.constOk ) );
 
 		if ( direct ) {
@@ -588,47 +604,64 @@ export class MaterialConverter {
 
 		}
 
+		const key = 'baked:' + slots.map( ( s ) => s ? `${ s.term.tex?.file }#${ s.term.channel }*${ s.term.scale }+${ s.term.bias }` : '-' ).join( ',' );
+		let imageIndex = this.images.get( key )?.index;
+
+		if ( imageIndex === undefined ) {
+
+			const image = this.bake( slots, textured, sources );
+			imageIndex = this.builder.addImage( await encodePNGAsync( image ), 'image/png', imageName( tex.file ) + '_packed' );
+			this.images.set( key, { index: imageIndex, mimeType: 'image/png' } );
+
+		}
+
+		return { info: this.textureInfo( imageIndex, tex, key ), factors: slots.map( () => 1 ) };
+
+	}
+
+	// Writes each slot's term into its output channel, resampling sources to the largest size.
+	// Only the channels glTF reads are stored: grey for a lone R, RGB, or RGBA when alpha is used.
+	bake( slots, textured, sources ) {
+
 		const width = Math.max( ...sources.map( ( s ) => s.width ) );
 		const height = Math.max( ...sources.map( ( s ) => s.height ) );
-		const out = new Uint8Array( width * height * 4 );
+		const used = slots.map( ( s, c ) => ( s ? c : - 1 ) ).filter( ( c ) => c >= 0 );
+		const channels = used.length === 1 && used[ 0 ] === 0 ? 1 : used.includes( 3 ) ? 4 : 3;
+		const out = new Uint8Array( width * height * channels );
 		const srcOf = new Map( textured.map( ( s, i ) => [ s, sources[ i ] ] ) );
 
-		for ( let c = 0; c < 4; c ++ ) {
+		for ( let c = 0; c < channels; c ++ ) {
 
 			const slot = slots.find( ( s ) => s && s.out === c );
 
-			if ( ! slot ) {
+			if ( ! slot || ! slot.term.tex ) {
 
-				for ( let i = c; i < out.length; i += 4 ) out[ i ] = 255;
+				const v = slot ? Math.round( clamp01( slot.term.bias ) * 255 ) : 255;
+				for ( let i = c; i < out.length; i += channels ) out[ i ] = v;
 				continue;
 
 			}
 
 			const { term } = slot;
-
-			if ( ! term.tex ) {
-
-				const v = Math.round( clamp01( term.bias ) * 255 );
-				for ( let i = c; i < out.length; i += 4 ) out[ i ] = v;
-				continue;
-
-			}
-
 			const src = srcOf.get( slot );
 			const max = src.bitDepth === 16 ? 65535 : 255;
-			const sc = Math.min( term.channel, src.channels - 1 );
 			const alphaMissing = term.channel === 3 && src.channels < 4 && src.channels !== 2;
-			const channel = src.channels === 2 && term.channel === 3 ? 1 : src.channels <= 2 && term.channel < 3 ? 0 : sc;
+			const channel = src.channels === 2 && term.channel === 3 ? 1 : src.channels <= 2 && term.channel < 3 ? 0 : Math.min( term.channel, src.channels - 1 );
 
-			for ( let y = 0; y < height; y ++ ) {
+			// output = clamp( raw / max * scale + bias ) * 255, as one multiply and add per pixel
+			const k = term.scale * 255 / max, b = term.bias * 255 + 0.5;
+			const xs = new Int32Array( width );
+			for ( let x = 0; x < width; x ++ ) xs[ x ] = Math.min( src.width - 1, Math.floor( x * src.width / width ) ) * src.channels + channel;
+			const data = src.data, sw = src.width * src.channels;
 
-				const sy = Math.min( src.height - 1, Math.floor( y * src.height / height ) );
+			for ( let y = 0, o = c; y < height; y ++ ) {
 
-				for ( let x = 0; x < width; x ++ ) {
+				const row = Math.min( src.height - 1, Math.floor( y * src.height / height ) ) * sw;
 
-					const sx = Math.min( src.width - 1, Math.floor( x * src.width / width ) );
-					const raw = alphaMissing ? 1 : src.data[ ( sy * src.width + sx ) * src.channels + channel ] / max;
-					out[ ( y * width + x ) * 4 + c ] = Math.round( clamp01( raw * term.scale + term.bias ) * 255 );
+				for ( let x = 0; x < width; x ++, o += channels ) {
+
+					const v = alphaMissing ? 255 * term.scale + b : data[ row + xs[ x ] ] * k + b;
+					out[ o ] = v <= 0 ? 0 : v >= 255 ? 255 : v | 0;
 
 				}
 
@@ -636,16 +669,7 @@ export class MaterialConverter {
 
 		}
 
-		const key = 'baked:' + slots.map( ( s ) => s ? `${ s.term.tex?.file }#${ s.term.channel }*${ s.term.scale }+${ s.term.bias }` : '-' ).join( ',' );
-		let imageIndex = this.images.get( key )?.index;
-		if ( imageIndex === undefined ) {
-
-			imageIndex = this.builder.addImage( encodePNG( { width, height, channels: 4, data: out } ), 'image/png', imageName( tex.file ) + '_packed' );
-			this.images.set( key, { index: imageIndex, mimeType: 'image/png' } );
-
-		}
-
-		return { info: this.textureInfo( imageIndex, tex, key ), factors: slots.map( () => 1 ) };
+		return { width, height, channels, data: out };
 
 	}
 

package/src/image/index.js

@@ -37,6 +37,34 @@ export function imageMimeType( bytes ) {
 
 }
 
+/**
+ * Whether a PNG or JPEG stores a single grey channel, from its header.
+ * @param {Uint8Array} bytes
+ */
+export function isGreyscaleImage( bytes ) {
+
+	bytes = toBytes( bytes );
+	const type = imageMimeType( bytes );
+	if ( type === 'image/png' ) return bytes[ 25 ] === 0 || bytes[ 25 ] === 4; // IHDR colour type
+
+	if ( type === 'image/jpeg' ) {
+
+		// walk the markers to the frame header, whose component count follows the dimensions
+		for ( let o = 2; o + 9 < bytes.length; ) {
+
+			if ( bytes[ o ] !== 0xFF ) return false;
+			const marker = bytes[ o + 1 ];
+			if ( marker >= 0xC0 && marker <= 0xCF && marker !== 0xC4 && marker !== 0xC8 && marker !== 0xCC ) return bytes[ o + 9 ] === 1;
+			o += 2 + ( ( bytes[ o + 2 ] << 8 ) | bytes[ o + 3 ] );
+
+		}
+
+	}
+
+	return false;
+
+}
+
 /**
  * Decodes a PNG, JPEG or WebP. The format is sniffed from the bytes; mimeType is only a fallback.
  * @param {Uint8Array|ArrayBuffer} bytes
@@ -57,6 +85,55 @@ export function decodeImage( bytes, mimeType ) {
 
 const hasNativeDecoder = typeof createImageBitmap === 'function' && typeof OffscreenCanvas === 'function';
 
+/**
+ * Encodes a PNG, with the platform's encoder where there is one (much faster) unless the image has
+ * partial transparency, which canvases store premultiplied.
+ * @param {{ width: number, height: number, channels: number, data: Uint8Array }} image 8 bit
+ * @returns {Promise<Uint8Array>}
+ */
+export async function encodePNGAsync( image ) {
+
+	const { width, height, channels, data } = image;
+	let opaque = channels !== 2 && channels !== 4;
+	if ( ! opaque ) {
+
+		opaque = true;
+		for ( let i = channels - 1; i < data.length; i += channels ) if ( data[ i ] !== 255 ) { opaque = false; break; }
+
+	}
+
+	if ( hasNativeDecoder && opaque && ( image.bitDepth ?? 8 ) === 8 ) {
+
+		try {
+
+			const rgba = new Uint8ClampedArray( width * height * 4 );
+			for ( let i = 0, n = width * height; i < n; i ++ ) {
+
+				const s = i * channels;
+				rgba[ i * 4 ] = data[ s ];
+				rgba[ i * 4 + 1 ] = data[ channels >= 3 ? s + 1 : s ];
+				rgba[ i * 4 + 2 ] = data[ channels >= 3 ? s + 2 : s ];
+				rgba[ i * 4 + 3 ] = 255;
+
+			}
+
+			const canvas = new OffscreenCanvas( width, height );
+			canvas.getContext( '2d' ).putImageData( new ImageData( rgba, width, height ), 0, 0 );
+			const blob = await canvas.convertToBlob( { type: 'image/png' } );
+			return new Uint8Array( await blob.arrayBuffer() );
+
+		} catch {
+
+			// fall through to the JavaScript encoder
+
+		}
+
+	}
+
+	return encodePNG( image );
+
+}
+
 /**
  * Decodes with the platform's image decoder where there is one (browsers and workers), which is
  * faster and supports more formats, falling back to the JavaScript decoders (Node).

package/src/index.d.ts

@@ -0,0 +1,71 @@
+/** 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>;
+
+export interface USDToGLBOptions {
+	/** 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 {
+	/** 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 and a binary buffer into a GLB. */
+export function writeGLB( json: object, 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/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() ) {