rayzee 8.8.2 → 9.1.0

package/src/managers/LightManager.js

@@ -2,6 +2,13 @@ import {
 	EventDispatcher, DirectionalLight, PointLight, SpotLight, RectAreaLight,
 	Object3D, MathUtils
 } from 'three';
+import { toPortable, fromPortable } from '../SceneState/portable.js';
+
+// Set on lights a host added, which live in the light scene alone: a rebuild re-transfers the
+// model's lights and keeps these.
+const USER_LIGHT = '__rayzeeUserLight';
+
+const LIGHT_TYPES = { DirectionalLight, PointLight, SpotLight, RectAreaLight };
 
 /**
  * Manages scene lights: add, remove, transfer from mesh scene to WebGPU
@@ -84,6 +91,8 @@ export class LightManager extends EventDispatcher {
 
 		}
 
+		light.userData[ USER_LIGHT ] = true;
+
 		// Blender-style emission controls common to every light type.
 		light.userData.temperature = 6500;
 		light.userData.useTemperature = false;
@@ -158,10 +167,11 @@ export class LightManager extends EventDispatcher {
 	 * Clones lights from the mesh scene into the WebGPU light scene,
 	 * then updates GPU uniform buffers.
 	 * @param {import('three').Scene} meshScene
+	 * @param {{keepUserLights?: boolean}} [options] - keep the lights a host added (an incremental rebuild)
 	 */
