rayzee 6.2.0 → 6.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "6.2.0",
+  "version": "6.4.0",
   "type": "module",
   "description": "Real-time WebGPU path tracing engine built on Three.js",
   "main": "dist/rayzee.umd.js",

package/src/EngineDefaults.js

@@ -146,35 +146,46 @@ export const ENGINE_DEFAULTS = {
 	autoExposureAdaptSpeedDark: 0.5,
 };
 
+// Albedo demodulation safety floor. ASVGF and BilateralFilter MUST use the
+// same value — demod (`color / safeAlbedo`) and remod (`lighting * safeAlbedo`)
+// only round-trip exactly when both sides agree.
+export const ALBEDO_EPS = 0.01;
+
 export const ASVGF_QUALITY_PRESETS = {
+	// phiColor / phiDepth are RELATIVE tolerances (fractions). Bigger = more
+	// permissive. gradientStrength = 0 keeps the adaptive-α boost off; the
+	// fixed-floor gradient misfires on 1-SPP noise. Pure SVGF temporal runs.
 	low: {
-		temporalAlpha: 0.3,
-		atrousIterations: 1,
-		phiColor: 30.0,
+		temporalAlpha: 0.1,
+		gradientStrength: 0.0,
+		atrousIterations: 3,
+		phiColor: 1.0,
 		phiNormal: 64.0,
-		phiDepth: 2.0,
+		phiDepth: 0.1,
 		phiLuminance: 6.0,
-		maxAccumFrames: 8,
+		maxAccumFrames: 16,
 		varianceBoost: 0.5
 	},
 	medium: {
-		temporalAlpha: 0.1,
-		atrousIterations: 3,
-		phiColor: 20.0,
+		temporalAlpha: 0.03,
+		gradientStrength: 0.0,
+		atrousIterations: 4,
+		phiColor: 0.5,
 		phiNormal: 128.0,
-		phiDepth: 1.0,
-		phiLuminance: 2.0,
-		maxAccumFrames: 32,
+		phiDepth: 0.05,
+		phiLuminance: 4.0,
+		maxAccumFrames: 64,
 		varianceBoost: 1.0
 	},
 	high: {
-		temporalAlpha: 0.05,
-		atrousIterations: 8,
-		phiColor: 5.0,
+		temporalAlpha: 0.0,
+		gradientStrength: 0.0,
+		atrousIterations: 6,
+		phiColor: 0.3,
 		phiNormal: 256.0,
-		phiDepth: 0.5,
+		phiDepth: 0.02,
 		phiLuminance: 2.0,
-		maxAccumFrames: 64,
+		maxAccumFrames: 128,
 		varianceBoost: 1.5
 	}
 };

package/src/Processor/AssetLoader.js

@@ -1,5 +1,6 @@
 import { Box3, Vector3, RectAreaLight, Color, FloatType, LinearFilter, EquirectangularReflectionMapping,
-	TextureLoader, Mesh, MeshStandardMaterial, MeshPhysicalMaterial, CircleGeometry, Points, PointsMaterial, LoadingManager, EventDispatcher
+	TextureLoader, Texture, SRGBColorSpace, RepeatWrapping, Mesh, MeshStandardMaterial, MeshPhysicalMaterial,
+	CircleGeometry, Points, PointsMaterial, LoadingManager, EventDispatcher
 } from 'three';
 import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
 import { HDRLoader } from 'three/addons/loaders/HDRLoader.js';
@@ -12,6 +13,7 @@ import { unzipSync, strFromU8 } from 'three/addons/libs/fflate.module.js';
 import { disposeObjectFromMemory, updateLoading } from './utils';
 import { BuildTimer } from './BuildTimer.js';
 import { getAssetConfig } from '../AssetConfig.js';
