rayzee 8.8.2 → 9.0.0

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,8 @@ 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 {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 +44,7 @@ export class VideoRenderManager {
 			speed = 1,
 			samplesPerFrame = PRODUCTION_RENDER_CONFIG.maxSamples,
 			enableOIDN = true,
+			timeline = null,
 			onFrame,
 			onProgress,
 			onComplete,
@@ -49,32 +52,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();
@@ -99,7 +102,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 +280,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 +338,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;
+
+	}
+
+}

package/src/managers/WalkControls.js

@@ -0,0 +1,262 @@
+import { Controls, MathUtils, Quaternion, Vector3 } from 'three';
+
+const CROSSING_SECONDS = 8;
+const FAST = 4;
+const SLOW = 0.25;
+const MAX_PITCH = MathUtils.degToRad( 89 );
+const MAX_STEP_SECONDS = 0.25;
+
+// Right, forward, up.
+const KEY_DIRECTIONS = {
+	KeyD: [ 1, 0, 0 ], ArrowRight: [ 1, 0, 0 ],
+	KeyA: [ - 1, 0, 0 ], ArrowLeft: [ - 1, 0, 0 ],
+	KeyW: [ 0, 1, 0 ], ArrowUp: [ 0, 1, 0 ],
+	KeyS: [ 0, - 1, 0 ], ArrowDown: [ 0, - 1, 0 ],
+	KeyE: [ 0, 0, 1 ],
+	KeyQ: [ 0, 0, - 1 ],
+};
+
+// Focus that types, or opens a list, keeps its keys. A widget that handled a key prevents its default.
+const TYPES_KEYS = 'input, textarea, select, [contenteditable]:not([contenteditable="false"]), '
+	+ '[role=textbox], [role=combobox], [role=listbox], [role=menu], [role=menuitem]';
+
+const speedFactor = event => event.shiftKey ? FAST : event.altKey ? SLOW : 1;
+
+const _changeEvent = { type: 'change' };
+const _startEvent = { type: 'start' };
+const _forward = new Vector3();
+const _right = new Vector3();
+const _move = new Vector3();
+const _axis = new Vector3();
+const _q = new Quaternion();
+
+/**
+ * First-person navigation: drag to look, W A S D or the arrows to walk level, E and Q to rise
+ * and sink, Shift faster, Alt slower.
+ *
+ * Rides on the orbit controls: moves only while they are enabled, and keeps their target ahead
+ * of the camera, since they re-aim the camera at it every frame.
+ */
+export class WalkControls extends Controls {
+
+	/**
+	 * @param {import('three').PerspectiveCamera} camera
+	 * @param {HTMLElement} domElement
+	 * @param {import('three/addons/controls/OrbitControls.js').OrbitControls} orbit
+	 */
+	constructor( camera, domElement, orbit ) {
+
+		super( camera, domElement );
+
+		this.orbit = orbit;
+		this.enabled = false;
+		/** Scene units per second. */
+		this.speed = 1 / CROSSING_SECONDS;
+
+		this._held = new Set();
+		this._factor = 1;
+		this._lastTime = 0;
+		this._drag = null;
+
+		this._onKeyDown = this._onKeyDown.bind( this );
+		this._onKeyUp = this._onKeyUp.bind( this );
+		this.release = this.release.bind( this );
+		this._onPointerDown = this._onPointerDown.bind( this );
+		this._onPointerMove = this._onPointerMove.bind( this );
+		this._onPointerUp = this._onPointerUp.bind( this );
+
+		if ( domElement ) this.connect( domElement );
+
+	}
+
+	get active() {
+
+		return this.enabled && this.orbit.enabled;
+
+	}
+
+	/** Cross a scene this long in about eight seconds. */
+	fitSpeed( sceneSize ) {
+
+		this.speed = ( sceneSize > 0 ? sceneSize : 1 ) / CROSSING_SECONDS;
+
+	}
+
+	connect( element ) {
+
+		super.connect( element );
+		const doc = element.ownerDocument;
+		doc?.addEventListener( 'keydown', this._onKeyDown );
+		doc?.addEventListener( 'keyup', this._onKeyUp );
+		doc?.addEventListener( 'visibilitychange', this.release );
+		doc?.defaultView?.addEventListener( 'blur', this.release );
+		element.addEventListener( 'pointerdown', this._onPointerDown );
+		element.addEventListener( 'pointermove', this._onPointerMove );
+		element.addEventListener( 'pointerup', this._onPointerUp );
+		element.addEventListener( 'pointercancel', this._onPointerUp );
+
+	}
+
+	disconnect() {
+
+		const element = this.domElement;
+		if ( ! element ) return;
+		const doc = element.ownerDocument;
+		doc?.removeEventListener( 'keydown', this._onKeyDown );
+		doc?.removeEventListener( 'keyup', this._onKeyUp );
+		doc?.removeEventListener( 'visibilitychange', this.release );
+		doc?.defaultView?.removeEventListener( 'blur', this.release );
+		element.removeEventListener( 'pointerdown', this._onPointerDown );
+		element.removeEventListener( 'pointermove', this._onPointerMove );
+		element.removeEventListener( 'pointerup', this._onPointerUp );
+		element.removeEventListener( 'pointercancel', this._onPointerUp );
+
+	}
+
+	dispose() {
+
+		this.disconnect();
+
+	}
+
+	update( delta = this._elapsed() ) {
+
+		if ( ! this._held.size || ! this.active ) return false;
+
+		let right = 0, forward = 0, up = 0;
+		for ( const code of this._held ) {
+
+			const [ r, f, u ] = KEY_DIRECTIONS[ code ];
+			right += r;
+			forward += f;
+			up += u;
+
+		}
+
+		if ( ! right && ! forward && ! up ) return false;
+
+		const camera = this.object;
+		// Level axes from the camera's right, which stays level however far it looks down.
+		_right.set( 1, 0, 0 ).applyQuaternion( camera.quaternion );
+		_forward.crossVectors( camera.up, _right ).normalize();
+		_right.crossVectors( _forward, camera.up );
+
+		_move.set( 0, 0, 0 )
+			.addScaledVector( _right, right )
+			.addScaledVector( _forward, forward )
+			.addScaledVector( camera.up, up )
+			.normalize()
+			.multiplyScalar( this.speed * this._factor * delta );
+		camera.position.add( _move );
+		this.orbit.target.add( _move );
+		camera.updateMatrixWorld();
+
+		this.dispatchEvent( _changeEvent );
+		return true;
+
+	}
+
+	_elapsed() {
+
+		const now = performance.now();
+		const delta = Math.min( ( now - this._lastTime ) / 1000, MAX_STEP_SECONDS );
+		this._lastTime = now;
+		return delta;
+
+	}
+
+	/** Turn by a drag of dx, dy pixels, so the scene follows the pointer. */
+	_look( dx, dy ) {
+
+		const camera = this.object;
+		const target = this.orbit.target;
+		const distance = camera.position.distanceTo( target ) || 1;
+		const radiansPerPixel = MathUtils.degToRad( camera.fov ) / ( this.domElement.clientHeight || 1 );
+
+		camera.quaternion.premultiply( _q.setFromAxisAngle( camera.up, dx * radiansPerPixel ) );
+
+		camera.getWorldDirection( _forward );
+		const pitch = Math.asin( MathUtils.clamp( _forward.dot( camera.up ), - 1, 1 ) );
+		const nextPitch = MathUtils.clamp( pitch + dy * radiansPerPixel, - MAX_PITCH, MAX_PITCH );
+		camera.quaternion.multiply( _q.setFromAxisAngle( _axis.set( 1, 0, 0 ), nextPitch - pitch ) );
+		camera.updateMatrixWorld();
+
+		target.copy( camera.position ).addScaledVector( camera.getWorldDirection( _forward ), distance );
+		this.dispatchEvent( _changeEvent );
+
+	}
+
+	_onKeyDown( event ) {
+
+		if ( ! this.active || event.defaultPrevented || event.target?.closest?.( TYPES_KEYS ) ) return;
+
+		// Browser shortcuts pass through, and macOS drops the key-up of a key pressed while Cmd is down.
+		if ( event.metaKey || event.ctrlKey ) {
+
+			this.release();
+			return;
+
+		}
+
+		this._factor = speedFactor( event );
+		if ( ! KEY_DIRECTIONS[ event.code ] ) return;
+
+		event.preventDefault();
+		if ( this._held.has( event.code ) ) return;
+		this._held.add( event.code );
+
+		// After the key is held: a woken loop runs its first frame inside this dispatch.
+		if ( this._held.size === 1 ) {
+
+			this._lastTime = performance.now();
+			this.dispatchEvent( _startEvent );
+
+		}
+
+	}
+
+	_onKeyUp( event ) {
+
+		this._factor = speedFactor( event );
+		this._held.delete( event.code );
+
+	}
+
+	/** Let go of every held key. */
+	release() {
+
+		this._held.clear();
+		this._factor = 1;
+
+	}
+
+	_onPointerDown( event ) {
+
+		if ( ! this.active || event.button !== 0 || ! event.isPrimary ) return;
+		this._drag = { id: event.pointerId, x: event.clientX, y: event.clientY };
+		this.domElement.setPointerCapture?.( event.pointerId );
+
+	}
+
+	_onPointerMove( event ) {
+
+		const drag = this._drag;
+		if ( ! drag || event.pointerId !== drag.id ) return;
+
+		const dx = event.clientX - drag.x;
+		const dy = event.clientY - drag.y;
+		drag.x = event.clientX;
+		drag.y = event.clientY;
+		if ( this.active && ( dx || dy ) ) this._look( dx, dy );
+
+	}
+
+	_onPointerUp( event ) {
+
+		if ( this._drag?.id !== event.pointerId ) return;
+		this._drag = null;
+		this.domElement.releasePointerCapture?.( event.pointerId );
+
+	}
+
+}

