rayzee 10.0.0 → 11.0.0

package/src/managers/AnimationManager.js

@@ -10,6 +10,23 @@
 import { AnimationMixer, EventDispatcher, Timer, Vector3, LoopRepeat, LoopOnce, PropertyBinding } from 'three';
 import { EngineEvents } from '../EngineEvents.js';
 
+/** The nodes of `nodes` with no ancestor in it, or null when updating each would cost more than one pass over `root`. */
+function subtreeRoots( nodes, root ) {
+
+	const roots = [ ...nodes ].filter( node => {
+
+		for ( let o = node.parent; o; o = o.parent ) if ( nodes.has( o ) ) return false;
+		return true;
+
+	} );
+
+	let total = 0, covered = 0;
+	root.traverse?.( () => total ++ );
+	for ( const node of roots ) node.traverse?.( () => covered ++ );
+	return covered + roots.length / 2 < total ? roots : null;
+
+}
+
 export class AnimationManager extends EventDispatcher {
 
 	constructor() {
@@ -39,6 +56,8 @@ export class AnimationManager extends EventDispatcher {
 		this._slotOf = null; // meshIndex -> row in the two caches below, or -1
 		this._lastWorld = null; // world matrix last handed to applyPoseCallback, 16 per row
 		this._lastVisible = null; // 0 / 1, or 2 before the first pose
+		this._lastMeshWorld = null; // deforming clips: world matrix at each mesh's last read, 16 per mesh
+		this._lastMorphWeights = null;
 
 		/** Injected by PathTracerApp — wakes the render loop after play/resume. */
 		this.wakeCallback = null;
@@ -135,6 +154,8 @@ export class AnimationManager extends EventDispatcher {
 		// 9 floats × every triangle — 1,030 MB at 30M, past what a renderer can allocate.
 		this._skinnedCache = [];
 		this._meshPositions = [];
+		this._lastMeshWorld = this._rigid ? null : new Float64Array( meshes.length * 16 ).fill( NaN );
+		this._lastMorphWeights = [];
 
 		const skinnedCount = meshes.filter( m => m.isSkinnedMesh ).length;
 		console.debug( `[AnimationManager] Init: ${animations.length} clips, ${meshes.length} meshes (${skinnedCount} skinned), ${offset} triangles, ${this._rigid ? 'rigid' : 'deforming'}` );
@@ -158,11 +179,19 @@ export class AnimationManager extends EventDispatcher {
 
 			const animated = new Set();
 			let visibility = false;
+			let unresolved = false;
 			for ( const track of clip.tracks ) {
 
 				const { nodeName, propertyName } = PropertyBinding.parseTrackName( track.name );
-				const node = byName.get( nodeName );
-				if ( ! node ) continue;
+				// As PropertyBinding.findNode: no node name binds the root itself.
+				const node = nodeName === '' || nodeName === '.' ? root : byName.get( nodeName );
+				if ( ! node ) {
+
+					unresolved = true;
+					continue;
+
+				}
+
 				animated.add( node );
 				if ( propertyName === 'visible' ) visibility = true;
 
@@ -187,7 +216,7 @@ export class AnimationManager extends EventDispatcher {
 			const cameras = new Set();
 			for ( const node of animated ) node.traverse( o => o.isCamera && cameras.add( o ) );
 
-			return { meshes: Int32Array.from( meshes ), visibility, cameras: [ ...cameras ] };
+			return { meshes: Int32Array.from( meshes ), visibility, cameras: [ ...cameras ], nodes: unresolved ? null : animated, roots: unresolved ? null : subtreeRoots( animated, root ) };
 
 		} );
 
@@ -214,15 +243,18 @@ export class AnimationManager extends EventDispatcher {
 
 			const meshes = new Set(), cameras = new Set();
 			let visibility = false;
+			let nodes = new Set();
 			for ( const plan of this._plans ) {
 
 				plan.meshes.forEach( m => meshes.add( m ) );
 				plan.cameras.forEach( c => cameras.add( c ) );
 				visibility ||= plan.visibility;
+				if ( nodes && plan.nodes ) plan.nodes.forEach( n => nodes.add( n ) );
+				else nodes = null;
 
 			}
 
-			this._allPlan = { meshes: Int32Array.from( meshes ), visibility, cameras: [ ...cameras ] };
+			this._allPlan = { meshes: Int32Array.from( meshes ), visibility, cameras: [ ...cameras ], nodes, roots: nodes ? subtreeRoots( nodes, this._mixerRoot ) : null };
 
 		}
 
@@ -487,7 +519,10 @@ export class AnimationManager extends EventDispatcher {
 
 		// Bones live outside mesh subtrees so per-mesh updateMatrixWorld() misses them. Doing it
 		// once here, on mixerRoot rather than the scene, keeps unrelated static objects out of it.
-		this._mixerRoot.updateMatrixWorld( true );
+		// A rigid clip moves only what its tracks name, so only those subtrees are updated.
+		const roots = this._rigid ? this._planFor( this._activeClip )?.roots : null;
+		if ( roots ) for ( const node of roots ) node.updateMatrixWorld( true );
+		else this._mixerRoot.updateMatrixWorld( true );
 
 		if ( this._rigid ) {
 
@@ -499,7 +534,52 @@ export class AnimationManager extends EventDispatcher {
 		const cameras = this._planFor( this._activeClip )?.cameras;
 		if ( cameras?.length ) this.applyPoseCallback?.( { meshIndices: [], visibilityChanged: false, cameras } );
 
-		return m => this._computeMeshPositions( m );
+		// Decided once per reader: an expanded instanced emitter asks for one mesh several times.
+		const moved = new Int8Array( this._meshes.length );
+		return m => {
+
+			if ( moved[ m ] === 0 ) moved[ m ] = this._meshes[ m ].isSkinnedMesh || this._poseChanged( m ) ? 1 : - 1;
+			return moved[ m ] > 0 ? this._computeMeshPositions( m ) : null;
+
+		};
+
+	}
+
+	/** Whether a mesh's world matrix or morph weights differ from when its positions were last read. @private */
+	_poseChanged( m ) {
+
+		const mesh = this._meshes[ m ];
+		const last = this._lastMeshWorld;
+		const e = mesh.matrixWorld.elements;
+		const o = m * 16;
+		let changed = false;
+
+		for ( let i = 0; i < 16; i ++ ) {
+
+			if ( last[ o + i ] !== e[ i ] ) {
+
+				for ( let j = 0; j < 16; j ++ ) last[ o + j ] = e[ j ];
+				changed = true;
+				break;
+
+			}
+
+		}
+
+		const weights = mesh.morphTargetInfluences;
+		if ( weights?.length ) {
+
+			const lastWeights = this._lastMorphWeights[ m ];
+			if ( ! lastWeights || lastWeights.length !== weights.length || lastWeights.some( ( w, i ) => w !== weights[ i ] ) ) {
+
+				this._lastMorphWeights[ m ] = Float64Array.from( weights );
+				changed = true;
+
+			}
+
+		}
+
+		return changed;
 
 	}
 
@@ -640,6 +720,8 @@ export class AnimationManager extends EventDispatcher {
 		this._slotOf = null;
 		this._lastWorld = null;
 		this._lastVisible = null;
+		this._lastMeshWorld = null;
+		this._lastMorphWeights = null;
 
 	}
 

package/src/managers/CameraManager.js

@@ -1,12 +1,22 @@
-import { EventDispatcher, MathUtils, OrthographicCamera, PerspectiveCamera, Quaternion, Vector3 } from 'three';
+import { EventDispatcher, MathUtils, Matrix4, OrthographicCamera, PerspectiveCamera, Quaternion, Vector3 } from 'three';
 import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
 import { EngineEvents, } from '../EngineEvents.js';
-import { AF_DEFAULTS, CAMERA_PROJECTION_IDS } from '../EngineDefaults.js';
+import { CAMERA_PROJECTION_IDS } from '../EngineDefaults.js';
 import { viewDepth } from './InteractionManager.js';
 import { ViewCamera } from './ViewCamera.js';
 import { WalkControls } from './WalkControls.js';
 import { toPortable, fromPortable } from '../SceneState/portable.js';
 
+export const AUTO_FOCUS_DEFAULTS = {
+	autoFocusMode: 'auto', // 'manual' | 'auto'
+	afScreenPoint: { x: 0.5, y: 0.5 },
+	afSmoothingFactor: 0.15,
+};
+
+const AF_RESET_THRESHOLD = 0.05;
+const AF_FALLBACK_DISTANCE = 10.0;
+const AF_SNAP_THRESHOLD = 0.5;
+
 const DEFAULT_CAMERA_SCALE = Object.freeze( new Vector3( 1, 1, 1 ) );
 
 /** The height of an orthographic camera's view in world units, or null for any other camera. */
@@ -55,13 +65,14 @@ export class CameraManager extends EventDispatcher {
 		this._userCameraCounter = 0;
 
 		// Auto-focus state
-		this.autoFocusMode = AF_DEFAULTS.SMOOTHING_FACTOR ? 'auto' : 'manual';
-		this.afScreenPoint = { x: 0.5, y: 0.5 };
-		this.afSmoothingFactor = AF_DEFAULTS.SMOOTHING_FACTOR;
+		this.autoFocusMode = AUTO_FOCUS_DEFAULTS.autoFocusMode;
+		this.afScreenPoint = { ...AUTO_FOCUS_DEFAULTS.afScreenPoint };
+		this.afSmoothingFactor = AUTO_FOCUS_DEFAULTS.afSmoothingFactor;
 		this._lastValidFocusDistance = null;
 		this._smoothedFocusDistance = null;
 		this._afPointDirty = false;
 		this._afSuspended = false;
+		this._afPick = null;
 
 		// Saved state for default camera when switching to model cameras
 		this._defaultCameraState = null;
@@ -311,40 +322,7 @@ export class CameraManager extends EventDispatcher {
 
 		} else {
 
-			const sourceCamera = this.cameras[ index ];
-
-			this.camera.position.copy( sourceCamera.position );
-			this.camera.quaternion.copy( sourceCamera.quaternion );
-			// An imported camera can carry a mirror (a negative axis scale) that no
-			// quaternion can express — a pbrt scene's `Scale -1 1 1`, for one. Copying
-			// pose alone would silently un-mirror the view.
-			this.camera.scale.copy( sourceCamera.scale );
-			if ( sourceCamera.isPerspectiveCamera ) this.camera.fov = sourceCamera.fov;
-			this.camera.near = sourceCamera.near;
-			this.camera.far = sourceCamera.far;
-			this.camera.updateProjectionMatrix();
-			this.camera.updateMatrixWorld( true );
-
-			// Restore the saved orbit target for user cameras; otherwise place it
-			// along the forward direction at the focus distance.
-			if ( this.controls ) {
-
-				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();
-
-			}
+			this._placeAt( this.cameras[ index ], focusDistance );
 
 		}
 
@@ -369,6 +347,60 @@ export class CameraManager extends EventDispatcher {
 
 	}
 
+	/**
+	 * Puts the active camera back at the view it starts from: the default camera at the framing the
+	 * model loaded with, any other at its own pose and lens. Its effects and projection stay.
+	 */
+	resetView() {
+
+		const source = this.currentCameraIndex > 0 ? this.cameras[ this.currentCameraIndex ] : null;
+		if ( ! source ) {
+
+			this.controls.reset();
+			return;
+
+		}
+
+		this._placeAt( source, this._getSettings?.( 'focusDistance' ) );
+		const height = orthoHeightOf( source );
+		if ( this.camera.orthographic ) this._setView( true, height ? height / 2 : this.camera.orthoHalfHeight );
+		this._onReset?.();
+
+	}
+
+	// The view takes a camera's pose and lens, orbiting its saved target or a point ahead at the focus distance.
+	_placeAt( source, focusDistance ) {
+
+		this.camera.position.copy( source.position );
+		this.camera.quaternion.copy( source.quaternion );
+		// An imported camera can carry a mirror (a negative axis scale) that no
+		// quaternion can express — a pbrt scene's `Scale -1 1 1`, for one. Copying
+		// pose alone would silently un-mirror the view.
+		this.camera.scale.copy( source.scale );
+		if ( source.isPerspectiveCamera ) this.camera.fov = source.fov;
+		this.camera.near = source.near;
+		this.camera.far = source.far;
+		this.camera.updateProjectionMatrix();
+		this.camera.updateMatrixWorld( true );
+
+		if ( ! this.controls ) return;
+
+		const savedTarget = source.userData?.__rayzeeOrbitTarget;
+		if ( savedTarget ) {
+
+			this.controls.target.copy( savedTarget );
+
+		} else {
+
+			const forward = new Vector3( 0, 0, - 1 ).applyQuaternion( source.quaternion );
+			this.controls.target.copy( this.camera.position ).addScaledVector( forward, focusDistance || 5.0 );
+
+		}
+
+		this.controls.update();
+
+	}
+
 	/**
 	 * Makes the camera orthographic at `height`, or perspective for null, then hands the `cameraProjection`
 	 * setting the outcome — after, so its handler finds the camera already there. A 360° panorama stays on
@@ -833,13 +865,12 @@ export class CameraManager extends EventDispatcher {
 			&& stage.frameCount > 0
 			&& ! stage.isComplete ) return;
 
-		// AF screen point (0 to 1, y down) to NDC.
-		const validHit = this.interactionManager.pickSurface( this.afScreenPoint.x * 2 - 1, 1 - this.afScreenPoint.y * 2 );
+		const hitPoint = this._pickFocusPoint( stage.resetCount );
 
 		let rawDistance;
-		if ( validHit ) {
+		if ( hitPoint ) {
 
-			rawDistance = viewDepth( validHit.point, this.camera );
+			rawDistance = viewDepth( hitPoint, this.camera );
 			this._lastValidFocusDistance = rawDistance;
 
 		} else {
@@ -852,7 +883,7 @@ export class CameraManager extends EventDispatcher {
 
 				// Nothing under the AF point on a fresh view: focus where the camera orbits.
 				const depth = this.controls ? viewDepth( this.controls.target, this.camera ) : 0;
-				rawDistance = depth > 0 ? depth : AF_DEFAULTS.FALLBACK_DISTANCE * ( assetLoader?.getSceneScale() || 1.0 );
+				rawDistance = depth > 0 ? depth : AF_FALLBACK_DISTANCE * ( assetLoader?.getSceneScale() || 1.0 );
 				this._lastValidFocusDistance = rawDistance;
 
 			}
@@ -872,7 +903,7 @@ export class CameraManager extends EventDispatcher {
 			const changeFraction = Math.abs( rawDistance - this._smoothedFocusDistance )
 				/ this._smoothedFocusDistance;
 
-			if ( changeFraction > AF_DEFAULTS.SNAP_THRESHOLD ) {
+			if ( changeFraction > AF_SNAP_THRESHOLD ) {
 
 				this._smoothedFocusDistance = rawDistance;
 
@@ -900,7 +931,7 @@ export class CameraManager extends EventDispatcher {
 
 				hardReset?.();
 
-			} else if ( changeRatio > AF_DEFAULTS.RESET_THRESHOLD ) {
+			} else if ( changeRatio > AF_RESET_THRESHOLD ) {
 
 				softReset?.();
 
@@ -910,6 +941,32 @@ export class CameraManager extends EventDispatcher {
 
 	}
 
+	/** Picks again only on a new view or AF point, or a render reset, which every scene change makes. @private */
+	_pickFocusPoint( resetCount ) {
+
+		const camera = this.camera;
+		const { x, y } = this.afScreenPoint;
+		const last = this._afPick ??= { point: new Vector3(), hit: false, resetCount: NaN, x: NaN, y: NaN, view: new Matrix4(), projection: new Matrix4() };
+
+		if ( this._afPointDirty || resetCount !== last.resetCount || x !== last.x || y !== last.y
+			|| ! last.view.equals( camera.matrixWorld ) || ! last.projection.equals( camera.projectionMatrix ) ) {
+
+			// AF screen point (0 to 1, y down) to NDC.
+			const hit = this.interactionManager.pickSurface( x * 2 - 1, 1 - y * 2 );
+			last.hit = !! hit;
+			if ( hit ) last.point.copy( hit.point );
+			last.resetCount = resetCount;
+			last.x = x;
+			last.y = y;
+			last.view.copy( camera.matrixWorld );
+			last.projection.copy( camera.projectionMatrix );
+
+		}
+
+		return last.hit ? last.point : null;
+
+	}
+
 	/**
 	 * Deferred dependency injection — InteractionManager needs the camera
 	 * in its constructor, so it can't be passed during CameraManager creation.

package/src/managers/DenoisingManager.js

@@ -9,7 +9,10 @@ import { createLogger } from '../utils/Logger.js';
 // The neural passes live in `../neural/` but report through the manager that drives them, so they
 // share one namespace: `rayzee.log.only( 'neural' )` shows the whole chain.
 const neuralLog = createLogger( 'neural' );
-import { ENGINE_DEFAULTS as DEFAULT_STATE, ASVGF_QUALITY_PRESETS, NRD_DEFAULTS, NRD_QUALITY_PRESETS, NRD_PRESET_KEYS, CAMERA_PROJECTION_IDS } from '../EngineDefaults.js';
+import { CAMERA_PROJECTION_IDS } from '../EngineDefaults.js';
+import {
+	DENOISER_DEFAULTS, ASVGF_QUALITY_PRESETS, NRD_DEFAULTS, NRD_QUALITY_PRESETS, NRD_PRESET_KEYS,
+} from '../Stages/DenoiserSettings.js';
 
 // A refresh slower than this is a slideshow, not a live view, so the cadence swaps to a cheaper
 // model and puts the chosen one back for the finished image. Resolution-aware by construction:
@@ -135,13 +138,13 @@ export class DenoisingManager extends EventDispatcher {
 
 		// The tier the finished image uses. The loaded tier is not always this one: while the
 		// image is still accumulating we run a cheaper model (see previewQuality).
-		this._finalQuality = DEFAULT_STATE.oidnQuality;
+		this._finalQuality = DENOISER_DEFAULTS.oidnQuality;
 		// Two independent decisions. `finalDenoise` is the OIDN pass on the finished image;
 		// `continuousDenoise` is OIDN as the live-view denoiser. `denoiser.enabled` means only
 		// "OIDN is in use at all", which is what the aux G-buffer wiring needs.
-		this.finalDenoise = DEFAULT_STATE.enableOIDN;
-		this.continuousDenoise = DEFAULT_STATE.continuousDenoise;
-		this.continuousDenoiseInterval = DEFAULT_STATE.continuousDenoiseInterval;
+		this.finalDenoise = DENOISER_DEFAULTS.enableOIDN;
+		this.continuousDenoise = DENOISER_DEFAULTS.continuousDenoise;
+		this.continuousDenoiseInterval = DENOISER_DEFAULTS.continuousDenoiseInterval;
 		// -Infinity, not 0: 0 reads as "denoised at time zero", which blocks the first cadence
 		// denoise while performance.now() is still below the interval.
 		this._lastCadenceAt = - Infinity;
@@ -160,7 +163,7 @@ export class DenoisingManager extends EventDispatcher {
 		this._onPostProcessRefresh = null;
 		this._onDisplayRefresh = null;
 
-		this.temporalHistory = DEFAULT_STATE.oidnTemporalHistory;
+		this.temporalHistory = DENOISER_DEFAULTS.oidnTemporalHistory;
 		this._history = null;
 		// Stale after a scene-changing reset, or one the app did not announce (material/env edits).
 		this._historyDirty = true;
@@ -307,7 +310,8 @@ export class DenoisingManager extends EventDispatcher {
 		// Compositor decides what the single canvas shows. The exposure, grade and tone curve
 		// come from the renderer's own output pass, so it is not told about them either.
 		this.denoiser = new OIDNDenoiser( this.renderer, {
-			...DEFAULT_STATE,
+			enableOIDN: DENOISER_DEFAULTS.enableOIDN,
+			oidnQuality: DENOISER_DEFAULTS.oidnQuality,
 
 			backendParams: () => ( {
 				device: this.renderer.backend.device,
@@ -378,8 +382,8 @@ export class DenoisingManager extends EventDispatcher {
 		const pt = this._stages.pathTracer;
 
 		this.upscaler = new AIUpscaler( this.upscalerCanvas, this.renderer, {
-			scaleFactor: DEFAULT_STATE.upscalerScale || 2,
-			quality: DEFAULT_STATE.upscalerQuality || 'fast',
+			scaleFactor: DENOISER_DEFAULTS.upscalerScale || 2,
+			quality: DENOISER_DEFAULTS.upscalerQuality || 'fast',
 
 			// One source: the render canvas shows whatever the Compositor picked — the denoised
 			// picture when OIDN is on, the raw render otherwise — so the upscaler always enlarges
@@ -407,7 +411,7 @@ export class DenoisingManager extends EventDispatcher {
 			getSaturation: () => this._getSaturation(),
 		} );
 
-		this.upscaler.enabled = DEFAULT_STATE.enableUpscaler || false;
+		this.upscaler.enabled = DENOISER_DEFAULTS.enableUpscaler || false;
 
 		// Forward lifecycle events (store refs for removal on re-setup / dispose)
 		this._upscalerResChangedHandler = ( e ) =>