rayzee 7.25.0 → 7.26.1

package/src/Processor/AssetLoader.js

@@ -1,4 +1,4 @@
-import { Box3, Vector3, RectAreaLight, Color, FloatType, LinearFilter, EquirectangularReflectionMapping,
+import { Box3, BufferGeometry, Vector3, RectAreaLight, Color, FloatType, LinearFilter, EquirectangularReflectionMapping,
 	TextureLoader, Texture, SRGBColorSpace, RepeatWrapping, Mesh, MeshStandardMaterial, MeshPhysicalMaterial,
 	CircleGeometry, Points, PointsMaterial, LoadingManager, EventDispatcher
 } from 'three';
@@ -8,12 +8,14 @@ import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
 import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
 import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';
 import { createMeshesFromMultiMaterialMesh } from 'three/addons/utils/SceneUtils.js';
+import { clone as cloneWithSkeletons } from 'three/addons/utils/SkeletonUtils.js';
 import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
 import { unzipSync, zipSync, strFromU8 } from 'three/addons/libs/fflate.module.js';
-import { disposeObjectFromMemory, updateLoading } from './utils';
+import { disposeEngineOwnedResources, disposeObjectFromMemory, updateLoading } from './utils';
 import { BuildTimer } from './BuildTimer.js';
 import { getAssetConfig } from '../AssetConfig.js';
 import { loadPBRTScene, pickEntryPath } from './PBRT/index.js';
+import { extractSceneMetadata } from './SceneMetadata.js';
 
 // Define supported file formats
 const SUPPORTED_FORMATS = {
@@ -35,6 +37,18 @@ const SUPPORTED_FORMATS = {
 // layers and the image assets they reference.
 const USD_LAYER_RE = /\.(usd|usda|usdc)$/i;
 const USD_IMAGE_RE = /\.(png|jpg|jpeg|avif)$/i;
+// A throwaway stand-in for a geometry the engine must not mutate: the split's mergeGroups()
+// reorders and disposes what it is given, but never writes the attributes.
+function standInForSplit( source ) {
+
+	const geometry = new BufferGeometry();
+	for ( const name in source.attributes ) geometry.setAttribute( name, source.attributes[ name ] );
+	if ( source.index ) geometry.setIndex( source.index );
+	for ( const group of source.groups ) geometry.addGroup( group.start, group.count, group.materialIndex );
+	return geometry;
+
+}
+
 /**
  * AssetLoader class - handles loading of 3D models, environment maps, and archives
  */
@@ -47,7 +61,6 @@ export class AssetLoader extends EventDispatcher {
 		this.camera = camera;
 		this.controls = controls;
 		this.targetModel = null;
-		this._externalModel = null;
 		this.floorPlane = null;
 		this.sceneScale = 1.0;
 		this.loaderCache = {};
@@ -55,6 +68,10 @@ export class AssetLoader extends EventDispatcher {
 		this.animations = [];
 		this.renderer = null;
 
+		// Scene-level authoring metadata from the current model (glTF `extras`), or null.
+		// See SceneMetadata.js. Cleared by releaseTargetModel() on every replace-load.
+		this.sceneMetadata = null;
+
 		// Shared across every loader so cancelActiveLoad() can abort whichever
 		// fetch is in flight (three r185 FileLoader wires the manager's abort
 		// signal into its fetch). One load runs at a time (guarded upstream).
@@ -127,27 +144,58 @@ export class AssetLoader extends EventDispatcher {
 	}
 
 	/**
-	 * Releases the current targetModel. If it was supplied by the caller via
-	 * loadObject3D(), we only detach it from its parent — the caller still owns
-	 * that Object3D and may reuse it. Otherwise we disposeObjectFromMemory() to
-	 * free geometry/material/texture GPU resources.
+	 * Deep-clones a caller-owned Object3D so the engine never mutates the host's tree.
+	 * Geometry/material/texture ride along by reference, so release frees only what the engine
+	 * allocated — see removeModelRoot().
+	 *
+	 * @param {import('three').Object3D} object3d - the caller's object; left untouched.
+	 * @returns {import('three').Object3D} the engine-owned copy.
 	 */
-	releaseTargetModel() {
+	_adoptExternalObject( object3d ) {
 
-		if ( ! this.targetModel ) return;
+		// Not Object3D.clone(): that leaves SkinnedMeshes bound to the source's bones.
+		let model;
+		try {
 
-		if ( this.targetModel === this._externalModel ) {
+			model = cloneWithSkeletons( object3d );
 
-			this.targetModel.parent?.remove( this.targetModel );
+		} catch ( error ) {
 
-		} else {
+			// Object3D.copy() round-trips userData through JSON, so a back-reference throws.
+			throw new Error(
+				`Cannot render "${object3d.name || object3d.type}": its userData must be JSON-serializable.`,
+				{ cause: error }
+			);
+
+		}
+
+		model.userData.__rayzeeExternal = true;
+
+		// Carried through as the scene-object id, unless a second copy already took it.
+		if ( ! this.scene?.children.some( c => c.uuid === object3d.uuid ) ) model.uuid = object3d.uuid;
 
-			disposeObjectFromMemory( this.targetModel );
+		// The copy sits under the engine's identity root, which keeps only a local transform.
+		if ( object3d.parent ) {
+
+			object3d.parent.updateWorldMatrix( true, false );
+			model.applyMatrix4( object3d.parent.matrixWorld );
 
 		}
 
+		return model;
+
+	}
+
+	/** Releases the current targetModel. See removeModelRoot() for what gets freed. */
+	releaseTargetModel() {
+
+		this.sceneMetadata = null;
+
+		if ( ! this.targetModel ) return;
+
+		this.removeModelRoot( this.targetModel );
+
 		this.targetModel = null;
-		this._externalModel = null;
 		// Drop the released model's animation clips so a later rebuild doesn't rebind
 		// a mixer to disposed nodes. Every load path re-populates this.animations after.
 		this.animations = [];
@@ -298,7 +346,7 @@ export class AssetLoader extends EventDispatcher {
 			texture.generateMipmaps = true;
 
 			this.applyEnvironmentToScene( texture );
-			this.dispatchEvent( { type: 'load', texture } );
+			this.dispatchEvent( { type: 'load', texture, url: envUrl, filename: envUrl.split( /[?#]/ )[ 0 ].split( '/' ).pop() } );
 			return texture;
 
 		} catch ( error ) {
@@ -804,6 +852,7 @@ export class AssetLoader extends EventDispatcher {
 
 							this.releaseTargetModel();
 							this.targetModel = gltf.scene;
+							this.sceneMetadata = extractSceneMetadata( gltf );
 							this.onModelLoad( this.targetModel ).then( () => resolve( gltf ) );
 
 						},
@@ -1104,6 +1153,7 @@ export class AssetLoader extends EventDispatcher {
 
 			this.targetModel = data.scene;
 			this.animations = data.animations || [];
+			this.sceneMetadata = extractSceneMetadata( data );
 			await this.onModelLoad( this.targetModel );
 			this.dispatchEvent( { type: 'load', model: data.scene, filename: modelUrl.split( '/' ).pop() } );
 			return data;
@@ -1171,21 +1221,32 @@ export class AssetLoader extends EventDispatcher {
 
 	}
 
-	// Append a caller-owned Object3D without releasing prior models or reframing.
+	// Append a copy of a caller-owned Object3D without releasing prior models or reframing.
 	appendObject3D( object3d, name = 'object3d' ) {
 
-		object3d.name = object3d.name || name;
-		this._processAndParent( object3d );
-		return { root: object3d };
+		const root = this._adoptExternalObject( object3d );
+		root.name = object3d.name || name;
+		this._processAndParent( root );
+		return { root };
 
 	}
 
-	// Detach + dispose an appended root. External (caller-owned) roots are only detached.
-	removeModelRoot( root, { external = false } = {} ) {
+	// Detach + dispose a model root. An adopted root's geometry/materials belong to the
+	// caller, so only the engine's own allocations go.
+	removeModelRoot( root ) {
 
 		if ( ! root ) return;
-		if ( external ) root.parent?.remove( root );
-		else disposeObjectFromMemory( root );
+
+		if ( root.userData.__rayzeeExternal ) {
+
+			disposeEngineOwnedResources( root );
+			root.parent?.remove( root );
+
+		} else {
+
+			disposeObjectFromMemory( root );
+
+		}
 
 	}
 
@@ -1204,6 +1265,7 @@ export class AssetLoader extends EventDispatcher {
 
 			this.targetModel = data.scene;
 			this.animations = data.animations || [];
+			this.sceneMetadata = extractSceneMetadata( data );
 			updateLoading( { isLoading: true, status: "Processing Data...", progress: 10 } );
 			await this.onModelLoad( this.targetModel );
 
@@ -1500,17 +1562,18 @@ export class AssetLoader extends EventDispatcher {
 
 	async loadObject3D( object3d, name = 'object3d' ) {
 
-		object3d.name = object3d.name || name;
-
 		this.releaseTargetModel();
-		this.targetModel = object3d;
-		this._externalModel = object3d;
+
+		const model = this._adoptExternalObject( object3d );
+		model.name = object3d.name || name;
+
+		this.targetModel = model;
 
 		updateLoading( { isLoading: true, status: "Processing Data...", progress: 10 } );
 		await this.onModelLoad( this.targetModel );
 
-		this.dispatchEvent( { type: 'load', model: object3d, filename: name } );
-		return object3d;
+		this.dispatchEvent( { type: 'load', model, filename: name } );
+		return model;
 
 	}
 
@@ -1646,6 +1709,9 @@ export class AssetLoader extends EventDispatcher {
 	processModelObjects( model ) {
 
 		let visitedAreaLights = [];
+		// Split after the walk: traverse() caches children.length, so splitting in place
+		// shifts later siblings down a slot and skips one.
+		const multiMaterialMeshes = [];
 		model.traverse( ( object ) => {
 
 			const userData = object.userData;
@@ -1699,19 +1765,29 @@ export class AssetLoader extends EventDispatcher {
 			// Handle multi-material meshes
 			if ( object.isMesh && Array.isArray( object.material ) ) {
 
-				console.log( 'Found multi-material mesh:', object.name );
-				const group = createMeshesFromMultiMaterialMesh( object );
+				multiMaterialMeshes.push( object );
 
-				if ( object.parent ) {
+			}
 
-					object.parent.add( group );
-					object.parent.remove( object );
+		} );
 
-				}
+		const shared = model.userData.__rayzeeExternal === true;
 
-			}
+		for ( const object of multiMaterialMeshes ) {
 
-		} );
+			if ( ! object.parent ) continue;
+
+			console.log( 'Found multi-material mesh:', object.name );
+			if ( shared ) object.geometry = standInForSplit( object.geometry );
+
+			const group = createMeshesFromMultiMaterialMesh( object );
+			// Fresh geometry per group; tag it so an adopted model's release can free it.
+			for ( const child of group.children ) child.geometry.userData.__rayzeeOwned = true;
+
+			object.parent.add( group );
+			object.parent.remove( object );
+
+		}
 
 	}
 

package/src/Processor/SceneMetadata.js

@@ -0,0 +1,123 @@
+/**
+ * SceneMetadata.js
+ * Scene-level authoring metadata carried inside an asset file.
+ *
+ * glTF/GLB carries it in `extras`, which three's GLTFLoader surfaces in three
+ * places depending on where the exporter wrote it: top-level `extras` becomes
+ * `gltf.userData`, `asset.extras` stays on `gltf.asset.extras`, and a scene's
+ * `extras` becomes `gltf.scene.userData`. All three are scanned, and the payload
+ * may sit at the root or be namespaced under a `rayzee` key.
+ *
+ * Recognised payload:
+ *   {
+ *     "environment": {
+ *       "sourceFile": "https://.../brown_photostudio_02_1k.hdr",
+ *       "rotation": 0,      // degrees around Y, matches the environmentRotation setting
+ *       "intensity": 1      // drives both environmentIntensity and backgroundIntensity
+ *     }
+ *   }
+ *
+ * Values may also arrive as JSON strings — DCC custom-property round-trips often
+ * stringify nested objects — so every container is parsed leniently.
+ */
+
+const ENV_URL_KEYS = [ 'sourceFile', 'url', 'file' ];
+
+function asObject( value ) {
+
+	if ( typeof value === 'string' ) {
+
+		try {
+
+			const parsed = JSON.parse( value );
+			return ( parsed && typeof parsed === 'object' ) ? parsed : null;
+
+		} catch {
+
+			return null;
+
+		}
+
+	}
+
+	return ( value && typeof value === 'object' ) ? value : null;
+
+}
+
+function asNumber( value ) {
+
+	const n = typeof value === 'string' ? parseFloat( value ) : value;
+	return Number.isFinite( n ) ? n : undefined;
+
+}
+
+function pickPayload( container ) {
+
+	const obj = asObject( container );
+	if ( ! obj ) return null;
+
+	const scoped = asObject( obj.rayzee );
+	if ( scoped && scoped.environment !== undefined ) return scoped;
+
+	return obj.environment !== undefined ? obj : null;
+
+}
+
+function normalizeEnvironment( raw ) {
+
+	const env = asObject( raw );
+	if ( ! env ) return null;
+
+	const sourceFile = ENV_URL_KEYS
+		.map( key => env[ key ] )
+		.find( value => typeof value === 'string' && value.trim() );
+	if ( ! sourceFile ) return null;
+
+	const rotation = asNumber( env.rotation );
+	const intensity = asNumber( env.intensity );
+
+	const normalized = { sourceFile: sourceFile.trim() };
+	if ( rotation !== undefined ) normalized.rotation = rotation;
+	if ( intensity !== undefined ) normalized.intensity = Math.max( 0, intensity );
+
+	return normalized;
+
+}
+
+/**
+ * Reads scene metadata out of one `extras`-shaped container.
+ * @param {Object|string|null} container
+ * @returns {{ environment?: { sourceFile: string, rotation?: number, intensity?: number } }|null}
+ */
+export function parseSceneMetadata( container ) {
+
+	const payload = pickPayload( container );
+	if ( ! payload ) return null;
+
+	const environment = normalizeEnvironment( payload.environment );
+	return environment ? { environment } : null;
+
+}
+
+/**
+ * Reads scene metadata out of a GLTFLoader parse result.
+ * @param {Object} gltf - The object GLTFLoader resolves with
+ * @returns {{ environment?: { sourceFile: string, rotation?: number, intensity?: number } }|null}
+ */
+export function extractSceneMetadata( gltf ) {
+
+	if ( ! gltf ) return null;
+
+	const containers = [ gltf.userData, gltf.asset?.extras, gltf.scene?.userData ];
+	if ( Array.isArray( gltf.scenes ) ) containers.push( ...gltf.scenes.map( scene => scene?.userData ) );
+
+	for ( const container of containers ) {
+
+		const metadata = parseSceneMetadata( container );
+		if ( metadata ) return metadata;
+
+	}
+
+	return null;
+
+}

package/src/Processor/utils.js

@@ -177,6 +177,17 @@ export function disposeObjectFromMemory( object, exeptions = [] ) {
 
 }
 
+/** Frees only geometry the engine allocated inside an adopted model; the rest is the host's. */
+export function disposeEngineOwnedResources( object ) {
+
+	object?.traverse( ( child ) => {
+
+		if ( child.geometry?.userData?.__rayzeeOwned ) child.geometry.dispose();
+
+	} );
+
+}
+
 
 
 /**

package/src/index.js

@@ -17,6 +17,9 @@ export { EngineEvents } from './EngineEvents.js';
 // Asset URL / cache namespace overrides (call before constructing PathTracerApp)
 export { configureAssets, getAssetConfig } from './AssetConfig.js';
 
+// Scene-level authoring metadata embedded in model files (glTF `extras`)
+export { extractSceneMetadata, parseSceneMetadata } from './Processor/SceneMetadata.js';
+
 // Logging — leveled/namespaced console output shared with the workers
 export { Logger, createLogger, fmt, LOG_LEVELS } from './utils/Logger.js';
 

package/src/managers/EnvironmentManager.js

@@ -360,8 +360,11 @@ export class EnvironmentManager {
 	/**
 	 * Set environment map, build CDF, and update shader texture nodes.
 	 * @param {import('three').Texture|null} envMap
+	 * @param {Object}  [options]
+	 * @param {boolean} [options.buildCDF=true] - Skip when the caller builds the CDF itself
+	 *   (PathTracerApp.loadSceneData builds it in parallel with the BVH, then calls applyCDFResults).
 	 */
-	async setEnvironmentMap( envMap ) {
+	async setEnvironmentMap( envMap, { buildCDF = true } = {} ) {
 
 		// Free the outgoing env texture's GPU memory before it is orphaned. Skip: the
 		// reusable placeholder, an idempotent re-set of the same texture, and the HDRI
@@ -379,7 +382,7 @@ export class EnvironmentManager {
 
 		if ( envMap ) {
 
-			await this.buildEnvironmentCDF();
+			if ( buildCDF ) await this.buildEnvironmentCDF();
 
 		} else {
 
@@ -411,6 +414,35 @@ export class EnvironmentManager {
 
 	}
 
+	/**
+	 * Enter 'hdri' mode ahead of an async HDRI install, and drop the texture stashed by a
+	 * previous setMode( 'gradient' | 'color' | 'procedural' ): a new HDRI makes it
+	 * unreachable, so leaving it in place both leaks it and lets a setMode( 'hdri' )
+	 * arriving mid-download restore it over the map we are about to install.
+	 * @param {import('three').Texture} [incoming] - Never disposed, even if it is the stash.
+	 */
+	beginHDRI( incoming = null ) {
+
+		if ( this._previousHDRI && this._previousHDRI !== incoming ) this._previousHDRI.dispose?.();
+
+		this._previousHDRI = null;
+		this.envParams.mode = 'hdri';
+
+	}
+
+	/**
+	 * Install an HDRI as the active environment, switching the mode state machine to 'hdri'.
+	 * @param {import('three').Texture} envMap
+	 * @param {Object}  [options]
+	 * @param {boolean} [options.buildCDF=true]
+	 */
+	async applyHDRI( envMap, { buildCDF = true } = {} ) {
+
+		this.beginHDRI( envMap );
+		await this.setEnvironmentMap( envMap, { buildCDF } );
+
+	}
+
 	// ===== SKY GENERATORS =====
 
 	/**