+import { loadPBRTScene, pickEntryPath } from './PBRT/index.js';
 
 // Define supported file formats
 const SUPPORTED_FORMATS = {
@@ -314,6 +316,10 @@ export class AssetLoader extends EventDispatcher {
 
 			const arrayBuffer = await this.readFileAsArrayBuffer( file );
 			const zip = unzipSync( new Uint8Array( arrayBuffer ) );
+
+			// A pbrt scene archive takes priority — it owns its own geometry/texture refs.
+			if ( pickEntryPath( zip ) ) return await this.loadPBRTFromZip( zip, filename );
+
 			const result = await this.processObjMtlPairsInZip( zip, filename );
 			if ( result ) return result;
 			return await this.findAndLoadModelFromZip( zip, filename );
@@ -327,6 +333,150 @@ export class AssetLoader extends EventDispatcher {
 
 	}
 
+	/**
+	 * Loads a pbrt-v4 scene from an unzipped archive. Parses the entry .pbrt
+	 * (following Include/Import), builds a THREE.Group, sets the infinite light
+	 * as the scene environment, and runs the standard onModelLoad pipeline.
+	 * @param {Object<string, Uint8Array>} zip - unzipped entries (path → bytes)
+	 * @param {string} filename - original archive name (for display/events)
+	 */
+	async loadPBRTFromZip( zip, filename ) {
+
+		updateLoading( { isLoading: true, status: 'Parsing PBRT scene...', progress: 5 } );
+
+		// Geometry decoder — reuse the cached PLYLoader (pbrt leans on .ply meshes).
+		if ( ! this.loaderCache.ply ) {
+
+			const { PLYLoader } = await import( 'three/examples/jsm/loaders/PLYLoader.js' );
+			this.loaderCache.ply = new PLYLoader();
+
+		}
+
+		const plyParser = ( buf ) => this.loaderCache.ply.parse( buf );
+
+		// Texture maps — decode by extension (pbrt uses .png/.jpg but also .exr/.hdr/.tga).
+		const imageFromBytes = ( bytes, fname ) => this._pbrtTextureFromBytes( bytes, fname );
+
+		// Infinite-light maps → HDR/EXR/LDR via the shared environment decoder.
+		const envFromBytes = async ( bytes, fname ) => {
+
+			const ext = fname.split( '.' ).pop().toLowerCase();
+			const url = URL.createObjectURL( new Blob( [ bytes ] ) );
+			try {
+
+				return await this.loadEnvironmentByExtension( url, ext );
+
+			} finally {
+
+				URL.revokeObjectURL( url );
+
+			}
+
+		};
+
+		const { group, environment, report, warnings, entryPath } = await loadPBRTScene( {
+			vfs: zip, plyParser, imageFromBytes, envFromBytes
+		} );
+
+		// Diagnostics — surface what each mesh resolved to (helps debug black/wrong materials).
+		if ( report && report.length && typeof console.table === 'function' ) {
+
+			console.groupCollapsed( `PBRT loader: ${report.length} mesh(es) from "${entryPath}"` );
+			console.table( report );
+			console.groupEnd();
+
+		}
+
+		if ( warnings && warnings.length ) {
+
+			console.warn( `PBRT loader: ${warnings.length} warning(s) parsing "${entryPath}"` );
+			warnings.forEach( w => console.warn( '  •', w ) );
+
+		}
+
+		// Infinite light → scene environment (CDF is built later in loadSceneData).
+		if ( environment?.texture ) {
+
+			environment.texture.generateMipmaps = true;
+			this.applyEnvironmentToScene( environment.texture );
+
+		}
+
+		group.name = entryPath || filename;
+		this.releaseTargetModel();
+		this.targetModel = group;
+
+		updateLoading( { isLoading: true, status: 'Processing PBRT geometry...', progress: 10 } );
+		await this.onModelLoad( this.targetModel );
+
+		this.dispatchEvent( { type: 'load', model: group, filename: `${entryPath} (from ZIP)` } );
+		return group;
+
+	}
+
+	/**
+	 * Decodes a pbrt texture map from raw bytes, picking a decoder by extension.
+	 * ImageBitmap can't handle EXR/HDR/TGA, which pbrt scenes use freely.
+	 * @param {Uint8Array} bytes
+	 * @param {string} fname
+	 * @returns {Promise<import('three').Texture>}
+	 */
+	async _pbrtTextureFromBytes( bytes, fname ) {
+
+		const ext = fname.split( '.' ).pop().toLowerCase();
+		let tex;
+
+		if ( ext === 'exr' || ext === 'hdr' ) {
+
+			const loader = ext === 'hdr'
+				? ( this.loaderCache.hdr || ( this.loaderCache.hdr = new HDRLoader().setDataType( FloatType ) ) )
+				: ( this.loaderCache.exr || ( this.loaderCache.exr = new EXRLoader().setDataType( FloatType ) ) );
+			tex = await this._loadViaObjectURL( loader, bytes );
+			// HDR/EXR maps are linear — leave colorSpace as the loader set it.
+
+		} else if ( ext === 'tga' ) {
+
+			if ( ! this.loaderCache.tga ) {
+
+				const { TGALoader } = await import( 'three/examples/jsm/loaders/TGALoader.js' );
+				this.loaderCache.tga = new TGALoader();
+
+			}
+
+			tex = await this._loadViaObjectURL( this.loaderCache.tga, bytes );
+			tex.colorSpace = SRGBColorSpace;
+
+		} else {
+
+			// png / jpg / webp / gif / bmp
+			const bitmap = await createImageBitmap( new Blob( [ bytes ] ) );
+			tex = new Texture( bitmap );
+			tex.colorSpace = SRGBColorSpace;
+
+		}
+
+		tex.wrapS = tex.wrapT = RepeatWrapping;
+		tex.needsUpdate = true;
+		return tex;
+
+	}
+
+	/** Decode bytes through a three loader's loadAsync via a transient object URL. */
+	async _loadViaObjectURL( loader, bytes ) {
+
+		const url = URL.createObjectURL( new Blob( [ bytes ] ) );
+		try {
+
+			return await loader.loadAsync( url );
+
+		} finally {
+
+			URL.revokeObjectURL( url );
+
+		}
+
+	}
+
 	async processObjMtlPairsInZip( zip, filename ) {
 
 		const objFiles = [];

package/src/Processor/PBRT/PBRTMaterials.js

@@ -0,0 +1,350 @@
+/**
+ * Translate pbrt-v4 materials and textures to THREE.MeshPhysicalMaterial.
+ *
+ * pbrt's BxDF model (diffuse / conductor / dielectric / coateddiffuse / ...) is
+ * mapped onto the Disney-style parameters the engine reads off a
+ * MeshPhysicalMaterial (see GeometryExtractor.createMaterialObject). The mapping
+ * is intentionally lossy — spectral data, measured BRDFs, and layered BxDFs are
+ * approximated to RGB. Anything unrecognized falls back to a neutral diffuse.
+ */
+
+import { MeshPhysicalMaterial, Color, DoubleSide } from 'three';
+
+// Normal-incidence reflectance approximations for pbrt's named conductor spectra.
+const METAL_ALBEDO = {
+	au: [ 1.0, 0.78, 0.34 ], gold: [ 1.0, 0.78, 0.34 ],
+	cu: [ 0.95, 0.64, 0.54 ], copper: [ 0.95, 0.64, 0.54 ],
+	ag: [ 0.97, 0.96, 0.91 ], silver: [ 0.97, 0.96, 0.91 ],
+	al: [ 0.91, 0.92, 0.92 ], aluminium: [ 0.91, 0.92, 0.92 ], aluminum: [ 0.91, 0.92, 0.92 ],
+	mgo: [ 0.9, 0.9, 0.9 ], tio2: [ 0.9, 0.9, 0.9 ]
+};
+
+const DEFAULT_METAL = [ 0.92, 0.92, 0.92 ];
+
+/** Crude blackbody-temperature → linear RGB (Planckian locus approximation). */
+function blackbodyToRGB( kelvin ) {
+
+	const t = Math.max( 1000, Math.min( 40000, kelvin ) ) / 100;
+	let r, g, b;
+
+	if ( t <= 66 ) {
+
+		r = 255;
+		g = 99.47 * Math.log( t ) - 161.12;
+
+	} else {
+
+		r = 329.7 * Math.pow( t - 60, - 0.1332 );
+		g = 288.12 * Math.pow( t - 60, - 0.0755 );
+
+	}
+
+	if ( t >= 66 ) b = 255;
+	else if ( t <= 19 ) b = 0;
+	else b = 138.52 * Math.log( t - 10 ) - 305.04;
+
+	const clamp = v => Math.max( 0, Math.min( 255, v ) ) / 255;
+	// sRGB → approx linear
+	return [ clamp( r ) ** 2.2, clamp( g ) ** 2.2, clamp( b ) ** 2.2 ];
+
+}
+
+// ── param accessors ────────────────────────────────────────────────
+
+export function pFloat( params, name, dflt ) {
+
+	const p = params[ name ];
+	return p && typeof p.value[ 0 ] === 'number' ? p.value[ 0 ] : dflt;
+
+}
+
+export function pString( params, name, dflt ) {
+
+	const p = params[ name ];
+	return p && typeof p.value[ 0 ] === 'string' ? p.value[ 0 ] : dflt;
+
+}
+
+/**
+ * Resolve a spectrum/color/float-valued parameter to an RGB triple and/or a
+ * texture. Returns `{ rgb, texture }` — exactly one is typically non-null.
+ * @returns {Promise<{rgb:number[]|null, texture:import('three').Texture|null}>}
+ */
+export async function resolveSpectrum( params, name, ctx, dfltRGB = null ) {
+
+	const p = params[ name ];
+	if ( ! p ) return { rgb: dfltRGB, texture: null };
+
+	// Reference to a named texture.
+	if ( p.type === 'texture' ) {
+
+		const texName = p.value[ 0 ];
+		const tex = await ctx.resolveNamedTexture( texName );
+		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` );
+		return { rgb: dfltRGB, texture: null };
+
+	}
+
+	if ( p.type === 'rgb' || p.type === 'color' ) {
+
+		return { rgb: [ p.value[ 0 ], p.value[ 1 ], p.value[ 2 ] ], texture: null };
+
+	}
+
+	if ( p.type === 'float' ) {
+
+		const v = p.value[ 0 ];
+		return { rgb: [ v, v, v ], texture: null };
+
+	}
+
+	if ( p.type === 'blackbody' ) {
+
+		return { rgb: blackbodyToRGB( p.value[ 0 ] ), texture: null };
+
+	}
+
+	if ( p.type === 'spectrum' ) {
+
+		// Named spectrum (e.g. "metal-Au-eta") or sampled [lambda val ...].
+		if ( typeof p.value[ 0 ] === 'string' ) {
+
+			const key = namedMetalKey( p.value[ 0 ] );
+			if ( key && METAL_ALBEDO[ key ] ) return { rgb: METAL_ALBEDO[ key ].slice(), texture: null };
+			ctx.warn( `named spectrum "${p.value[ 0 ]}" approximated to gray` );
+			return { rgb: [ 0.5, 0.5, 0.5 ], texture: null };
+
+		}
+
+		// Sampled spectrum → average value as gray (coarse).
+		let sum = 0, count = 0;
+		for ( let i = 1; i < p.value.length; i += 2 ) {
+
+			sum += p.value[ i ]; count ++;
+
+		}
+
+		const v = count ? sum / count : 0.5;
+		return { rgb: [ v, v, v ], texture: null };
+
+	}
+
+	return { rgb: dfltRGB, texture: null };
+
+}
+
+function namedMetalKey( s ) {
+
+	const m = s.toLowerCase().match( /metal-([a-z]+)/ );
+	if ( m ) return m[ 1 ];
+	for ( const k of Object.keys( METAL_ALBEDO ) ) if ( s.toLowerCase().includes( k ) ) return k;
+	return null;
+
+}
+
+/** Roughness from `roughness` or anisotropic `uroughness`/`vroughness`. */
+function resolveRoughness( params, dflt ) {
+
+	if ( params.roughness && typeof params.roughness.value[ 0 ] === 'number' ) return params.roughness.value[ 0 ];
+	const u = pFloat( params, 'uroughness', null );
+	const v = pFloat( params, 'vroughness', null );
+	if ( u !== null && v !== null ) return ( u + v ) / 2;
+	if ( u !== null ) return u;
+	return dflt;
+
+}
+
+/**
+ * Build a MeshPhysicalMaterial from a pbrt material definition.
+ * @param {{type:string, params:object}} def
+ * @param {object} ctx - { resolveNamedTexture, warn }
+ * @returns {Promise<MeshPhysicalMaterial>}
+ */
+export async function buildMaterial( def, ctx ) {
+
+	const type = def?.type || 'diffuse';
+	const params = def?.params || {};
+	const mat = new MeshPhysicalMaterial( { side: DoubleSide, roughness: 1, metalness: 0 } );
+
+	const setColor = ( rgb ) => {
+
+		if ( rgb ) mat.color.setRGB( rgb[ 0 ], rgb[ 1 ], rgb[ 2 ] );
+
+	};
+
+	// Apply a resolved reflectance to the base color + map. A `scale` texture
+	// yields BOTH an rgb tint and a texture — keep the tint as color so three
+	// multiplies map×color. A plain imagemap (no tint) neutralizes color to white.
+	const applyAlbedo = ( refl ) => {
+
+		setColor( refl.rgb );
+		if ( refl.texture ) {
+
+			mat.map = refl.texture;
+			if ( ! refl.rgb ) mat.color.setRGB( 1, 1, 1 );
+
+		}
+
+	};
+
+	switch ( type ) {
+
+		case 'diffuse': {
+
+			applyAlbedo( await resolveSpectrum( params, 'reflectance', ctx, [ 0.5, 0.5, 0.5 ] ) );
+			mat.roughness = 1;
+			mat.metalness = 0;
+			break;
+
+		}
+
+		case 'conductor':
+		case 'metal': {
+
+			const refl = await resolveSpectrum( params, 'reflectance', ctx, null );
+			const etaP = params.eta, kP = params.k;
+			const etaNamed = etaP && etaP.type === 'spectrum' && typeof etaP.value[ 0 ] === 'string';
+
+			if ( refl.rgb || refl.texture ) {
+
+				applyAlbedo( refl );
+
+			} else if ( etaP && kP && ! etaNamed ) {
+
+				// Normal-incidence reflectance from complex IOR: ((η-1)²+k²)/((η+1)²+k²).
+				const eta = ( await resolveSpectrum( params, 'eta', ctx, [ 0.2, 0.92, 1.1 ] ) ).rgb;
+				const k = ( await resolveSpectrum( params, 'k', ctx, [ 3.9, 2.45, 2.14 ] ) ).rgb;
+				const fr = ( n, kk ) => ( ( n - 1 ) ** 2 + kk ** 2 ) / ( ( n + 1 ) ** 2 + kk ** 2 );
+				setColor( [ fr( eta[ 0 ], k[ 0 ] ), fr( eta[ 1 ], k[ 1 ] ), fr( eta[ 2 ], k[ 2 ] ) ] );
+
+			} else if ( etaP ) {
+
+				// Named conductor spectrum → metal albedo table.
+				setColor( ( await resolveSpectrum( params, 'eta', ctx, DEFAULT_METAL ) ).rgb || DEFAULT_METAL );
+
+			} else {
+
+				setColor( METAL_ALBEDO.cu ); // pbrt-v4 default conductor is copper
+
+			}
+
+			mat.metalness = 1;
+			mat.roughness = resolveRoughness( params, 0.1 );
+			break;
+
+		}
+
+		case 'dielectric':
+		case 'thindielectric': {
+
+			mat.transmission = 1;
+			mat.metalness = 0;
+			mat.color.setRGB( 1, 1, 1 );
+			mat.ior = pFloat( params, 'eta', 1.5 );
+			mat.roughness = resolveRoughness( params, 0 );
+			mat.thickness = type === 'thindielectric' ? 0 : pFloat( params, 'thickness', 0 );
+			break;
+
+		}
+
+		case 'coateddiffuse': {
+
+			applyAlbedo( await resolveSpectrum( params, 'reflectance', ctx, [ 0.5, 0.5, 0.5 ] ) );
+			mat.roughness = 0.6;
+			mat.metalness = 0;
+			mat.clearcoat = 1;
+			mat.clearcoatRoughness = resolveRoughness( params, 0 );
+			break;
+
+		}
+
+		case 'diffusetransmission': {
+
+			const trans = await resolveSpectrum( params, 'transmittance', ctx, [ 0.25, 0.25, 0.25 ] );
+			applyAlbedo( await resolveSpectrum( params, 'reflectance', ctx, [ 0.25, 0.25, 0.25 ] ) );
+			mat.transmission = trans.rgb ? ( trans.rgb[ 0 ] + trans.rgb[ 1 ] + trans.rgb[ 2 ] ) / 3 : 0.5;
+			mat.roughness = 1;
+			mat.ior = 1.0;
+			break;
+
+		}
+
+		case 'interface':
+		case 'none':
+		case '': {
+
+			// Medium boundary with no surface scattering — render as clear passthrough.
+			mat.transmission = 1;
+			mat.ior = 1.0;
+			mat.roughness = 0;
+			mat.color.setRGB( 1, 1, 1 );
+			break;
+
+		}
+
+		case 'mix': {
+
+			// pbrt blends two named materials by `amount`. Without a real layered BxDF
+			// we lerp the two resolved MeshPhysicalMaterials' scalar/color properties
+			// — 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 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;
+
+			if ( defA && defB ) {
+
+				const [ matA, matB ] = await Promise.all( [ buildMaterial( defA, ctx ), buildMaterial( defB, ctx ) ] );
+				const lerp = ( a, b ) => a * ( 1 - t ) + b * t;
+				mat.color.lerpColors( matA.color, matB.color, t );
+				mat.roughness = lerp( matA.roughness, matB.roughness );
+				mat.metalness = lerp( matA.metalness, matB.metalness );
+				mat.ior = lerp( matA.ior ?? 1.5, matB.ior ?? 1.5 );
+				mat.transmission = lerp( matA.transmission ?? 0, matB.transmission ?? 0 );
+				mat.thickness = lerp( matA.thickness ?? 0, matB.thickness ?? 0 );
+				mat.clearcoat = lerp( matA.clearcoat ?? 0, matB.clearcoat ?? 0 );
+				mat.clearcoatRoughness = lerp( matA.clearcoatRoughness ?? 0, matB.clearcoatRoughness ?? 0 );
+				mat.emissive.lerpColors( matA.emissive, matB.emissive, t );
+				mat.emissiveIntensity = lerp( matA.emissiveIntensity ?? 0, matB.emissiveIntensity ?? 0 );
+				// Maps can't be lerped — pick the dominant side.
+				mat.map = ( t < 0.5 ? matA.map : matB.map ) || null;
+				break;
+
+			}
+
+			ctx.warn( `material "mix" — could not resolve inner materials [${matNames.join( ', ' )}], falling back to diffuse` );
+			mat.color.set( new Color( 0.6, 0.6, 0.6 ) );
+			break;
+
+		}
+
+		case 'subsurface':
+		case 'hair':
+		case 'measured': {
+
+			ctx.warn( `material "${type}" not supported — using diffuse approximation` );
+			const refl = await resolveSpectrum( params, 'reflectance', ctx, [ 0.5, 0.5, 0.5 ] );
+			setColor( refl.rgb );
+			mat.roughness = 1;
+			break;
+
+		}
+
+		default: {
+
+			ctx.warn( `unknown material "${type}" — using neutral diffuse` );
+			mat.color.set( new Color( 0.6, 0.6, 0.6 ) );
+			break;
+
+		}
+
+	}
+
+	mat.roughness = Math.max( 0, Math.min( 1, mat.roughness ) );
+	return mat;
+
+}