@unikia/upe-renderer 0.186.110 → 0.187.11

package/examples/jsm/loaders/materialx/MaterialXDocument.js

@@ -1,10 +1,8 @@
 import {
 	Texture,
-	RepeatWrapping,
-	ClampToEdgeWrapping,
-	MirroredRepeatWrapping,
 	ImageLoader,
 	ImageBitmapLoader,
+	LoaderUtils,
 	Matrix3,
 	Matrix4,
 	MeshBasicNodeMaterial,
@@ -13,6 +11,7 @@ import {
 
 import {
 	float,
+	texture,
 	int,
 	bool,
 	sub,
@@ -26,6 +25,14 @@ import {
 	element,
 	mx_transform_uv,
 	mx_srgb_texture_to_lin_rec709,
+	positionLocal,
+	positionWorld,
+	normalLocal,
+	normalWorld,
+	tangentLocal,
+	tangentWorld,
+	bitangentLocal,
+	bitangentWorld,
 } from 'three/tsl';
 
 import { MaterialXLogCodes } from './MaterialXLog.js';
@@ -33,8 +40,9 @@ import { createMaterialXCompileRegistry, compileNodeFromRegistry } from './compi
 import { parseMaterialXNodeTree, parseMaterialXText } from './parse/MaterialXParser.js';
 import { getSurfaceMapper } from './MaterialXSurfaceMappings.js';
 import { MtlXLibrary } from './MaterialXNodeLibrary.js';
+import { resolveNodeDef } from './MaterialXNodeDefs.js';
 import { mxHextileCoord, mxHextileComputeBlendWeights } from './MaterialXHextile.js';
-import { toBooleanNode } from './MaterialXUtils.js';
+import { resolveTextureAddressMode, TEXTURE_ADDRESS_MODE_WRAPPING, toBooleanNode } from './MaterialXUtils.js';
 
 const colorSpaceLib = {
 	mx_srgb_texture_to_lin_rec709,
@@ -45,12 +53,6 @@ const IDENTITY_MAT3_VALUES = [ 1, 0, 0, 0, 1, 0, 0, 0, 1 ];
 const IDENTITY_MAT4_VALUES = [ 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1 ];
 const MATRIX_INVERSE_EPSILON = 1e-8;
 const COMPILE_REGISTRY = createMaterialXCompileRegistry();
-const TEXTURE_ADDRESS_MODE_WRAPPING = {
-	constant: ClampToEdgeWrapping,
-	clamp: ClampToEdgeWrapping,
-	periodic: RepeatWrapping,
-	mirror: MirroredRepeatWrapping,
-};
 const NODE_CLASS_BY_TYPE = {
 	integer: int,
 	float,
@@ -63,6 +65,84 @@ const NODE_CLASS_BY_TYPE = {
 	matrix33: mat3,
 	matrix44: mat4,
 };
+// Geometric properties a nodedef input can default to via `defaultgeomprop`.
+const GEOMPROP_NODES = {
+	Pobject: positionLocal,
+	Pworld: positionWorld,
+	Nobject: normalLocal,
+	Nworld: normalWorld,
+	Tobject: tangentLocal,
+	Tworld: tangentWorld,
+	Bobject: bitangentLocal,
+	Bworld: bitangentWorld,
+	Vworld: MtlXLibrary.viewdirection.nodeFunc( 'world' ),
+};
+
+function parseValueVector( value ) {
+
+	const vector = [];
+	for ( const val of value.split( /[,|\s]/ ) ) {
+
+		if ( val !== '' ) vector.push( Number( val.trim() ) );
+
+	}
+
+	return vector;
+
+}
+
+function createMatrixNode( size, vector ) {
+
+	const expectedLength = size * size;
+	if ( vector.length !== expectedLength ) return null;
+
+	// MaterialX matrix values are serialized in column-major order.
+	// Reorder to row-major before constructing TSL matrix nodes so
+	// transformmatrix semantics match MaterialXJS and MaterialXView.
+	const reordered = [];
+	for ( let row = 0; row < size; row += 1 ) {
+
+		for ( let column = 0; column < size; column += 1 ) {
+
+			reordered.push( vector[ column * size + row ] );
+
+		}
+
+	}
+
+	return size === 3 ? mat3( ...reordered ) : mat4( ...reordered );
+
+}
+
+// Empty strings are valid string defaults, but an empty filename means "no texture".
+function hasDefaultValue( input ) {
+
+	if ( input.value === undefined ) return false;
+	return input.value !== '' || input.type === 'string';
+
+}
+
+// string values stay strings so the compiler can read e.g. space names
+function createValueNode( type, value ) {
+
+	const trimmed = value.trim();
+
+	if ( type === 'boolean' ) {
+
+		const normalized = trimmed.toLowerCase();
+		return bool( normalized === 'true' || normalized === '1' );
+
+	}
+
+	if ( type === 'matrix33' ) return createMatrixNode( 3, parseValueVector( trimmed ) ) || mat3( ...IDENTITY_MAT3_VALUES );
+	if ( type === 'matrix44' ) return createMatrixNode( 4, parseValueVector( trimmed ) ) || mat4( ...IDENTITY_MAT4_VALUES );
+	if ( type === 'string' || type === 'filename' ) return trimmed;
+
+	const nodeClass = NODE_CLASS_BY_TYPE[ type ];
+	return nodeClass ? nodeClass( ...parseValueVector( trimmed ) ) : float( 0 );
+
+}
+
 const OUTPUT_CHANNELS = {
 	outx: 0,
 	outr: 0,
@@ -111,15 +191,6 @@ function isSvgUri( uri ) {
 
 }
 
-function normalizeTextureAddressMode( value ) {
-
-	if ( value === null || value === undefined || value === '' ) return 'periodic';
-
-	const mode = value.trim().toLowerCase();
-	return mode in TEXTURE_ADDRESS_MODE_WRAPPING ? mode : null;
-
-}
-
 function invertConstantMatrixValues( values, size ) {
 
 	if ( ! Array.isArray( values ) || values.length !== size * size ) return null;
@@ -170,6 +241,7 @@ class MaterialXNode {
 		this.parent = null;
 		this.node = null;
 		this.children = [];
+		this._nodeDef = undefined;
 
 	}
 
@@ -273,6 +345,19 @@ class MaterialXNode {
 
 		return this.referencePath !== null;
 
+	}
+
+	getReferencedNode() {
+
+		if ( this.nodeGraph !== null ) {
+
+			const graph = this.materialX.getMaterialXNode( this.nodeGraph );
+			return graph ? this.output !== null ? graph.getChildByName( this.output ) || null : graph.children.find( ( child ) => child.element === 'output' ) || null : null;
+
+		}
+
+		return this.hasReference ? this.materialX.getMaterialXNode( this.referencePath ) || null : null;
+
 	}
 	get isConst() {
 
@@ -280,9 +365,65 @@ class MaterialXNode {
 
 	}
 
+	/**
+	 * The stdlib or document nodedef this node instance resolves to, or `null` when the category is unknown.
+	 *
+	 * @type {?Object}
+	 */
+	get nodeDef() {
+
+		if ( this._nodeDef === undefined ) this._nodeDef = resolveNodeDef( this );
+		return this._nodeDef;
+
+	}
+
+	hasDeclaredOutput( name ) {
+
+		return this.nodeDef !== null && name in this.nodeDef.outputs;
+
+	}
+
+	// The declared type of a nodedef input, or `null` when the nodedef does not declare it.
+	getNodeDefInputType( name ) {
+
+		const input = this.nodeDef ? this.nodeDef.inputs[ name ] : undefined;
+		return input ? input.type : null;
+
+	}
+
+	// `undefined` when the nodedef declares no default (e.g. filenames)
+	getDefaultInputNode( name ) {
+
+		const input = this.nodeDef ? this.nodeDef.inputs[ name ] : undefined;
+		if ( ! input ) return undefined;
+
+		if ( input.defaultgeomprop ) return this.materialX.compileContext.getGeomPropNode( input.defaultgeomprop );
+		if ( ! hasDefaultValue( input ) ) return undefined;
+
+		return createValueNode( input.type, input.value );
+
+	}
+
+	// geometric defaults are left out so surface mappers can tell an authored normal from the default
+	getDefaultInputNodes() {
+
+		const nodes = {};
+		if ( this.nodeDef === null ) return nodes;
+
+		for ( const [ name, input ] of Object.entries( this.nodeDef.inputs ) ) {
+
+			if ( input.defaultgeomprop || ! hasDefaultValue( input ) ) continue;
+			nodes[ name ] = createValueNode( input.type, input.value );
+
+		}
+
+		return nodes;
+
+	}
+
 	getColorSpaceNode() {
 
-		const csSource = this.getAttribute( 'colorspace' );
+		const csSource = this.getValueInput().getAttribute( 'colorspace' ) || this.getAttribute( 'colorspace' );
 		const csTarget = this.getRoot().getAttribute( 'colorspace' );
 		if ( ! csSource || ! csTarget ) return null;
 		const nodeName = `mx_${csSource}_to_${csTarget}`;
@@ -290,10 +431,23 @@ class MaterialXNode {
 
 	}
 
+	logUnsupportedNode() {
+
+		this.materialX.log.add(
+			MaterialXLogCodes.UNSUPPORTED_NODE,
+			`Unsupported MaterialX node category "${this.element}" on "${this.name}".`,
+			this.name,
+		);
+
+	}
+
 	getTextureAddressMode( inputName ) {
 
-		const rawMode = this.getInputValueByName( inputName );
-		const mode = normalizeTextureAddressMode( rawMode );
+		// e.g. tiledimage, which samples with the image node's default addressing.
+		if ( this.declaresInput( inputName ) === false ) return 'periodic';
+
+		const rawMode = this.getNodeByName( inputName );
+		const mode = resolveTextureAddressMode( rawMode );
 		if ( mode ) return mode;
 
 		this.materialX.log.add(
@@ -314,10 +468,22 @@ class MaterialXNode {
 
 	}
 
+	// Follow an interfacename binding to its source input.
+	getValueInput() {
+
+		if ( this.interfaceName === null ) return this;
+		const boundInput = this.materialX.getInterfaceInput( this );
+		return boundInput !== null ? boundInput : this;
+
+	}
+
 	getTexture() {
 
-		const filePrefix = this.getRecursiveAttribute( 'fileprefix' ) || '';
-		const sourceURI = filePrefix + this.value;
+		const valueInput = this.getValueInput();
+		if ( valueInput.getValue() === '' ) return null;
+
+		const filePrefix = valueInput.getRecursiveAttribute( 'fileprefix' ) || '';
+		const sourceURI = filePrefix + valueInput.value;
 		const resolvedURI = this.materialX.resolveTextureURI( sourceURI );
 		const svgTexture = isSvgUri( resolvedURI );
 		const textureSourceNode = this.parent && typeof this.parent.getTextureAddressModes === 'function' ? this.parent : this;
@@ -331,29 +497,66 @@ class MaterialXNode {
 		}
 
 		let loader = svgTexture ? this.materialX.imageLoader : this.materialX.textureLoader;
+		let textureURL = resolvedURI;
 		if ( resolvedURI && ! svgTexture ) {
 
 			const handler = this.materialX.manager.getHandler( resolvedURI );
-			if ( handler !== null ) loader = handler;
+			if ( handler !== null ) {
+
+				// The built-in loaders carry the document path; handlers do not.
+				loader = handler;
+				textureURL = LoaderUtils.resolveURL( resolvedURI, this.materialX.path );
+
+			}
 
 		}
 
-		const textureNode = new Texture();
-		textureNode.wrapS = TEXTURE_ADDRESS_MODE_WRAPPING[ addressModes.u ];
-		textureNode.wrapT = TEXTURE_ADDRESS_MODE_WRAPPING[ addressModes.v ];
-		textureNode.flipY = false;
+		const textureNode = texture( new Texture() );
+		textureNode.value.wrapS = TEXTURE_ADDRESS_MODE_WRAPPING[ addressModes.u ];
+		textureNode.value.wrapT = TEXTURE_ADDRESS_MODE_WRAPPING[ addressModes.v ];
+		textureNode.value.flipY = false;
 		this.materialX.textureCache.set( textureCacheKey, textureNode );
 
-		loader.load( resolvedURI, ( imageData ) => {
+		const nodeName = this.name;
+		const materialX = this.materialX;
+
+		materialX.pendingResources.push( new Promise( ( resolveLoad ) => {
+
+			loader.load( textureURL, ( imageData ) => {
 
-			textureNode.image = imageData;
-			textureNode.needsUpdate = true;
+				if ( imageData.isTexture ) {
 
-		}, undefined, () => {
+					// Clone so the wrapping and orientation set below don't modify the handler's texture.
+					textureNode.value = imageData.clone();
+					textureNode.value.wrapS = TEXTURE_ADDRESS_MODE_WRAPPING[ addressModes.u ];
+					textureNode.value.wrapT = TEXTURE_ADDRESS_MODE_WRAPPING[ addressModes.v ];
 
-			throw new Error( `Failed to load texture "${resolvedURI}".` );
+					// MaterialXLoader keeps textures top-first. Loaders such as EXRLoader store rows
+					// bottom-first (flipY = false), so invert the loader's orientation to match.
+					// flipY has no meaning for compressed textures.
+					if ( imageData.isCompressedTexture !== true ) textureNode.value.flipY = ! imageData.flipY;
 
-		} );
+				} else {
+
+					textureNode.value.image = imageData;
+
+				}
+
+				textureNode.value.needsUpdate = true;
+				resolveLoad();
+
+			}, undefined, () => {
+
+				materialX.log.add(
+					MaterialXLogCodes.TEXTURE_LOAD_FAILED,
+					`Failed to load texture "${resolvedURI}".`,
+					nodeName,
+				);
+				resolveLoad();
+
+			} );
+
+		} ) );
 
 		return textureNode;
 
@@ -373,12 +576,17 @@ class MaterialXNode {
 
 	getNode( out = null ) {
 
-		if ( this.node !== null && out === null ) return this.node;
+		// A named output must not replace the cached default output.
+		const cacheDefaultOutput = out === null;
+		const cachedNode = this.materialX.getCachedNode( this );
+		if ( cachedNode !== null && cacheDefaultOutput ) return cachedNode;
 
 		let node;
+		let implemented = false;
 
 
-		if ( ( this.element === 'separate2' || this.element === 'separate3' || this.element === 'separate4' ) && out ) {
+		// A connection that names no output reads the first one, as in MaterialX.
+		if ( this.element === 'separate2' || this.element === 'separate3' || this.element === 'separate4' ) {
 
 			const inNode = this.getNodeByName( 'in' );
 			return element( inNode, getOutputChannel( out ) );
@@ -386,33 +594,12 @@ class MaterialXNode {
 		}
 
 		const type = this.type;
-		const channelRequested = this.element !== 'input' && this.element !== 'gltf_colorimage' && isChannelOutput( out );
+		// Channel suffixes (outr, outy, ...) extract a component unless the nodedef declares an output of that name.
+		const channelRequested = this.element !== 'input' && isChannelOutput( out ) && this.hasDeclaredOutput( out ) === false;
 
 		if ( this.isConst ) {
 
-			if ( type === 'boolean' ) {
-
-				const normalized = this.getValue().trim().toLowerCase();
-				node = bool( normalized === 'true' || normalized === '1' );
-
-			} else if ( type === 'matrix33' ) {
-
-				node = this.getMatrix( 3 ) || mat3( 1, 0, 0, 0, 1, 0, 0, 0, 1 );
-
-			} else if ( type === 'matrix44' ) {
-
-				node = this.getMatrix( 4 ) || mat4( 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1 );
-
-			} else if ( type === 'string' ) {
-
-				node = this.getValue();
-
-			} else {
-
-				const nodeClass = this.getClassFromType( type );
-				node = nodeClass ? nodeClass( ...this.getVector() ) : float( 0 );
-
-			}
+			node = createValueNode( type, this.getValue() );
 
 		} else if ( this.hasReference ) {
 
@@ -426,9 +613,14 @@ class MaterialXNode {
 
 			}
 
-			const referenceNode = this.materialX.getMaterialXNode( this.referencePath );
+			const interfaceNode = this.interfaceName !== null ? this.materialX.getInterfaceNode( this ) : null;
+			const referenceNode = interfaceNode === null ? this.materialX.getMaterialXNode( this.referencePath ) : null;
+
+			if ( interfaceNode !== null ) {
 
-			if ( referenceNode ) {
+				node = interfaceNode;
+
+			} else if ( referenceNode ) {
 
 				node = referenceNode.getNode( requestedOutput );
 
@@ -443,31 +635,22 @@ class MaterialXNode {
 
 			}
 
-		} else if ( this.element === 'input' && this.name === 'texcoord' && this.type === 'vector2' ) {
-
-			let index = 0;
-			const defaultGeomProp = this.getAttribute( 'defaultgeomprop' );
-			if ( defaultGeomProp && /^UV(\d+)$/.test( defaultGeomProp ) ) {
+		} else if ( this.element === 'input' && this.getAttribute( 'defaultgeomprop' ) !== null ) {
 
-				index = parseInt( defaultGeomProp.match( /^UV(\d+)$/ )[ 1 ], 10 );
-
-			}
-
-			node = this.materialX.compileContext.mxToBottomLeftUvSpace( uv( index ) );
+			// An unconnected interface input takes its value from its declared geometric property.
+			node = this.materialX.compileContext.getGeomPropNode( this.getAttribute( 'defaultgeomprop' ) );
 
 		} else {
 
-			node = compileNodeFromRegistry( this, out, this.materialX.compileContext );
+			const resolvedNode = this.materialX.nodeResolver !== null ? this.materialX.nodeResolver( this, out ) : null;
+			implemented = ( resolvedNode === null || resolvedNode === undefined ) && this.materialX.getScope( this ) !== null;
+			node = resolvedNode !== null && resolvedNode !== undefined ? resolvedNode : implemented ? this.materialX.compileImplementation( this, channelRequested ? null : out ) : compileNodeFromRegistry( this, out, this.materialX.compileContext );
 
 		}
 
 		if ( node === null || node === undefined ) {
 
-			this.materialX.log.add(
-				MaterialXLogCodes.UNSUPPORTED_NODE,
-				`Unsupported MaterialX node category "${this.element}" on "${this.name}".`,
-				this.name,
-			);
+			this.logUnsupportedNode();
 			node = float( 0 );
 
 		}
@@ -515,7 +698,7 @@ class MaterialXNode {
 
 		}
 
-		this.node = node;
+		if ( cacheDefaultOutput ) this.materialX.setCachedNode( this, node );
 		return node;
 
 	}
@@ -544,17 +727,43 @@ class MaterialXNode {
 
 	}
 
-	getNodeByName( name ) {
+	getInputTypes() {
 
-		const child = this.getChildByName( name );
-		return child ? child.getNode( child.output ) : undefined;
+		const types = {};
+		for ( const input of this.children ) {
+
+			types[ input.name ] = input.type;
+
+		}
+
+		return types;
+
+	}
+
+	// nodes without a nodedef (e.g. from a host node resolver) accept any input
+	declaresInput( name ) {
+
+		return this.getChildByName( name ) !== undefined || this.nodeDef === null || name in this.nodeDef.inputs;
 
 	}
 
-	getInputValueByName( name ) {
+	getNodeByName( name ) {
 
 		const child = this.getChildByName( name );
-		return child ? child.value : null;
+		if ( child ) return child.getNode( child.output );
+
+		if ( this.declaresInput( name ) === false ) {
+
+			this.materialX.log.add(
+				MaterialXLogCodes.UNKNOWN_INPUT,
+				`"${this.element}" reads input "${name}", which nodedef "${this.nodeDef.name}" does not declare. Using fallback 0.`,
+				this.name,
+			);
+			return float( 0 );
+
+		}
+
+		return this.getDefaultInputNode( name );
 
 	}
 
@@ -580,37 +789,7 @@ class MaterialXNode {
 
 	getVector() {
 
-		const vector = [];
-		for ( const val of this.getValue().split( /[,|\s]/ ) ) {
-
-			if ( val !== '' ) vector.push( Number( val.trim() ) );
-
-		}
-
-		return vector;
-
-	}
-
-	getMatrix( size ) {
-
-		const vector = this.getVector();
-		const expectedLength = size * size;
-		if ( vector.length !== expectedLength ) return null;
-		// MaterialX matrix values are serialized in column-major order.
-		// Reorder to row-major before constructing TSL matrix nodes so
-		// transformmatrix semantics match MaterialXJS and MaterialXView.
-		const reordered = [];
-		for ( let row = 0; row < size; row += 1 ) {
-
-			for ( let column = 0; column < size; column += 1 ) {
-
-				reordered.push( vector[ column * size + row ] );
-
-			}
-
-		}
-
-		return size === 3 ? mat3( ...reordered ) : mat4( ...reordered );
+		return parseValueVector( this.getValue() );
 
 	}
 
@@ -640,26 +819,33 @@ class MaterialXNode {
 
 	}
 
-	setMaterial( material ) {
+	setMaterial( material, out = null ) {
+
+		if ( this.element === 'input' || this.element === 'output' ) {
+
+			const shader = this.getReferencedNode();
+			if ( shader !== null ) shader.setMaterial( material, this.nodeGraph !== null ? null : this.output || out );
+			return;
+
+		}
+
+		if ( this.materialX.setImplementationMaterial( this, material, out ) ) return;
 
 		const mapper = getSurfaceMapper( this.element );
 		if ( mapper ) {
 
-			mapper.apply( material, this.getNodes(), this.materialX.log, this.name );
+			const authored = this.getNodes();
+			mapper.apply( material, { ...this.getDefaultInputNodes(), ...authored }, this.materialX.log, this.name, authored, this.getInputTypes() );
 
 		} else {
 
-			this.materialX.log.add(
-				MaterialXLogCodes.UNSUPPORTED_NODE,
-				`Unsupported MaterialX node category "${this.element}" on "${this.name}".`,
-				this.name,
-			);
+			this.logUnsupportedNode();
 
 		}
 
 	}
 
-	toBasicMaterial() {
+	toNodeGraphMaterial() {
 
 		const material = new MeshBasicNodeMaterial();
 		material.name = this.name;
@@ -681,29 +867,49 @@ class MaterialXNode {
 
 	resolveSurfaceShaderNode( nodeX ) {
 
-		if ( nodeX.hasReference ) {
-
-			return this.materialX.getMaterialXNode( nodeX.referencePath ) || null;
+		const visited = new Set();
+		let shader = nodeX || null;
+		let out = null;
 
-		}
+		while ( shader !== null && ( shader.element === 'input' || shader.element === 'output' ) ) {
 
-		if ( nodeX.nodeName ) {
-
-			return this.materialX.getMaterialXNode( nodeX.nodeName ) || null;
+			if ( visited.has( shader ) ) return null;
+			visited.add( shader );
+			out = shader.nodeGraph !== null ? null : shader.output;
+			shader = shader.getReferencedNode();
 
 		}
 
-		return null;
+		return shader !== null ? this.materialX.resolveImplementationShader( shader, out ) : null;
 
 	}
 
-	toPhysicalMaterial() {
+	toSurfaceMaterial() {
 
-		const material = new MeshPhysicalNodeMaterial();
+		const surfaceShader = this.resolveSurfaceShaderNode( this.getChildByName( 'surfaceshader' ) );
+		const material = surfaceShader?.nodeDef?.name === 'ND_surface_unlit' ? new MeshBasicNodeMaterial() : new MeshPhysicalNodeMaterial();
 		material.name = this.name;
 
 		for ( const nodeX of this.children ) {
 
+			if ( nodeX.name === 'backsurfaceshader' ) {
+
+				// MaterialX supports separate back-surface shaders. Their use in practice
+				// is unclear; translating them per face is left for future work.
+				if ( nodeX.hasReference || nodeX.nodeGraph !== null ) {
+
+					this.materialX.log.add(
+						MaterialXLogCodes.IGNORED_SURFACE_INPUT,
+						'surfacematerial input "backsurfaceshader" is currently ignored in MaterialX translation.',
+						this.name,
+					);
+
+				}
+
+				continue;
+
+			}
+
 			const shaderProperties = this.resolveSurfaceShaderNode( nodeX );
 			if ( shaderProperties === null ) {
 
@@ -716,7 +922,7 @@ class MaterialXNode {
 
 			}
 
-			shaderProperties.setMaterial( material );
+			nodeX.setMaterial( material );
 
 		}
 
@@ -747,7 +953,7 @@ class MaterialXNode {
 
 		for ( const nodeX of selectedSurfaceMaterials ) {
 
-			const material = nodeX.toPhysicalMaterial();
+			const material = nodeX.toSurfaceMaterial();
 			materials[ material.name ] = material;
 
 		}
@@ -756,9 +962,10 @@ class MaterialXNode {
 
 			for ( const nodeX of this.children ) {
 
-				if ( nodeX.element === 'nodegraph' ) {
+				// Only standalone nodegraphs should create preview materials.
+				if ( nodeX.element === 'nodegraph' && nodeX.getAttribute( 'nodedef' ) === null && this.materialX.implementationGraphNodes.has( nodeX ) === false ) {
 
-					const material = nodeX.toBasicMaterial();
+					const material = nodeX.toNodeGraphMaterial();
 					materials[ material.name ] = material;
 
 				}
@@ -797,12 +1004,28 @@ class MaterialXDocument {
 		this.textureLoader.setOptions( { imageOrientation: 'none' } );
 		this.textureLoader.setPath( path );
 		this.textureCache = new Map();
+		this.pendingResources = [];
+		this.nodeResolver = null;
+		this.documentNodeDefs = null;
+
+		this.implementationGraphs = new Map();
+		this.implementationGraphNodes = new Set();
+		this.scope = null;
+		this.rootScopes = new Map();
 		const bottomLeftUvSpaceHelpers = getBottomLeftUvSpaceHelpers( this.uvSpace );
 
 		this.compileContext = {
 			compileRegistry: COMPILE_REGISTRY,
 			nodeLibrary: MtlXLibrary,
 			...bottomLeftUvSpaceHelpers,
+			getTexcoordNode: ( index = 0 ) => bottomLeftUvSpaceHelpers.mxToBottomLeftUvSpace( uv( index ) ),
+			getGeomPropNode: ( name ) => {
+
+				const uvMatch = /^UV(\d+)$/.exec( name );
+				if ( uvMatch ) return bottomLeftUvSpaceHelpers.mxToBottomLeftUvSpace( uv( parseInt( uvMatch[ 1 ], 10 ) ) );
+				return GEOMPROP_NODES[ name ];
+
+			},
 			mxTransformUv: mx_transform_uv,
 			mxHextileCoord,
 			mxHextileComputeBlendWeights,
@@ -826,6 +1049,207 @@ class MaterialXDocument {
 
 	}
 
+	indexImplementations( rootNode ) {
+
+		for ( const nodeX of rootNode.children ) {
+
+			const nodeDefName = nodeX.getAttribute( 'nodedef' );
+			const graphName = nodeX.element === 'implementation' ? nodeX.getAttribute( 'nodegraph' ) : null;
+			const graph = nodeX.element === 'nodegraph' && nodeDefName !== null ? nodeX : graphName !== null ? this.getMaterialXNode( graphName ) : undefined;
+			if ( graph === undefined ) continue;
+
+			this.implementationGraphNodes.add( graph );
+			if ( this.implementationGraphs.has( nodeDefName ) === false ) this.implementationGraphs.set( nodeDefName, graph );
+
+		}
+
+	}
+
+	// Each custom node instance needs its own inputs and cached TSL nodes.
+	getScope( materialXNode ) {
+
+		const nodeDef = materialXNode.nodeDef;
+		const graph = nodeDef !== null ? this.implementationGraphs.get( nodeDef.name ) : undefined;
+		if ( graph === undefined ) return null;
+
+		for ( let parent = this.scope; parent !== null; parent = parent.parent ) {
+
+			if ( parent.graph === graph ) {
+
+				this.log.add(
+					MaterialXLogCodes.INVALID_VALUE,
+					`The nodegraph of "${ materialXNode.element }" uses the node it implements.`,
+					materialXNode.name,
+				);
+				return null;
+
+			}
+
+		}
+
+		const scopes = this.scope !== null ? this.scope.childScopes : this.rootScopes;
+		let scope = scopes.get( materialXNode );
+
+		if ( scope === undefined ) {
+
+			scope = { instance: materialXNode, nodeDef, graph, parent: this.scope, nodes: new Map(), childScopes: new Map() };
+			scopes.set( materialXNode, scope );
+
+		}
+
+		return scope;
+
+	}
+
+	withScope( scope, callback ) {
+
+		const previous = this.scope;
+		this.scope = scope;
+
+		try {
+
+			return callback();
+
+		} finally {
+
+			this.scope = previous;
+
+		}
+
+	}
+
+	isInScope( materialXNode ) {
+
+		if ( this.scope === null ) return false;
+
+		for ( let parent = materialXNode.parent; parent !== null; parent = parent.parent ) {
+
+			if ( parent === this.scope.graph ) return true;
+
+		}
+
+		return false;
+
+	}
+
+	getCachedNode( materialXNode ) {
+
+		if ( this.isInScope( materialXNode ) ) return this.scope.nodes.get( materialXNode ) ?? null;
+		return materialXNode.node;
+
+	}
+
+	setCachedNode( materialXNode, node ) {
+
+		if ( this.isInScope( materialXNode ) ) this.scope.nodes.set( materialXNode, node );
+		else materialXNode.node = node;
+
+	}
+
+	getGraphOutput( scope, out ) {
+
+		// An omitted selector uses the first output declared by the nodedef.
+		const name = out === null ? Object.keys( scope.nodeDef.outputs )[ 0 ] : out;
+		return scope.graph.children.find( ( child ) => child.element === 'output' && child.name === name ) || null;
+
+	}
+
+	compileImplementation( materialXNode, out ) {
+
+		const scope = this.getScope( materialXNode );
+		if ( scope === null ) return null;
+
+		const output = this.getGraphOutput( scope, out );
+		if ( output === null ) {
+
+			this.log.add(
+				MaterialXLogCodes.MISSING_REFERENCE,
+				`Missing output "${ out || 'out' }" in the nodegraph of "${ materialXNode.name }".`,
+				materialXNode.name,
+			);
+			return float( 0 );
+
+		}
+
+		// Use the output selector stored on the graph output.
+		return this.withScope( scope, () => output.getNode() );
+
+	}
+
+	setImplementationMaterial( materialXNode, material, out ) {
+
+		const scope = this.getScope( materialXNode );
+		if ( scope === null ) return false;
+
+		const output = this.getGraphOutput( scope, out );
+		const shaderNode = output !== null && output.hasReference ? this.getMaterialXNode( output.referencePath ) : undefined;
+		if ( shaderNode === undefined ) {
+
+			this.log.add(
+				MaterialXLogCodes.MISSING_REFERENCE,
+				`Missing shader output "${ out || 'out' }" in the nodegraph of "${ materialXNode.name }".`,
+				materialXNode.name,
+			);
+			return true;
+
+		}
+
+		this.withScope( scope, () => shaderNode.setMaterial( material, output.output ) );
+		return true;
+
+	}
+
+	resolveImplementationShader( materialXNode, out ) {
+
+		const scope = this.getScope( materialXNode );
+		if ( scope === null ) return materialXNode;
+
+		const output = this.getGraphOutput( scope, out );
+		return this.withScope( scope, () => materialXNode.resolveSurfaceShaderNode( output ) );
+
+	}
+
+	// Resolve interfacename to the node instance's input.
+	// If that input is omitted, use the nodedef default.
+	getInterfaceInput( materialXNode ) {
+
+		// Regular nodegraphs bind to their own inputs.
+		if ( ! this.isInScope( materialXNode ) ) {
+
+			const graphInput = this.getMaterialXNode( materialXNode.referencePath );
+			return graphInput !== undefined && graphInput !== materialXNode ? graphInput : null;
+
+		}
+
+		const scope = this.scope;
+		const name = materialXNode.interfaceName;
+		const input = scope.instance.getChildByName( name );
+		if ( input !== undefined ) return this.withScope( scope.parent, () => input.getValueInput() );
+		const declaration = this.getMaterialXNode( scope.nodeDef.name );
+		return declaration ? declaration.getChildByName( name ) ?? null : null;
+
+	}
+
+	getInterfaceNode( materialXNode ) {
+
+		if ( ! this.isInScope( materialXNode ) ) return null;
+
+		const scope = this.scope;
+		const name = materialXNode.interfaceName;
+		const input = scope.instance.getChildByName( name );
+		// Evaluate the instance input in the parent scope to resolve nested interface bindings.
+		if ( input !== undefined ) return this.withScope( scope.parent, () => input.getNode( input.output ) );
+
+		return this.withScope( null, () => scope.instance.getDefaultInputNode( name ) ?? null );
+
+	}
+
+	waitForResources() {
+
+		return Promise.all( this.pendingResources ).then( () => undefined );
+
+	}
+
 	addMaterialXNode( materialXNode ) {
 
 		this.nodesXLib.set( materialXNode.nodePath, materialXNode );
@@ -838,6 +1262,49 @@ class MaterialXDocument {
 
 	}
 
+	// Convert document nodedefs to the format used by the stdlib registry.
+	getDocumentNodeDefs() {
+
+		if ( this.documentNodeDefs !== null ) return this.documentNodeDefs;
+
+		this.documentNodeDefs = {};
+
+		for ( const nodeX of this.nodesXLib.values() ) {
+
+			if ( nodeX.element !== 'nodedef' ) continue;
+
+			const nodedef = { node: nodeX.getAttribute( 'node' ), inputs: {}, outputs: {} };
+			const version = nodeX.getAttribute( 'version' );
+			if ( version ) nodedef.version = version;
+			if ( nodeX.getAttribute( 'isdefaultversion' ) === 'true' ) nodedef.isdefaultversion = true;
+			if ( nodeX.type && nodeX.type !== 'multioutput' ) nodedef.outputs.out = nodeX.type;
+
+			for ( const child of nodeX.children ) {
+
+				if ( child.element === 'output' ) {
+
+					nodedef.outputs[ child.name ] = child.type;
+
+				} else if ( child.element === 'input' ) {
+
+					const input = { type: child.type };
+					if ( child.value !== null ) input.value = child.value;
+					const geomprop = child.getAttribute( 'defaultgeomprop' );
+					if ( geomprop ) input.defaultgeomprop = geomprop;
+					nodedef.inputs[ child.name ] = input;
+
+				}
+
+			}
+
+			this.documentNodeDefs[ nodeX.name ] = nodedef;
+
+		}
+
+		return this.documentNodeDefs;
+
+	}
+
 	parseNode( nodeXML, nodePath = '' ) {
 
 		return parseMaterialXNodeTree(
@@ -851,12 +1318,17 @@ class MaterialXDocument {
 
 	parse( text, materialName = null, options = {} ) {
 
+		this.nodeResolver = options.nodeResolver || null;
+		this.documentNodeDefs = null;
+
 		const rootNode = parseMaterialXText(
 			text,
 			( childNodeXML, childNodePath ) => new MaterialXNode( this, childNodeXML, childNodePath ),
 			( materialXNode ) => this.addMaterialXNode( materialXNode ),
 		);
 
+		this.indexImplementations( rootNode );
+
 		if ( options.interfaceValidator ) {
 
 			options.interfaceValidator( rootNode, this.log );