rayzee 9.0.0 → 9.1.1

package/src/Processor/ZipReader.js

@@ -0,0 +1,207 @@
+/**
+ * Reads a .zip in place: the central directory at the end names every entry and where it
+ * starts, so one entry is read and inflated at a time and the archive is never resident.
+ */
+
+import { inflateSync } from 'three/addons/libs/fflate.module.js';
+
+const EOCD = 0x06054b50;
+const ZIP64_LOCATOR = 0x07064b50;
+const ZIP64_EOCD = 0x06064b50;
+const CENTRAL = 0x02014b50;
+const LOCAL = 0x04034b50;
+const EOCD_MAX_SEARCH = 65535 + 22;
+
+const utf8 = new TextDecoder();
+
+async function bytes( blob, start, end ) {
+
+	return new Uint8Array( await blob.slice( start, end ).arrayBuffer() );
+
+}
+
+function u64( view, offset ) {
+
+	return view.getUint32( offset + 4, true ) * 0x100000000 + view.getUint32( offset, true );
+
+}
+
+function latin1( b ) {
+
+	let out = '';
+	for ( let i = 0; i < b.length; i += 8192 ) out += String.fromCharCode( ...b.subarray( i, i + 8192 ) );
+	return out;
+
+}
+
+/**
+ * @param {Blob|File} blob
+ * @returns {Promise<Array<{name:string, size:number, compSize:number, method:number, local:number, encrypted:boolean}>>}
+ */
+export async function readZipDirectory( blob ) {
+
+	const size = blob.size;
+	const tailStart = Math.max( 0, size - EOCD_MAX_SEARCH - 20 );
+	const tail = await bytes( blob, tailStart, size );
+	const tv = new DataView( tail.buffer );
+
+	let eocd = - 1;
+	for ( let i = tail.length - 22; i >= 0; i -- ) {
+
+		if ( tv.getUint32( i, true ) === EOCD ) {
+
+			eocd = i;
+			break;
+
+		}
+
+	}
+
+	if ( eocd < 0 ) throw new Error( 'zip: end of central directory not found' );
+
+	let count = tv.getUint16( eocd + 10, true );
+	let cdSize = tv.getUint32( eocd + 12, true );
+	let cdOffset = tv.getUint32( eocd + 16, true );
+
+	if ( count === 0xffff || cdSize === 0xffffffff || cdOffset === 0xffffffff ) {
+
+		const locator = eocd - 20;
+		if ( locator < 0 || tv.getUint32( locator, true ) !== ZIP64_LOCATOR ) throw new Error( 'zip: ZIP64 locator missing' );
+		const recordOffset = u64( tv, locator + 8 );
+		const record = new DataView( ( await bytes( blob, recordOffset, recordOffset + 56 ) ).buffer );
+		if ( record.getUint32( 0, true ) !== ZIP64_EOCD ) throw new Error( 'zip: ZIP64 end record missing' );
+		count = u64( record, 32 );
+		cdSize = u64( record, 40 );
+		cdOffset = u64( record, 48 );
+
+	}
+
+	const cd = await bytes( blob, cdOffset, cdOffset + cdSize );
+	const v = new DataView( cd.buffer );
+	const entries = [];
+
+	let p = 0;
+	for ( let i = 0; i < count && p + 46 <= cd.length; i ++ ) {
+
+		if ( v.getUint32( p, true ) !== CENTRAL ) throw new Error( 'zip: corrupt central directory' );
+
+		const flags = v.getUint16( p + 8, true );
+		const method = v.getUint16( p + 10, true );
+		let compSize = v.getUint32( p + 20, true );
+		let entrySize = v.getUint32( p + 24, true );
+		const nameLen = v.getUint16( p + 28, true );
+		const extraLen = v.getUint16( p + 30, true );
+		const commentLen = v.getUint16( p + 32, true );
+		let local = v.getUint32( p + 42, true );
+
+		const rawName = cd.subarray( p + 46, p + 46 + nameLen );
+		const name = flags & 0x800 ? utf8.decode( rawName ) : latin1( rawName );
+
+		// ZIP64 extra field: only the saturated 32-bit fields are present, in this order.
+		for ( let e = p + 46 + nameLen, end = e + extraLen; e + 4 <= end; ) {
+
+			const id = v.getUint16( e, true );
+			const len = v.getUint16( e + 2, true );
+			if ( id === 0x0001 ) {
+
+				let q = e + 4;
+				if ( entrySize === 0xffffffff ) {
+
+					entrySize = u64( v, q );
+					q += 8;
+
+				}
+
+				if ( compSize === 0xffffffff ) {
+
+					compSize = u64( v, q );
+					q += 8;
+
+				}
+
+				if ( local === 0xffffffff ) local = u64( v, q );
+
+			}
+
+			e += 4 + len;
+
+		}
+
+		if ( ! name.endsWith( '/' ) ) entries.push( { name, size: entrySize, compSize, method, local, encrypted: ( flags & 1 ) !== 0 } );
+		p += 46 + nameLen + extraLen + commentLen;
+
+	}
+
+	return entries;
+
+}
+
+async function dataStart( blob, entry ) {
+
+	if ( entry.encrypted ) throw new Error( `zip: "${entry.name}" is encrypted` );
+
+	const head = new DataView( ( await bytes( blob, entry.local, entry.local + 30 ) ).buffer );
+	if ( head.getUint32( 0, true ) !== LOCAL ) throw new Error( `zip: bad local header for "${entry.name}"` );
+	return entry.local + 30 + head.getUint16( 26, true ) + head.getUint16( 28, true );
+
+}
+
+async function readEntry( blob, entry ) {
+
+	const start = await dataStart( blob, entry );
+	const raw = await bytes( blob, start, start + entry.compSize );
+
+	if ( entry.method === 0 ) return raw;
+	if ( entry.method === 8 ) return entry.size === 0 ? new Uint8Array( 0 ) : inflateSync( raw, { out: new Uint8Array( entry.size ) } );
+	throw new Error( `zip: "${entry.name}" uses compression method ${entry.method}, which is not supported` );
+
+}
+
+/**
+ * Same shape as `openTar`: `listing` holds every entry, with an `offset` on those `filter` keeps,
+ * and `read( path )` inflates one on demand; `slice( path )` gives it as a Blob. Paths are the archive's own, as fflate's unzipSync keys them.
+ * @param {Blob|File} blob
+ * @param {{filter?: (path:string, size:number) => boolean}} [options]
+ */
+export async function openZip( blob, { filter = null } = {} ) {
+
+	const directory = await readZipDirectory( blob );
+	const byPath = new Map();
+
+	const listing = directory.map( e => {
+
+		if ( filter && ! filter( e.name, e.size ) ) return { path: e.name, size: e.size };
+		byPath.set( e.name, e );
+		return { path: e.name, size: e.size, offset: e.local };
+
+	} );
+
+	const read = async ( path ) => {
+
+		const entry = byPath.get( path );
+		return entry ? readEntry( blob, entry ) : null;
+
+	};
+
+	// A stored entry is a slice of the archive itself, so a large one never passes through memory.
+	const slice = async ( path ) => {
+
+		const entry = byPath.get( path );
+		if ( ! entry ) return null;
+		if ( entry.method !== 0 ) return new Blob( [ await readEntry( blob, entry ) ] );
+		const start = await dataStart( blob, entry );
+		return blob.slice( start, start + entry.compSize );
+
+	};
+
+	// A stored entry's head is a slice; a deflated one is inflated whole, as a read would.
+	const readHead = async ( path, bytes ) => {
+
+		const part = await slice( path );
+		return part ? new Uint8Array( await part.slice( 0, bytes ).arrayBuffer() ) : null;
+
+	};
+
+	return { entries: Object.create( null ), listing, read, readHead, slice, retainedBytes: 0, truncated: false, indexed: byPath.size };
+
+}

