rayzee 8.8.2 → 9.1.0

package/package.json

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

package/src/AssetConfig.js

@@ -56,6 +56,10 @@ const config = {
 	// Prefix used when the engine writes to client-side stores (IndexedDB, etc).
 	// Set to a unique value to avoid collisions when multiple apps embed the engine on the same origin.
 	cacheNamespace: 'rayzee',
+
+	// On-disk storage (origin private file system) under a directory named by cacheNamespace:
+	// 'auto' uses it where the browser has one, false turns every storage feature off.
+	storage: 'auto',
 };
 
 /**

package/src/EngineDefaults.js

@@ -1,3 +1,10 @@
+import { sunPosition, dayOfYearForMonth } from './Processor/SunPosition.js';
+
+/** The default sun as a time of day (solar hours), month and latitude; north lies along −Z. */
+export const DEFAULT_SUN_PATH = Object.freeze( { time: 10, month: 3, latitude: 40 } );
+
+const DEFAULT_SUN = sunPosition( { hours: DEFAULT_SUN_PATH.time, dayOfYear: dayOfYearForMonth( DEFAULT_SUN_PATH.month ), latitude: DEFAULT_SUN_PATH.latitude } );
+
 /**
  * Engine-owned default values and configuration constants.
  * These are used exclusively by the rendering engine (src/core/)
@@ -14,6 +21,7 @@ export const RENDER_PROFILES = Object.freeze( {
 		environmentRotation: 0.0, // degrees — the HDRI as authored, as Blender shows it
 		toneMapping: 6, // AgXToneMapping
 		saturation: 1.0, // no grade
+		dofMode: 'look', // depth of field set by how blurry it looks, not by a lens — right at any scene scale
 	} ),
 	physical: Object.freeze( {
 		areaLightIntensityScale: 1.0,
@@ -22,6 +30,7 @@ export const RENDER_PROFILES = Object.freeze( {
 		// engine's own corpus (shade 1.48 vs AgX 3.01 from identical radiance).
 		toneMapping: 6,
 		saturation: 1.0, // no grade
+		dofMode: 'physical',
 	} ),
 } );
 
@@ -92,16 +101,19 @@ export const ENGINE_DEFAULTS = {
 	// Solid Color Sky
 	solidSkyColor: '#87CEEB',
 
-	// Procedural Sky Parameters (Preetham Model - Clear Morning preset)
-	skySunAzimuth: 90,
-	skySunElevation: 20,
-	skySunIntensity: 15.0,
-	skyRayleighDensity: 0.9,
-	skyTurbidity: 0.8,
-	skyMieAnisotropy: 0.76,
-	skyPreset: 'clearMorning',
-
-	// Camera projection — 'perspective' | 'equirectangular'. Panorama ranges are UI-facing degrees.
+	// Physical sky (Processor/PhysicalSky.js) — the Clear Day preset
+	skySunAzimuth: 180 - DEFAULT_SUN.azimuth,
+	skySunElevation: DEFAULT_SUN.elevation,
+	skySunStrength: 1, // artistic multiplier on the disc and its light; 1 is physical
+	skySunSize: 0.53, // angular diameter, degrees
+	skyTurbidity: 2, // 1 is aerosol-free air, ~2 a clear day, 6+ hazy
+	skyOzone: 300, // Dobson units
+	skyAirDensity: 1,
+	skyGroundAlbedo: '#959595', // 0.3 linear
+	skyAltitude: 50, // metres
+	skyPreset: 'clearDay',
+
+	// Camera projection — 'perspective' | 'orthographic' | 'equirectangular'. Panorama ranges are UI-facing degrees.
 	cameraProjection: 'perspective',
 	panoramaLonRange: [ - 180, 180 ],
 	panoramaLatRange: [ - 90, 90 ],
@@ -114,6 +126,9 @@ export const ENGINE_DEFAULTS = {
 	focalLength: 50,
 	apertureScale: 1.0,
 	anamorphicRatio: 1.0,
+	unitsPerMetre: 1, // scene units per real metre; the lens is specified in mm
+	dofMode: RENDER_PROFILES.viewer.dofMode, // 'look' | 'physical'
+	dofBlur: 0.05, // look mode: a far background's blur, as a fraction of the image height
 
 	// Auto-focus
 	autoFocusMode: 'auto', // 'manual' | 'auto'
@@ -252,6 +267,9 @@ export const ENGINE_DEFAULTS = {
 	autoExposureAdaptSpeedDark: 0.5,
 };
 
+/** The `cameraProjection` uniform's value for each setting value. */
+export const CAMERA_PROJECTION_IDS = Object.freeze( { perspective: 0, equirectangular: 1, orthographic: 2 } );
+
 // Ray distance NormalDepth writes on a miss. Max finite half-float, so miss−miss diffs stay 0
 // rather than Inf−Inf=NaN.
 export const GBUFFER_MISS_DEPTH = 65504.0;
