rayzee 7.9.2 → 7.10.0

package/package.json

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

package/src/PathTracerApp.js

@@ -689,6 +689,21 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Cancel the in-flight model/environment download, if any. The active
+	 * loadAsync() rejects with a typed LOAD_CANCELLED error, which callers treat
+	 * as a user cancellation (not a load failure). Only the network-download phase
+	 * is cancelable — once processing (BVH/textures) has started this is a no-op.
+	 * The scene is untouched: replace-loads release the old model only after the
+	 * download succeeds, and appends parent nothing until then.
+	 */
+	cancelLoad() {
+
+		if ( ! this._loadingInProgress ) return;
+		this.assetLoader?.cancelActiveLoad();
+
+	}
+
 	/**
 	 * Set the max material-texture dimension (longest edge) used when processing a
 	 * scene's textures into GPU arrays. Clamped to the hardware ceiling. Larger =
@@ -744,6 +759,10 @@ export class PathTracerApp extends EventDispatcher {
 		try {
 
 			await loadFn();
+			// Replace-load clears any dynamically-appended models — but only AFTER
+			// loadFn() succeeds, so a failed load leaves the current scene intact.
+			// (The old primary was already released by releaseTargetModel() in loadFn.)
+			this._clearAppendedModels();
 			this._syncControlsAfterLoad();
 			await this.loadSceneData();
 			this.pipeline?.eventBus.emit( 'autoexposure:resetHistory' );
@@ -770,13 +789,18 @@ export class PathTracerApp extends EventDispatcher {
 	 */
 	async loadSceneData() {
 
-		// Clear selection before rebuilding — the old object leaves the scene graph
-		this.interactionManager?.deselect();
+		// Clear selection before rebuilding — the old object leaves the scene graph.
+		// Skipped on the append path (addModel): the selected object persists, so its
+		// selection + transform gizmo should survive the rebuild.
+		if ( ! this._preserveSelectionOnRebuild ) this.interactionManager?.deselect();
 
 		// Stop any running animation before rebuilding scene data
 		this.animationManager.dispose();
 		this._animRefitInFlight = false;
 
+		// Tag the primary (replace-loaded) model so it appears in the scene-object list.
+		this._tagPrimarySceneObject();
+
 		const timer = new BuildTimer( 'loadSceneData' );
 		const environmentTexture = this.meshScene.environment;
 
@@ -863,6 +887,188 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	// ═══════════════════════════════════════════════════════════════
+	// Dynamic scene objects (add / remove / list / visibility)
+	//
+	// Top-level objects are the auto-created "Ground" plane plus each loaded
+	// model root parented into meshScene. The scene graph + per-root userData
+	// tags are the single source of truth (no separate registry): ids are
+	// Object3D uuids (stable across rebuilds, since the same root persists).
+	// ═══════════════════════════════════════════════════════════════
+
+	/** Tag the primary (replace-loaded) model as a removable scene object (read by the Outliner + removeSceneObject). Idempotent. */
+	_tagPrimarySceneObject() {
+
+		const m = this.assetLoader?.targetModel;
+		if ( ! m ) return;
+		m.userData.__rayzeeSceneObject = true;
+		m.userData.__rayzeeExternal = ( m === this.assetLoader._externalModel );
+
+	}
+
+	/** Remove + dispose all dynamically-appended models (keeps Ground and the primary). */
+	_clearAppendedModels() {
+
+		const scene = this.meshScene;
+		if ( ! scene ) return;
+		const floor = this.assetLoader?.floorPlane;
+		const primary = this.assetLoader?.targetModel;
+		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 } );
+
+		}
+
+	}
+
+	/** Reframe-free rebuild sequence. Assumes the _loadingInProgress guard is already held. */
+	async _finishRebuildNoReframe( eventPayload ) {
+
+		await this.loadSceneData(); // emits 'SceneRebuild'
+		this.pipeline?.eventBus.emit( 'autoexposure:resetHistory' );
+		this.reset();
+		if ( eventPayload ) this.dispatchEvent( eventPayload );
+
+	}
+
+	/**
+	 * Append a model by URL to the current scene (does NOT replace it), then rebuild
+	 * without reframing the camera.
+	 * @param {string} url
+	 * @param {Object} [opts]
+	 * @param {string} [opts.name] - Display name for the scene-object list.
+	 * @returns {Promise<string>} the new object's id (Object3D uuid).
+	 */
+	async addModel( url, { name } = {} ) {
+
+		if ( this._loadingInProgress ) {
+
+			throw new Error( 'PathTracerApp.addModel: another load is already in progress' );
+
+		}
+
+		this._loadingInProgress = true;
+		this._preserveSelectionOnRebuild = true;
+		try {
+
+			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;
+
+		} finally {
+
+			this._preserveSelectionOnRebuild = false;
+			this._loadingInProgress = false;
+
+		}
+
+	}
+
+	/**
+	 * Append a caller-owned Object3D to the current scene, then rebuild (no reframe).
+	 * The caller retains ownership — removal only detaches it.
+	 * @param {import('three').Object3D} object3d
+	 * @param {Object} [opts]
+	 * @param {string} [opts.name]
+	 * @returns {Promise<string>} the new object's id (Object3D uuid).
+	 */
+	async addModelFromObject3D( object3d, { name } = {} ) {
+
+		if ( this._loadingInProgress ) {
+
+			throw new Error( 'PathTracerApp.addModelFromObject3D: another load is already in progress' );
+
+		}
+
+		this._loadingInProgress = true;
+		this._preserveSelectionOnRebuild = true;
+		try {
+
+			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;
+
+		} finally {
+
+			this._preserveSelectionOnRebuild = false;
+			this._loadingInProgress = false;
+
+		}
+
+	}
+
+	/**
+	 * Remove a scene object by id (Object3D uuid). The Ground plane is permanent.
+	 * @param {string} id
+	 * @returns {Promise<boolean>} true if removed.
+	 */
+	async removeSceneObject( id ) {
+
+		const scene = this.meshScene;
+		if ( ! scene ) return false;
+
+		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 );
+		if ( ! root ) return false;
+
+		if ( this._loadingInProgress ) {
+
+			throw new Error( 'PathTracerApp.removeSceneObject: another load is already in progress' );
+
+		}
+
+		this._loadingInProgress = true;
+		try {
+
+			this.interactionManager?.deselect();
+			this.transformManager?.detach?.();
+
+			if ( root === this.assetLoader.targetModel ) {
+
+				this.assetLoader.releaseTargetModel();
+
+			} else {
+
+				this.assetLoader.removeModelRoot( root, { external: !! root.userData.__rayzeeExternal } );
+
+			}
+
+			// Ground is permanent (removal refused above), so the scene always keeps
+			// renderable geometry — a full rebuild is always valid here.
+			await this._finishRebuildNoReframe( { type: 'SceneObjectRemoved', id } );
+
+			return true;
+
+		} finally {
+
+			this._loadingInProgress = false;
+
+		}
+
+	}
+
+	/**
+	 * Toggle a scene object's visibility without rebuilding (O(1) TLAS-leaf patch).
+	 * @param {string} id - Object3D uuid.
+	 * @param {boolean | ((prev:boolean)=>boolean)} visible
+	 * @returns {boolean|null} new visibility, or null if not found.
+	 */
+	setSceneObjectVisibility( id, visible ) {
+
+		return this.setMeshVisibilityByUuid( id, visible );
+
+	}
+
 	// ═══════════════════════════════════════════════════════════════
 	// BVH Refit (Animation)
 	// ═══════════════════════════════════════════════════════════════
