rayzee 11.8.0 → 11.9.0

package/src/Processor/PBRT/PBRTSceneBuilder.js

@@ -24,8 +24,9 @@ import {
 	RepeatWrapping
 } from 'three';
 import { buildMaterial, pBool, pFloat, pString, resolveSpectrum } from './PBRTMaterials.js';
-import { makeLayer, layerMean, bake, mixOf, srgbToLinear, linearToSRGB, hasAlpha } from './PBRTTextureBake.js';
+import { makeLayer, layerMean, bake, mixOf, srgbToLinear, linearToSRGB, hasAlpha, generateUV, uvKey } from './PBRTTextureBake.js';
 import { loopSubdivide } from './LoopSubdivision.js';
+import { approximated, param } from './PBRTParser.js';
 import { octahedralToEquirect } from './EqualAreaOctahedral.js';
 import { tessellateCurve, tessellateCurves } from './PBRTCurves.js';
 import * as M from './PBRTMath.js';
@@ -36,7 +37,7 @@ const LAMP_TYPES = new Set( [ 'distant', 'point', 'spot' ] );
 // pbrt scales a light's spectrum to luminance 1 unless it is RGB, so a blackbody of any temperature is equally bright.
 async function lightRGB( params, name, ctx ) {
 
-	const p = params[ name ];
+	const p = param( params, name );
 	if ( p?.type === 'spectrum' && typeof p.value[ 0 ] === 'string' && p.value[ 0 ].startsWith( 'stdillum' ) ) return [ 1, 1, 1 ];
 	const rgb = ( await resolveSpectrum( params, name, ctx, [ 1, 1, 1 ] ) ).rgb || [ 1, 1, 1 ];
 	if ( ! p || p.type === 'rgb' || p.type === 'color' || p.type === 'float' ) return rgb;
@@ -98,6 +99,8 @@ export { SPILL_TRIANGLE_BUDGET, SPILL_PLACEMENT_BUDGET } from '../HostMemory.js'
 const DEFAULT_MERGE_MIN_SHAPES = 256;
 const MERGE_VERTEX_LIMIT = 4096;
 const MERGE_BATCH_TRIANGLES = 500_000;
+// Copies of a template shape textured by position, each stored with its own uv, up to this many triangles in all.
+const MAPPED_COPY_TRIANGLES = 1_000_000;
 // Curve tessellation defaults. pbrt sweeps a spline analytically; a triangle tracer has to
 // pick a resolution, and isMountainB alone declares 5.18M curves — two samples per span and
 // a crossed pair of ribbons is 16 triangles a curve.
@@ -108,7 +111,7 @@ const DEFAULT_CURVE_SIDES = { flat: 1, ribbon: 1, cylinder: 2 };
 const DEFAULT_CURVE_TOLERANCE = 0.05;
 
 /** Bumped whenever the same scene files build a different graph, so a stored graph is not reused. */
-export const PBRT_BUILD_REVISION = 11;
+export const PBRT_BUILD_REVISION = 13;
 
 function samePlacements( a, b ) {
 
@@ -209,10 +212,62 @@ function uvMapping( params ) {
 
 }
 
-function setMapping( texture, { su, sv, du, dv } ) {
+const POSITION_MAPPINGS = new Set( [ 'planar', 'spherical', 'cylindrical' ] );
+
+function pVector( params, name, dflt ) {
+
+	const v = param( params, name )?.value;
+	return v && v.length >= 3 ? [ v[ 0 ], v[ 1 ], v[ 2 ] ] : dflt;
+
+}
+
+/**
+ * pbrt's TextureMapping2D::Create: `uv` scales and shifts the mesh's uv; a position mapping is a uv set of its own (`uv`),
+ * generated per shape and read as it is. It maps from where the texture was declared (`ctm`).
+ */
+function textureMapping( params, ctm ) {
+
+	const type = pString( params, 'mapping', 'uv' );
+	if ( ! POSITION_MAPPINGS.has( type ) ) return { ...uvMapping( params ), uv: null };
+
+	const uv = { type, textureFromWorld: M.invert( ctm ?? M.identity() ) };
+	if ( type === 'planar' ) Object.assign( uv, {
+		vs: pVector( params, 'v1', [ 1, 0, 0 ] ), vt: pVector( params, 'v2', [ 0, 1, 0 ] ),
+		ds: pFloat( params, 'udelta', 0 ), dt: pFloat( params, 'vdelta', 0 )
+	} );
+	uv.key = JSON.stringify( uv );
+	return { su: 1, sv: 1, du: 0, dv: 0, uv };
+
+}
+
+function setMapping( texture, { su, sv, du, dv, uv = null } ) {
 
 	texture.repeat.set( su, sv );
 	texture.offset.set( du, dv );
+	if ( uv ) texture.userData.pbrtUV = uv;
+
+}
+
+// Material maps in the order that picks a surface's one uv set: its base colour's, else the first it has.
+const UV_MAPS = [ 'map', 'roughnessMap', 'clearcoatRoughnessMap', 'normalMap' ];
+const MAP_SCALARS = { roughnessMap: 'roughness', clearcoatRoughnessMap: 'clearcoatRoughness' };
+
+/** The position mapping a material's textures are read in, or null for the mesh's own uv. */
+function uvSetOf( material ) {
+
+	for ( const slot of UV_MAPS ) if ( material[ slot ] ) return material[ slot ].userData.pbrtUV ?? null;
+	return null;
+
+}
+
+// An attribute with `sources`' values appended, one copy each.
+function withCopies( attribute, sources ) {
+
+	const { array, itemSize, count } = attribute;
+	const out = new array.constructor( ( count + sources.length ) * itemSize );
+	out.set( array.subarray( 0, count * itemSize ) );
+	for ( let i = 0; i < sources.length; i ++ ) for ( let c = 0; c < itemSize; c ++ ) out[ ( count + i ) * itemSize + c ] = array[ sources[ i ] * itemSize + c ];
+	return new BufferAttribute( out, itemSize, attribute.normalized );
 
 }
 
@@ -464,8 +519,9 @@ function translucent( material, alpha ) {
 
 }
 
-const sameMapping = ( texture, { su, sv, du, dv } ) =>
-	texture.repeat.x === su && texture.repeat.y === sv && texture.offset.x === du && texture.offset.y === dv;
+const sameMapping = ( texture, { su, sv, du, dv, uv } ) =>
+	texture.repeat.x === su && texture.repeat.y === sv && texture.offset.x === du && texture.offset.y === dv &&
+	uvKey( texture.userData.pbrtUV ) === uvKey( uv );
 
 // An 8-bit image's colour with its alpha decoded as pbrt reads it; null when its alpha is opaque throughout.
 function withDecodedAlpha( pixels, decode ) {
@@ -547,6 +603,7 @@ export class PBRTSceneBuilder {
 		this.resolveImage = resolvers.resolveImage || ( async () => null );
 		this.resolveEnvironment = resolvers.resolveEnvironment || resolvers.resolveImage || ( async () => null );
 		this.convertHandedness = resolvers.convertHandedness === true;
+		this._usage = resolvers.usage ?? null;
 
 		this.warnings = [];
 		this.report = []; // per-mesh diagnostics for debugging imports
@@ -560,6 +617,9 @@ export class PBRTSceneBuilder {
 		this._termCache = new Map(); // texture name + channels -> Promise<{rgb}|{layer, tint?}|null>
 		this._mediumMaterials = new Map(); // material -> Map(medium name -> material with its attenuation)
 		this._alphaMaterials = new Map(); // material -> Map(alpha texture name or #value -> Promise<material>)
+		this._mappings = new Map(); // texture name -> its textureMapping()
+		this._oneUVSets = new WeakMap(); // material -> itself, or its maps read in one uv set
+		this._uvWarnings = new Set();
 
 	}
 
@@ -576,9 +636,15 @@ export class PBRTSceneBuilder {
 	async build( ir ) {
 
 		this.ir = ir;
-		// Built again for their moving placements after the static ones, so never freed early.
+		// Built again for their moving placements, so freed and accounted for only at the end.
 		this._keepShapes = new Set();
-		for ( const { name } of ir.animatedInstances ?? [] ) for ( const shape of ir.objects.get( name ) ?? [] ) this._keepShapes.add( shape );
+		for ( const { name } of ir.animatedInstances ?? [] ) for ( const shape of ir.objects.get( name ) ?? [] ) {
+
+			this._keepShapes.add( shape );
+			this._usage?.open( shape.params, `Shape ${shape.type}`, 'alpha' );
+
+		}
+
 		// One decoded .ply serves every shape naming it: a merge frees it only as its last direct
 		// user, and never while a template or an unmerged shape holds its geometry.
 		this._plyUsers = new Map();
@@ -635,7 +701,7 @@ export class PBRTSceneBuilder {
 
 			if ( shape.type === 'plymesh' ) this._plyHeld.add( pString( shape.params, 'filename', null ) );
 
-			const mesh = this._meshFromGeometry( shape, geometry, sharedMaterial, shape.ctm, `shape_${i}` );
+			const mesh = this._meshFromGeometry( shape, this._mappedGeometry( geometry, sharedMaterial, shape.ctm ), sharedMaterial, shape.ctm, `shape_${i}` );
 			if ( ! mesh ) continue;
 			group.add( mesh );
 			if ( shape.motion ) this._animate( mesh, shape.motion );
@@ -675,6 +741,7 @@ export class PBRTSceneBuilder {
 
 		const animations = ir.animation ? this._buildClip( ir, camera ) : [];
 
+		for ( const light of ir.lights ) this._usage?.open( light.params, `LightSource ${light.type}` );
 		// Infinite light → environment
 		const environment = await this._buildEnvironment( ir.lights );
 		await this._buildLamps( ir.lights, group );
@@ -828,16 +895,23 @@ export class PBRTSceneBuilder {
 
 				}
 
-				const [ geometry, sharedMaterial ] = await Promise.all( [
+				const [ built, sharedMaterial ] = await Promise.all( [
 					this._buildGeometry( shape ),
 					this._getMaterial( shape )
 				] );
-				if ( ! geometry ) continue;
+				if ( ! built ) continue;
+				let geometry = built;
+
+				const rel = shape.relativeCTM || shape.ctm;
+				if ( uvSetOf( sharedMaterial ) ) {
 
-				if ( batches && shape.type !== 'plymesh' && ! shape.shared && geometry.getAttribute( 'position' ).count <= MERGE_VERTEX_LIMIT ) {
+					if ( this._placeMapped( list, shape, geometry, sharedMaterial, rel, group, name ) ) continue;
+					geometry = this._mappedGeometry( geometry, sharedMaterial, M.multiplyInto( new Array( 16 ), list.matrices, 0, rel ) );
+
+				} else if ( batches && shape.type !== 'plymesh' && ! shape.shared && geometry.getAttribute( 'position' ).count <= MERGE_VERTEX_LIMIT ) {
 
 					this._geometryCache.delete( shape );
-					const full = this._appendToBatch( batches, shape, geometry, sharedMaterial, shape.relativeCTM || shape.ctm );
+					const full = this._appendToBatch( batches, shape, geometry, sharedMaterial, rel );
 					this._releaseMerged( shape, geometry );
 					placeBatch( list, full );
 					continue;
@@ -846,7 +920,7 @@ export class PBRTSceneBuilder {
 
 				const tris = this._accountGeometry( geometry );
 				const material = this._materialForGeometry( shape, geometry, sharedMaterial, `instances_${name}` );
-				place( list, geometry, material, shape.relativeCTM || shape.ctm, shape.type, shape.material?.type || 'diffuse', tris );
+				place( list, geometry, material, rel, shape.type, shape.material?.type || 'diffuse', tris );
 
 			}
 
@@ -865,6 +939,34 @@ export class PBRTSceneBuilder {
 
 	}
 
+	/**
+	 * pbrt maps each copy of a template where it stands, so a shape textured by position is placed as a mesh a copy, each
+	 * with its own uv set. False, placing nothing, past MAPPED_COPY_TRIANGLES: the copies then share the first one's.
+	 * @private
+	 */
+	_placeMapped( list, shape, geometry, material, rel, group, name ) {
+
+		const tris = ( geometry.index ? geometry.index.count : geometry.getAttribute( 'position' ).count ) / 3;
+		if ( list.count * tris > MAPPED_COPY_TRIANGLES ) {
+
+			this.warn( `ObjectInstance "${name}": its ${list.count.toLocaleString()} copies share the first one's uv from a position-mapped texture` );
+			return false;
+
+		}
+
+		let i = 0;
+		for ( ; i < list.count && ! this._overBudget(); i ++ ) {
+
+			const world = M.multiplyInto( new Array( 16 ), list.matrices, i * 16, rel );
+			group.add( this._meshFromGeometry( shape, this._mappedGeometry( geometry, material, world ), material, world, `instances_${name}_${i}` ) );
+
+		}
+
+		this.skippedForBudget += list.count - i;
+		return true;
+
+	}
+
 	/**
 	 * Templates placed at exactly the same transforms, as one template. Each Pandanus tree
 	 * includes ten leaf files; kept apart they were ten overlapping instances a ray entered
@@ -942,7 +1044,9 @@ export class PBRTSceneBuilder {
 				const shape = template[ s ];
 				const [ geometry, sharedMaterial ] = await Promise.all( [ this._buildGeometry( shape ), this._getMaterial( shape ) ] );
 				if ( ! geometry ) continue;
-				const mesh = this._meshFromGeometry( shape, geometry, sharedMaterial, shape.relativeCTM || shape.ctm, `${node.name}_${s}`, true );
+				const rel = shape.relativeCTM || shape.ctm;
+				const mapped = this._mappedGeometry( geometry, sharedMaterial, M.multiply( start, rel ) );
+				const mesh = this._meshFromGeometry( shape, mapped, sharedMaterial, rel, `${node.name}_${s}`, true );
 				if ( mesh ) node.add( mesh );
 
 			}
@@ -1145,7 +1249,7 @@ export class PBRTSceneBuilder {
 
 		this.reportedMeshes ++;
 		const world = this.convertHandedness ? M.multiply( FLIP_Z, shape.ctm ) : shape.ctm;
-		const full = this._appendToBatch( this._batches, shape, geometry, sharedMaterial, world );
+		const full = this._appendToBatch( this._batches, shape, this._mappedGeometry( geometry, sharedMaterial, shape.ctm ), sharedMaterial, world );
 		this._releaseMerged( shape, geometry );
 		if ( full ) this._flushBatch( full, group );
 
@@ -1322,7 +1426,9 @@ export class PBRTSceneBuilder {
 
 	async _createGeometry( shape ) {
 
-		const geometry = await this._shapeGeometry( shape );
+		// A shape's parameters are all read before the first await; its `alpha`, by its material.
+		const read = () => this._shapeGeometry( shape );
+		const geometry = await ( this._usage ? this._usage.translate( shape.params, `Shape ${shape.type}`, read, 'alpha' ) : read() );
 		return geometry && shape.areaLight && ! pBool( shape.areaLight.params, 'twosided', false ) ? this._facingEmission( shape, geometry ) : geometry;
 
 	}
@@ -1395,7 +1501,7 @@ export class PBRTSceneBuilder {
 
 	_triangleMesh( params ) {
 
-		const P = params.P?.value;
+		const P = param( params, 'P' )?.value;
 		if ( ! P || P.length < 9 ) {
 
 			this.warn( 'trianglemesh missing P' ); return null;
@@ -1405,7 +1511,7 @@ export class PBRTSceneBuilder {
 		const geo = new BufferGeometry();
 		geo.setAttribute( 'position', new Float32BufferAttribute( float32( P ), 3 ) );
 
-		const N = params.N?.value;
+		const N = param( params, 'N' )?.value;
 		if ( N && N.length === P.length ) {
 
 			geo.setAttribute( 'normal', new Float32BufferAttribute( float32( N ), 3 ) );
@@ -1413,10 +1519,10 @@ export class PBRTSceneBuilder {
 
 		}
 
-		const uv = ( params.uv || params.st )?.value;
+		const uv = param( params, params.uv ? 'uv' : 'st' )?.value;
 		if ( uv && uv.length === ( P.length / 3 ) * 2 ) geo.setAttribute( 'uv', new Float32BufferAttribute( float32( uv ), 2 ) );
 
-		const indices = params.indices?.value;
+		const indices = param( params, 'indices' )?.value;
 		if ( indices && indices.length ) geo.setIndex( indexAttribute( indices ) );
 
 		if ( ! N ) geo.computeVertexNormals();
@@ -1426,7 +1532,7 @@ export class PBRTSceneBuilder {
 
 	_curve( params ) {
 
-		const P = params.P?.value;
+		const P = param( params, 'P' )?.value;
 		if ( ! P || P.length < 12 ) {
 
 			this.warn( 'curve needs at least 4 control points' ); return null;
@@ -1447,7 +1553,7 @@ export class PBRTSceneBuilder {
 			basis: pString( params, 'basis', 'bezier' ),
 			width0: pFloat( params, 'width0', width ),
 			width1: pFloat( params, 'width1', width ),
-			N: params.N?.value || null,
+			N: param( params, 'N' )?.value || null,
 			steps: this.curveSteps,
 			sides: this.curveSides ?? DEFAULT_CURVE_SIDES[ type ] ?? 1,
 			tolerance: this.curveTolerance
@@ -1473,11 +1579,11 @@ export class PBRTSceneBuilder {
 	_curves( params ) {
 
 		const built = tessellateCurves( {
-			P: params.P.value,
-			counts: params.counts.value,
-			widths: params.widths?.value ?? null,
+			P: param( params, 'P' ).value,
+			counts: param( params, 'counts' ).value,
+			widths: param( params, 'widths' )?.value ?? null,
 			widthMode: pString( params, 'widthMode', 'constant' ),
-			N: params.N?.value ?? null,
+			N: param( params, 'N' )?.value ?? null,
 			normalMode: pString( params, 'normalMode', 'vertex' ),
 			type: pString( params, 'type', 'cubic' ),
 			basis: pString( params, 'basis', 'bspline' ),
@@ -1506,8 +1612,8 @@ export class PBRTSceneBuilder {
 
 	_loopSubdiv( params ) {
 
-		const P = params.P?.value;
-		const indices = params.indices?.value;
+		const P = param( params, 'P' )?.value;
+		const indices = param( params, 'indices' )?.value;
 		if ( ! P || P.length < 9 || ! indices || indices.length < 3 ) {
 
 			this.warn( 'loopsubdiv missing P/indices' ); return null;
@@ -1538,8 +1644,8 @@ export class PBRTSceneBuilder {
 	 */
 	_bilinearMesh( params ) {
 
-		const P = params.P?.value;
-		const quad = params.indices?.value ?? ( P?.length === 12 ? [ 0, 1, 2, 3 ] : null );
+		const P = param( params, 'P' )?.value;
+		const quad = param( params, 'indices' )?.value ?? ( P?.length === 12 ? [ 0, 1, 2, 3 ] : null );
 		if ( ! P || ! quad ) {
 
 			this.warn( 'bilinearmesh missing P/indices' ); return null;
@@ -1547,8 +1653,8 @@ export class PBRTSceneBuilder {
 		}
 
 		const count = P.length / 3;
-		const uv = params.uv?.value?.length === count * 2 ? params.uv.value : null;
-		const N = params.N?.value?.length === count * 3 ? params.N.value : null;
+		const uv = param( params, 'uv' )?.value?.length === count * 2 ? params.uv.value : null;
+		const N = param( params, 'N' )?.value?.length === count * 3 ? params.N.value : null;
 		const geo = new BufferGeometry();
 
 		if ( uv ) {
@@ -1691,7 +1797,75 @@ export class PBRTSceneBuilder {
 
 		let material = await this._surfaceMaterial( shape );
 		if ( shape.interior ) material = await this._inMedium( material, shape.interior );
-		return shape.params.alpha ? this._withAlpha( material, shape.params.alpha ) : material;
+		if ( shape.params.alpha ) material = await this._withAlpha( material, shape.params.alpha );
+		return this._oneUVSet( material );
+
+	}
+
+	/**
+	 * The material with every map in its one uv set (`uvSetOf`): the engine reads one a triangle. A map in another
+	 * counts as its mean (a roughness) or is dropped, reported once.
+	 * @private
+	 */
+	_oneUVSet( material ) {
+
+		let out = this._oneUVSets.get( material );
+		if ( out ) return out;
+		out = material;
+		const set = uvSetOf( material );
+		const what = ( uv ) => ( uv ? `a "${uv.type}" mapping` : 'the mesh\'s uv' );
+
+		for ( const slot of UV_MAPS ) {
+
+			const map = material[ slot ];
+			if ( ! map || uvKey( map.userData.pbrtUV ) === uvKey( set ) ) continue;
+			if ( out === material ) out = cloneMaterial( material );
+			out[ slot ] = null;
+			const scalar = MAP_SCALARS[ slot ];
+			const layer = scalar && this._textureLayer( map, 1 );
+			if ( layer ) out[ scalar ] *= layerMean( layer );
+			const message = `a ${slot} in ${what( map.userData.pbrtUV )} on a surface textured in ${what( set )}: ` +
+				`one uv set a surface — ${layer ? 'its mean used' : 'dropped'}`;
+			if ( ! this._uvWarnings.has( message ) ) {
+
+				this._uvWarnings.add( message );
+				this.warn( message );
+
+			}
+
+		}
+
+		this._oneUVSets.set( material, out );
+		return out;
+
+	}
+
+	/**
+	 * `geometry` with the uv set its material's position mapping gives it at `world` (pbrt's, column-major); as it is
+	 * when the material reads the mesh's own uv. Attributes are shared unless a seam copied vertices.
+	 * @private
+	 */
+	_mappedGeometry( geometry, material, world ) {
+
+		const mapping = uvSetOf( material );
+		if ( ! mapping ) return geometry;
+
+		const { uv, index, extra } = generateUV(
+			geometry.getAttribute( 'position' ).array, geometry.index?.array ?? null, M.multiply( mapping.textureFromWorld, world ), mapping
+		);
+		const out = new BufferGeometry();
+		out.name = geometry.name;
+		Object.assign( out.userData, geometry.userData );
+		for ( const name in geometry.attributes ) {
+
+			if ( name !== 'uv' ) out.setAttribute( name, extra.length ? withCopies( geometry.getAttribute( name ), extra ) : geometry.getAttribute( name ) );
+
+		}
+
+		out.setAttribute( 'uv', new BufferAttribute( uv, 2 ) );
+		if ( index ) out.setIndex( new Uint32BufferAttribute( index, 1 ) );
+		else if ( geometry.index ) out.setIndex( geometry.index );
+		return out;
 
 	}
 
@@ -1734,17 +1908,18 @@ export class PBRTSceneBuilder {
 	 */
 	async _alphaMap( colorMap, name ) {
 
-		const def = this.ir.namedTextures.get( name );
+		const def = this._textureDef( name );
 		const filename = def?.class === 'imagemap' ? pString( def.params, 'filename', null ) : null;
+		const mapping = filename && this._textureMapping( name, def );
 		// Most often the alpha is the colour map's own image: its colour stays as it is.
-		if ( filename && colorMap?.userData.pbrtImage === filename && pString( def.params, 'mapping', 'uv' ) === 'uv'
-			&& pFloat( def.params, 'scale', 1 ) === 1 && ! pBool( def.params, 'invert', false ) && sameMapping( colorMap, uvMapping( def.params ) ) ) {
+		if ( filename && colorMap?.userData.pbrtImage === filename
+			&& pFloat( def.params, 'scale', 1 ) === 1 && ! pBool( def.params, 'invert', false ) && sameMapping( colorMap, mapping ) ) {
 
 			const pixels = texturePixels( colorMap );
 			const own = pixels && withDecodedAlpha( pixels, decoderFor( def.params ) );
 			if ( own ) {
 
-				setMapping( own, uvMapping( def.params ) );
+				setMapping( own, mapping );
 				return own;
 
 			}
@@ -1756,7 +1931,7 @@ export class PBRTSceneBuilder {
 		if ( ! alpha.layer ) return { constant: alpha.rgb[ 0 ] };
 		const color = colorMap ? this._textureLayer( colorMap, 3 ) : null;
 		if ( colorMap && ! color ) return null;
-		const baked = bake( [ color ? { layer: color } : { rgb: [ 1, 1, 1 ] }, alpha ], ( [ c ] ) => c, { alphaOf: ( [ , a ] ) => a[ 0 ] } );
+		const baked = this._bake( `alpha "${name}"`, [ color ? { layer: color } : { rgb: [ 1, 1, 1 ] }, alpha ], ( [ c ] ) => c, { alphaOf: ( [ , a ] ) => a[ 0 ] } );
 		return baked && bakedTexture( baked );
 
 	}
@@ -1792,6 +1967,7 @@ export class PBRTSceneBuilder {
 		return this._ctx ??= {
 			resolveNamedTexture: ( n ) => this._resolveNamedTexture( n ),
 			namedMaterials: this.ir.namedMaterials,
+			trackParams: ( params, label, consumed ) => this._usage?.open( params, label, consumed ),
 			warn: ( m ) => this.warn( m ),
 			floatTextureMean: async ( n ) => {
 
@@ -1844,6 +2020,7 @@ export class PBRTSceneBuilder {
 
 		const params = this.ir.media?.get( name );
 		const type = params && pString( params, 'type', '' );
+		this._usage?.open( params, `MakeNamedMedium ${type}`, 'type' );
 		if ( type !== 'homogeneous' ) {
 
 			this.warn( params ? `medium "${name}" (${type}) is not supported — "${name}" glass left clear` : `medium "${name}" not defined` );
@@ -1851,7 +2028,13 @@ export class PBRTSceneBuilder {
 
 		}
 
-		if ( params.preset ) this.warn( `medium preset "${pString( params, 'preset', '' )}" is not supported — using sigma_a / sigma_s` );
+		if ( params.preset ) {
+
+			this.warn( `medium preset "${pString( params, 'preset', '' )}" is not supported — using sigma_a / sigma_s` );
+			approximated( params, 'preset' );
+
+		}
+
 		const ctx = this._materialContext();
 		const a = ( await resolveSpectrum( params, 'sigma_a', ctx, [ 1, 1, 1 ] ) ).rgb;
 		const s = ( await resolveSpectrum( params, 'sigma_s', ctx, [ 1, 1, 1 ] ) ).rgb;
@@ -1909,6 +2092,7 @@ export class PBRTSceneBuilder {
 
 	async _applyAreaLight( material, areaLight, ctx ) {
 
+		this._usage?.open( areaLight.params, `AreaLightSource ${areaLight.type}` );
 		const rgb = await lightRGB( areaLight.params, 'L', ctx );
 		const scale = pFloat( areaLight.params, 'scale', 1 );
 		material.emissive.setRGB( rgb[ 0 ], rgb[ 1 ], rgb[ 2 ] );
@@ -1918,11 +2102,20 @@ export class PBRTSceneBuilder {
 
 	}
 
+	/** A named texture's definition, its parameters accounted from here to the end of the build. @private */
+	_textureDef( name ) {
+
+		const def = this.ir.namedTextures.get( name );
+		if ( def ) this._usage?.open( def.params, `Texture ${def.class}` );
+		return def;
+
+	}
+
 	async _resolveNamedTexture( name ) {
 
 		if ( this._textureCache.has( name ) ) return this._textureCache.get( name );
 
-		const def = this.ir.namedTextures.get( name );
+		const def = this._textureDef( name );
 		let result = null;
 
 		if ( ! def ) {
@@ -1939,7 +2132,7 @@ export class PBRTSceneBuilder {
 
 		} else if ( def.class === 'constant' ) {
 
-			const v = def.params.value;
+			const v = param( def.params, 'value' );
 			if ( v && v.type === 'rgb' ) result = { constant: [ v.value[ 0 ], v.value[ 1 ], v.value[ 2 ] ] };
 			else if ( v ) result = { constant: [ v.value[ 0 ], v.value[ 0 ], v.value[ 0 ] ] };
 
@@ -1987,15 +2180,19 @@ export class PBRTSceneBuilder {
 		const ctx = this._materialContext();
 		const value = async ( key, dflt ) => {
 
-			const p = params[ key ];
-			if ( p?.type === 'texture' ) return ( await ctx.textureMeanRGB( p.value[ 0 ] ) ) ?? dflt;
+			const p = param( params, key );
+			if ( p?.type === 'texture' ) {
+
+				approximated( params, key );
+				return ( await ctx.textureMeanRGB( p.value[ 0 ] ) ) ?? dflt;
+
+			}
+
 			return ( await resolveSpectrum( params, key, ctx, dflt ) ).rgb ?? dflt;
 
 		};
 
-		const mapping = pString( params, 'mapping', 'uv' );
-		if ( mapping !== 'uv' ) this.warn( `texture "${name}": "${mapping}" mapping is not supported — using the mesh's uv` );
-		const { su, sv, du, dv } = uvMapping( params );
+		const { su, sv, du, dv, uv } = this._textureMapping( name, def );
 
 		if ( def.class === 'checkerboard' ) {
 
@@ -2009,7 +2206,7 @@ export class PBRTSceneBuilder {
 			const [ a, b ] = await Promise.all( [ value( 'tex1', [ 1, 1, 1 ] ), value( 'tex2', [ 0, 0, 0 ] ) ] );
 			const n = 2 * CHECK_TEXELS;
 			const data = rasterize( n, n, ( s, t ) => ( ( Math.floor( 2 * s ) + Math.floor( 2 * t ) ) % 2 ? b : a ) );
-			return { texture: bakedTexture( { data, width: n, height: n, mapping: { su: su / 2, sv: sv / 2, du: du / 2, dv: dv / 2 } } ) };
+			return { texture: bakedTexture( { data, width: n, height: n, mapping: { su: su / 2, sv: sv / 2, du: du / 2, dv: dv / 2, uv } } ) };
 
 		}
 
@@ -2018,7 +2215,32 @@ export class PBRTSceneBuilder {
 		] );
 		const data = rasterize( BILERP_TEXELS, BILERP_TEXELS, ( s, t ) => [ 0, 1, 2 ].map( ( c ) =>
 			( 1 - s ) * ( 1 - t ) * v00[ c ] + s * ( 1 - t ) * v10[ c ] + ( 1 - s ) * t * v01[ c ] + s * t * v11[ c ] ) );
-		return { texture: bakedTexture( { data, width: BILERP_TEXELS, height: BILERP_TEXELS, mapping: { su, sv, du, dv } } ) };
+		return { texture: bakedTexture( { data, width: BILERP_TEXELS, height: BILERP_TEXELS, mapping: { su, sv, du, dv, uv } } ) };
+
+	}
+
+	/** A named texture's textureMapping(), once; a mapping pbrt does not know is reported and read as `uv`. @private */
+	_textureMapping( name, def ) {
+
+		let mapping = this._mappings.get( name );
+		if ( ! mapping ) {
+
+			const type = pString( def.params, 'mapping', 'uv' );
+			if ( type !== 'uv' && ! POSITION_MAPPINGS.has( type ) ) this.warn( `texture "${name}": unknown mapping "${type}" — using the mesh's uv` );
+			this._mappings.set( name, mapping = textureMapping( def.params, def.ctm ) );
+
+		}
+
+		return mapping;
+
+	}
+
+	/** bake(), reporting the inputs it had to read as their mean. @private */
+	_bake( label, terms, combine, options ) {
+
+		const baked = bake( terms, combine, options );
+		if ( baked?.averaged ) this.warn( `${label}: ${baked.averaged} input(s) in another uv set than the first image — read as their mean` );
+		return baked;
 
 	}
 
@@ -2059,14 +2281,12 @@ export class PBRTSceneBuilder {
 
 		}
 
-		const mapping = pString( def.params, 'mapping', 'uv' );
-		if ( mapping !== 'uv' ) this.warn( `texture "${name}": "${mapping}" mapping is not supported — using the mesh's uv` );
-
+		const mapping = this._textureMapping( name, def );
 		const scale = pFloat( def.params, 'scale', 1 );
 		if ( scale > 1 || pBool( def.params, 'invert', false ) ) {
 
 			const term = await this._bakeTerm( name, 3 );
-			const baked = term?.layer && bake( [ { ...term, clamp: true } ], ( [ v ] ) => v );
+			const baked = term?.layer && this._bake( `texture "${name}"`, [ { ...term, clamp: true } ], ( [ v ] ) => v );
 			if ( baked ) return { texture: bakedTexture( baked ) };
 			this.warn( `texture "${name}": its scale or invert could not be baked here — ignored` );
 
@@ -2075,7 +2295,7 @@ export class PBRTSceneBuilder {
 		const color = eightBit( image, { srgb: true } );
 		const texture = color === image ? image.clone() : color;
 		texture.userData.pbrtImage = filename;
-		setMapping( texture, uvMapping( def.params ) );
+		setMapping( texture, mapping );
 		texture.needsUpdate = true;
 		return scale < 1 ? { texture, constant: [ scale, scale, scale ] } : { texture };
 
@@ -2090,7 +2310,7 @@ export class PBRTSceneBuilder {
 
 		const terms = await Promise.all( keys.map( ( key ) => this._paramTerm( params, key, 1, [ 0, 0, 0 ] ) ) );
 		if ( terms.some( ( term ) => ! term ) ) return null;
-		const baked = bake( terms, ( values ) => {
+		const baked = this._bake( `"${keys.join( '", "' )}"`, terms, ( values ) => {
 
 			const v = combine( values.map( ( value ) => value[ 0 ] ) );
 			return [ v, v, v ];
@@ -2116,7 +2336,7 @@ export class PBRTSceneBuilder {
 		}
 
 		const unit = ( rgb ) => rgb.map( ( v ) => Math.min( 1, Math.max( 0, v ) ) );
-		const baked = bake( [ { ...a, clamp: true }, { ...b, clamp: true }, amount ], mixOf );
+		const baked = this._bake( `texture "${name}"`, [ { ...a, clamp: true }, { ...b, clamp: true }, amount ], mixOf );
 		return baked ? { texture: bakedTexture( baked ) } : { constant: mixOf( [ unit( a.rgb ), unit( b.rgb ), amount.rgb ] ) };
 
 	}
@@ -2124,7 +2344,7 @@ export class PBRTSceneBuilder {
 	/** A texture parameter as a bake term: a constant, or the texture it names. @private */
 	async _paramTerm( params, key, channels, dflt ) {
 
-		const p = params[ key ];
+		const p = param( params, key );
 		if ( ! p ) return { rgb: dflt };
 		if ( p.type === 'texture' ) return this._bakeTerm( p.value[ 0 ], channels );
 		const rgb = ( await resolveSpectrum( params, key, this._materialContext(), dflt ) ).rgb;
@@ -2150,16 +2370,15 @@ export class PBRTSceneBuilder {
 
 	async _createBakeTerm( name, channels ) {
 
-		const def = this.ir.namedTextures.get( name );
+		const def = this._textureDef( name );
 		if ( def?.class === 'imagemap' ) {
 
-			if ( pString( def.params, 'mapping', 'uv' ) !== 'uv' ) return null;
 			const filename = pString( def.params, 'filename', null );
 			const pixels = texturePixels( filename && await this._image( filename ) );
 			if ( ! pixels ) return null;
 			return { layer: makeLayer( pixels, {
 				channels, decode: pixels.float ? null : decoderFor( def.params ),
-				scale: pFloat( def.params, 'scale', 1 ), invert: pBool( def.params, 'invert', false ), mapping: uvMapping( def.params )
+				scale: pFloat( def.params, 'scale', 1 ), invert: pBool( def.params, 'invert', false ), mapping: this._textureMapping( name, def )
 			} ) };
 
 		}
@@ -2180,7 +2399,7 @@ export class PBRTSceneBuilder {
 		const srgb = ! pixels.float && texture.colorSpace === SRGBColorSpace;
 		return makeLayer( pixels, {
 			channels, decode: pixels.float ? null : ( srgb ? srgbToLinear : ( v ) => v ),
-			mapping: { su: texture.repeat.x, sv: texture.repeat.y, du: texture.offset.x, dv: texture.offset.y }
+			mapping: { su: texture.repeat.x, sv: texture.repeat.y, du: texture.offset.x, dv: texture.offset.y, uv: texture.userData.pbrtUV ?? null }
 		} );
 
 	}
@@ -2207,7 +2426,7 @@ export class PBRTSceneBuilder {
 
 		const a = term( matA ), b = term( matB );
 		if ( ! a || ! b ) return { mean, texture: null };
-		const baked = bake( [ a, b, amount ], mixOf );
+		const baked = this._bake( `mix amount "${amountName}"`, [ a, b, amount ], mixOf );
 		return { mean, texture: baked ? bakedTexture( baked ) : null };
 
 	}
@@ -2243,7 +2462,7 @@ export class PBRTSceneBuilder {
 			const product = ( [ a, f ] ) => [ a[ 0 ] * f[ 0 ], a[ 1 ] * f[ 0 ], a[ 2 ] * f[ 0 ] ];
 			if ( inner && factor ) {
 
-				const baked = bake( [ { ...inner, clamp: true }, factor ], product );
+				const baked = this._bake( `texture "${name}"`, [ { ...inner, clamp: true }, factor ], product );
 				return baked ? { texture: bakedTexture( baked ) } : { constant: product( [ inner.rgb, factor.rgb ] ) };
 
 			}
@@ -2252,7 +2471,7 @@ export class PBRTSceneBuilder {
 
 		}
 
-		const innerP = def.params.tex;
+		const innerP = param( def.params, 'tex' );
 		let inner = null;
 
 		if ( innerP?.type === 'texture' && typeof innerP.value[ 0 ] === 'string' ) {
@@ -2270,7 +2489,7 @@ export class PBRTSceneBuilder {
 
 		}
 
-		const sP = def.params.scale;
+		const sP = param( def.params, 'scale' );
 		let scale = [ 1, 1, 1 ];
 		if ( sP?.type === 'rgb' || sP?.type === 'color' ) scale = [ sP.value[ 0 ], sP.value[ 1 ], sP.value[ 2 ] ];
 		else if ( sP?.type === 'float' ) {
@@ -2299,12 +2518,13 @@ export class PBRTSceneBuilder {
 	_buildCamera( cam, film ) {
 
 		const aspect = film && film.yresolution ? film.xresolution / film.yresolution : 16 / 9;
+		this._usage?.open( cam.params, `Camera ${cam.type}` );
 
 		let camera;
 		if ( cam.type === 'orthographic' ) {
 
 			// pbrt's default screen window spans [-1, 1] along the shorter image axis.
-			const window = cam.params?.screenwindow?.value;
+			const window = param( cam.params, 'screenwindow' )?.value;
 			const half = window?.length === 4 ? ( window[ 3 ] - window[ 2 ] ) / 2 : Math.max( 1, 1 / aspect );
 			camera = new OrthographicCamera( - half * aspect, half * aspect, half, - half, 0.01, 10000 );
 
@@ -2493,7 +2713,7 @@ export class PBRTSceneBuilder {
 			const world = new Matrix4().fromArray( this.convertHandedness ? M.multiply( FLIP_Z, l.ctm ) : l.ctm );
 			const point = ( name, dflt ) => {
 
-				const v = l.params[ name ]?.value;
+				const v = param( l.params, name )?.value;
 				return new Vector3().fromArray( v?.length >= 3 ? v : dflt ).applyMatrix4( world );
 
 			};