rayzee 7.25.0 → 7.26.1

package/package.json

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

package/src/PathTracerApp.js

@@ -57,6 +57,8 @@ const _appsByCanvas = new WeakMap();
  * - `app.settings`           — {@link RenderSettings} (all render parameters)
  * - `app.stages`             — Named pipeline stages for advanced control
  * - `app.sceneMeshes`        — meshes backing the BVH, in buffer order (see {@link refitBVH})
+ * - `app.sceneModel`         — root of the rendered model (a copy, for {@link loadObject3D})
+ * - `app.getSceneObject(id)` — the rendered root for an appended object's id
  *
  * Extends EventDispatcher for event-driven communication with stores/UI.
  */
@@ -109,6 +111,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 );
@@ -623,8 +628,6 @@ export class PathTracerApp extends EventDispatcher {
 		this.interactionManager?.deselect();
 		this.transformManager?.detach?.();
 
-		// Release the loaded model. If loaded via loadObject3D(), the caller owns it —
-		// we only detach it from the scene. Otherwise dispose geometries/materials/textures.
 		this.assetLoader?.releaseTargetModel();
 
 		// Clear lights in the WebGPU light scene
@@ -662,7 +665,13 @@ export class PathTracerApp extends EventDispatcher {
 	/**
 	 * Loads a Three.js Object3D directly into the path tracer scene.
 	 * Builds BVH from the object's meshes and uploads scene data.
-	 * @param {import('three').Object3D} object3d - The Object3D to render
+	 *
+	 * Renders a copy: `object3d` is never reparented, rewritten or disposed, so passing a
+	 * subtree of a scene the host still renders is safe. Geometry/material/texture are shared
+	 * by reference, and any ancestor transform is baked in. Later edits to `object3d` do not
+	 * reach the render — mutate {@link sceneModel}, then {@link refitBVH}/{@link refitBLASes}.
+	 *
+	 * @param {import('three').Object3D} object3d - The Object3D to render; left untouched.
 	 * @param {string} [name='object3d'] - Display name for the object
 	 */
 	async loadObject3D( object3d, name = 'object3d' ) {
@@ -674,17 +683,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 +729,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 +859,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 +874,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 +889,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 +1000,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 +1036,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 );
@@ -963,10 +1140,9 @@ export class PathTracerApp extends EventDispatcher {
 	/** Tag the primary (replace-loaded) model as a removable scene object (read by the Outliner + removeSceneObject). Idempotent. */
 	_tagPrimarySceneObject() {
 
-		const m = this.assetLoader?.targetModel;
+		const m = this.sceneModel;
 		if ( ! m ) return;
 		m.userData.__rayzeeSceneObject = true;
-		m.userData.__rayzeeExternal = ( m === this.assetLoader._externalModel );
 
 	}
 
@@ -976,12 +1152,12 @@ export class PathTracerApp extends EventDispatcher {
 		const scene = this.meshScene;
 		if ( ! scene ) return;
 		const floor = this.assetLoader?.floorPlane;
-		const primary = this.assetLoader?.targetModel;
+		const primary = this.sceneModel;
 		for ( const child of [ ...scene.children ] ) {
 
 			if ( child === floor || child === primary ) continue;
 			if ( ! child.userData?.__rayzeeSceneObject ) continue;
-			this.assetLoader.removeModelRoot( child, { external: !! child.userData.__rayzeeExternal } );
+			this.assetLoader.removeModelRoot( child );
 
 		}
 
@@ -1020,7 +1196,6 @@ export class PathTracerApp extends EventDispatcher {
 
 			const { root } = await this.assetLoader.appendModel( url );
 			root.userData.__rayzeeSceneObject = true;
-			root.userData.__rayzeeExternal = false;
 			if ( name ) root.userData.__rayzeeName = name;
 			await this._finishRebuildNoReframe( { type: 'ModelAdded', url, id: root.uuid } );
 			return root.uuid;
@@ -1036,7 +1211,7 @@ export class PathTracerApp extends EventDispatcher {
 
 	/**
 	 * Append a caller-owned Object3D to the current scene, then rebuild (no reframe).
-	 * The caller retains ownership — removal only detaches it.
+	 * Appends a copy; the object passed in is never mutated. Same rules as {@link loadObject3D}.
 	 * @param {import('three').Object3D} object3d
 	 * @param {Object} [opts]
 	 * @param {string} [opts.name]
@@ -1056,7 +1231,6 @@ export class PathTracerApp extends EventDispatcher {
 
 			const { root } = this.assetLoader.appendObject3D( object3d, name || 'object3d' );
 			root.userData.__rayzeeSceneObject = true;
-			root.userData.__rayzeeExternal = true;
 			if ( name ) root.userData.__rayzeeName = name;
 			await this._finishRebuildNoReframe( { type: 'ModelAdded', id: root.uuid } );
 			return root.uuid;
@@ -1083,7 +1257,7 @@ export class PathTracerApp extends EventDispatcher {
 		const floor = this.assetLoader?.floorPlane;
 		if ( floor && floor.uuid === id ) return false; // Ground is not deletable
 
-		const root = scene.children.find( c => c.uuid === id && c.userData?.__rayzeeSceneObject );
+		const root = this.getSceneObject( id );
 		if ( ! root ) return false;
 
 		if ( this._loadingInProgress ) {
@@ -1098,13 +1272,13 @@ export class PathTracerApp extends EventDispatcher {
 			this.interactionManager?.deselect();
 			this.transformManager?.detach?.();
 
-			if ( root === this.assetLoader.targetModel ) {
+			if ( root === this.sceneModel ) {
 
 				this.assetLoader.releaseTargetModel();
 
 			} else {
 
-				this.assetLoader.removeModelRoot( root, { external: !! root.userData.__rayzeeExternal } );
+				this.assetLoader.removeModelRoot( root );
 
 			}
 
@@ -1207,6 +1381,32 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Root of the model actually being rendered. For {@link loadObject3D} this is the engine's
+	 * copy, not the object you passed — mutate this one, then {@link refitBVH}/{@link refitBLASes}.
+	 *
+	 * @returns {import('three').Object3D|null} Live reference, or null when nothing is loaded.
+	 */
+	get sceneModel() {
+
+		return this.assetLoader?.targetModel ?? null;
+
+	}
+
+	/**
+	 * Resolve an id from {@link addModel}/{@link addModelFromObject3D} to the root being
+	 * rendered for it — for an appended Object3D, the engine's copy.
+	 *
+	 * @param {string} id
+	 * @returns {import('three').Object3D|null} Live reference, or null if no such object.
+	 */
+	getSceneObject( id ) {
+
+		const root = this.meshScene?.children.find( c => c.uuid === id );
+		return root?.userData?.__rayzeeSceneObject ? root : null;
+
+	}
+
 	/**
 	 * Update vertex positions for animation without full BVH rebuild.
 	 * O(N) bottom-up AABB refit instead of O(N log N) SAH rebuild.
@@ -2612,11 +2812,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 ) {
 
@@ -2661,7 +2868,7 @@ export class PathTracerApp extends EventDispatcher {
 		const animations = this.assetLoader?.animations || [];
 		if ( animations.length > 0 ) {
 
-			const mixerRoot = this.assetLoader?.targetModel || this.meshScene;
+			const mixerRoot = this.sceneModel || this.meshScene;
 			this.animationManager.init( this.meshScene, mixerRoot, this._sdf.meshes, animations );
 			this.animationManager.onFinished = () => {