rayzee 7.24.0 → 7.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "7.24.0",
+  "version": "7.25.0",
   "type": "module",
   "description": "Real-time WebGPU path tracing engine built on Three.js",
   "main": "dist/rayzee.umd.js",
@@ -18,7 +18,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/atul-mourya/RayTracing.git",
+    "url": "git+https://github.com/atul-mourya/rayzee-renderer.git",
     "directory": "rayzee"
   },
   "keywords": [

package/src/Passes/AIUpscaler.js

@@ -1,5 +1,5 @@
 import { EventDispatcher, ACESFilmicToneMapping } from 'three';
-import { TONE_MAP_FNS, SRGB_GAMMA, applySaturation } from '../Processor/ToneMapCPU.js';
+import { TONE_MAP_FNS, SRGB_GAMMA, applySaturation, effectiveExposure } from '../Processor/ToneMapCPU.js';
 import { getAssetConfig } from '../AssetConfig.js';
 import AIUpscalerWorker from '../Processor/Workers/AIUpscalerWorker.js?worker&inline';
 
@@ -400,7 +400,7 @@ export class AIUpscaler extends EventDispatcher {
 		if ( sourceImageData.isHDR ) {
 
 			this._hdrToneMapFn = TONE_MAP_FNS.get( this.getToneMapping() ) || TONE_MAP_FNS.get( ACESFilmicToneMapping );
-			this._hdrExposure = this.getExposure();
+			this._hdrExposure = effectiveExposure( this.getExposure(), this.getToneMapping() );
 			this._hdrSaturation = this.getSaturation();
 			this._tmOut = new Float32Array( 3 );
 
@@ -793,7 +793,7 @@ export class AIUpscaler extends EventDispatcher {
 			const imageData = ctx.createImageData( width, height );
 			const pixels = imageData.data;
 			const tmFn = TONE_MAP_FNS.get( this.getToneMapping() ) || TONE_MAP_FNS.get( ACESFilmicToneMapping );
-			const exposure = this.getExposure();
+			const exposure = effectiveExposure( this.getExposure(), this.getToneMapping() );
 			const saturation = this.getSaturation();
 			const out = new Float32Array( 3 );
 

package/src/Passes/OIDNDenoiser.js

@@ -16,7 +16,7 @@ async function getInitUNetFromURL() {
 
 }
 
-import { TONE_MAP_FNS, linearToSRGB, applySaturation } from '../Processor/ToneMapCPU.js';
+import { TONE_MAP_FNS, linearToSRGB, applySaturation, effectiveExposure } from '../Processor/ToneMapCPU.js';
 import { getAssetConfig } from '../AssetConfig.js';
 
 /** Reusable RGB output buffer (avoids per-pixel allocation). */
@@ -764,7 +764,7 @@ export class OIDNDenoiser extends EventDispatcher {
 	/** Display exposure with the input scale divided back out — output arrives pre-multiplied. */
 	_outputExposure() {
 
-		return this.getExposure() / this._oidnInputScale;
+		return effectiveExposure( this.getExposure(), this.getToneMapping() ) / this._oidnInputScale;
 
 	}
 

package/src/PathTracerApp.js

@@ -366,8 +366,11 @@ export class PathTracerApp extends EventDispatcher {
 				memoryPeak: tracker?.peak ?? 0,
 			} );
 
-			// Check time limit
-			if ( this.completion.isTimeLimitReached( this.settings.get( 'renderLimitMode' ), this.settings.get( 'renderTimeLimit' ) ) ) {
+			// Only the wall-clock stop — PathTracer.render() retires the ceiling and convergence
+			// itself, so whichever of the three arrives first wins.
+			if ( this.completion.isTimeLimitReached(
+				this.stages.pathTracer, this.settings.get( 'renderLimitMode' ), this.settings.get( 'renderTimeLimit' )
+			) ) {
 
 				this.stages.pathTracer.isComplete = true;
 
@@ -381,8 +384,14 @@ export class PathTracerApp extends EventDispatcher {
 					context: this.pipeline?.context,
 				} );
 
-				this.dispatchEvent( { type: 'RenderComplete' } );
-				this.dispatchEvent( { type: EngineEvents.RENDER_COMPLETE } );
+				const completionInfo = {
+					samples: this.stages.pathTracer.frameCount,
+					timeElapsed: this.completion.timeElapsed,
+					budgetOverrun: this.completion.budgetOverrun,
+				};
+
+				this.dispatchEvent( { type: 'RenderComplete', ...completionInfo } );
+				this.dispatchEvent( { type: EngineEvents.RENDER_COMPLETE, ...completionInfo } );
 
 			}
 

package/src/Pipeline/CompletionTracker.js

@@ -1,3 +1,7 @@
+import { createLogger } from '../utils/Logger.js';
+
+const log = createLogger( 'engine' );
+
 /**
  * Tracks render completion state, time limits, and sample limits.
  *
@@ -12,6 +16,10 @@ export class CompletionTracker {
 		this.lastResetTime = performance.now();
 		this.renderCompleteDispatched = false;
 
+		/** Whether the deadline — rather than the ceiling or convergence — retired the frame. */
+		this.budgetOverrun = false;
+		this._budgetHeldWarned = false;
+
 	}
 
 	/**
@@ -24,19 +32,48 @@ export class CompletionTracker {
 	}
 
 	/**
-	 * Checks whether the time-based render limit has been reached.
-	 * @param {string} renderLimitMode - 'time' or 'samples'
+	 * Checks whether the wall-clock render budget has expired. An additional stop condition,
+	 * never a replacement — the sample ceiling and convergence still bind when they come first.
+	 *
+	 * Floored at one sample: frameCount does not advance while the stage compiles kernels or
+	 * while the camera is in interaction mode, and retiring in that window denoises an empty
+	 * buffer and captures a blank canvas.
+	 *
+	 * @param {Object} pathTracer - The PathTracer stage
+	 * @param {string} renderLimitMode - 'time' or 'frames'
 	 * @param {number} renderTimeLimit - Time limit in seconds
 	 * @returns {boolean}
 	 */
-	isTimeLimitReached( renderLimitMode, renderTimeLimit ) {
+	isTimeLimitReached( pathTracer, renderLimitMode, renderTimeLimit ) {
+
+		if ( renderLimitMode !== 'time' || ! ( renderTimeLimit > 0 ) ) return false;
+		if ( this.timeElapsed < renderTimeLimit ) return false;
+
+		if ( ! ( pathTracer?.frameCount > 0 ) ) {
 
-		return renderLimitMode === 'time' && renderTimeLimit > 0 && this.timeElapsed >= renderTimeLimit;
+			if ( ! this._budgetHeldWarned ) {
+
+				this._budgetHeldWarned = true;
+				log.warn(
+					`render time limit (${renderTimeLimit}s) expired before the first sample landed — ` +
+					'holding the deadline open to avoid capturing an empty frame'
+				);
+
+			}
+
+			return false;
+
+		}
+
+		this.budgetOverrun = true;
+		return true;
 
 	}
 
 	/**
-	 * Checks whether ANY render limit (time or samples) is reached.
+	 * Checks whether ANY render limit is reached: sample ceiling, convergence, or time budget,
+	 * whichever arrives first.
+	 *
 	 * @param {Object} pathTracer - The PathTracer stage
 	 * @param {string} renderLimitMode
 	 * @param {number} renderTimeLimit
@@ -46,7 +83,7 @@ export class CompletionTracker {
 
 		if ( ! pathTracer ) return false;
 
-		if ( this.isTimeLimitReached( renderLimitMode, renderTimeLimit ) ) return true;
+		if ( this.isTimeLimitReached( pathTracer, renderLimitMode, renderTimeLimit ) ) return true;
 
 		// Tier-1 convergence early-stop must agree with PathTracer.render()'s own check, else the app-level
 		// reconcile would flip isComplete back off and keep dispatching after the frame converged.
@@ -75,6 +112,8 @@ export class CompletionTracker {
 		this.timeElapsed = 0;
 		this.lastResetTime = performance.now();
 		this.renderCompleteDispatched = false;
+		this.budgetOverrun = false;
+		this._budgetHeldWarned = false;
 
 	}
 

package/src/Processor/AssetLoader.js

@@ -9,7 +9,7 @@ import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
 import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';
 import { createMeshesFromMultiMaterialMesh } from 'three/addons/utils/SceneUtils.js';
 import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
-import { unzipSync, strFromU8 } from 'three/addons/libs/fflate.module.js';
+import { unzipSync, zipSync, strFromU8 } from 'three/addons/libs/fflate.module.js';
 import { disposeObjectFromMemory, updateLoading } from './utils';
 import { BuildTimer } from './BuildTimer.js';
 import { getAssetConfig } from '../AssetConfig.js';
@@ -21,13 +21,20 @@ const SUPPORTED_FORMATS = {
 	'fbx': { type: 'model', name: 'FBX' }, 'obj': { type: 'model', name: 'OBJ' },
 	'stl': { type: 'model', name: 'STL' }, 'ply': { type: 'model', name: 'PLY (Polygon File Format)' },
 	'dae': { type: 'model', name: 'Collada' }, '3mf': { type: 'model', name: '3D Manufacturing Format' },
-	'usdz': { type: 'model', name: 'Universal Scene Description' },
+	'usd': { type: 'model', name: 'USD (Universal Scene Description)' },
+	'usda': { type: 'model', name: 'USDA (USD ASCII)' },
+	'usdc': { type: 'model', name: 'USDC (USD Crate)' },
+	'usdz': { type: 'model', name: 'USDZ (USD Archive)' },
 	'hdr': { type: 'environment', name: 'HDR (High Dynamic Range)' }, 'exr': { type: 'environment', name: 'EXR (OpenEXR)' },
 	'png': { type: 'image', name: 'PNG' }, 'jpg': { type: 'image', name: 'JPEG' },
 	'jpeg': { type: 'image', name: 'JPEG' }, 'webp': { type: 'image', name: 'WebP' },
 	'zip': { type: 'archive', name: 'ZIP Archive' }
 };
 
+// Loose USD layers inside a ZIP compose into one scene; these pick out the
+// layers and the image assets they reference.
+const USD_LAYER_RE = /\.(usd|usda|usdc)$/i;
+const USD_IMAGE_RE = /\.(png|jpg|jpeg|avif)$/i;
 /**
  * AssetLoader class - handles loading of 3D models, environment maps, and archives
  */
@@ -234,7 +241,10 @@ export class AssetLoader extends EventDispatcher {
 			case 'ply': return await this.loadPLYFromArrayBuffer( arrayBuffer, filename );
 			case 'dae': return await this.loadColladaFromFile( file, filename );
 			case '3mf': return await this.load3MFFromArrayBuffer( arrayBuffer, filename );
-			case 'usdz': return await this.loadUSDZFromArrayBuffer( arrayBuffer, filename );
+			case 'usd':
+			case 'usda':
+			case 'usdc':
+			case 'usdz': return await this.loadUSDFromArrayBuffer( arrayBuffer, filename );
 			default: throw new Error( `Support for ${extension} files is not yet implemented` );
 
 		}
@@ -647,6 +657,10 @@ export class AssetLoader extends EventDispatcher {
 			const extension = path.split( '.' ).pop().toLowerCase();
 			if ( SUPPORTED_FORMATS[ extension ] && SUPPORTED_FORMATS[ extension ].type === 'model' ) {
 
+				// A loose layer is only one slice of a USD scene — hand the whole
+				// archive over so its references and payloads can resolve.
+				if ( USD_LAYER_RE.test( path ) ) return await this.loadUSDHierarchyFromZip( zip );
+
 				console.log( `Loading model file from ZIP: ${path}` );
 				return await this.loadModelFromZipEntry( zip[ path ], path, extension, zip );
 
@@ -658,6 +672,48 @@ export class AssetLoader extends EventDispatcher {
 
 	}
 
+	// USDLoader only builds a cross-layer asset map on its USDZ branch, so repack
+	// the archive as USDZ — root layer first, per AOUSD core spec 16.4.1.2 — and
+	// let the loader resolve the references/payloads itself.
+	async loadUSDHierarchyFromZip( zip ) {
+
+		const layers = Object.keys( zip ).filter( name => USD_LAYER_RE.test( name ) );
+		if ( layers.length === 0 ) throw new Error( 'No USD layers found in the ZIP archive' );
+
+		const root = AssetLoader._pickUSDRootLayer( layers );
+		console.log( `Loading USD scene from ZIP: ${root} (${layers.length} layers)` );
+
+		const packed = { [ root ]: [ zip[ root ], { level: 0 } ] };
+		for ( const name of Object.keys( zip ) ) {
+
+			if ( name === root ) continue;
+			if ( USD_LAYER_RE.test( name ) || USD_IMAGE_RE.test( name ) ) packed[ name ] = [ zip[ name ], { level: 0 } ];
+
+		}
+
+		return await this.loadUSDFromArrayBuffer( zipSync( packed ), root );
+
+	}
+
+	// Shallowest layer wins; among ties prefer the <dir>/<dir>.usd convention so a
+	// set's entry point beats its sibling variants.
+	static _pickUSDRootLayer( layers ) {
+
+		const depth = name => name.split( '/' ).length;
+		const minDepth = Math.min( ...layers.map( depth ) );
+		const candidates = layers.filter( name => depth( name ) === minDepth );
+
+		const conventional = candidates.find( name => {
+
+			const parts = name.split( '/' );
+			return parts.length > 1 && parts[ parts.length - 1 ].replace( USD_LAYER_RE, '' ) === parts[ parts.length - 2 ];
+
+		} );
+
+		return conventional || candidates[ 0 ];
+
+	}
+
 	async loadModelFromZipEntry( fileContent, filePath, extension, zipContents ) {
 
 		try {
@@ -698,8 +754,11 @@ export class AssetLoader extends EventDispatcher {
 				case '3mf':
 					result = await this.load3MFFromArrayBuffer( fileContent.buffer, filePath );
 					break;
+				case 'usd':
+				case 'usda':
+				case 'usdc':
 				case 'usdz':
-					result = await this.loadUSDZFromArrayBuffer( fileContent.buffer, filePath );
+					result = await this.loadUSDFromArrayBuffer( fileContent, filePath );
 					break;
 				default:
 					throw new Error( `Support for ${extension} files is not yet implemented` );
@@ -1396,21 +1455,28 @@ export class AssetLoader extends EventDispatcher {
 
 	}
 
-	async loadUSDZFromArrayBuffer( arrayBuffer, filename = 'model.usdz' ) {
+	async loadUSDFromArrayBuffer( data, filename = 'model.usd' ) {
 
 		try {
 
-			updateLoading( { isLoading: true, status: "Processing USDZ Data...", progress: 5 } );
+			updateLoading( { isLoading: true, status: "Processing USD Data...", progress: 5 } );
 			await new Promise( r => setTimeout( r, 0 ) );
 
-			if ( ! this.loaderCache.usdz ) {
+			if ( ! this.loaderCache.usd ) {
 
-				const { USDZLoader } = await import( 'three/examples/jsm/loaders/USDZLoader.js' );
-				this.loaderCache.usdz = new USDZLoader();
+				const { USDLoader } = await import( 'three/examples/jsm/loaders/USDLoader.js' );
+				this.loaderCache.usd = new USDLoader();
 
 			}
 
-			const object = this.loaderCache.usdz.parse( arrayBuffer );
+			// parse() returns the group synchronously but resolves textures async;
+			// setupPathTracing snapshots materials, so maps must land before it runs.
+			const object = await new Promise( ( resolve, reject ) => {
+
+				this.loaderCache.usd.parse( data, '', resolve, reject );
+
+			} );
+
 			object.name = filename;
 
 			this.releaseTargetModel();
@@ -1424,7 +1490,7 @@ export class AssetLoader extends EventDispatcher {
 
 		} catch ( error ) {
 
-			console.error( 'Error loading USDZ:', error );
+			console.error( 'Error loading USD:', error );
 			this.dispatchEvent( { type: 'error', message: error.message, filename } );
 			throw error;
 

package/src/Processor/ToneMapCPU.js

@@ -140,15 +140,26 @@ function neutralToneMap( r, g, b, exposure, out ) {
 
 }
 
+/**
+ * Three.js clamps the fragment output with `.max( 0 )` *before* tone mapping
+ * (NodeMaterial.js, "force unsigned floats"), so the GPU curves never see a negative
+ * channel. Compositor's saturation grade (default 1.2) drives complementary channels
+ * below zero on a third of a typical frame, and AgX/Neutral mix those negatives across
+ * channels instead of clipping them — measured 7-10 levels of shadow error against the
+ * viewport until the readback clamps the same way.
+ */
+const clampNegative = fn => ( r, g, b, exposure, out ) =>
+	fn( r > 0 ? r : 0, g > 0 ? g : 0, b > 0 ? b : 0, exposure, out );
+
 /** Look-up table mapping Three.js ToneMapping constants to CPU functions. */
 export const TONE_MAP_FNS = new Map( [
-	[ NoToneMapping, noToneMap ],
-	[ LinearToneMapping, linearToneMap ],
-	[ ReinhardToneMapping, reinhardToneMap ],
-	[ CineonToneMapping, cineonToneMap ],
-	[ ACESFilmicToneMapping, acesFilmicToneMap ],
-	[ AgXToneMapping, agxToneMap ],
-	[ NeutralToneMapping, neutralToneMap ]
+	[ NoToneMapping, clampNegative( noToneMap ) ],
+	[ LinearToneMapping, clampNegative( linearToneMap ) ],
+	[ ReinhardToneMapping, clampNegative( reinhardToneMap ) ],
+	[ CineonToneMapping, clampNegative( cineonToneMap ) ],
+	[ ACESFilmicToneMapping, clampNegative( acesFilmicToneMap ) ],
+	[ AgXToneMapping, clampNegative( agxToneMap ) ],
+	[ NeutralToneMapping, clampNegative( neutralToneMap ) ]
 ] );
 
 /** sRGB gamma (1/2.2) — fast pow approximation. Prefer `linearToSRGB` when matching Three.js's output. */
@@ -165,6 +176,25 @@ export function linearToSRGB( c ) {
 
 }
 
+/**
+ * Exposure as the WebGPU output pass applies it.
+ *
+ * Three.js applies `toneMappingExposure` *inside* ToneMappingNode's tone-mapping branch, and
+ * that branch returns the colour untouched for NoToneMapping (ToneMappingNode.js: `if
+ * ( toneMapping === NoToneMapping ) return colorNode`). So exposure is a no-op on screen there,
+ * and a CPU readback that applies it anyway paints brighter than the viewport it replaces
+ * (measured +33.6 % at exposure 2).
+ *
+ * @param {number} exposure - renderer.toneMappingExposure
+ * @param {number} toneMapping - Three.js ToneMapping constant
+ * @returns {number}
+ */
+export function effectiveExposure( exposure, toneMapping ) {
+
+	return toneMapping === NoToneMapping ? 1.0 : exposure;
+
+}
+
 /** Rec.709 luminance coefficients (same as Display / Common.js). */
 const LUM_R = 0.2126, LUM_G = 0.7152, LUM_B = 0.0722;
 

package/src/RenderSettings.js

@@ -224,6 +224,7 @@ export class RenderSettings extends EventDispatcher {
 			handleRenderLimitMode: ( value ) => {
 
 				stages.pathTracer?.setRenderLimitMode?.( value );
+				reconcileCompletion?.();
 
 			},
 

package/src/Stages/PathTracerStage.js

@@ -1185,25 +1185,15 @@ export class PathTracerStage extends RenderStage {
 	}
 
 	/**
-	 * Update completion threshold based on render mode
+	 * Update completion threshold based on render mode. The ceiling holds in every limit mode —
+	 * uncapping it under a time budget lets a generous deadline silently slow every render.
 	 */
 	updateCompletionThreshold() {
 
-		const renderMode = this.renderMode.value;
-		const maxFrames = this.maxSamples.value;
-
-		if ( this.renderLimitMode === 'time' ) {
-
-			this.completionThreshold = Infinity;
-
-		} else {
-
-			this.completionThreshold = updateCompletionThreshold(
-				renderMode,
-				maxFrames
-			);
-
-		}
+		this.completionThreshold = updateCompletionThreshold(
+			this.renderMode.value,
+			this.maxSamples.value
+		);
 
 	}