rayzee 11.7.0 → 11.9.0

package/src/Processor/PBRT/PBRTMaterials.js

@@ -10,6 +10,7 @@
 
 import { MeshPhysicalMaterial, Color, DoubleSide } from 'three';
 import { namedScattering, dipoleReflectance, albedoForReflectance } from './PBRTScattering.js';
+import { approximated, param } from './PBRTParser.js';
 
 // Normal-incidence reflectance approximations for pbrt's named conductor spectra.
 const METAL_ALBEDO = {
@@ -54,21 +55,37 @@ function blackbodyToRGB( kelvin ) {
 
 export function pFloat( params, name, dflt ) {
 
-	const p = params[ name ];
+	const p = param( params, name );
+	if ( p && p.type !== 'float' && p.type !== 'integer' ) approximated( params, name );
 	return p && typeof p.value[ 0 ] === 'number' ? p.value[ 0 ] : dflt;
 
 }
 
+/** An index of refraction: a sampled spectrum ( λ value pairs ) is read at 550 nm, linearly between its samples. */
+export function pEta( params, name, dflt ) {
+
+	const p = param( params, name );
+	if ( p?.type !== 'spectrum' || typeof p.value[ 0 ] !== 'number' ) return pFloat( params, name, dflt );
+	approximated( params, name );
+	const v = p.value;
+	if ( v.length < 2 ) return dflt;
+	let i = 2;
+	while ( i < v.length - 1 && v[ i ] < 550 ) i += 2;
+	if ( i >= v.length - 1 || v[ i - 2 ] >= 550 ) return v[ i >= v.length - 1 ? i - 1 : 1 ];
+	return v[ i - 1 ] + ( v[ i + 1 ] - v[ i - 1 ] ) * ( 550 - v[ i - 2 ] ) / ( v[ i ] - v[ i - 2 ] );
+
+}
+
 export function pString( params, name, dflt ) {
 
-	const p = params[ name ];
+	const p = param( params, name );
 	return p && typeof p.value[ 0 ] === 'string' ? p.value[ 0 ] : dflt;
 
 }
 
 export function pBool( params, name, dflt ) {
 
-	const v = params[ name ]?.value?.[ 0 ];
+	const v = param( params, name )?.value?.[ 0 ];
 	return v === undefined ? dflt : v === true || v === 'true';
 
 }
@@ -80,7 +97,7 @@ export function pBool( params, name, dflt ) {
  */
 export async function resolveSpectrum( params, name, ctx, dfltRGB = null ) {
 
-	const p = params[ name ];
+	const p = param( params, name );
 	if ( ! p ) return { rgb: dfltRGB, texture: null };
 
 	// Reference to a named texture.
@@ -91,6 +108,7 @@ export async function resolveSpectrum( params, name, ctx, dfltRGB = null ) {
 		if ( tex && tex.texture ) return { rgb: tex.constant ?? null, texture: tex.texture };
 		if ( tex && tex.constant ) return { rgb: tex.constant, texture: null };
 		ctx.warn( `texture "${texName}" could not be resolved` );
+		approximated( params, name );
 		return { rgb: dfltRGB, texture: null };
 
 	}
@@ -110,6 +128,7 @@ export async function resolveSpectrum( params, name, ctx, dfltRGB = null ) {
 
 	if ( p.type === 'blackbody' ) {
 
+		approximated( params, name );
 		return { rgb: blackbodyToRGB( p.value[ 0 ] ), texture: null };
 
 	}
@@ -117,6 +136,7 @@ export async function resolveSpectrum( params, name, ctx, dfltRGB = null ) {
 	if ( p.type === 'spectrum' ) {
 
 		// Named spectrum (e.g. "metal-Au-eta") or sampled [lambda val ...].
+		approximated( params, name );
 		if ( typeof p.value[ 0 ] === 'string' ) {
 
 			const key = namedMetalKey( p.value[ 0 ] );
@@ -139,6 +159,7 @@ export async function resolveSpectrum( params, name, ctx, dfltRGB = null ) {
 
 	}
 
+	approximated( params, name );
 	return { rgb: dfltRGB, texture: null };
 
 }
@@ -155,9 +176,10 @@ function namedMetalKey( s ) {
 // A float parameter's value, or a float texture's mean (`ctx.floatTextureMean`); null when absent or unreadable.
 async function floatOrMean( params, name, ctx ) {
 
-	const p = params[ name ];
+	const p = param( params, name );
 	if ( ! p ) return null;
 	if ( typeof p.value[ 0 ] === 'number' ) return p.value[ 0 ];
+	approximated( params, name );
 	if ( p.type === 'texture' ) return ( await ctx.floatTextureMean?.( p.value[ 0 ] ) ) ?? null;
 	return null;
 
@@ -171,7 +193,7 @@ async function floatOrMean( params, name, ctx ) {
  */
 const remapsRoughness = ( params ) => {
 
-	const remap = params.remaproughness?.value?.[ 0 ];
+	const remap = param( params, 'remaproughness' )?.value?.[ 0 ];
 	return remap !== false && remap !== 'false';
 
 };
@@ -225,8 +247,14 @@ async function applyRoughness( mat, target, params, dflt, ctx, prefix = '' ) {
 // A spectrum parameter as one RGB; a texture counts as its mean (`ctx.textureMeanRGB`).
 async function spectrumMean( params, key, ctx, 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;
 
 }
@@ -243,7 +271,7 @@ const SUBSURFACE_SIGMA_S = [ 2.55, 3.21, 3.77 ];
  */
 async function applySubsurface( mat, params, ctx ) {
 
-	const eta = pFloat( params, 'eta', 1.33 );
+	const eta = pEta( params, 'eta', 1.33 );
 	const scale = pFloat( params, 'scale', 1 );
 	const scaled = ( rgb ) => rgb.map( ( v ) => Math.max( 0, v * scale ) );
 	let g = pFloat( params, 'g', 0 );
@@ -353,6 +381,7 @@ export async function buildMaterial( def, ctx ) {
 
 	const type = def?.type || 'diffuse';
 	const params = def?.params || {};
+	ctx.trackParams?.( params, `Material ${type}`, 'type' );
 	const mat = new MeshPhysicalMaterial( { side: DoubleSide, roughness: 1, metalness: 0 } );
 
 	const setColor = ( rgb ) => {
@@ -393,7 +422,8 @@ export async function buildMaterial( def, ctx ) {
 		case 'metal': {
 
 			await applyConductorColor( mat, params, ctx, '', applyAlbedo, setColor );
-			await applyRoughness( mat, 'roughness', params, 0.1, ctx );
+			// pbrt's roughness defaults to 0, a mirror.
+			await applyRoughness( mat, 'roughness', params, 0, ctx );
 			break;
 
 		}
@@ -415,7 +445,7 @@ export async function buildMaterial( def, ctx ) {
 			mat.transmission = 1;
 			mat.metalness = 0;
 			mat.color.setRGB( 1, 1, 1 );
-			mat.ior = pFloat( params, 'eta', 1.5 );
+			mat.ior = pEta( params, 'eta', 1.5 );
 			await applyRoughness( mat, 'roughness', params, 0, ctx );
 			mat.thickness = type === 'thindielectric' ? 0 : pFloat( params, 'thickness', 0 );
 			break;
@@ -446,7 +476,13 @@ export async function buildMaterial( def, ctx ) {
 			const refl = await resolveSpectrum( params, 'reflectance', ctx, [ 0.25, 0.25, 0.25 ] );
 			const base = ( v ) => Math.min( 1, unit( v ) / ( 1 - dt ) );
 			applyAlbedo( { texture: refl.texture, rgb: refl.rgb ? refl.rgb.map( base ) : ( refl.texture ? [ 1, 1, 1 ].map( base ) : null ) } );
-			if ( trans.texture ) ctx.warn( 'diffusetransmission: a textured "transmittance" is not supported — using 0.5' );
+			if ( trans.texture ) {
+
+				ctx.warn( 'diffusetransmission: a textured "transmittance" is not supported — using 0.5' );
+				approximated( params, 'transmittance' );
+
+			}
+
 			mat.diffuseTransmission = dt;
 			mat.diffuseTransmissionColor = new Color().setRGB( ...T.map( ( v ) => ( dt > 0 ? Math.min( 1, v / dt ) : 1 ) ) );
 			mat.roughness = 1;
@@ -476,7 +512,7 @@ export async function buildMaterial( def, ctx ) {
 			// — physically loose but visually faithful, and crucially silent on success
 			// instead of warning per shape. Recursive: mix-in-mix terminates as the
 			// chain bottoms out at a non-mix.
-			const matNames = params.materials?.value || [];
+			const matNames = param( params, 'materials' )?.value || [];
 			let t = Math.max( 0, Math.min( 1, pFloat( params, 'amount', 0.5 ) ) );
 			const defA = matNames[ 0 ] ? ctx.namedMaterials?.get( matNames[ 0 ] ) : null;
 			const defB = matNames[ 1 ] ? ctx.namedMaterials?.get( matNames[ 1 ] ) : null;

package/src/Processor/PBRT/PBRTParser.js

@@ -14,7 +14,7 @@
  *   film:   { xresolution, yresolution, filename } | null,
  *   camera: { type, params, cameraToWorld:number[16] } | null,
  *   namedMaterials: Map<name, { type, params }>,
- *   namedTextures:  Map<name, { dataType, class, params }>,
+ *   namedTextures:  Map<name, { dataType, class, params, ctm? }>,  (ctm: where a position mapping was declared)
  *   shapes: [ { type, params, ctm, ctmEnd?, material, areaLight, reverseOrientation } ],
  *   lights: [ { type, params, ctm } ],
  *   instances: Map<name, { name, count, matrices, matricesEnd? }>,
@@ -68,6 +68,101 @@ const NUMERIC_STORAGE = {
 	rgb: Float32Array
 };
 
+// The directive `ParamUsage.translate` is in, and each directive open until `ParamUsage.finish`.
+let current = null;
+const scopes = new Map();
+
+/** A directive's parameter, counted as used: every translator reads through this, as pbrt-v4's lookups mark theirs. */
+export function param( params, name ) {
+
+	if ( current !== null && current.params === params ) current.read.push( name );
+	else if ( scopes.size !== 0 ) scopes.get( params )?.read.push( name );
+	return params?.[ name ];
+
+}
+
+/**
+ * A parameter read but not honoured exactly: a texture's mean where the engine takes one value,
+ * a default for a type it cannot read.
+ */
+export function approximated( params, name ) {
+
+	const scope = current !== null && current.params === params ? current : scopes.get( params );
+	if ( scope ) ( scope.approximated ??= new Set() ).add( name );
+
+}
+
+/**
+ * What one load did not honour, as pbrt's ReportUnused: each translated directive's parameters that nothing looked up,
+ * or that were approximated, counted per `directive type: name`. Holds nothing per directive once it is accounted for.
+ */
+export class ParamUsage {
+
+	constructor() {
+
+		this.unused = new Map();
+		this.approximated = new Map();
+
+	}
+
+	/**
+	 * Runs `read`, which looks up every parameter it uses before it returns, and accounts for the directive at once.
+	 * `consumed` names one read before, where nothing counted it. A directive left open is accounted for by `finish`.
+	 */
+	translate( params, label, read, consumed = null ) {
+
+		if ( scopes.has( params ) ) return read();
+		const outer = current;
+		const scope = current = { params, label, approximated: null, read: [ consumed ] };
+		try {
+
+			return read();
+
+		} finally {
+
+			current = outer;
+			for ( const name in params ) this._count( scope, name, ! scope.read.includes( name ) );
+
+		}
+
+	}
+
+	/** Accounts for a directive read across awaits, from here to `finish`. */
+	open( params, label, consumed = null ) {
+
+		if ( params && ! scopes.has( params ) ) scopes.set( params, { usage: this, label, approximated: null, read: [ consumed ] } );
+
+	}
+
+	/** @returns {{unused: Object<string, number>, approximated: Object<string, number>}} */
+	finish() {
+
+		for ( const [ params, scope ] of scopes ) {
+
+			if ( scope.usage !== this ) continue;
+			scopes.delete( params );
+			for ( const name in params ) this._count( scope, name, ! scope.read.includes( name ) );
+
+		}
+
+		const flat = ( counts ) => [ ...counts ].flatMap( ( [ label, byName ] ) => [ ...byName ].map( ( [ name, n ] ) => [ `${label}: ${name}`, n ] ) );
+		const sorted = ( counts ) => Object.fromEntries( flat( counts ).sort( ( a, b ) => ( a[ 0 ] < b[ 0 ] ? - 1 : 1 ) ) );
+		return { unused: sorted( this.unused ), approximated: sorted( this.approximated ) };
+
+	}
+
+	_count( scope, name, unused ) {
+
+		const counts = scope.approximated?.has( name ) ? this.approximated : unused ? this.unused : null;
+		if ( ! counts ) return;
+		let byName = counts.get( scope.label );
+		if ( ! byName ) counts.set( scope.label, byName = new Map() );
+		byName.set( name, ( byName.get( name ) ?? 0 ) + 1 );
+
+	}
+
+}
+
 export class PBRTParser {
 
 	/**
@@ -90,6 +185,7 @@ export class PBRTParser {
 		// is the parse itself, so a limit applied later saves nothing.
 		this.maxPlacements = opts.maxPlacements ?? Infinity;
 		this.instanceIncludes = opts.instanceIncludes !== false;
+		this.usage = opts.usage ?? null;
 		this._includes = new Map();
 		this._stateIds = new WeakMap();
 		this._nextStateId = 1;
@@ -598,14 +694,18 @@ export class PBRTParser {
 
 			case 'Film': {
 
-				this._expectString( 'Film type' );
+				const type = this._expectString( 'Film type' );
 				const params = this._parseParams();
-				this.ir.film = {
-					xresolution: this._num( params.xresolution, 1280 ),
-					yresolution: this._num( params.yresolution, 720 ),
-					resolutionGiven: Boolean( params.xresolution || params.yresolution ),
-					filename: this._str( params.filename, null )
-				};
+				this._translate( params, `${name} ${type}`, () => {
+
+					this.ir.film = {
+						xresolution: this._num( param( params, 'xresolution' ), 1280 ),
+						yresolution: this._num( param( params, 'yresolution' ), 720 ),
+						resolutionGiven: Boolean( params.xresolution || params.yresolution ),
+						filename: this._str( param( params, 'filename' ), null )
+					};
+
+				} );
 				break;
 
 			}
@@ -613,18 +713,26 @@ export class PBRTParser {
 			// What the scene asks the renderer for; reported, not applied (PBRTSceneBuilder renderRequest).
 			case 'Integrator': {
 
-				this._expectString( 'Integrator type' );
+				const type = this._expectString( 'Integrator type' );
 				const params = this._parseParams();
-				if ( params.maxdepth ) this.ir.integrator = { maxdepth: this._num( params.maxdepth, 5 ) };
+				this._translate( params, `${name} ${type}`, () => {
+
+					if ( params.maxdepth ) this.ir.integrator = { maxdepth: this._num( param( params, 'maxdepth' ), 5 ) };
+
+				} );
 				break;
 
 			}
 
 			case 'Sampler': {
 
-				this._expectString( 'Sampler type' );
+				const type = this._expectString( 'Sampler type' );
 				const params = this._parseParams();
-				if ( params.pixelsamples ) this.ir.sampler = { pixelsamples: this._num( params.pixelsamples, 16 ) };
+				this._translate( params, `${name} ${type}`, () => {
+
+					if ( params.pixelsamples ) this.ir.sampler = { pixelsamples: this._num( param( params, 'pixelsamples' ), 16 ) };
+
+				} );
 				break;
 
 			}
@@ -633,11 +741,17 @@ export class PBRTParser {
 			case 'PixelFilter':
 			case 'Filter':
 			case 'Accelerator':
-			case 'ColorSpace':
-			case 'Option':
-				this._skipTypeAndParams();
+			case 'ColorSpace': {
+
+				const type = this._peek()?.type === TokenType.STRING ? this._next().value : '';
+				this._translate( this._parseParams(), `${name} ${type}` );
 				break;
 
+			}
+
+			// `Option "type name" value`: one parameter, no type before it.
+			case 'Option': this._translate( this._parseParams(), name ); break;
+
 			// ── world block ──
 			case 'WorldBegin':
 				this.ctm = M.identity();
@@ -669,7 +783,14 @@ export class PBRTParser {
 			case 'ReverseOrientation': this.state.reverseOrientation = ! this.state.reverseOrientation; break;
 
 			// `Attribute "target" params` — v4 default-setting; ignored for MVP.
-			case 'Attribute': this._expectString( 'Attribute target' ); this._parseParams(); break;
+			case 'Attribute': {
+
+				const target = this._expectString( 'Attribute target' );
+				this._translate( this._parseParams(), `${name} ${target}` );
+				break;
+
+			}
+
 			case 'ActiveTransform': {
 
 				const t = this._next();
@@ -744,7 +865,9 @@ export class PBRTParser {
 				const dataType = this._expectString( 'Texture data type' ); // float | spectrum
 				const texClass = this._expectString( 'Texture class' ); // imagemap | scale | ...
 				const params = this._parseParams();
-				this.ir.namedTextures.set( texName, { dataType, class: texClass, params } );
+				const def = { dataType, class: texClass, params };
+				if ( this._str( params.mapping, 'uv' ) !== 'uv' ) def.ctm = this._ctmSnapshot();
+				this.ir.namedTextures.set( texName, def );
 				break;
 
 			}
@@ -839,7 +962,7 @@ export class PBRTParser {
 			default:
 				this._warnUnknown( name );
 				// Best effort: swallow any trailing parameter list to stay in sync.
-				this._parseParams();
+				this._translate( this._parseParams(), name );
 				break;
 
 		}
@@ -992,11 +1115,10 @@ export class PBRTParser {
 
 	}
 
-	_skipTypeAndParams() {
+	/** Runs `read` over a directive's parameters, and counts what it leaves unread: all of them by default. */
+	_translate( params, label, read = () => {} ) {
 
-		// "type" then params
-		if ( this._peek() && this._peek().type === TokenType.STRING ) this._next();
-		this._parseParams();
+		return this.usage ? this.usage.translate( params, label, read ) : read();
 
 	}