package/src/RenderSettings.js

@@ -2,6 +2,7 @@ import { EventDispatcher, Color, Vector2, MathUtils } from 'three';
 import { ENGINE_DEFAULTS, CAMERA_PROJECTION_IDS } from './EngineDefaults.js';
 import { EngineEvents } from './EngineEvents.js';
 import { ISSUE_CODES } from './EngineIssues.js';
+import { toPortable, fromPortable } from './SceneState/portable.js';
 
 /**
  * Routing table: maps each setting key to its target stage/handler.
@@ -424,6 +425,43 @@ export class RenderSettings extends EventDispatcher {
 
 	}
 
+	/** The settings a host set, as portable values (see SceneState/portable.js): what a session restores. */
+	serialize() {
+
+		const out = {};
+		for ( const [ key, value ] of this._values ) {
+
+			if ( this._sources.get( key ) !== SETTING_SOURCE.HOST || ! SETTING_ROUTES[ key ] ) continue;
+			const portable = toPortable( value );
+			if ( portable !== undefined ) out[ key ] = portable;
+
+		}
+
+		return out;
+
+	}
+
+	/**
+	 * Applies {@link serialize}'s values as host settings, once reset at the end. Keys this engine
+	 * no longer routes are left out rather than recorded as unknown.
+	 * @returns {string[]} the keys left out
+	 */
+	restore( values ) {
+
+		const known = {};
+		const unknown = [];
+		for ( const [ key, value ] of Object.entries( values ?? {} ) ) {
+
+			if ( SETTING_ROUTES[ key ] ) known[ key ] = fromPortable( value );
+			else unknown.push( key );
+
+		}
+
+		this.setMany( known );
+		return unknown;
+
+	}
+
 	/**
 	 * Pushes all stored values to their target stages.
 	 * Called after loadSceneData() to ensure GPU uniforms match stored values.

package/src/SceneState/SceneState.js

@@ -0,0 +1,367 @@
+/**
+ * A scene's state after it loaded: everything a host or user changed, as plain data. Saved
+ * sessions and project files carry it; the model itself is the host's to reload first.
+ *
+ * Objects, materials and cameras are matched by position in this load plus a name check, never by
+ * UUID — those change on every load.
+ */
+
+import { VERSION } from '../version.js';
+import { fromPortable } from './portable.js';
+
+export const SCENE_STATE_VERSION = 1;
+
+const isUrl = source => typeof source === 'string' && /^https?:\/\//.test( source );
+
+function pathOf( object, root ) {
+
+	const path = [];
+	while ( object && object !== root ) {
+
+		const parent = object.parent;
+		if ( ! parent ) return null;
+		path.unshift( parent.children.indexOf( object ) );
+		object = parent;
+
+	}
+
+	return object === root ? path : null;
+
+}
+
+function objectAt( root, path ) {
+
+	let object = root;
+	for ( const index of path ) {
+
+		object = object?.children[ index ];
+		if ( ! object ) return null;
+
+	}
+
+	return object;
+
+}
+
+function signature( app ) {
+
+	return {
+		key: app.assetLoader?.sceneSourceKey ?? null,
+		name: app.sceneModel?.name ?? null,
+		meshes: app.sceneMeshes.length,
+		materials: app.stages.pathTracer?.materialData.materialCount ?? 0,
+	};
+
+}
+
+function materialsByIndex( app ) {
+
+	const out = new Map();
+	for ( const mesh of app.sceneMeshes ) {
+
+		const index = mesh.userData?.materialIndex;
+		if ( index !== undefined && ! out.has( index ) ) out.set( index, Array.isArray( mesh.material ) ? mesh.material[ 0 ] : mesh.material );
+
+	}
+
+	return out;
+
+}
+
+function colorState( cm ) {
+
+	if ( ! cm ) return null;
+	const status = cm.status();
+	const view = status.activeView;
+	const configId = status.config?.id ?? view?.configId ?? null;
+
+	return {
+		config: configId ? { id: configId } : null,
+		view: view ? { display: view.display, view: view.view, look: view.look ?? null } : null,
+		transform: view ? null : status.activeTransform?.id ?? null,
+		workingSpace: status.workingSpaceAdopted ? status.workingSpace : null,
+		context: status.context ?? null,
+	};
+
+}
+
+/**
+ * @param {import('../PathTracerApp.js').PathTracerApp} app
+ * @returns {Object} JSON-safe
+ */
+export function captureSceneState( app ) {
+
+	const root = app.meshScene;
+	const materials = materialsByIndex( app );
+
+	const hidden = [];
+	root.traverse( object => {
+
+		if ( object !== root && object.visible === false ) hidden.push( pathOf( object, root ) );
+
+	} );
+
+	return {
+		v: SCENE_STATE_VERSION,
+		engine: VERSION,
+		savedAt: Date.now(),
+		scene: signature( app ),
+		appended: root.children
+			.filter( c => c !== app.sceneModel && c.userData?.__rayzeeSceneObject )
+			.map( c => ( { name: c.userData.__rayzeeName ?? c.name, url: c.userData.__rayzeeSourceUrl ?? null, cacheKey: c.userData.__rayzeeCacheKey ?? null } ) ),
+		settings: app.settings.serialize(),
+		environment: app.environmentManager?.serialize() ?? null,
+		color: colorState( app.color ),
+		lights: app.lightManager.serialize(),
+		cameras: app.cameraManager.serialize(),
+		timeline: app.timeline?.serialize() ?? null,
+		materials: ( app.stages.pathTracer?.materialData.serializeHostEdits() ?? [] ).map( edit => ( { ...edit, name: materials.get( edit.index )?.name ?? '' } ) ),
+		hidden,
+		moved: ( app.transformManager?.movedObjects ?? [] ).map( object => ( {
+			path: pathOf( object, root ),
+			name: object.name,
+			position: object.position.toArray(),
+			quaternion: object.quaternion.toArray(),
+			scale: object.scale.toArray(),
+		} ) ).filter( m => m.path ),
+	};
+
+}
+
+function applyMaterialValue( material, property, value ) {
+
+	const current = material[ property ];
+	if ( current?.copy && ( value?.isColor || value?.isVector2 || value?.isVector3 ) ) current.copy( value );
+	else material[ property ] = value;
+	material.needsUpdate = true;
+
+}
+
+async function restoreEnvironment( app, env, resolve, skip ) {
+
+	if ( ! env ) return;
+	const manager = app.environmentManager;
+
+	if ( env.hdri && env.hdri !== manager.hdriSource ) {
+
+		const input = isUrl( env.hdri ) ? env.hdri : await resolve( { kind: 'environment', source: env.hdri } );
+		try {
+
+			if ( typeof input === 'string' ) await app.loadEnvironment( input );
+			else if ( input ) await app.loadFile( input );
+			else skip( 'environment', 'source unavailable', { source: env.hdri } );
+
+		} catch ( error ) {
+
+			skip( 'environment', error.message, { source: env.hdri } );
+
+		}
+
+	}
+
+	await manager.restore( env );
+
+}
+
+async function restoreColor( app, color, resolve, skip ) {
+
+	const cm = app.color;
+	if ( ! color || ! cm ) return;
+
+	const status = cm.status();
+	const active = status.activeView;
+	const sameView = !! color.view && !! active
+		&& active.display === color.view.display && active.view === color.view.view && ( active.look ?? null ) === color.view.look;
+	const loadedId = status.config?.id ?? null;
+	const shownId = loadedId ?? active?.configId ?? null;
+	const settled = ( color.config?.id ?? null ) === shownId && ! color.workingSpace && ! color.context
+		&& ( color.view ? sameView : ! active && ( ! color.transform || color.transform === status.activeTransform?.id ) );
+	if ( settled ) return;
+
+	try {
+
+		if ( color.config && color.config.id !== loadedId ) {
+
+			if ( ! await resolve( { kind: 'colorConfig', config: color.config } ) ) {
+
+				const builtins = await cm.constructor.listBuiltinConfigs().catch( () => [] );
+				const known = builtins.some( b => ( b.name ?? b ) === color.config.id || `ocio://${b.name ?? b}` === color.config.id );
+				if ( ! known ) {
+
+					skip( 'color', 'config unavailable', { config: color.config.id } );
+					return;
+
+				}
+
+				await app.loadColorConfig( { builtin: color.config.id, registerViews: false } );
+
+			}
+
+		} else if ( ! color.config && loadedId ) {
+
+			await app.unloadColorConfig();
+
+		}
+
+		if ( color.context ) cm.setContext( color.context );
+		if ( color.view ) cm.setView( color.view );
+		else if ( color.transform ) cm.setActiveView( color.transform );
+
+		if ( ( color.workingSpace ?? null ) !== ( cm.workingSpaceAdopted ? cm.workingSpace : null ) ) {
+
+			cm.setWorkingSpace( color.workingSpace );
+			await app.applyColorWorkingSpace();
+
+		}
+
+	} catch ( error ) {
+
+		skip( 'color', error.message, { config: color.config?.id ?? null } );
+
+	}
+
+}
+
+/**
+ * Applies a captured state to the scene now loaded. Call once the model has loaded.
+ *
+ * @param {import('../PathTracerApp.js').PathTracerApp} app
+ * @param {Object} state - from {@link captureSceneState}
+ * @param {Object} [options]
+ * @param {function(Object): Promise<*>} [options.resolve] - the host's answer for an input the
+ *   engine cannot reach itself: `{ kind: 'environment', source }` → a File, a URL or null;
+ *   `{ kind: 'colorConfig', config }` → true once the host has loaded it
+ * @returns {Promise<{skipped: Array<{section: string, reason: string}>}>} what could not be put back
+ */
+export async function applySceneState( app, state, { resolve = async () => null } = {} ) {
+
+	if ( state?.v !== SCENE_STATE_VERSION ) throw new Error( `scene state version ${state?.v} is not ${SCENE_STATE_VERSION}` );
+
+	const skipped = [];
+	const skip = ( section, reason, detail = {} ) => skipped.push( { section, reason, ...detail } );
+
+	for ( const model of state.appended ?? [] ) {
+
+		if ( ! model.url ) {
+
+			skip( 'appended', 'added from memory, not a file', { name: model.name } );
+			continue;
+
+		}
+
+		try {
+
+			await app.addModel( model.url, { name: model.name, cacheKey: model.cacheKey ?? undefined } );
+
+		} catch ( error ) {
+
+			skip( 'appended', error.message, { name: model.name } );
+
+		}
+
+	}
+
+	const now = signature( app );
+	const saved = state.scene ?? {};
+	const sameScene = saved.meshes === now.meshes && saved.materials === now.materials;
+	if ( ! sameScene ) skip( 'scene', 'the loaded scene is not the one saved: objects and materials left as loaded', { saved, now } );
+
+	await restoreEnvironment( app, state.environment, resolve, skip );
+	await restoreColor( app, state.color, resolve, skip );
+
+	const unknown = app.settings.restore( state.settings );
+	if ( unknown.length ) skip( 'settings', 'not settings in this engine', { keys: unknown } );
+
+	const lights = app.lightManager.restore( state.lights );
+	for ( const light of lights ) {
+
+		const { gobo, ies } = light.userData;
+		if ( gobo && app.goboManager?.entries?.length ) app.goboManager.setLightGobo( light.uuid, gobo.name, gobo );
+		if ( ies && app.iesManager?.entries?.length ) app.iesManager.setSpotLightProfile( light.uuid, ies.name, ies.intensity, { applyAutoCone: false } );
+
+	}
+
+	if ( sameScene ) {
+
+		const materials = materialsByIndex( app );
+		for ( const edit of state.materials ?? [] ) {
+
+			const material = materials.get( edit.index );
+			if ( ! material || ( material.name ?? '' ) !== edit.name ) {
+
+				skip( 'materials', 'no such material', { index: edit.index, name: edit.name } );
+				continue;
+
+			}
+
+			for ( const [ property, portable ] of Object.entries( edit.props ) ) {
+
+				const value = fromPortable( portable );
+				applyMaterialValue( material, property, value );
+				app.setMaterialProperty( edit.index, property, value );
+
+			}
+
+		}
+
+		const root = app.meshScene;
+		const hidden = new Set( ( state.hidden ?? [] ).map( path => objectAt( root, path ) ).filter( Boolean ) );
+		root.traverse( object => {
+
+			if ( object !== root && ! object.isLight ) object.visible = ! hidden.has( object );
+
+		} );
+		app.updateAllMeshVisibility();
+
+		const moved = [];
+		for ( const entry of state.moved ?? [] ) {
+
+			const object = objectAt( root, entry.path );
+			if ( ! object || object.name !== entry.name ) {
+
+				skip( 'moved', 'no such object', { name: entry.name } );
+				continue;
+
+			}
+
+			object.position.fromArray( entry.position );
+			object.quaternion.fromArray( entry.quaternion );
+			object.scale.fromArray( entry.scale );
+			object.updateMatrixWorld( true );
+			app.transformManager?.noteMoved( object );
+			moved.push( object );
+
+		}
+
+		if ( moved.length ) {
+
+			const affected = [];
+			app.sceneMeshes.forEach( ( mesh, index ) => {
+
+				for ( let o = mesh; o; o = o.parent ) {
+
+					if ( moved.includes( o ) ) {
+
+						affected.push( index );
+						break;
+
+					}
+
+				}
+
+			} );
+			if ( affected.length ) app.updateMeshTransforms( affected );
+
+		}
+
+	}
+
+	const { mismatched } = app.cameraManager.restore( state.cameras );
+	if ( mismatched.length ) skip( 'cameras', 'model cameras changed', { names: mismatched } );
+	app._dispatchCamerasUpdated();
+	app.timeline?.restore( state.timeline );
+
+	app.reset();
+	return { skipped };
+
+}

