rayzee 7.15.2 → 7.16.0

package/package.json

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

package/src/PathTracerApp.js

@@ -775,11 +775,7 @@ export class PathTracerApp extends EventDispatcher {
 			this.reset();
 			this.cameraManager.currentCameraIndex = 0;
 			this.dispatchEvent( eventPayload );
-			this.dispatchEvent( {
-				type: 'CamerasUpdated',
-				cameras: this.cameraManager.cameras,
-				cameraNames: this.cameraManager.getCameraNames()
-			} );
+			this._dispatchCamerasUpdated();
 
 		} finally {
 
@@ -1093,6 +1089,57 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	// ═══════════════════════════════════════════════════════════════
+	// Dynamic cameras (add / remove)
+	// ═══════════════════════════════════════════════════════════════
+
+	/** The index of the currently active camera (0 = built-in default). */
+	get currentCameraIndex() {
+
+		return this.cameraManager?.currentCameraIndex ?? 0;
+
+	}
+
+	/**
+	 * Snapshot the current view as a new named camera and switch to it.
+	 * @param {Object} [opts]
+	 * @param {string} [opts.name] - Display name (auto-generated otherwise).
+	 * @returns {number} The index of the newly added camera.
+	 */
+	addCamera( { name } = {} ) {
+
+		const index = this.cameraManager.addCameraFromView( name );
+		this.cameraManager.switchCamera( index );
+		this._dispatchCamerasUpdated();
+		return index;
+
+	}
+
+	/**
+	 * Remove a user-added camera by index. Built-in and model-embedded cameras
+	 * are protected. Falls back to the default camera if the active one is removed.
+	 * @param {number} index
+	 * @returns {boolean} true if a camera was removed.
+	 */
+	removeCamera( index ) {
+
+		const removed = this.cameraManager.removeCamera( index );
+		if ( removed ) this._dispatchCamerasUpdated();
+		return removed;
+
+	}
+
+	/** Notify consumers that the camera list changed (names / count). */
+	_dispatchCamerasUpdated() {
+
+		this.dispatchEvent( {
+			type: 'CamerasUpdated',
+			cameras: this.cameraManager.cameras,
+			cameraNames: this.cameraManager.getCameraNames(),
+		} );
+
+	}
+
 	// ═══════════════════════════════════════════════════════════════
 	// BVH Refit (Animation)
 	// ═══════════════════════════════════════════════════════════════
@@ -1874,6 +1921,8 @@ export class PathTracerApp extends EventDispatcher {
 			onResize: () => this.onResize(),
 			onReset: () => this.reset(),
 			getSettings: ( k ) => this.settings.get( k ),
+			// Per-camera DOF restore — silent + reset:false so switchCamera's own onReset() is the single reset.
+			applySettings: ( updates ) => this.settings.setMany( updates, { silent: true, reset: false } ),
 		} );
 
 		// Auto-focus context — CameraManager stores it, reads it each frame

package/src/RenderSettings.js

