rayzee 7.25.0 → 7.26.0

package/package.json

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

package/src/PathTracerApp.js

@@ -109,6 +109,9 @@ export class PathTracerApp extends EventDispatcher {
 		this.canvas = canvas;
 		this._autoResize = options.autoResize !== false;
 		this._container = options.container || null;
+		// Apply the environment authored into a model file's metadata on load. See _beginSceneMetadataEnvironment().
+		this._applySceneMetadataEnabled = options.applySceneMetadata !== false;
+		this._applyingSceneMetadata = false;
 
 		// ── Settings (single source of truth for all render parameters) ──
 		this.settings = new RenderSettings( DEFAULT_STATE );
@@ -674,17 +677,26 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * A load is already running. Typed so hosts can tell "you clicked too fast" apart from
+	 * a genuine load failure and say so, instead of dropping the request on the floor.
+	 * @private
+	 */
+	_busyError( where ) {
+
+		const error = new Error( `${where}: another load is already in progress` );
+		error.code = 'LOAD_IN_PROGRESS';
+		return error;
+
+	}
+
 	/**
 	 * Loads an environment map and rebuilds CDF.
 	 * @param {string} url - Environment URL
 	 */
 	async loadEnvironment( url ) {
 
-		if ( this._loadingInProgress ) {
-
-			throw new Error( 'PathTracerApp.loadEnvironment: another load is already in progress' );
-
-		}
+		if ( this._loadingInProgress ) throw this._busyError( 'PathTracerApp.loadEnvironment' );
 
 		this._loadingInProgress = true;
 
@@ -711,6 +723,63 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Loads a user-supplied File (drag-drop, file picker) — model, archive, or environment
+	 * map, dispatched by extension.
+	 *
+	 * Prefer this over driving `assetLoader.loadAssetFromFile()` directly. That bypasses the
+	 * in-progress guard, and AssetLoader disposes the outgoing model before it knows whether
+	 * the engine will rebuild: a file dropped mid-load would tear down the live scene, add the
+	 * new one to the graph, and then be discarded by the `load` handler — leaving the path
+	 * tracer rendering buffers whose geometry has been freed. Here a concurrent call throws
+	 * LOAD_IN_PROGRESS before anything is touched.
+	 *
+	 * @param {File} file
+	 * @returns {Promise<void>}
+	 */
+	async loadFile( file ) {
+
+		const format = this.assetLoader?.getFileFormat( file?.name || '' );
+		if ( ! format ) throw new Error( `Unsupported file format: ${file?.name}` );
+
+		if ( format.type !== 'environment' && format.type !== 'image' ) {
+
+			await this._loadWithSceneRebuild(
+				() => this.assetLoader.loadAssetFromFile( file ),
+				{ type: 'ModelLoaded', filename: file.name }
+			);
+			return;
+
+		}
+
+		// Environment drop: install it, no scene rebuild.
+		if ( this._loadingInProgress ) throw this._busyError( 'PathTracerApp.loadFile' );
+
+		this._loadingInProgress = true;
+
+		try {
+
+			await this.assetLoader.loadAssetFromFile( file );
+
+			const texture = this.meshScene.environment;
+			if ( texture && this.stages.pathTracer ) {
+
+				await this.stages.pathTracer.environment.applyHDRI( texture );
+
+			}
+
+			this.pipeline?.eventBus.emit( 'autoexposure:resetHistory' );
+			this.reset();
+			this.dispatchEvent( { type: 'EnvironmentLoaded', filename: file.name } );
+
+		} finally {
+
+			this._loadingInProgress = false;
+
+		}
+
+	}
+
 	/**
 	 * Loads example models by index.
 	 * @param {number} index
@@ -784,11 +853,7 @@ export class PathTracerApp extends EventDispatcher {
 	/** Shared pipeline: load asset → sync controls → build BVH → reset → dispatch events */
 	async _loadWithSceneRebuild( loadFn, eventPayload ) {
 
-		if ( this._loadingInProgress ) {
-
-			throw new Error( 'PathTracerApp: another load is already in progress' );
-
-		}
+		if ( this._loadingInProgress ) throw this._busyError( 'PathTracerApp' );
 
 		this._loadingInProgress = true;
 
@@ -803,7 +868,7 @@ export class PathTracerApp extends EventDispatcher {
 			// (The old primary was already released by releaseTargetModel() in loadFn.)
 			this._clearAppendedModels();
 			this._syncControlsAfterLoad();
-			await this.loadSceneData();
+			await this.loadSceneData( { pendingEnvironment: this._beginSceneMetadataEnvironment() } );
 			this.pipeline?.eventBus.emit( 'autoexposure:resetHistory' );
 			this.reset();
 			this.cameraManager.currentCameraIndex = 0;
@@ -818,11 +883,99 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Scene-level authoring metadata carried by the current model file (glTF `extras`),
+	 * or null when the file has none. See {@link module:Processor/SceneMetadata}.
+	 * @type {{ environment?: { sourceFile: string, rotation?: number, intensity?: number } }|null}
+	 */
+	get sceneMetadata() {
+
+		return this.assetLoader?.sceneMetadata ?? null;
+
+	}
+
+	/**
+	 * Starts fetching the environment authored into the just-loaded model's metadata and
+	 * returns a promise for the texture — deliberately NOT awaited here. The fetch is the
+	 * longest single step of such a load (measured 1448 ms for a 1k HDRI against 325 ms to
+	 * build and upload a 112k-triangle scene), so the promise is handed to loadSceneData(),
+	 * which installs it and builds its CDF while the BVH builds.
+	 *
+	 * Called from both replace-load seams: the URL/catalog path (_loadWithSceneRebuild) and
+	 * the drag-drop / File-open path, which drives the AssetLoader directly and rebuilds via
+	 * the 'load' event (_onAssetLoaded). Appending a model never applies it — an appended
+	 * model must not hijack the scene's environment.
+	 *
+	 * Resolves to null and never rejects: a failed fetch leaves the model on the current
+	 * environment. Returns null outright when there is nothing to apply.
+	 * Opt out per app with `new PathTracerApp( canvas, { applySceneMetadata: false } )`.
+	 *
+	 * @returns {Promise<import('three').Texture|null>|null}
+	 */
+	_beginSceneMetadataEnvironment() {
+
+		const env = this.sceneMetadata?.environment;
+		if ( ! this._applySceneMetadataEnabled || ! env?.sourceFile || ! this.stages.pathTracer ) return null;
+
+		// Claim 'hdri' mode up front: loadEnvironment() fires beforeEnvironmentLoad, and a
+		// host that answers it with setMode( 'hdri' ) would otherwise restore the HDRI
+		// stashed by the current sky mode on top of the download now in flight.
+		this.stages.pathTracer.environment.beginHDRI();
+		this._applyingSceneMetadata = true;
+
+		return this.assetLoader.loadEnvironment( env.sourceFile )
+			.catch( error => {
+
+				log.warn( `scene metadata: environment "${env.sourceFile}" failed to load`, error );
+				return null;
+
+			} )
+			.finally( () => {
+
+				this._applyingSceneMetadata = false;
+
+			} );
+
+	}
+
+	/**
+	 * Mirrors the authored environment onto the settings once its texture is installed.
+	 * The authored env is both the light and the backdrop, so the backdrop axis
+	 * (showBackground / transparentBackground) is forced to the image.
+	 * @private
+	 */
+	_applySceneMetadataSettings( texture ) {
+
+		const metadata = this.sceneMetadata;
+		const env = metadata?.environment;
+		if ( ! env ) return;
+
+		const updates = { enableEnvironment: true, showBackground: true, transparentBackground: false };
+		if ( env.intensity !== undefined ) {
+
+			updates.environmentIntensity = env.intensity;
+			updates.backgroundIntensity = env.intensity;
+
+		}
+
+		if ( env.rotation !== undefined ) updates.environmentRotation = env.rotation;
+
+		this.settings.setMany( updates, { reset: false } );
+		if ( this.scene ) this.scene.background = texture;
+
+		this.dispatchEvent( { type: 'SceneMetadataApplied', metadata, environment: { ...env } } );
+
+	}
+
 	/**
 	 * Builds BVH from meshScene and uploads all scene data to the path tracer.
+	 * @param {Object} [options]
+	 * @param {Promise<import('three').Texture|null>} [options.pendingEnvironment] - An
+	 *   environment still being fetched (see _beginSceneMetadataEnvironment). Installed and
+	 *   CDF'd concurrently with the BVH build rather than before it.
 	 * @returns {boolean}
 	 */
-	async loadSceneData() {
+	async loadSceneData( { pendingEnvironment = null } = {} ) {
 
 		// Clear selection before rebuilding — the old object leaves the scene graph.
 		// Skipped on the append path (addModel): the selected object persists, so its
@@ -841,7 +994,23 @@ export class PathTracerApp extends EventDispatcher {
 
 		// Environment CDF build in parallel with BVH
 		let cdfPromise = null;
-		if ( environmentTexture?.image?.data ) {
+		if ( pendingEnvironment ) {
+
+			// The authored environment is still downloading. Install + CDF it off to the side so
+			// the fetch overlaps the BVH build below instead of gating it.
+			timer.start( 'Environment fetch + CDF (concurrent)' );
+			cdfPromise = pendingEnvironment
+				.then( async texture => {
+
+					if ( ! texture ) return;
+					await this.stages.pathTracer.environment.applyHDRI( texture );
+					this._applySceneMetadataSettings( texture );
+
+				} )
+				.catch( error => log.warn( 'scene metadata: environment install failed', error ) )
+				.finally( () => timer.end( 'Environment fetch + CDF (concurrent)' ) );
+
+		} else if ( environmentTexture?.image?.data ) {
 
 			timer.start( 'Environment CDF build (worker)' );
 			this.stages.pathTracer.scene.environment = environmentTexture;
@@ -861,7 +1030,9 @@ export class PathTracerApp extends EventDispatcher {
 		await new Promise( r => setTimeout( r, 0 ) );
 		timer.start( 'GPU data transfer' );
 
-		if ( ! this._sdf.uploadToPathTracer( this.stages.pathTracer, this.lightManager, this.meshScene, environmentTexture ) ) return false;
+		// Re-read rather than reusing the snapshot above: a pendingEnvironment may have landed
+		// during the BVH build, and the snapshot is then a disposed texture.
+		if ( ! this._sdf.uploadToPathTracer( this.stages.pathTracer, this.lightManager, this.meshScene, this.meshScene.environment ) ) return false;
 
 		// Patch per-mesh visibility into the TLAS leaves we just uploaded
 		this.stages.pathTracer._meshRefs = this.stages.pathTracer._collectMeshRefs( this.meshScene );
@@ -2612,11 +2783,18 @@ export class PathTracerApp extends EventDispatcher {
 
 			if ( this._loadingInProgress ) return;
 
+			// The authored-environment fetch runs through this same AssetLoader, so its 'load'
+			// event lands right back here. We install that texture ourselves — without the
+			// guard the texture branch below would rebuild the CDF a second time and
+			// resetLoading() would tear down the overlay mid-upload. Model events still pass:
+			// a user can drop another file while the environment is in flight.
+			if ( this._applyingSceneMetadata && event.texture ) return;
+
 			if ( event.model ) {
 
 				// Drag-drop / file load is a replace: clear any appended models first.
 				this._clearAppendedModels();
-				await this.loadSceneData();
+				await this.loadSceneData( { pendingEnvironment: this._beginSceneMetadataEnvironment() } );
 
 			} else if ( event.texture ) {
 

package/src/Processor/AssetLoader.js

@@ -14,6 +14,7 @@ import { disposeObjectFromMemory, updateLoading } from './utils';
 import { BuildTimer } from './BuildTimer.js';
 import { getAssetConfig } from '../AssetConfig.js';
 import { loadPBRTScene, pickEntryPath } from './PBRT/index.js';
+import { extractSceneMetadata } from './SceneMetadata.js';
 
 // Define supported file formats
 const SUPPORTED_FORMATS = {
@@ -55,6 +56,10 @@ export class AssetLoader extends EventDispatcher {
 		this.animations = [];
 		this.renderer = null;
 
+		// Scene-level authoring metadata from the current model (glTF `extras`), or null.
+		// See SceneMetadata.js. Cleared by releaseTargetModel() on every replace-load.
+		this.sceneMetadata = null;
+
 		// Shared across every loader so cancelActiveLoad() can abort whichever
 		// fetch is in flight (three r185 FileLoader wires the manager's abort
 		// signal into its fetch). One load runs at a time (guarded upstream).
@@ -134,6 +139,8 @@ export class AssetLoader extends EventDispatcher {
 	 */
 	releaseTargetModel() {
 
+		this.sceneMetadata = null;
+
 		if ( ! this.targetModel ) return;
 
 		if ( this.targetModel === this._externalModel ) {
@@ -298,7 +305,7 @@ export class AssetLoader extends EventDispatcher {
 			texture.generateMipmaps = true;
 
 			this.applyEnvironmentToScene( texture );
-			this.dispatchEvent( { type: 'load', texture } );
+			this.dispatchEvent( { type: 'load', texture, url: envUrl, filename: envUrl.split( /[?#]/ )[ 0 ].split( '/' ).pop() } );
 			return texture;
 
 		} catch ( error ) {
@@ -804,6 +811,7 @@ export class AssetLoader extends EventDispatcher {
 
 							this.releaseTargetModel();
 							this.targetModel = gltf.scene;
+							this.sceneMetadata = extractSceneMetadata( gltf );
 							this.onModelLoad( this.targetModel ).then( () => resolve( gltf ) );
 
 						},
@@ -1104,6 +1112,7 @@ export class AssetLoader extends EventDispatcher {
 
 			this.targetModel = data.scene;
 			this.animations = data.animations || [];
+			this.sceneMetadata = extractSceneMetadata( data );
 			await this.onModelLoad( this.targetModel );
 			this.dispatchEvent( { type: 'load', model: data.scene, filename: modelUrl.split( '/' ).pop() } );
 			return data;
@@ -1204,6 +1213,7 @@ export class AssetLoader extends EventDispatcher {
 
 			this.targetModel = data.scene;
 			this.animations = data.animations || [];
+			this.sceneMetadata = extractSceneMetadata( data );
 			updateLoading( { isLoading: true, status: "Processing Data...", progress: 10 } );
 			await this.onModelLoad( this.targetModel );
 

package/src/Processor/SceneMetadata.js

@@ -0,0 +1,123 @@
+/**
+ * SceneMetadata.js
+ * Scene-level authoring metadata carried inside an asset file.
+ *
+ * glTF/GLB carries it in `extras`, which three's GLTFLoader surfaces in three
+ * places depending on where the exporter wrote it: top-level `extras` becomes
+ * `gltf.userData`, `asset.extras` stays on `gltf.asset.extras`, and a scene's
+ * `extras` becomes `gltf.scene.userData`. All three are scanned, and the payload
+ * may sit at the root or be namespaced under a `rayzee` key.
+ *
+ * Recognised payload:
+ *   {
+ *     "environment": {
+ *       "sourceFile": "https://.../brown_photostudio_02_1k.hdr",
+ *       "rotation": 0,      // degrees around Y, matches the environmentRotation setting
+ *       "intensity": 1      // drives both environmentIntensity and backgroundIntensity
+ *     }
+ *   }
+ *
+ * Values may also arrive as JSON strings — DCC custom-property round-trips often
+ * stringify nested objects — so every container is parsed leniently.
+ */
+
+const ENV_URL_KEYS = [ 'sourceFile', 'url', 'file' ];
+
+function asObject( value ) {
+
+	if ( typeof value === 'string' ) {
+
+		try {
+
+			const parsed = JSON.parse( value );
+			return ( parsed && typeof parsed === 'object' ) ? parsed : null;
+
+		} catch {
+
+			return null;
+
+		}
+
+	}
+
+	return ( value && typeof value === 'object' ) ? value : null;
+
+}
+
+function asNumber( value ) {
+
+	const n = typeof value === 'string' ? parseFloat( value ) : value;
+	return Number.isFinite( n ) ? n : undefined;
+
+}
+
+function pickPayload( container ) {
+
+	const obj = asObject( container );
+	if ( ! obj ) return null;
+
+	const scoped = asObject( obj.rayzee );
+	if ( scoped && scoped.environment !== undefined ) return scoped;
+
+	return obj.environment !== undefined ? obj : null;
+
+}
+
+function normalizeEnvironment( raw ) {
+
+	const env = asObject( raw );
+	if ( ! env ) return null;
+
+	const sourceFile = ENV_URL_KEYS
+		.map( key => env[ key ] )
+		.find( value => typeof value === 'string' && value.trim() );
+	if ( ! sourceFile ) return null;
+
+	const rotation = asNumber( env.rotation );
+	const intensity = asNumber( env.intensity );
+
+	const normalized = { sourceFile: sourceFile.trim() };
+	if ( rotation !== undefined ) normalized.rotation = rotation;
+	if ( intensity !== undefined ) normalized.intensity = Math.max( 0, intensity );
+
+	return normalized;
+
+}
+
+/**
+ * Reads scene metadata out of one `extras`-shaped container.
+ * @param {Object|string|null} container
+ * @returns {{ environment?: { sourceFile: string, rotation?: number, intensity?: number } }|null}
+ */
+export function parseSceneMetadata( container ) {
+
+	const payload = pickPayload( container );
+	if ( ! payload ) return null;
+
+	const environment = normalizeEnvironment( payload.environment );
+	return environment ? { environment } : null;
+
+}
+
+/**
+ * Reads scene metadata out of a GLTFLoader parse result.
+ * @param {Object} gltf - The object GLTFLoader resolves with
+ * @returns {{ environment?: { sourceFile: string, rotation?: number, intensity?: number } }|null}
+ */
+export function extractSceneMetadata( gltf ) {
+
+	if ( ! gltf ) return null;
+
+	const containers = [ gltf.userData, gltf.asset?.extras, gltf.scene?.userData ];
+	if ( Array.isArray( gltf.scenes ) ) containers.push( ...gltf.scenes.map( scene => scene?.userData ) );
+
+	for ( const container of containers ) {
+
+		const metadata = parseSceneMetadata( container );
+		if ( metadata ) return metadata;
+
+	}
+
+	return null;
+
+}

package/src/index.js

@@ -17,6 +17,9 @@ export { EngineEvents } from './EngineEvents.js';
 // Asset URL / cache namespace overrides (call before constructing PathTracerApp)
 export { configureAssets, getAssetConfig } from './AssetConfig.js';
 
+// Scene-level authoring metadata embedded in model files (glTF `extras`)
+export { extractSceneMetadata, parseSceneMetadata } from './Processor/SceneMetadata.js';
+
 // Logging — leveled/namespaced console output shared with the workers
 export { Logger, createLogger, fmt, LOG_LEVELS } from './utils/Logger.js';
 

package/src/managers/EnvironmentManager.js

@@ -360,8 +360,11 @@ export class EnvironmentManager {
 	/**
 	 * Set environment map, build CDF, and update shader texture nodes.
 	 * @param {import('three').Texture|null} envMap
+	 * @param {Object}  [options]
+	 * @param {boolean} [options.buildCDF=true] - Skip when the caller builds the CDF itself
+	 *   (PathTracerApp.loadSceneData builds it in parallel with the BVH, then calls applyCDFResults).
 	 */
-	async setEnvironmentMap( envMap ) {
+	async setEnvironmentMap( envMap, { buildCDF = true } = {} ) {
 
 		// Free the outgoing env texture's GPU memory before it is orphaned. Skip: the
 		// reusable placeholder, an idempotent re-set of the same texture, and the HDRI
@@ -379,7 +382,7 @@ export class EnvironmentManager {
 
 		if ( envMap ) {
 
-			await this.buildEnvironmentCDF();
+			if ( buildCDF ) await this.buildEnvironmentCDF();
 
 		} else {
 
@@ -411,6 +414,35 @@ export class EnvironmentManager {
 
 	}
 
+	/**
+	 * Enter 'hdri' mode ahead of an async HDRI install, and drop the texture stashed by a
+	 * previous setMode( 'gradient' | 'color' | 'procedural' ): a new HDRI makes it
+	 * unreachable, so leaving it in place both leaks it and lets a setMode( 'hdri' )
+	 * arriving mid-download restore it over the map we are about to install.
+	 * @param {import('three').Texture} [incoming] - Never disposed, even if it is the stash.
+	 */
+	beginHDRI( incoming = null ) {
+
+		if ( this._previousHDRI && this._previousHDRI !== incoming ) this._previousHDRI.dispose?.();
+
+		this._previousHDRI = null;
+		this.envParams.mode = 'hdri';
+
+	}
+
+	/**
+	 * Install an HDRI as the active environment, switching the mode state machine to 'hdri'.
+	 * @param {import('three').Texture} envMap
+	 * @param {Object}  [options]
+	 * @param {boolean} [options.buildCDF=true]
+	 */
+	async applyHDRI( envMap, { buildCDF = true } = {} ) {
+
+		this.beginHDRI( envMap );
+		await this.setEnvironmentMap( envMap, { buildCDF } );
+
+	}
+
 	// ===== SKY GENERATORS =====
 
 	/**