package/src/SceneState/portable.js

@@ -0,0 +1,52 @@
+import { Color, Quaternion, Vector2, Vector3, Vector4 } from 'three';
+
+/**
+ * JSON-safe copies of setting and material values: colours, vectors and non-finite numbers are
+ * tagged so {@link fromPortable} gives back the same types. Anything else that is not plain data
+ * comes back undefined, so a caller can leave it out.
+ */
+export function toPortable( value ) {
+
+	if ( value === null || typeof value === 'boolean' || typeof value === 'string' ) return value;
+	if ( typeof value === 'number' ) return Number.isFinite( value ) ? value : { $num: String( value ) };
+	if ( typeof value !== 'object' ) return undefined;
+	if ( value.isColor ) return { $color: [ value.r, value.g, value.b ] };
+	if ( value.isQuaternion ) return { $quat: [ value.x, value.y, value.z, value.w ] };
+	if ( value.isVector2 || value.isVector3 || value.isVector4 ) return { $vec: value.toArray() };
+	if ( ArrayBuffer.isView( value ) ) return Array.from( value );
+	if ( Array.isArray( value ) ) return value.map( v => toPortable( v ) ?? null );
+
+	const proto = Object.getPrototypeOf( value );
+	if ( proto !== Object.prototype && proto !== null ) return undefined;
+
+	const out = {};
+	for ( const [ key, v ] of Object.entries( value ) ) {
+
+		const p = toPortable( v );
+		if ( p !== undefined ) out[ key ] = p;
+
+	}
+
+	return out;
+
+}
+
+export function fromPortable( value ) {
+
+	if ( value === null || typeof value !== 'object' ) return value;
+	if ( Array.isArray( value ) ) return value.map( fromPortable );
+	if ( '$num' in value ) return Number( value.$num );
+	if ( value.$color ) return new Color( ...value.$color );
+	if ( value.$quat ) return new Quaternion( ...value.$quat );
+	if ( value.$vec ) {
+
+		const Vector = [ null, null, Vector2, Vector3, Vector4 ][ value.$vec.length ];
+		return new Vector( ...value.$vec );
+
+	}
+
+	const out = {};
+	for ( const [ key, v ] of Object.entries( value ) ) out[ key ] = fromPortable( v );
+	return out;
+
+}