@@ -1611,6 +1817,8 @@ export class PathTracerApp extends EventDispatcher {
 
 			if ( event.model ) {
 
+				// Drag-drop / file load is a replace: clear any appended models first.
+				this._clearAppendedModels();
 				await this.loadSceneData();
 
 			} else if ( event.texture ) {

package/src/Processor/AssetLoader.js

@@ -48,6 +48,75 @@ export class AssetLoader extends EventDispatcher {
 		this.animations = [];
 		this.renderer = 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).
+		this._loadingManager = new LoadingManager();
+		this._loadCancelled = false;
+
+	}
+
+	/**
+	 * Abort the network download for the in-flight load, if any. The aborted
+	 * loadAsync() rejects with an AbortError, which each load path re-throws as a
+	 * typed LOAD_CANCELLED error. Only the download phase is cancelable — once the
+	 * bytes are in and BVH/texture processing has begun, this is a no-op.
+	 */
+	cancelActiveLoad() {
+
+		this._loadCancelled = true;
+		this._loadingManager.abort();
+
+	}
+
+	_isCancellation( error ) {
+
+		return this._loadCancelled || error?.name === 'AbortError' || error?.code === 'LOAD_CANCELLED';
+
+	}
+
+	_cancellationError() {
+
+		const err = new Error( 'Load cancelled' );
+		err.code = 'LOAD_CANCELLED';
+		return err;
+
+	}
+
+	// Build an onProgress handler that reports download byte counts to the UI.
+	// `cancelable` gates the Cancel affordance (true only for network URLs — blob
+	// and data URLs resolve locally and have nothing to abort). Download maps onto
+	// 2→60% of the bar, leaving headroom for the processing phases that follow.
+	_downloadProgress( status, cancelable ) {
+
+		return ( event ) => {
+
+			const loaded = event?.loaded || 0;
+			const total = event?.lengthComputable ? ( event.total || 0 ) : 0;
+			updateLoading( {
+				isLoading: true,
+				status,
+				loadedBytes: loaded,
+				totalBytes: total,
+				canCancel: !! cancelable,
+				progress: total ? Math.min( 60, 2 + Math.round( ( loaded / total ) * 58 ) ) : 2,
+			} );
+
+		};
+
+	}
+
+	// Called once bytes are in, before the (non-cancelable) processing phases.
+	_downloadComplete( status = 'Processing Data...', progress = 62 ) {
+
+		updateLoading( { status, progress, canCancel: false, loadedBytes: null, totalBytes: null } );
+
+	}
+
+	static _isNetworkUrl( url ) {
+
+		return typeof url === 'string' && /^https?:/i.test( url );
+
 	}
 
 	/**
@@ -72,6 +141,9 @@ export class AssetLoader extends EventDispatcher {
 
 		this.targetModel = null;
 		this._externalModel = null;
+		// Drop the released model's animation clips so a later rebuild doesn't rebind
+		// a mixer to disposed nodes. Every load path re-populates this.animations after.
+		this.animations = [];
 
 	}
 
@@ -189,6 +261,8 @@ export class AssetLoader extends EventDispatcher {
 
 	async loadEnvironment( envUrl ) {
 
+		this._loadCancelled = false;
+
 		try {
 
 			// Dispatch event before loading environment to allow UI to prepare
@@ -219,6 +293,7 @@ export class AssetLoader extends EventDispatcher {
 
 		} catch ( error ) {
 
+			if ( this._isCancellation( error ) ) throw this._cancellationError();
 			console.error( "Error loading environment:", error );
 			this.dispatchEvent( { type: 'error', message: error.message, filename: envUrl } );
 			throw error;
@@ -280,24 +355,29 @@ export class AssetLoader extends EventDispatcher {
 
 	async loadEnvironmentByExtension( url, extension ) {
 
+		const cancelable = AssetLoader._isNetworkUrl( url );
+		const onProgress = this._downloadProgress( "Downloading Environment...", cancelable );
+
 		let texture;
 		if ( extension === 'hdr' || extension === 'exr' ) {
 
 			const loader = extension === 'hdr'
-				? ( this.loaderCache.hdr || ( this.loaderCache.hdr = new HDRLoader().setDataType( FloatType ) ) )
-				: ( this.loaderCache.exr || ( this.loaderCache.exr = new EXRLoader().setDataType( FloatType ) ) );
-			texture = await loader.loadAsync( url );
+				? ( this.loaderCache.hdr || ( this.loaderCache.hdr = new HDRLoader( this._loadingManager ).setDataType( FloatType ) ) )
+				: ( this.loaderCache.exr || ( this.loaderCache.exr = new EXRLoader( this._loadingManager ).setDataType( FloatType ) ) );
+			texture = await loader.loadAsync( url, onProgress );
 
 		} else {
 
-			if ( ! this.loaderCache.texture ) this.loaderCache.texture = new TextureLoader();
-			texture = await this.loaderCache.texture.loadAsync( url );
+			if ( ! this.loaderCache.texture ) this.loaderCache.texture = new TextureLoader( this._loadingManager );
+			texture = await this.loaderCache.texture.loadAsync( url, onProgress );
 			// LDR env maps (jpg/png/webp) are authored in sRGB; tag them so the backend
 			// decodes to linear. HDR/EXR are already linear and keep the loader's setting.
 			texture.colorSpace = SRGBColorSpace;
 
 		}
 
+		this._downloadComplete( "Processing Environment...", 62 );
+
 		texture.mapping = EquirectangularReflectionMapping;
 		texture.minFilter = LinearFilter;
 		texture.magFilter = LinearFilter;
@@ -919,7 +999,7 @@ export class AssetLoader extends EventDispatcher {
 
 		}
 
-		const loader = new GLTFLoader();
+		const loader = new GLTFLoader( this._loadingManager );
 		loader.setDRACOLoader( dracoLoader );
 		loader.setKTX2Loader( ktx2Loader );
 		loader.setMeshoptDecoder( MeshoptDecoder );
@@ -951,13 +1031,15 @@ export class AssetLoader extends EventDispatcher {
 
 	async loadModel( modelUrl ) {
 
+		this._loadCancelled = false;
 		const loader = await this.createGLTFLoader();
+		const cancelable = AssetLoader._isNetworkUrl( modelUrl );
 
 		try {
 
-			updateLoading( { status: "Loading Model...", progress: 2 } );
-			const data = await loader.loadAsync( modelUrl );
-			updateLoading( { status: "Processing Data...", progress: 10 } );
+			updateLoading( { isLoading: true, status: "Downloading Model...", progress: 2, canCancel: cancelable, loadedBytes: 0, totalBytes: 0 } );
+			const data = await loader.loadAsync( modelUrl, this._downloadProgress( "Downloading Model...", cancelable ) );
+			this._downloadComplete();
 
 			this.releaseTargetModel();
 
@@ -969,6 +1051,7 @@ export class AssetLoader extends EventDispatcher {
 
 		} catch ( error ) {
 
+			if ( this._isCancellation( error ) ) throw this._cancellationError();
 			console.error( "Error loading model:", error );
 			this.dispatchEvent( { type: 'error', message: error.message, filename: modelUrl } );
 			throw error;
@@ -981,6 +1064,72 @@ export class AssetLoader extends EventDispatcher {
 
 	}
 
+	// ─────────────────────────────────────────────────────────────
+	// Append / remove primitives (dynamic object add/remove).
+	// These deliberately do NOT touch targetModel/animations and do NOT
+	// reframe the camera or dispatch load/modelProcessed — the caller
+	// (PathTracerApp) drives a reframe-free scene rebuild.
+	// ─────────────────────────────────────────────────────────────
+
+	// Multi-material split + area-light placeholders, then parent into meshScene.
+	_processAndParent( model ) {
+
+		this.processModelObjects( model );
+		this.scene.add( model );
+		// Refresh world matrices for the whole subtree — the reframe-free rebuild
+		// extracts geometry immediately (rAF is gated off), so nothing else would
+		// update matrices first and any ancestor-node transform would be dropped.
+		model.updateMatrixWorld( true );
+
+	}
+
+	// Append a model from URL without releasing prior models or reframing.
+	// Reuses createGLTFLoader() so appended KTX2 textures stay RGBA DataArrayTexture.
+	async appendModel( url ) {
+
+		this._loadCancelled = false;
+		const loader = await this.createGLTFLoader();
+		const cancelable = AssetLoader._isNetworkUrl( url );
+
+		try {
+
+			updateLoading( { isLoading: true, status: "Downloading Model...", progress: 2, canCancel: cancelable, loadedBytes: 0, totalBytes: 0 } );
+			const data = await loader.loadAsync( url, this._downloadProgress( "Downloading Model...", cancelable ) );
+			this._downloadComplete();
+			this._processAndParent( data.scene );
+			return { root: data.scene, animations: data.animations || [] };
+
+		} catch ( error ) {
+
+			if ( this._isCancellation( error ) ) throw this._cancellationError();
+			throw error;
+
+		} finally {
+
+			this._disposeGLTFLoader( loader );
+
+		}
+
+	}
+
+	// Append a caller-owned Object3D without releasing prior models or reframing.
+	appendObject3D( object3d, name = 'object3d' ) {
+
+		object3d.name = object3d.name || name;
+		this._processAndParent( object3d );
+		return { root: object3d };
+
+	}
+
+	// Detach + dispose an appended root. External (caller-owned) roots are only detached.
+	removeModelRoot( root, { external = false } = {} ) {
+
+		if ( ! root ) return;
+		if ( external ) root.parent?.remove( root );
+		else disposeObjectFromMemory( root );
+
+	}
+
 	async loadGLBFromArrayBuffer( arrayBuffer, filename = 'model.glb' ) {
 
 		const loader = await this.createGLTFLoader();

package/src/Stages/PathTracer.js

@@ -425,9 +425,13 @@ export class PathTracer extends PathTracerStage {
 	// Async readback of the per-bounce snapshot every N frames; never awaited, so the early-exit uses past-frame data.
 	_maybeReadbackCounters() {
 
-		// Never sample the survivor curve mid-motion — those counts belong to a pose we're leaving and
-		// would mis-size the first settled frame. Prime the counter so the settled view re-measures promptly.
-		if ( this.cameraChanged ) {
+		// Never sample the survivor curve mid-motion, nor while the CameraOptimizer is holding maxBounces
+		// down to its interaction value (1): mid-motion counts belong to a pose we're leaving, and a curve
+		// measured at the interaction budget stores _lastBounceCountsBudget=1 — when the real (high) budget
+		// is restored on exit that stale curve forces curveReliableUpto=1, killing the per-bounce early-exit
+		// and full-sizing the whole loopBound for a few frames (the dramatic FPS drop right when movement
+		// ends, worst at high maxBounces). Prime the counter so the first settled frame re-measures promptly.
+		if ( this.cameraChanged || this.cameraOptimizer?.isInInteractionMode() ) {
 
 			this._readbackFrameCounter = this._readbackEveryNFrames;
 			return;

package/src/managers/TransformManager.js

@@ -75,6 +75,10 @@ export class TransformManager {
 		this._posBuffer = new Float32Array( offset * 9 );
 		this._normalBuffer = new Float32Array( offset * 9 );
 
+		// Mesh indices/buffers were just reallocated (e.g. after a scene rebuild) —
+		// force the next drag to recompute the transform baseline.
+		this._baselineComputed = false;
+
 	}
 
 	/**