package/src/managers/helpers/OutlineHelper.js

@@ -28,12 +28,22 @@ export class OutlineHelper {
 
 		this.layer = 'scene';
 		this._enabled = true;
+		this._scene = scene;
+		this._camera = camera;
+		this._build( [] );
+
+	}
+
+	// OutlineNode reads the camera's type once, as it builds its depth test.
+	_build( selectedObjects ) {
+
+		this._orthographic = this._camera.isOrthographicCamera === true;
 
 		// Outline node (handles its own multi-pass rendering via updateBefore).
 		// It sizes its render targets from the drawing buffer of whatever renderer
 		// draws it — the view overlay surface — so no size override is needed.
-		this._outlineNode = outline( scene, camera, {
-			selectedObjects: [],
+		this._outlineNode = outline( this._scene, this._camera, {
+			selectedObjects,
 			edgeThickness: uniform( 1.0 ),
 			edgeGlow: uniform( 0.0 ),
 		} );
@@ -98,6 +108,16 @@ export class OutlineHelper {
 
 		if ( ! this.visible ) return;
 
+		if ( this._camera.isOrthographicCamera !== this._orthographic ) {
+
+			// dispose() empties the list it was given.
+			const selected = [ ...this._outlineNode.selectedObjects ];
+			this._outlineNode.dispose();
+			this._material.dispose();
+			this._build( selected );
+
+		}
+
 		const prevAutoClear = renderer.autoClear;
 		renderer.autoClear = false;
 		renderer.setRenderTarget( null );