-	transferSceneLights( meshScene ) {
+	transferSceneLights( meshScene, { keepUserLights = false } = {} ) {
 
-		this._removeAllLights();
+		this._removeAllLights( keepUserLights ? light => ! light.userData?.[ USER_LIGHT ] : undefined );
 
 		const sourceLights = meshScene.getObjectsByProperty( 'isLight', true );
 
@@ -228,6 +238,89 @@ export class LightManager extends EventDispatcher {
 
 	}
 
+	/**
+	 * Every light as plain data, for a saved session: the model's (with any edits) and the host's.
+	 * @returns {Object[]}
+	 */
+	serialize() {
+
+		return this.scene.getObjectsByProperty( 'isLight', true ).map( light => {
+
+			const record = {
+				type: light.type,
+				name: light.name,
+				visible: light.visible,
+				color: [ light.color.r, light.color.g, light.color.b ],
+				intensity: light.intensity,
+				position: light.position.toArray(),
+				quaternion: light.quaternion.toArray(),
+				scale: light.scale.toArray(),
+				userData: toPortable( light.userData ) ?? {},
+			};
+
+			if ( light.isSpotLight ) Object.assign( record, { angle: light.angle, penumbra: light.penumbra, distance: light.distance, decay: light.decay } );
+			if ( light.isPointLight ) Object.assign( record, { distance: light.distance, decay: light.decay } );
+			if ( light.isRectAreaLight ) Object.assign( record, { width: light.width, height: light.height } );
+			if ( light.target && ( light.isSpotLight || light.isDirectionalLight ) ) record.target = light.target.position.toArray();
+			return record;
+
+		} );
+
+	}
+
+	/**
+	 * Replaces every light with the ones {@link serialize} described.
+	 * @param {Object[]} records
+	 * @returns {import('three').Light[]} the new lights, in record order (unknown types skipped)
+	 */
+	restore( records ) {
+
+		this.sceneHelpers?.clear();
+		this._removeAllLights();
+
+		const lights = [];
+		for ( const record of records ?? [] ) {
+
+			const Type = LIGHT_TYPES[ record.type ];
+			if ( ! Type ) continue;
+
+			const light = new Type();
+			light.name = record.name ?? '';
+			light.visible = record.visible !== false;
+			light.color.setRGB( ...record.color );
+			light.intensity = record.intensity;
+			light.position.fromArray( record.position );
+			light.quaternion.fromArray( record.quaternion );
+			light.scale.fromArray( record.scale ?? [ 1, 1, 1 ] );
+			light.userData = fromPortable( record.userData ) ?? {};
+
+			for ( const key of [ 'angle', 'penumbra', 'distance', 'decay', 'width', 'height' ] ) {
+
+				if ( typeof record[ key ] === 'number' ) light[ key ] = record[ key ];
+
+			}
+
+			if ( record.target ) {
+
+				const target = new Object3D();
+				target.position.fromArray( record.target );
+				this.scene.add( target );
+				light.target = target;
+
+			}
+
+			this.scene.add( light );
+			lights.push( light );
+
+		}
+
+		this.updateLights();
+		this._syncHelpers();
+		this._onReset?.();
+		return lights;
+
+	}
+
 	// ── Aliases (match Sub-API surface for zero-churn migration) ──
 
 	/** @see addLight */
@@ -295,10 +388,10 @@ export class LightManager extends EventDispatcher {
 
 	// ── Private ───────────────────────────────────────────────────
 
-	/** Syncs helpers in sceneHelpers with current scene lights. */
-	_removeAllLights() {
+	/** @param {function(import('three').Light): boolean} [which] - all lights when omitted */
+	_removeAllLights( which ) {
 
-		this.scene.getObjectsByProperty( 'isLight', true ).forEach( light => {
+		this.scene.getObjectsByProperty( 'isLight', true ).filter( light => ! which || which( light ) ).forEach( light => {
 
 			this._onLightRemoved?.( light );
 			if ( light.target ) this.scene.remove( light.target );

package/src/managers/MaterialDataManager.js

@@ -17,6 +17,7 @@ import { packMaterial, UNIT_RANGE_PROPERTIES, clampUnit } from '../Processor/Mat
 import { resolveMaterialTextures, MATERIAL_VALUE_SOURCE } from '../Processor/GeometryExtractor.js';
 import { convertLinearTriple, convertLinearTriples, getWorkingMatrixSpace } from '../Color/WorkingMatrix.js';
 import { createLogger, fmt } from '../utils/Logger.js';
+import { toPortable } from '../SceneState/portable.js';
 
 /** Material buffers already moved into the working space, so a re-init cannot convert twice. */
 const convertedBuffers = new WeakSet();
@@ -30,6 +31,9 @@ const TRI_FLAGS_OFFSET = T.MATERIAL_FLAGS_OFFSET;
 // Material properties that affect the shadow-ray opaque-blocker flag.
 const BLOCKER_PROPS = new Set( [ 'transmission', 'transparent', 'opacity', 'alphaMode' ] );
 
+/** Material properties whose edit rewrites triangle records (side, shadow blocker, emitters). */
+export const TRIANGLE_PATCH_PROPERTIES = new Set( [ 'side', ...BLOCKER_PROPS, 'emissive', 'emissiveIntensity' ] );
+
 // Map slot → sRGB pool (true) or linear pool.
 const TEXTURE_POOLS = [
 	[ 'map', true ], [ 'emissiveMap', true ], [ 'sheenColorMap', true ], [ 'specularColorMap', true ],
@@ -98,7 +102,7 @@ export class MaterialDataManager {
 		 */
 		this.callbacks = {};
 
-		// Per material index: createMaterialObject's sources, and properties a host set since.
+		// Per material index: createMaterialObject's sources, and properties a host set since (name → portable value).
 		this._sources = [];
 		this._hostSet = [];
 
@@ -310,6 +314,22 @@ export class MaterialDataManager {
 
 	}
 
+	/**
+	 * Every property a host set, per material, as portable values (see SceneState/portable.js).
+	 * @returns {Array<{index: number, props: Object<string, *>}>}
+	 */
+	serializeHostEdits() {
+
+		const out = [];
+		this._hostSet.forEach( ( props, index ) => {
+
+			if ( props?.size ) out.push( { index, props: Object.fromEntries( props ) } );
+
+		} );
+		return out;
+
+	}
+
 	/**
 	 * Update a single material property in the storage buffer.
 	 * @param {number} materialIndex
@@ -481,7 +501,7 @@ export class MaterialDataManager {
 		}
 
 		this.materialStorageAttr.needsUpdate = true;
-		( this._hostSet[ materialIndex ] ??= new Set() ).add( property );
+		( this._hostSet[ materialIndex ] ??= new Map() ).set( property, toPortable( value ) );
 
 		// Recompute triangle-data opaque-blocker flag when any input to it changes.
 		if ( BLOCKER_PROPS.has( property ) ) {

package/src/managers/TransformManager.js

@@ -14,6 +14,13 @@ import { EngineEvents } from '../EngineEvents.js';
 // does not mutate its arguments, so this can be a shared constant.
 const FORWARD = new Vector3( 0, 0, - 1 );
 
+const rootScene = object => {
+
+	while ( object.parent ) object = object.parent;
+	return object.isScene ? object : null;
+
+};
+
 export class TransformManager {
 
 	constructor( { camera, canvas, orbitControls, app } ) {
@@ -33,6 +40,8 @@ export class TransformManager {
 		this._meshes = null;
 		this._refitInFlight = false;
 		this._baselineComputed = false;
+		// Objects the gizmo moved, so a saved session can put them back.
+		this._moved = new Set();
 
 		// Light transform state — spot/directional lights aim via a separate
 		// `.target` Object3D rather than their own rotation (see attach()).
@@ -56,6 +65,21 @@ export class TransformManager {
 	setMeshData( meshes ) {
 
 		this._meshes = meshes;
+		for ( const object of this._moved ) if ( ! rootScene( object ) ) this._moved.delete( object );
+
+	}
+
+	/** Objects the gizmo has moved that are still in the scene (lights are saved with the lights). */
+	get movedObjects() {
+
+		return [ ...this._moved ].filter( object => rootScene( object ) );
+
+	}
+
+	/** Counts an object as moved, as a gizmo drag would — for a restored session. */
+	noteMoved( object ) {
+
+		if ( object && ! object.isLight ) this._moved.add( object );
 
 	}
 
@@ -335,6 +359,7 @@ export class TransformManager {
 			// instead costs a pass over every vertex, and corrupts any other object sharing
 			// this geometry.
 			this._app.updateMeshTransforms( affectedIndices );
+			this._moved.add( this._attached );
 
 		} catch ( err ) {
 
@@ -393,6 +418,7 @@ export class TransformManager {
 		this._controls.dispose();
 
 		this._meshes = null;
+		this._moved.clear();
 		this._baselineComputed = false;
 		this._tempForward = null;
 		this._lightTargetDistance = null;

package/src/managers/UniformManager.js

@@ -6,9 +6,9 @@
  */
 
 import { uniform, uniformArray } from 'three/tsl';
-import { Vector2, Matrix4, Vector3, Color, MathUtils } from 'three';
+import { Vector2, Matrix4, Vector3, Vector4, Color, MathUtils } from 'three';
 import { samplingTechniqueUniform } from '../TSL/Random.js';
-import { ENGINE_DEFAULTS as DEFAULT_STATE } from '../EngineDefaults.js';
+import { ENGINE_DEFAULTS as DEFAULT_STATE, CAMERA_PROJECTION_IDS } from '../EngineDefaults.js';
 
 /**
  * Map of uniform names to their WGSL shader names (where different).
@@ -249,9 +249,11 @@ export class UniformManager {
 		ub( 'enableGroundCatcher', DEFAULT_STATE.enableGroundCatcher );
 		u( 'groundCatcherHeight', DEFAULT_STATE.groundCatcherHeight, 'float' );
 
-		// Sun parameters
+		// The physical sky's sun (TSL/Sun.js): world direction, disc-average radiance, and
+		// ( cos half-angle, solid angle, 1 / sin² half-angle, horizon dip sin )
 		u( 'sunDirection', new Vector3( 0, 1, 0 ), 'vec3' );
-		u( 'sunAngularSize', 0.0087, 'float' );
+		u( 'sunRadiance', new Vector3(), 'vec3' );
+		u( 'sunParams', new Vector4( 1, 0, 0, 0 ), 'vec4' );
 		ub( 'hasSun', false );
 
 		// Lighting
@@ -278,9 +280,9 @@ export class UniformManager {
 		u( 'cameraViewMatrix', new Matrix4(), 'mat4' );
 		u( 'cameraProjectionMatrix', new Matrix4(), 'mat4' );
 
-		// Projection: 0 = pinhole, 1 = equirectangular panorama. Ranges are radians (UI carries degrees).
+		// Projection: CAMERA_PROJECTION_IDS. Ranges are radians (UI carries degrees).
 		const radRange = ( [ min, max ] ) => new Vector2( min, max ).multiplyScalar( MathUtils.DEG2RAD );
-		u( 'cameraProjection', DEFAULT_STATE.cameraProjection === 'equirectangular' ? 1 : 0, 'int' );
+		u( 'cameraProjection', CAMERA_PROJECTION_IDS[ DEFAULT_STATE.cameraProjection ], 'int' );
 		u( 'panoLonRange', radRange( DEFAULT_STATE.panoramaLonRange ), 'vec2' );
 		u( 'panoLatRange', radRange( DEFAULT_STATE.panoramaLatRange ), 'vec2' );
 		ub( 'panoLevelHorizon', DEFAULT_STATE.panoramaLevelHorizon );
@@ -292,7 +294,9 @@ export class UniformManager {
 		u( 'aperture', DEFAULT_STATE.aperture, 'float' );
 		u( 'apertureScale', 1.0, 'float' );
 		u( 'anamorphicRatio', DEFAULT_STATE.anamorphicRatio ?? 1.0, 'float' );
-		u( 'sceneScale', 1.0, 'float' );
+		u( 'unitsPerMetre', DEFAULT_STATE.unitsPerMetre, 'float' );
+		u( 'dofMode', DEFAULT_STATE.dofMode === 'look' ? 1 : 0, 'int' );
+		u( 'dofBlur', DEFAULT_STATE.dofBlur, 'float' );
 
 		// Sampling — use the module-level uniform from Random.js so TSL sees the same node
 		this._uniforms.set( 'samplingTechnique', samplingTechniqueUniform );

package/src/managers/VideoRenderManager.js

@@ -1,9 +1,9 @@
 /**
  * VideoRenderManager — Drives offline frame-by-frame animation rendering.
  *
- * Seeks the animation to each frame time, accumulates SPP until convergence,
- * optionally denoises, captures the output canvas, and delivers each frame
- * via a callback for encoding.
+ * Seeks the animation clip and the timeline, when given one, to each frame time, accumulates SPP
+ * until convergence, optionally denoises, captures the output canvas, and delivers each frame via a
+ * callback for encoding.
  */
 
 import { EngineEvents } from '../EngineEvents.js';
@@ -30,6 +30,9 @@ export class VideoRenderManager {
 	 * @param {boolean} [options.enableOIDN=true]    - Run OIDN denoiser per frame
 	 * @param {number} [options.speed=1]              - Playback speed multiplier (maps video time to animation time)
 	 * @param {number} [options.totalFrames]         - Override total frame count (for looped animations)
+	 * @param {number} [options.startFrame=0]        - First frame to render: a resumed export skips those it has
+	 * @param {import('./timeline/TimelineManager.js').TimelineManager} [options.timeline] - Keyframes to
+	 *   play in video time; without a clip the video lasts as long as they do
 	 * @param {Function} [options.onFrame]           - async (ImageBitmap, frameIndex, totalFrames) => void
 	 * @param {Function} [options.onProgress]        - ({ frame, totalFrames, percent }) => void
 	 * @param {Function} [options.onComplete]        - (success: boolean) => void
@@ -42,6 +45,8 @@ export class VideoRenderManager {
 			speed = 1,
 			samplesPerFrame = PRODUCTION_RENDER_CONFIG.maxSamples,
 			enableOIDN = true,
+			timeline = null,
+			startFrame = 0,
 			onFrame,
 			onProgress,
 			onComplete,
@@ -49,32 +54,32 @@ export class VideoRenderManager {
 
 		const app = this._app;
 
-		if ( ! app.animationManager?.hasAnimations ) {
+		// Keyframes alone make a video too.
+		const clip = app.animationManager?.hasAnimations ? app.animationManager.clips[ clipIndex ] : null;
+		if ( ! clip && ! timeline?.animates ) {
 
-			console.warn( 'VideoRenderManager: No animation clips available' );
+			console.warn( app.animationManager?.hasAnimations ? `VideoRenderManager: Invalid clip index ${clipIndex}` : 'VideoRenderManager: No animation clips or keyframes' );
 			onComplete?.( false );
 			return;
 
 		}
 
-		const clip = app.animationManager.clips[ clipIndex ];
-		if ( ! clip ) {
+		const effectiveDuration = clip ? clip.duration / ( speed || 1 ) : timeline.duration;
+		const totalFrames = options.totalFrames || Math.ceil( effectiveDuration * fps );
+		const frameDuration = 1 / fps;
+		if ( ! ( totalFrames > 0 ) ) {
 
-			console.warn( `VideoRenderManager: Invalid clip index ${clipIndex}` );
+			console.warn( 'VideoRenderManager: No frames to render' );
 			onComplete?.( false );
 			return;
 
 		}
 
-		const effectiveDuration = clip.duration / ( speed || 1 );
-		const totalFrames = options.totalFrames || Math.ceil( effectiveDuration * fps );
-		const frameDuration = 1 / fps;
-
 		this._cancelled = false;
 		this._rendering = true;
 
 		// Save current engine state
-		const savedState = this._saveState();
+		const savedState = this._saveState( { view: !! timeline } );
 
 		// Stop the rAF loop — we drive rendering manually
 		app.stopAnimation();
@@ -91,7 +96,7 @@ export class VideoRenderManager {
 
 		try {
 
-			for ( let i = 0; i < totalFrames; i ++ ) {
+			for ( let i = Math.max( 0, startFrame ); i < totalFrames; i ++ ) {
 
 				if ( this._cancelled ) break;
 
@@ -99,7 +104,16 @@ export class VideoRenderManager {
 				const animationTime = i * frameDuration * speed;
 
 				// 1. Seek animation to frame time
-				const positions = app.animationManager.seekTo( animationTime, clipIndex );
+				const positions = clip ? app.animationManager.seekTo( animationTime, clipIndex ) : null;
+
+				// After the clip, which moves a followed model camera.
+				if ( timeline?.seek( i * frameDuration ) ) {
+
+					// A moving camera changes what is under the focus point.
+					app.cameraManager.resetAutoFocus();
+					app.cameraManager.updateAutoFocus();
+
+				}
 
 				// 2. Refit BVH with deformed positions (also calls reset())
 				if ( positions ) {
@@ -268,16 +282,21 @@ export class VideoRenderManager {
 
 	/**
 	 * Save engine state that we'll modify during video render.
+	 * @param {Object} options
+	 * @param {boolean} options.view - a timeline will move the camera, and auto-focus with it
 	 * @private
 	 */
-	_saveState() {
+	_saveState( { view } ) {
 
 		const app = this._app;
 		const effective = app.settings.getEffective();
+		const keys = Object.keys( modePresetSettings( PRODUCTION_RENDER_CONFIG ) );
+		if ( view ) keys.push( 'focusDistance' );
 
 		return {
+			view: view ? app.cameraManager.captureView() : null,
 			// Everything configureForMode( 'production' ) overwrites, with who set it.
-			settings: Object.keys( modePresetSettings( PRODUCTION_RENDER_CONFIG ) ).map( key => [ key, effective[ key ] ] ),
+			settings: keys.map( key => [ key, effective[ key ] ] ),
 			renderMode: app.stages.pathTracer?.renderMode?.value,
 			controlsEnabled: app.cameraManager.controls?.enabled,
 			oidnEnabled: app.denoisingManager?.finalDenoise,
@@ -321,6 +340,8 @@ export class VideoRenderManager {
 
 		app.pauseRendering = state.pauseRendering ?? false;
 
+		if ( state.view ) app.cameraManager.applyPose( state.view );
+
 		// configureForMode( 'production' ) suspended the live-view refresh and nothing here switches
 		// back, so the viewport would stay un-denoised until the host changed tab.
 		app.denoisingManager?.setCadenceSuspended( false );

package/src/managers/ViewCamera.js

@@ -0,0 +1,77 @@
+import { OrthographicCamera, PerspectiveCamera } from 'three';
+
+/**
+ * The view's camera: a perspective camera that can also project orthographically.
+ *
+ * It switches in place, so everything holding it (the controls, picking, the gizmo, the overlays
+ * and the path tracer) follows. three.js reads the camera's type from the two flags below, and an
+ * orthographic camera's frustum from `top`, `bottom`, `left` and `right`.
+ */
+export class ViewCamera extends PerspectiveCamera {
+
+	constructor( fov, aspect, near, far ) {
+
+		super( fov, aspect, near, far );
+
+		this.orthographic = false;
+		/** Half the view's height in world units while orthographic, before `zoom`. */
+		this.orthoHalfHeight = 1;
+
+	}
+
+	get isPerspectiveCamera() {
+
+		return ! this.orthographic;
+
+	}
+
+	// PerspectiveCamera's constructor assigns the flag.
+	set isPerspectiveCamera( value ) {}
+
+	get isOrthographicCamera() {
+
+		return this.orthographic;
+
+	}
+
+	get top() {
+
+		return this.orthoHalfHeight;
+
+	}
+
+	get bottom() {
+
+		return - this.orthoHalfHeight;
+
+	}
+
+	get right() {
+
+		return this.orthoHalfHeight * this.aspect;
+
+	}
+
+	get left() {
+
+		return - this.orthoHalfHeight * this.aspect;
+
+	}
+
+	updateProjectionMatrix() {
+
+		if ( this.orthographic ) OrthographicCamera.prototype.updateProjectionMatrix.call( this );
+		else super.updateProjectionMatrix();
+
+	}
+
+	copy( source, recursive ) {
+
+		super.copy( source, recursive );
+		this.orthographic = source.orthographic === true;
+		this.orthoHalfHeight = source.orthoHalfHeight ?? this.orthoHalfHeight;
+		return this;
+
+	}
+
+}