@@ -419,99 +437,56 @@ export const CAMERA_RANGES = {
 	}
 };
 
+// `exposure` (EV) makes up about two thirds of the light a lower sun loses, as a photographer
+// would: a sunset still reads darker than noon.
 export const SKY_PRESETS = {
-	clearMorning: {
-		name: "Clear Morning",
-		sunAzimuth: 90,
-		sunElevation: 20,
-		sunIntensity: 15.0,
-		rayleighDensity: 0.9,
-		turbidity: 0.8,
-	},
-	clearNoon: {
-		name: "Clear Noon",
-		sunAzimuth: 0,
-		sunElevation: 75,
-		sunIntensity: 20.0,
-		rayleighDensity: 1.0,
-		turbidity: 0.3,
-	},
-	overcast: {
-		name: "Overcast",
-		sunAzimuth: 0,
-		sunElevation: 45,
-		sunIntensity: 6.0,
-		rayleighDensity: 0.6,
-		turbidity: 4.0,
-	},
-	goldenHour: {
-		name: "Golden Hour",
-		sunAzimuth: 270,
-		sunElevation: 10,
-		sunIntensity: 19.0,
-		rayleighDensity: 0.8,
-		turbidity: 1.2,
-	},
-	sunset: {
-		name: "Sunset",
-		sunAzimuth: 270,
-		sunElevation: 2,
-		sunIntensity: 18.0,
-		rayleighDensity: 0.7,
-		turbidity: 2.0,
-	},
-	dusk: {
-		name: "Dusk",
-		sunAzimuth: 270,
-		sunElevation: - 8,
-		sunIntensity: 8.0,
-		rayleighDensity: 0.5,
-		turbidity: 1.5,
-	}
+	clearDay: { name: 'Clear Day', sunAzimuth: 180 - DEFAULT_SUN.azimuth, sunElevation: DEFAULT_SUN.elevation, turbidity: 2, exposure: 0 },
+	clearMorning: { name: 'Clear Morning', sunAzimuth: 90, sunElevation: 15, turbidity: 2, exposure: 1.4 },
+	clearNoon: { name: 'Clear Noon', sunAzimuth: 180, sunElevation: 70, turbidity: 2, exposure: 0 },
+	hazyAfternoon: { name: 'Hazy Afternoon', sunAzimuth: 225, sunElevation: 35, turbidity: 4.5, exposure: 0.4 },
+	goldenHour: { name: 'Golden Hour', sunAzimuth: 270, sunElevation: 6, turbidity: 2.5, exposure: 2.7 },
+	sunset: { name: 'Sunset', sunAzimuth: 270, sunElevation: 1, turbidity: 3, exposure: 4.2 },
+	blueHour: { name: 'Blue Hour', sunAzimuth: 270, sunElevation: - 4, turbidity: 2, exposure: 7 },
+	mountain: { name: 'Mountain Air', sunAzimuth: 135, sunElevation: 40, turbidity: 1.3, altitude: 3000, exposure: 0 },
 };
 
 export const CAMERA_PRESETS = {
 	portrait: {
 		name: "Portrait",
 		description: "Shallow depth of field, background blur",
-		fov: 45,
-		focusDistance: 1.5,
+		dofBlur: 0.10,
 		aperture: 1.4,
 		focalLength: 135,
-		apertureScale: 1.5
+		apertureScale: 1.0
 	},
 	landscape: {
 		name: "Landscape",
 		description: "Maximum depth of field, everything in focus",
-		fov: 65,
-		focusDistance: 10.0,
+		dofBlur: 0.001,
 		aperture: 16.0,
 		focalLength: 24,
 		apertureScale: 0.5
 	},
 	macro: {
 		name: "Macro",
-		description: "Extreme close-up with thin focus plane",
-		fov: 40,
-		focusDistance: 0.3,
-		aperture: 2.0,
+		description: "Very thin focus plane for close-ups",
+		dofBlur: 0.14,
+		aperture: 1.4,
 		focalLength: 100,
 		apertureScale: 2.0
 	},
 	product: {
 		name: "Product",
 		description: "Sharp detail with subtle background separation",
-		fov: 50,
-		focusDistance: 0.8,
+		dofBlur: 0.013,
 		aperture: 2.8,
 		focalLength: 85,
-		apertureScale: 1.0
+		apertureScale: 0.4
 	},
 	architectural: {
 		name: "Architectural",
-		description: "Wide view with deep focus",
-		fov: 75,
-		focusDistance: 5.0,
+		description: "Deep focus for rooms and buildings",
+		dofBlur: 0.001,
 		aperture: 11.0,
 		focalLength: 16,
 		apertureScale: 0.5
@@ -519,11 +494,10 @@ export const CAMERA_PRESETS = {
 	cinematic: {
 		name: "Cinematic",
 		description: "Dramatic depth separation with anamorphic bokeh",
-		fov: 35,
-		focusDistance: 3.0,
+		dofBlur: 0.13,
 		aperture: 1.4,
 		focalLength: 200,
-		apertureScale: 1.8,
+		apertureScale: 1.0,
 		anamorphicRatio: 1.5
 	}
 };
@@ -834,6 +808,16 @@ export const BVH_LEAF_MARKERS = {
 	FRONTIER: 0x40000002, // parallel-build placeholder, overwritten during assembly
 };
 
+/**
+ * A triangle leaf of at most this many triangles is folded into its parent: the child's slot ([3]
+ * or [7]) holds `~( first << 4 | count )`, the very value traversal pushes, so an inner node is
+ * read exactly as before and only popping a negative entry differs. Node indices stay below
+ * {@link BVH_MAX_INDEX}, leaf tags between it and 2^31, folded leaves from 2^31 up — so the count
+ * has four bits and the first triangle must stay below {@link BVH_FOLDED_FIRST_LIMIT}.
+ */
+export const BVH_FOLDED_LEAF_MAX = 15;
+export const BVH_FOLDED_FIRST_LIMIT = 1 << 27;
+
 /** A u32 view over a float buffer, for writing index fields as exact bit patterns. */
 export function bvhIndexView( f32 ) {
 

package/src/EngineEvents.js

@@ -36,6 +36,7 @@ export const EngineEvents = {
 
 	// Camera
 	AUTO_FOCUS_UPDATED: 'engine:autoFocusUpdated',
+	ORTHO_HEIGHT_UPDATED: 'engine:orthoHeightUpdated',
 	AUTO_EXPOSURE_UPDATED: 'engine:autoExposureUpdated',
 	AF_POINT_PLACED: 'engine:afPointPlaced',
 
@@ -48,6 +49,9 @@ export const EngineEvents = {
 	ANIMATION_STOPPED: 'engine:animationStopped',
 	ANIMATION_FINISHED: 'engine:animationFinished',
 
+	// Timeline (authored keyframes)
+	TIMELINE_CHANGED: 'engine:timelineChanged',
+
 	// Video rendering
 	VIDEO_RENDER_PROGRESS: 'engine:videoRenderProgress',
 	VIDEO_RENDER_COMPLETE: 'engine:videoRenderComplete',
@@ -61,4 +65,7 @@ export const EngineEvents = {
 
 	// Scene metadata
 	SCENE_METADATA_APPLIED: 'engine:sceneMetadataApplied',
+
+	// Storage (OPFS): usage or entries changed
+	STORAGE_CHANGED: 'engine:storageChanged',
 };

package/src/EngineIssues.js

@@ -24,6 +24,12 @@ export const ISSUE_CODES = Object.freeze( {
 	VIEW_TRANSFORM_DISPLAY_MISMATCH: 'viewTransform.display_mismatch',
 	VIEW_TRANSFORM_BAKE_FAILED: 'viewTransform.bake_failed',
 	COLOR_CONFIG_LOAD_FAILED: 'color.config_load_failed',
+	STORAGE_UNAVAILABLE: 'storage.unavailable',
+	STORAGE_QUOTA_EXCEEDED: 'storage.quota_exceeded',
+	STORAGE_WRITE_FAILED: 'storage.write_failed',
+	STORAGE_READ_FAILED: 'storage.read_failed',
+	STORAGE_ENTRY_CORRUPT: 'storage.entry_corrupt',
+	STORAGE_CACHE_MISMATCH: 'storage.cache_mismatch',
 } );
 
 /** Strict throws on ERROR only. */

package/src/Headless.js

@@ -81,11 +81,13 @@ export async function openHeadless( {
 	profile = 'physical',
 	deterministic = true,
 	settings = null,
+	storage = false,
 } = {} ) {
 
 	if ( ! canvas ) throw new Error( 'openHeadless: a canvas is required' );
 
-	const app = new PathTracerApp( canvas, { autoResize: false, strict, profile } );
+	// Off unless asked for: cached state from an earlier run must not change what a batch renders.
+	const app = new PathTracerApp( canvas, { autoResize: false, strict, profile, storage } );
 
 	try {
 

package/src/Passes/AIUpscaler.js

@@ -205,7 +205,7 @@ export class AIUpscaler extends EventDispatcher {
 
 				};
 
-				const { ortRuntimeUrl, ortWasmPaths, cacheNamespace } = getAssetConfig();
+				const { ortRuntimeUrl, ortWasmPaths, cacheNamespace, storage } = getAssetConfig();
 				this._worker.addEventListener( 'message', handler );
 				this._worker.postMessage( {
 					type: 'load',
@@ -214,6 +214,7 @@ export class AIUpscaler extends EventDispatcher {
 					ortRuntimeUrl,
 					ortWasmPaths,
 					cacheNamespace,
+					storage,
 				} );
 
 			} );

package/src/Passes/OIDNDenoiser.js

@@ -21,6 +21,7 @@ async function getInitUNetFromBuffer() {
 }
 
 import { getAssetConfig } from '../AssetConfig.js';
+import { sharedDownloads, DOWNLOAD_POLICY } from '../Storage/DownloadCache.js';
 
 const MODEL_CONFIG = {
 	// No cleanAux flag in oidn-web, so the blob is it — and it must match what setCleanAuxNormal
@@ -466,12 +467,8 @@ export class OIDNDenoiser extends EventDispatcher {
 		let bytes = this._weights.get( url );
 		if ( ! bytes ) {
 
-			bytes = fetch( url ).then( res => {
-
-				if ( ! res.ok ) throw new Error( `HTTP ${ res.status } fetching ${ url }` );
-				return res.arrayBuffer();
-
-			} );
+			bytes = sharedDownloads().fetch( url, { policy: DOWNLOAD_POLICY.IMMUTABLE } )
+				.then( ( { file, release } ) => file.arrayBuffer().finally( release ) );
 			bytes.catch( () => this._weights.delete( url ) );
 			this._weights.set( url, bytes );
 

package/src/Passes/OIDNTemporalHistory.js

@@ -22,10 +22,11 @@ export const HISTORY_DEFAULTS = Object.freeze( {
 } );
 
 const WG = 8;
-const PARAMS_BYTES = 288;
+const PARAMS_BYTES = 304;
 const MIN_MOVED_CAPACITY = 16;
 const FLAG_CLEAN_AUX = 1;
 const FLAG_SPLIT_COPIES = 2;
+const FLAG_ORTHOGRAPHIC = 4;
 const PICK_MOVED = 0x40000000;
 
 const COMMON_WGSL = /* wgsl */`
@@ -47,6 +48,7 @@ struct Params {
 	prevCamPos: vec4<f32>,
 	moved: vec4<u32>,
 	movedLength: f32,
+	prevCamDir: vec4<f32>,
 };
 
 @group(0) @binding(0) var<uniform> P: Params;
@@ -104,9 +106,19 @@ fn main( @builtin(global_invocation_id) gid: vec3<u32> ) {
 
 		let size = vec2<f32>( P.size );
 		let uv = ( vec2<f32>( gid.xy ) + 0.5 ) / size;
-		let rc = P.projInv * vec4<f32>( uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0, 1.0, 1.0 );
-		let dir = normalize( ( P.camWorld * vec4<f32>( rc.xyz / rc.w, 0.0 ) ).xyz );
-		var wp = P.camWorld[ 3 ].xyz + dir * g.w;
+		// Depth is along the ray: from the camera, or from its image plane when orthographic.
+		let ortho = ( P.flags & ${ FLAG_ORTHOGRAPHIC }u ) != 0u;
+		let ndc = vec2<f32>( uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0 );
+		var origin = P.camWorld[ 3 ].xyz;
+		var dir: vec3<f32>;
+		if ( ortho ) {
+			origin = ( P.camWorld * vec4<f32>( ( P.projInv * vec4<f32>( ndc, 0.0, 1.0 ) ).xy, 0.0, 1.0 ) ).xyz;
+			dir = - normalize( P.camWorld[ 2 ].xyz );
+		} else {
+			let rc = P.projInv * vec4<f32>( ndc, 1.0, 1.0 );
+			dir = normalize( ( P.camWorld * vec4<f32>( rc.xyz / rc.w, 0.0 ) ).xyz );
+		}
+		var wp = origin + dir * g.w;
 		var n = g.xyz * 2.0 - 1.0;
 
 		// A moved object's surface is looked for where the object was.
@@ -132,7 +144,7 @@ fn main( @builtin(global_invocation_id) gid: vec3<u32> ) {
 			let pos = vec2<f32>( clip.x / clip.w * 0.5 + 0.5, 0.5 - clip.y / clip.w * 0.5 ) * size - 0.5;
 			let base = vec2<i32>( floor( pos ) );
 			let f = fract( pos );
-			let expected = length( wp - P.prevCamPos.xyz );
+			let expected = select( length( wp - P.prevCamPos.xyz ), dot( wp - P.prevCamPos.xyz, P.prevCamDir.xyz ), ortho );
 
 			for ( var j = 0; j < 2; j++ ) {
 				for ( var i = 0; i < 2; i++ ) {
@@ -306,6 +318,7 @@ export class OIDNTemporalHistory {
 		this._paramF32 = new Float32Array( this._paramData );
 		this._prevViewProj = new Float32Array( 16 );
 		this._prevCamPos = new Float32Array( 4 );
+		this._prevCamDir = new Float32Array( 4 );
 
 	}
 
@@ -325,7 +338,7 @@ export class OIDNTemporalHistory {
 	/**
 	 * Blends the frame just traced (a restart: one sample) into the reprojected history.
 	 * @param {Object} src - GPUTextures { color, albedo, normal, geo, geoPrev, shading, leaf } and { width, height }
-	 * @param {{ world: Float32Array, projInv: Float32Array, viewProj: Float32Array }} camera - of that frame
+	 * @param {{ world: Float32Array, projInv: Float32Array, viewProj: Float32Array, orthographic: boolean }} camera - of that frame
 	 * @param {?{ count: number, leaves: Uint32Array, toPrev: Float32Array }} [moved] - TLAS leaves
 	 *   (ascending) that moved since the last frame, with each one's current→previous world matrix
 	 */
@@ -524,7 +537,7 @@ export class OIDNTemporalHistory {
 		u[ 0 ] = this.width;
 		u[ 1 ] = this.height;
 		u[ 2 ] = reset ? 1 : 0;
-		u[ 3 ] = ( s.cleanAux ? FLAG_CLEAN_AUX : 0 ) | ( s.splitCopies ? FLAG_SPLIT_COPIES : 0 );
+		u[ 3 ] = ( s.cleanAux ? FLAG_CLEAN_AUX : 0 ) | ( s.splitCopies ? FLAG_SPLIT_COPIES : 0 ) | ( camera.orthographic ? FLAG_ORTHOGRAPHIC : 0 );
 		f[ 4 ] = s.maxLength;
 		f[ 5 ] = s.smoothLength;
 		f[ 6 ] = s.depthTolerance;
@@ -539,6 +552,7 @@ export class OIDNTemporalHistory {
 		f.set( this._prevCamPos, 60 );
 		u[ 64 ] = this._movedCount;
 		f[ 68 ] = s.movedLength;
+		f.set( this._prevCamDir, 72 );
 		this.device.queue.writeBuffer( this._paramsBuffer, 0, this._paramData );
 
 	}
@@ -549,6 +563,10 @@ export class OIDNTemporalHistory {
 		this._prevCamPos[ 0 ] = camera.world[ 12 ];
 		this._prevCamPos[ 1 ] = camera.world[ 13 ];
 		this._prevCamPos[ 2 ] = camera.world[ 14 ];
+		const back = Math.hypot( camera.world[ 8 ], camera.world[ 9 ], camera.world[ 10 ] );
+		this._prevCamDir[ 0 ] = - camera.world[ 8 ] / back;
+		this._prevCamDir[ 1 ] = - camera.world[ 9 ] / back;
+		this._prevCamDir[ 2 ] = - camera.world[ 10 ] / back;
 
 	}