@@ -252,8 +252,9 @@ export class RenderSettings extends EventDispatcher {
 	 * @param {Object} updates - Key/value pairs
 	 * @param {Object} [options]
 	 * @param {boolean} [options.silent] - Suppress settingChanged events
+	 * @param {boolean} [options.reset]  - Override the routes' default reset behavior
 	 */
-	setMany( updates, { silent } = {} ) {
+	setMany( updates, { silent, reset } = {} ) {
 
 		let needsReset = false;
 
@@ -279,7 +280,8 @@ export class RenderSettings extends EventDispatcher {
 
 		}
 
-		if ( needsReset ) this._resetCallback?.();
+		const shouldReset = reset !== undefined ? reset : needsReset;
+		if ( shouldReset ) this._resetCallback?.();
 
 	}
 

package/src/managers/CameraManager.js

@@ -35,6 +35,9 @@ export class CameraManager extends EventDispatcher {
 		this.cameras = [ this.camera ];
 		this.currentCameraIndex = 0;
 
+		// Monotonic counter for naming user-added cameras (reset when the list is replaced).
+		this._userCameraCounter = 0;
+
 		// Auto-focus state
 		this.autoFocusMode = AF_DEFAULTS.SMOOTHING_FACTOR ? 'auto' : 'manual';
 		this.afScreenPoint = { x: 0.5, y: 0.5 };
@@ -51,6 +54,7 @@ export class CameraManager extends EventDispatcher {
 		this._onResize = null;
 		this._onReset = null;
 		this._getSettings = null;
+		this._applySettings = null;
 
 	}
 
@@ -61,6 +65,70 @@ export class CameraManager extends EventDispatcher {
 	setCameras( cameras ) {
 
 		this.cameras = cameras;
+		this._userCameraCounter = 0;
+
+	}
+
+	/**
+	 * Adds a new user camera that snapshots the current render camera's pose,
+	 * FOV, clip planes, and orbit target. The snapshot is a standalone template
+	 * appended to the list; switching to it restores this exact framing.
+	 *
+	 * @param {string} [name] - Optional display name (auto-generated otherwise).
+	 * @returns {number} The index of the newly added camera.
+	 */
+	addCameraFromView( name ) {
+
+		const src = this.camera;
+		const cam = new PerspectiveCamera( src.fov, src.aspect, src.near, src.far );
+		cam.position.copy( src.position );
+		cam.quaternion.copy( src.quaternion );
+		cam.updateMatrixWorld( true );
+
+		cam.userData.__rayzeeUserCamera = true;
+		cam.userData.__rayzeeEffects = this._captureEffects();
+		if ( this.controls ) cam.userData.__rayzeeOrbitTarget = this.controls.target.clone();
+
+		this._userCameraCounter += 1;
+		cam.name = name || `View Camera ${this._userCameraCounter}`;
+
+		this.cameras.push( cam );
+		return this.cameras.length - 1;
+
+	}
+
+	/**
+	 * Removes a user-added camera by index. Built-in (index 0) and
+	 * model-embedded cameras are protected and cannot be removed.
+	 * If the active camera is removed, falls back to the default camera.
+	 *
+	 * @param {number} index
+	 * @returns {boolean} true if a camera was removed.
+	 */
+	removeCamera( index ) {
+
+		if ( ! Number.isInteger( index ) || index <= 0 || index >= this.cameras.length ) return false;
+		if ( ! this.cameras[ index ]?.userData?.__rayzeeUserCamera ) return false;
+
+		const wasActive = this.currentCameraIndex === index;
+		this.cameras.splice( index, 1 );
+
+		if ( wasActive ) {
+
+			// The active camera is gone. Invalidate currentCameraIndex before falling
+			// back so switchCamera(0) skips both the (deleted) outgoing-effects save and
+			// the default-state save, and runs the restore path instead.
+			this.currentCameraIndex = - 1;
+			this.switchCamera( 0 );
+
+		} else if ( this.currentCameraIndex > index ) {
+
+			// Indices after the removed slot shift down by one.
+			this.currentCameraIndex -= 1;
+
+		}
+
+		return true;
 
 	}
 
@@ -86,15 +154,74 @@ export class CameraManager extends EventDispatcher {
 	 * Call once after all managers are ready.
 	 *
 	 * @param {Object} callbacks
-	 * @param {Function} callbacks.onResize   - Trigger viewport resize
-	 * @param {Function} callbacks.onReset    - Trigger accumulation reset
-	 * @param {Function} callbacks.getSettings - (key) => value
+	 * @param {Function} callbacks.onResize     - Trigger viewport resize
+	 * @param {Function} callbacks.onReset      - Trigger accumulation reset
+	 * @param {Function} callbacks.getSettings  - (key) => value
+	 * @param {Function} callbacks.applySettings - (updates) => void, batch-writes render settings
 	 */
-	initCallbacks( { onResize, onReset, getSettings } ) {
+	initCallbacks( { onResize, onReset, getSettings, applySettings } ) {
 
 		this._onResize = onResize;
 		this._onReset = onReset;
 		this._getSettings = getSettings;
+		this._applySettings = applySettings;
+
+	}
+
+	// ── Per-camera effects (DOF / focus) ──────────────────────────
+	// Each camera keeps its own depth-of-field + focus configuration so effects
+	// defined on one camera don't leak to another. State is stored on the camera
+	// object's userData and swapped in/out on switchCamera().
+
+	/**
+	 * Snapshot the current global DOF/focus settings into a plain object.
+	 * focusDistance is stored scaled (as held in RenderSettings).
+	 * @returns {Object|null}
+	 */
+	_captureEffects() {
+
+		const get = this._getSettings;
+		if ( ! get ) return null;
+
+		return {
+			enableDOF: get( 'enableDOF' ),
+			focusDistance: get( 'focusDistance' ),
+			aperture: get( 'aperture' ),
+			focalLength: get( 'focalLength' ),
+			apertureScale: get( 'apertureScale' ),
+			anamorphicRatio: get( 'anamorphicRatio' ),
+			autoFocusMode: this.autoFocusMode,
+			afScreenPoint: { ...this.afScreenPoint },
+		};
+
+	}
+
+	/**
+	 * Apply a previously-captured effects object to the global settings + focus state.
+	 * @param {Object} [eff]
+	 */
+	_applyEffects( eff ) {
+
+		if ( ! eff ) return;
+
+		this._applySettings?.( {
+			enableDOF: eff.enableDOF,
+			focusDistance: eff.focusDistance,
+			aperture: eff.aperture,
+			focalLength: eff.focalLength,
+			apertureScale: eff.apertureScale,
+			anamorphicRatio: eff.anamorphicRatio,
+		} );
+
+		if ( eff.autoFocusMode !== undefined ) this.setAutoFocusMode( eff.autoFocusMode );
+		if ( eff.afScreenPoint ) this.setAFScreenPoint( eff.afScreenPoint.x, eff.afScreenPoint.y );
+
+	}
+
+	/** Scene scale used to convert scaled focusDistance to UI-facing units. */
+	_getSceneScale() {
+
+		return this._afContext?.assetLoader?.getSceneScale?.() || 1;
 
 	}
 
@@ -122,6 +249,10 @@ export class CameraManager extends EventDispatcher {
 
 		}
 
+		// Save the outgoing camera's DOF/focus effects so they can be restored later.
+		const outgoing = this.cameras[ this.currentCameraIndex ];
+		if ( outgoing ) outgoing.userData.__rayzeeEffects = this._captureEffects();
+
 		// Save default camera state before switching away from it
 		if ( this.currentCameraIndex === 0 && index !== 0 ) {
 
@@ -169,21 +300,41 @@ export class CameraManager extends EventDispatcher {
 			this.camera.updateProjectionMatrix();
 			this.camera.updateMatrixWorld( true );
 
-			// Place orbit target along forward direction
+			// Restore the saved orbit target for user cameras; otherwise place it
+			// along the forward direction at the focus distance.
 			if ( this.controls ) {
 
-				const forward = new Vector3( 0, 0, - 1 ).applyQuaternion( sourceCamera.quaternion );
-				const focusDist = focusDistance || 5.0;
-				this.controls.target.copy( this.camera.position ).addScaledVector( forward, focusDist );
+				const savedTarget = sourceCamera.userData?.__rayzeeOrbitTarget;
+				if ( savedTarget ) {
+
+					this.controls.target.copy( savedTarget );
+
+				} else {
+
+					const forward = new Vector3( 0, 0, - 1 ).applyQuaternion( sourceCamera.quaternion );
+					const focusDist = focusDistance || 5.0;
+					this.controls.target.copy( this.camera.position ).addScaledVector( forward, focusDist );
+
+				}
+
 				this.controls.update();
 
 			}
 
 		}
 
+		// Restore the incoming camera's own DOF/focus effects (if it has any saved;
+		// otherwise it inherits the current global config).
+		this._applyEffects( this.cameras[ index ]?.userData?.__rayzeeEffects );
+
 		onResize?.();
 		onReset?.();
-		this.dispatchEvent( { type: 'CameraSwitched', cameraIndex: index } );
+
+		// Emit UI-facing effects: focusDistance unscaled (matching AUTO_FOCUS_UPDATED),
+		// so the adapter is a plain passthrough with no scene-scale awareness.
+		const effects = this._captureEffects();
+		if ( effects ) effects.focusDistance /= this._getSceneScale();
+		this.dispatchEvent( { type: 'CameraSwitched', cameraIndex: index, effects, fov: this.camera.fov } );
 
 	}