@preference-sl/pref-viewer 2.13.0-beta.0 → 2.13.0-beta.2

package/src/babylonjs-controller.js

@@ -8,101 +8,71 @@ import JSZip from "jszip";
 import GLTFResolver from "./gltf-resolver.js";
 import { MaterialData } from "./pref-viewer-3d-data.js";
 import BabylonJSAnimationController from "./babylonjs-animation-controller.js";
+import { translate } from "./localization/i18n.js";
 
 /**
- * BabylonJSController - Main controller for managing Babylon.js 3D scenes, assets, rendering, and user interactions in PrefViewer.
+ * BabylonJSController is the PrefViewer 3D engine coordinator: it bootstraps Babylon.js, manages asset containers,
+ * rebuilds post-process pipelines on demand, brokers XR/download interactions, and persists user render toggles so UI
+ * components can stay declarative. Higher layers hand over container + option state, while this class turns it into a
+ * fully interactive scene with deterministic reloads and exports.
  *
- * Summary:
- *  Provides a high-level API for initializing, loading, displaying, and exporting 3D models and environments using Babylon.js.
- *  Manages advanced rendering features, AR integration, asset containers, and user interaction logic.
+ * Overview
+ *  - Spins up the Babylon.js engine/scene/camera stack, configures Draco loaders, and wires resize + render loops.
+ *  - Resolves GLTF/GLB sources through GLTFResolver, loads them into `AssetContainer`s, and toggles their visibility.
+ *  - Applies render-setting switches (AA, SSAO, IBL, shadows), persists them in localStorage, and rehydrates on startup.
+ *  - Rebuilds DefaultRenderingPipeline, SSAO, IBL, and shadow pipelines every time the active camera or assets change.
+ *  - Connects keyboard, pointer, wheel, hover, and XR events so menus, animation controllers, and PrefViewer attributes stay in sync.
+ *  - Generates GLB, glTF+ZIP, or USDZ exports with timestamped names and localized dialog copy.
+ *  - Translates metadata (inner floor offsets, cast/receive shadows, camera locks) into scene adjustments after reloads.
  *
- * Key Responsibilities:
- *  - Initializes and manages the Babylon.js engine, scene, camera, lights, and asset containers.
- *  - Handles loading, replacing, and disposing of 3D models, environments, and materials.
- *  - Configures advanced rendering features such as Draco mesh compression, shadows, and image-based lighting (IBL).
- *  - Integrates Babylon.js WebXR experience for augmented reality (AR) support.
- *  - Provides methods for downloading models and scenes in GLB, glTF (ZIP), and USDZ formats.
- *  - Manages camera and material options, container visibility, and user interactions.
- *  - Observes canvas resize events and updates the engine accordingly.
- *  - Applies metadata-driven scene adjustments (e.g., inner floor translation) after asset reloads.
- *  - Designed for integration with PrefViewer and GLTFResolver.
- *  - All resource management and rendering operations are performed asynchronously for performance.
+ * Runtime Flow
+ *  1. Instantiate with `new BabylonJSController(canvas, containers, options)`.
+ *  2. Call `enable()` to configure Draco, create the engine/scene, observers, and XR hooks.
+ *  3. Whenever PrefViewer marks containers/options pending, invoke `load()` to fetch sources and rebuild pipelines.
+ *  4. Use `applyRenderSettings` helpers (via menu events) to merge toggles, persist them, and trigger reloads when needed.
+ *  5. Respond to PrefViewer tasks by calling `showModel()/hideModel()` equivalents through container state changes.
+ *  6. Surface downloads through `downloadGLB/GLTF/USDZ` or the private `#openDownloadDialog()` triggered by keyboard shortcuts.
+ *  7. Invoke `disable()` when the element disconnects to teardown scenes, XR sessions, and listeners.
  *
- * Usage:
- *  - Instantiate: const controller = new BabylonJSController(canvas, containers, options);
- *  - Enable rendering: await controller.enable();
- *  - Load assets: await controller.load();
- *  - Set camera/material options: controller.setCameraOptions(), controller.setMaterialOptions();
- *  - Control visibility: controller.setContainerVisibility(name, show);
- *  - Download assets: controller.downloadGLB(), controller.downloadGLTF(), controller.downloadUSDZ();
- *  - Disable rendering: controller.disable();
+ * Public API Highlights
+ *  - constructor(canvas, containers, options)
+ *  - enable() / disable()
+ *  - load()
+ *  - downloadGLB(content) / downloadGLTF(content) / downloadUSDZ(content)
+ *  - getRenderSettings() / applyRenderSettings(partial)
+ *  - setRenderSettings(settings) [via PrefViewer menu integration]
  *
- * Public Methods:
- *  - constructor(canvas, containers, options): Creates the controller, wires container state, and stores runtime options.
- *  - enable(): Boots the Babylon.js engine, scene, camera, baseline lights, XR support, and the render loop.
- *  - disable(): Stops rendering and disposes the engine, lights, XR experience, and observers.
- *  - load(): Reloads every pending asset container, re-applies options, and resolves with the loading summary { success, error }.
- *  - setCameraOptions(): Applies the pending camera selection, reinstalls dependent pipelines, and restarts rendering safely.
- *  - setMaterialOptions(): Re-applies all configured material overrides across visible containers and restarts rendering.
- *  - setIBLOptions(): Pushes pending HDR/IBL updates, refreshes dependent effects, resumes the render loop, and reports whether anything changed.
- *  - setContainerVisibility(name, show): Toggles model/environment containers, syncing wall/floor helpers and component attributes.
- *  - downloadGLB(content): Exports the selected scope (scene/model/environment) into a time-stamped GLB and triggers the download.
- *  - downloadGLTF(content): Generates a glTF + BIN + textures ZIP for the requested scope, adding metadata comments for traceability.
- *  - downloadUSDZ(content): Builds an Apple USDZ archive for the requested scope and downloads it via blob streaming.
+ * Key Subsystems
+ *  - Persistence: #applyRenderSettings, #loadStoredRenderSettings, #saveRenderSettings keep AA/SSAO/IBL/shadow flags synced.
+ *  - Loading pipeline: #markContainersForReload, #markOptionsForReload, #loadAssetContainer, #loadContainers orchestrate deterministic reloads.
+ *  - Visual setup: #configureDracoCompression, #createCamera, #createLights, #initializeVisualImprovements, #initializeAmbientOcclussion,
+ *    #initializeIBLShadows, #initializeDefaultLightShadows, #initializeEnvironmentShadows, #setMaxSimultaneousLights.
+ *  - Interaction + XR: #bindHandlers, #enableInteraction, #onPointerObservable, #onMouseWheel, #onKeyUp, #createXRExperience,
+ *    #addStylesToARButton, #disposeXRExperience.
+ *  - Container helpers: #addContainer, #removeContainer, #replaceContainer, #setOptions_Materials, #setOptions_Camera,
+ *    #setOptions_IBL, #setVisibilityOfWallAndFloorInModel, #getPrefViewerComponent.
+ *  - Metadata + download utilities: #checkModelMetadata, #checkInnerFloorTranslation, #translateNodeY, #addDateToName,
+ *    #downloadZip, #openDownloadDialog.
  *
- * Private Methods (using ECMAScript private fields):
- *  - #bindHandlers(): Pre-binds reusable event handlers to preserve stable references.
- *  - #configureDracoCompression(): Sets up Draco mesh compression.
- *  - #renderLoop(): Babylon.js render loop callback.
- *  - #addStylesToARButton(): Styles AR button.
- *  - #createXRExperience(): Initializes WebXR AR experience.
- *  - #createCamera(): Creates and configures the main camera.
- *  - #createLights(): Creates and configures scene lights and shadows.
- *  - #initializeAmbientOcclussion(): Rebuilds the SSAO pipeline for the active camera.
- *  - #initializeVisualImprovements(): Reinstalls the default rendering pipeline (MSAA/FXAA/grain).
- *  - #initializeEnvironmentTexture(): Loads and sets the HDR environment texture.
- *  - #initializeIBLShadows(): Sets up IBL shadow pipeline and assigns meshes/materials.
- *  - #addMeshToShadowGenerator(shadowGenerator, mesh): Adds eligible meshes to the provided shadow generator while honoring GLTF metadata.
- *  - #initializeShadows(): Sets up standard or IBL shadows for meshes.
- *  - #initializeDefaultLightShadows(): Configures soft shadows when no HDR environment exists.
- *  - #initializeEnvironmentShadows(): Rebuilds environment-provided shadow generators.
- *  - #ensureMeshesReceiveShadows(): Ensures every non-root mesh receives shadows unless metadata opts out.
- *  - #setMaxSimultaneousLights(): Updates max simultaneous lights for all materials.
- *  - #onPointerObservable(info): Handles pointer events and dispatches to pointer/mouse handlers.
- *  - #onPointerUp(event, pickInfo): Handles pointer up events (e.g., right-click for animation menu).
- *  - #onPointerMove(event, pickInfo): Handles pointer move events (e.g., mesh highlighting).
- *  - #onMouseWheel(event, pickInfo): Handles mouse wheel events for camera zoom.
- *  - #onKeyUp(event): Handles keyup events for download dialog and shortcuts.
- *  - #enableInteraction(): Adds canvas and scene interaction event listeners.
- *  - #disableInteraction(): Removes canvas and scene interaction event listeners.
- *  - #disposeAnimationController(): Disposes the animation controller if it exists.
- *  - #disposeXRExperience(): Disposes the Babylon.js WebXR experience if it exists.
- *  - #disposeEngine(): Disposes engine and releases all resources.
- *  - #setOptionsMaterial(optionMaterial): Applies a material option to relevant meshes.
- *  - #setOptions_Materials(): Applies all material options from configuration.
- *  - #setOptions_Camera(): Applies camera options from configuration.
- *  - #setOptions_IBL(): Applies pending HDR/IBL option updates and refreshes lights.
- *  - #findContainerByName(name): Finds a container by its name.
- *  - #addContainer(container, updateVisibility): Adds a container to the scene and updates visibility.
- *  - #removeContainer(container, updateVisibility): Removes a container from the scene and updates visibility.
- *  - #replaceContainer(container, newAssetContainer): Replaces a container in the scene.
- *  - #getPrefViewer3DComponent(): Caches and retrieves the parent PREF-VIEWER-3D element.
- *  - #getPrefViewerComponent(): Caches and retrieves the parent PREF-VIEWER element.
- *  - #updateVisibilityAttributeInComponents(name, isVisible): Updates parent visibility attributes.
- *  - #setVisibilityOfWallAndFloorInModel(show): Controls wall/floor mesh visibility.
- *  - #stopRender(): Stops the Babylon.js render loop.
- *  - #startRender(): Starts the Babylon.js render loop.
- *  - #loadAssetContainer(container): Loads an asset container asynchronously.
- *  - #loadContainers(): Loads all asset containers and adds them to the scene.
- *  - #loadCameraDepentEffects(): Re-initializes camera-bound post-processes after reloads or option changes.
- *  - #checkModelMetadata(oldMetadata, newMetadata): Processes metadata changes after loading.
- *  - #checkInnerFloorTranslation(oldMetadata, newMetadata): Applies inner floor Y translations from metadata.
- *  - #translateNodeY(name, deltaY): Adjusts the Y position of a scene node.
- *  - #addDateToName(name): Appends the current date/time to a name string.
- *  - #downloadZip(files, name, comment, addDateInName): Generates and downloads a ZIP file.
- *  - #openDownloadDialog(): Opens the modal download dialog.
+ * Notes
+ *  - Designed to be long-lived per PrefViewer instance; it caches parent components to reflect `show-model/show-scene` attributes.
+ *  - All browser-only features guard against SSR/Node usage by checking `window` before touching localStorage or XR APIs.
+ *  - Relies on PrefViewerMenu3D events to trigger render-setting updates, ensuring UI and persisted state never drift apart.
  */
 export default class BabylonJSController {
+
+    #RENDER_SETTINGS_STORAGE_KEY = "pref-viewer/render-settings";
+
+    // Default render settings
+    // Add here new render toggles that require persistence here, and remember to update the matching labels
+    // under translations.prefViewer.menu3d.switches in ./localization/translations.js.
+    static DEFAULT_RENDER_SETTINGS = {
+        antiAliasingEnabled: true,
+        ambientOcclusionEnabled: true,
+        iblEnabled: true,
+        shadowsEnabled: false,
+    };
+    
     // Canvas HTML element
     #canvas = null;
 
@@ -126,19 +96,20 @@ export default class BabylonJSController {
     
     #gltfResolver = null; // GLTFResolver instance
     #babylonJSAnimationController = null; // AnimationController instance
-    
+
+    #renderPipelines = {
+        default: null,
+        ssao: null,
+        iblShadows: null,
+    };
+
     #handlers = {
         onKeyUp: null,
         onPointerObservable: null,
         renderLoop: null,
     };
     
-    #settings = {
-        antiAliasingEnabled: true,
-        ambientOcclusionEnabled: true,
-        iblEnabled: true,
-        shadowsEnabled: false,
-    };
+    #settings = { ...BabylonJSController.DEFAULT_RENDER_SETTINGS };
 
     /**
      * Constructs a new BabylonJSController instance.
@@ -162,6 +133,7 @@ export default class BabylonJSController {
             };
         });
         this.#options = options;
+        this.#loadStoredRenderSettings();
         this.#bindHandlers();
     }
 
@@ -194,6 +166,114 @@ export default class BabylonJSController {
         };
     }
 
+    /**
+     * Merges boolean render toggles into the current configuration, clearing the environment texture when IBL turns off
+     * and persisting the updated state when at least one flag changed.
+     * @private
+     * @param {object} [settings={}] - Partial map of render settings (AA, SSAO, IBL, shadows, etc.).
+     * @returns {boolean} True when any setting changed and was saved.
+     */
+    #applyRenderSettings(settings = {}) {
+        if (!settings) {
+            return false;
+        }
+
+        let changed = false;
+        Object.keys(settings).forEach((key) => {
+            if (typeof settings[key] === "boolean" && this.#settings[key] !== settings[key]) {
+                this.#settings[key] = settings[key];
+                changed = true;
+            }
+        });
+
+        if (changed && settings.iblEnabled === false && this.#scene) {
+            this.#scene.environmentTexture = null;
+        }
+
+        if (changed) {
+            this.#saveRenderSettings();
+        }
+
+        return changed;
+    }
+
+    /**
+     * Restores previously persisted render toggles from localStorage, falling back to defaults when parsing fails or
+     * the browser environment is unavailable.
+     * @private
+     * @returns {void}
+     */
+    #loadStoredRenderSettings() {
+        if (typeof window === "undefined" || !window?.localStorage) {
+            return;
+        }
+        try {
+            const serialized = window.localStorage.getItem(this.#RENDER_SETTINGS_STORAGE_KEY);
+            if (!serialized) {
+                return;
+            }
+            const parsed = JSON.parse(serialized);
+            Object.keys(BabylonJSController.DEFAULT_RENDER_SETTINGS).forEach((key) => {
+                if (typeof parsed?.[key] === "boolean") {
+                    this.#settings[key] = parsed[key];
+                }
+            });
+        } catch (error) {
+            console.warn("PrefViewer: unable to load render settings", error);
+        }
+    }
+
+    /**
+     * Serializes the current render toggle object to localStorage, ignoring non-browser contexts and logging warnings
+     * if persistence fails.
+     * @private
+     * @returns {void}
+     */
+    #saveRenderSettings() {
+        if (typeof window === "undefined" || !window?.localStorage) {
+            return;
+        }
+        try {
+            window.localStorage.setItem(this.#RENDER_SETTINGS_STORAGE_KEY, JSON.stringify(this.#settings));
+        } catch (error) {
+            console.warn("PrefViewer: unable to save render settings", error);
+        }
+    }
+
+    /**
+     * Walks every container state and marks it as pending using `setPendingWithCurrentStorage` so asset sources are
+     * re-requested on the next load cycle.
+     * @private
+     * @returns {boolean} True when at least one container flipped to pending.
+     */
+    #markContainersForReload() {
+        let marked = false;
+        Object.values(this.#containers).forEach((container) => {
+            if (container?.state?.setPendingWithCurrentStorage && container.state.setPendingWithCurrentStorage()) {
+                marked = true;
+            }
+        });
+        return marked;
+    }
+
+    /**
+     * Re-schedules option-driven resources (camera, materials, IBL) for application by calling their respective
+     * `setPendingWithCurrent`/`setPending` helpers when available.
+     * @private
+     * @returns {void}
+     */
+    #markOptionsForReload() {
+        if (this.#options?.camera?.setPendingWithCurrent) {
+            this.#options.camera.setPendingWithCurrent();
+        }
+        if (this.#options?.materials) {
+            Object.values(this.#options.materials).forEach((material) => material?.setPendingWithCurrent?.());
+        }
+        if (this.#options?.ibl?.setPending) {
+            this.#options.ibl.setPending();
+        }
+    }
+
     /**
      * Render loop callback for Babylon.js.
      * @private
@@ -338,6 +418,43 @@ export default class BabylonJSController {
         }
     }
 
+    /**
+     * Detaches and disposes the SSAO render pipeline from the active camera when it exists.
+     * Guards against missing scene resources or absent pipelines, returning false when no cleanup is needed.
+     * @private
+     * @returns {boolean} Returns true when the SSAO pipeline was disabled, false otherwise.
+     */
+    #disableAmbientOcclusion() {
+        const pipelineManager = this.#scene?.postProcessRenderPipelineManager;
+
+        if (!this.#scene || !pipelineManager || this.#scene?.activeCamera === null) {
+            return false;
+        }
+
+        const supportedPipelines = pipelineManager.supportedPipelines;
+        
+        if (supportedPipelines === undefined) {
+            return false;
+        }
+
+        if (!this.#renderPipelines.ssao) {
+            return false;
+        }
+
+        const pipelineName = this.#renderPipelines.ssao.name;
+        const ssaoPipeline = supportedPipelines ? supportedPipelines.find((pipeline) => pipeline.name === pipelineName) : false;
+
+        if (ssaoPipeline) {
+            pipelineManager.detachCamerasFromRenderPipeline(pipelineName, [this.#scene.activeCamera]);
+            ssaoPipeline.dispose();
+            pipelineManager.removePipeline(pipelineName);
+            pipelineManager.update();
+            this.#renderPipelines.ssao = null;
+        }
+
+        return true;
+    }
+
     /**
      * Rebuilds the SSAO post-process pipeline to inject screenspace ambient occlusion on the active camera.
      * Disposes previous SSAO pipelines, instantiates a tuned `SSAORenderingPipeline`, and attaches it to the
@@ -346,138 +463,166 @@ export default class BabylonJSController {
      * @returns {boolean} True if the SSAO pipeline is supported and enabled, otherwise false.
      */
     #initializeAmbientOcclussion() {
-        if (!this.#scene || !this.#scene.postProcessRenderPipelineManager || this.#scene.activeCamera === null) {
+        const pipelineManager = this.#scene?.postProcessRenderPipelineManager;
+        if (!this.#scene || !pipelineManager || this.#scene?.activeCamera === null) {
             return false;
         }
 
         if (!this.#settings.ambientOcclusionEnabled) {
             return false;
         }
-
-        const pipelineName = "PrefViewerSSAORenderingPipeline";
-
-        const supportedPipelines = this.#scene.postProcessRenderPipelineManager.supportedPipelines;
-
-        if (!supportedPipelines) {
+        const supportedPipelines = pipelineManager.supportedPipelines;
+        
+        if (supportedPipelines === undefined) {
             return false;
         }
-
-        const oldSsaoPipeline = supportedPipelines ? supportedPipelines.find((pipeline) => pipeline.name === pipelineName) : false;
-
-        if (oldSsaoPipeline) {
-            oldSsaoPipeline.dispose();
-            this.#scene.postProcessRenderPipelineManager.update();
-        }
+        
+        const pipelineName = "PrefViewerSSAORenderingPipeline";
 
         const ssaoRatio = {
             ssaoRatio: 0.5,
             combineRatio: 1.0
         };
 
-        const ssaoPipeline = new SSAORenderingPipeline(pipelineName, this.#scene, ssaoRatio, [this.#scene.activeCamera]);
+        this.#renderPipelines.ssao = new SSAORenderingPipeline(pipelineName, this.#scene, ssaoRatio, [this.#scene.activeCamera]);
 
-        if (!ssaoPipeline){
+        if (!this.#renderPipelines.ssao){
             return false;
         }   
 
-        if (ssaoPipeline.isSupported) {
-            ssaoPipeline.fallOff = 0.000001;
-            ssaoPipeline.area = 1;
-            ssaoPipeline.radius = 0.0001;
-            ssaoPipeline.totalStrength = 1;
-            ssaoPipeline.base = 0.6;
+        if (this.#renderPipelines.ssao.isSupported) {
+            this.#renderPipelines.ssao.fallOff = 0.000001;
+            this.#renderPipelines.ssao.area = 1;
+            this.#renderPipelines.ssao.radius = 0.0001;
+            this.#renderPipelines.ssao.totalStrength = 1;
+            this.#renderPipelines.ssao.base = 0.6;
             
             // Configure SSAO to calculate only once instead of every frame for better performance
-            if (ssaoPipeline._ssaoPostProcess) {
-                ssaoPipeline._ssaoPostProcess.autoClear = false;
-                ssaoPipeline._ssaoPostProcess.samples = 1;
+            if (this.#renderPipelines.ssao._ssaoPostProcess) {
+                this.#renderPipelines.ssao._ssaoPostProcess.autoClear = false;
+                this.#renderPipelines.ssao._ssaoPostProcess.samples = 1;
+            }
+            if (this.#renderPipelines.ssao._combinePostProcess) {
+                this.#renderPipelines.ssao._combinePostProcess.autoClear = false;
+                this.#renderPipelines.ssao._combinePostProcess.samples = 1;
             }
             
-            this.#scene.postProcessRenderPipelineManager.update();
+            pipelineManager.update();
             return true;
         } else {
-            ssaoPipeline.dispose();
-            this.#scene.postProcessRenderPipelineManager.update();
+            this.#renderPipelines.ssao.dispose();
+            this.#renderPipelines.ssao = null;
+            pipelineManager.update();
             return false;
         }
     }
 
     /**
-     * Rebuilds the custom default rendering pipeline (MSAA, FXAA, film grain) for the active camera.
-     * Disposes any previous pipeline instance to avoid duplicates, then attaches a fresh
-     * `DefaultRenderingPipeline` with tuned settings for sharper anti-aliasing and subtle grain.
+     * Tears down the default rendering pipeline (MSAA/FXAA/grain) for the active camera when present.
+     * Ensures stale pipelines detach cleanly so a fresh one can be installed on the next load.
      * @private
-     * @returns {boolean} True when the pipeline is supported and active, otherwise false.
-     * @see {@link https://doc.babylonjs.com/features/featuresDeepDive/postProcesses/defaultRenderingPipeline|Using the Default Rendering Pipeline | Babylon.js Documentation}
+     * @returns {boolean} Returns true when the pipeline was removed, false otherwise.
      */
-    #initializeVisualImprovements() {
-        if (!this.#scene || !this.#scene.postProcessRenderPipelineManager || this.#scene.activeCamera === null) {
+    #disableVisualImprovements() {
+        const pipelineManager = this.#scene?.postProcessRenderPipelineManager;
+
+        if (!this.#scene || !pipelineManager || this.#scene?.activeCamera === null) {
             return false;
         }
 
-        const pipelineName = "PrefViewerDefaultRenderingPipeline";
-        const supportedPipelines = this.#scene.postProcessRenderPipelineManager.supportedPipelines;
+        const supportedPipelines = pipelineManager.supportedPipelines;
+        
+        if (supportedPipelines === undefined) {
+            return false;
+        }
 
-        if (!supportedPipelines) {
+        if (!this.#renderPipelines.default) {
             return false;
         }
 
-        const oldDefaultPipeline = supportedPipelines ? supportedPipelines.find((pipeline) => pipeline.name === pipelineName) : false;
+        const pipelineName = this.#renderPipelines.default.name;
+        const defaultPipeline = supportedPipelines ? supportedPipelines.find((pipeline) => pipeline.name === pipelineName) : false;
+
+        if (defaultPipeline) {
+            pipelineManager.detachCamerasFromRenderPipeline(pipelineName, [this.#scene.activeCamera]);
+            defaultPipeline.dispose();
+            pipelineManager.removePipeline(pipelineName);
+            pipelineManager.update();
+            this.#renderPipelines.default = null;
+        }
+
+        return true;
+    }
 
-        if (oldDefaultPipeline) {
-            oldDefaultPipeline.dispose();
-            this.#scene.postProcessRenderPipelineManager.update();
+    /**
+     * Rebuilds the custom default rendering pipeline (MSAA, FXAA, film grain) for the active camera.
+     * Disposes any previous pipeline instance to avoid duplicates, then attaches a fresh
+     * `DefaultRenderingPipeline` with tuned settings for sharper anti-aliasing and subtle grain.
+     * @private
+     * @returns {boolean} True when the pipeline is supported and active, otherwise false.
+     * @see {@link https://doc.babylonjs.com/features/featuresDeepDive/postProcesses/defaultRenderingPipeline|Using the Default Rendering Pipeline | Babylon.js Documentation}
+     */
+    #initializeVisualImprovements() {
+        const pipelineManager = this.#scene?.postProcessRenderPipelineManager;
+        if (!this.#scene || !pipelineManager || this.#scene?.activeCamera === null) {
+            return false;
         }
 
         if (!this.#settings.antiAliasingEnabled) {
             return false;
         }
+        const supportedPipelines = pipelineManager.supportedPipelines;
+        
+        if (supportedPipelines === undefined) {
+            return false;
+        }
+        
+        const pipelineName = "PrefViewerDefaultRenderingPipeline";
 
-        const defaultPipeline = new DefaultRenderingPipeline(pipelineName, true, this.#scene, [this.#scene.activeCamera], true);
+        this.#renderPipelines.default = new DefaultRenderingPipeline(pipelineName, true, this.#scene, [this.#scene.activeCamera], true);
 
-        if (!defaultPipeline){
+        if (!this.#renderPipelines.default){
             return false;
         } 
 
-        if (defaultPipeline.isSupported) {
+        if (this.#renderPipelines.default.isSupported) {
             // MSAA - Multisample Anti-Aliasing
             const caps = this.#scene.getEngine()?.getCaps?.() || {};
             const maxSamples = typeof caps.maxMSAASamples === "number" ? caps.maxMSAASamples : 4;
-            defaultPipeline.samples = Math.max(1, Math.min(8, maxSamples));
-
+            this.#renderPipelines.default.samples = Math.max(1, Math.min(8, maxSamples));
             // FXAA - Fast Approximate Anti-Aliasing
-            defaultPipeline.fxaaEnabled = true;
-            defaultPipeline.fxaa.samples = 8;
-            defaultPipeline.fxaa.adaptScaleToCurrentViewport = true;
-            if (defaultPipeline.fxaa.edgeThreshold !== undefined) {
-                defaultPipeline.fxaa.edgeThreshold = 0.125;
+            this.#renderPipelines.default.fxaaEnabled = true;
+            this.#renderPipelines.default.fxaa.samples = 8;
+            this.#renderPipelines.default.fxaa.adaptScaleToCurrentViewport = true;
+            if (this.#renderPipelines.default.fxaa.edgeThreshold !== undefined) {
+                this.#renderPipelines.default.fxaa.edgeThreshold = 0.125;
             }
-            if (defaultPipeline.fxaa.edgeThresholdMin !== undefined) {
-                defaultPipeline.fxaa.edgeThresholdMin = 0.0625;
+            if (this.#renderPipelines.default.fxaa.edgeThresholdMin !== undefined) {
+                this.#renderPipelines.default.fxaa.edgeThresholdMin = 0.0625;
             }
-            if (defaultPipeline.fxaa.subPixelQuality !== undefined) {
-                defaultPipeline.fxaa.subPixelQuality = 0.75;
+            if (this.#renderPipelines.default.fxaa.subPixelQuality !== undefined) {
+                this.#renderPipelines.default.fxaa.subPixelQuality = 0.75;
             }
 
             // Grain
-            defaultPipeline.grainEnabled = true;
-            defaultPipeline.grain.adaptScaleToCurrentViewport = true;
-            defaultPipeline.grain.animated = false;
-            defaultPipeline.grain.intensity = 3;
+            this.#renderPipelines.default.grainEnabled = true;
+            this.#renderPipelines.default.grain.adaptScaleToCurrentViewport = true;
+            this.#renderPipelines.default.grain.animated = false;
+            this.#renderPipelines.default.grain.intensity = 3;
 
             // Configure post-processes to calculate only once instead of every frame for better performance
-            if (defaultPipeline.fxaa?._postProcess) {
-                defaultPipeline.fxaa._postProcess.autoClear = false;
+            if (this.#renderPipelines.default.fxaa?._postProcess) {
+                this.#renderPipelines.default.fxaa._postProcess.autoClear = false;
             }
-            if (defaultPipeline.grain?._postProcess) {
-                defaultPipeline.grain._postProcess.autoClear = false;
+            if (this.#renderPipelines.default.grain?._postProcess) {
+                this.#renderPipelines.default.grain._postProcess.autoClear = false;
             }
 
-            this.#scene.postProcessRenderPipelineManager.update();
+            pipelineManager.update();
             return true;
         } else {
-            defaultPipeline.dispose();
-            this.#scene.postProcessRenderPipelineManager.update();
+            this.#renderPipelines.default.dispose();
+            pipelineManager.update();
             return false;
         }
     }
@@ -497,6 +642,43 @@ export default class BabylonJSController {
         return true;
     }
 
+    /**
+     * Removes the IBL shadow render pipeline from the active camera when present.
+     * Ensures voxelized shadow data is disposed so reloading environments installs a clean pipeline.
+     * @private
+     * @returns {boolean} Returns true when the pipeline was removed, false otherwise.
+     */
+    #disableIBLShadows() {
+        const pipelineManager = this.#scene?.postProcessRenderPipelineManager;
+
+        if (!this.#scene || !pipelineManager || this.#scene?.activeCamera === null) {
+            return false;
+        }
+
+        const supportedPipelines = pipelineManager.supportedPipelines;
+        
+        if (supportedPipelines === undefined) {
+            return false;
+        }
+
+        if (!this.#renderPipelines.iblShadows) {
+            return false;
+        }
+
+        const pipelineName = this.#renderPipelines.iblShadows.name;
+        const defaultPipeline = supportedPipelines ? supportedPipelines.find((pipeline) => pipeline.name === pipelineName) : false;
+
+        if (defaultPipeline) {
+            pipelineManager.detachCamerasFromRenderPipeline(pipelineName, [this.#scene.activeCamera]);
+            defaultPipeline.dispose();
+            pipelineManager.removePipeline(pipelineName);
+            pipelineManager.update();
+            this.#renderPipelines.iblShadows = null;
+        }
+
+        return true;
+    }
+
     /**
      * Initializes the Image-Based Lighting (IBL) shadows for the Babylon.js scene.
      * Creates an IBL shadow render pipeline and adds all relevant meshes and materials for shadow casting and receiving.
@@ -506,27 +688,22 @@ export default class BabylonJSController {
      * @returns {void|false} Returns false if no environment texture is set; otherwise void.
      */
     #initializeIBLShadows() {
-        if (!this.#scene || !this.#scene.postProcessRenderPipelineManager || this.#scene.activeCamera === null) {
+        const pipelineManager = this.#scene?.postProcessRenderPipelineManager;
+
+        if (!this.#scene || !pipelineManager || this.#scene?.activeCamera === null) {
             return false;
         }
 
-        // if (!this.#scene.environmentTexture || !this.#scene.environmentTexture.isReady()) {
         if (!this.#scene.environmentTexture) {
             return false;
         }
-        const pipelineName = "PrefViewerIblShadowsRenderPipeline";
-        const supportedPipelines = this.#scene.postProcessRenderPipelineManager.supportedPipelines;
-
+        const supportedPipelines = pipelineManager.supportedPipelines;
+        
         if (!supportedPipelines) {
             return false;
         }
-
-        const oldIblShadowsRenderPipeline = supportedPipelines ? supportedPipelines.find((pipeline) => pipeline.name === pipelineName) : false;
-
-        if (oldIblShadowsRenderPipeline) {
-            oldIblShadowsRenderPipeline.dispose();
-            this.#scene.postProcessRenderPipelineManager.update();
-        }
+        
+        const pipelineName = "PrefViewerIblShadowsRenderPipeline";
 
         const pipelineOptions = {
             resolutionExp: 1, // Higher resolution for better shadow quality (recomended 8)
@@ -537,13 +714,13 @@ export default class BabylonJSController {
             shadowOpacity: 0.85,
         };
 
-        const iblShadowsRenderPipeline = new IblShadowsRenderPipeline(pipelineName, this.#scene, pipelineOptions, [this.#scene.activeCamera]);
+        this.#renderPipelines.iblShadows = new IblShadowsRenderPipeline(pipelineName, this.#scene, pipelineOptions, [this.#scene.activeCamera]);
 
-        if (!iblShadowsRenderPipeline) {
+        if (!this.#renderPipelines.iblShadows) {
             return false;
         }
        
-        if (iblShadowsRenderPipeline.isSupported) {
+        if (this.#renderPipelines.iblShadows.isSupported) {
             // Disable all debug passes for performance
             const pipelineProps = {
                 allowDebugPasses: false,
@@ -557,11 +734,11 @@ export default class BabylonJSController {
                 accumulationPassDebugEnabled: false,
             };
 
-            Object.assign(iblShadowsRenderPipeline, pipelineProps);
+            Object.assign(this.#renderPipelines.iblShadows, pipelineProps);
 
-            if (iblShadowsRenderPipeline._ssaoPostProcess) {
-                iblShadowsRenderPipeline._ssaoPostProcess.autoClear = false;
-                iblShadowsRenderPipeline._ssaoPostProcess.samples = 1;
+            if (this.#renderPipelines.iblShadows._ssaoPostProcess) {
+                this.#renderPipelines.iblShadows._ssaoPostProcess.autoClear = false;
+                this.#renderPipelines.iblShadows._ssaoPostProcess.samples = 1;
             }
 
             this.#scene.meshes.forEach((mesh) => {
@@ -575,8 +752,8 @@ export default class BabylonJSController {
                 const meshGenerateShadows = typeof extrasCastShadows === "boolean" ? extrasCastShadows : isHDRIMesh ? false : true;
 
                 if (meshGenerateShadows) {
-                    iblShadowsRenderPipeline.addShadowCastingMesh(mesh);
-                    iblShadowsRenderPipeline.updateSceneBounds();
+                    this.#renderPipelines.iblShadows.addShadowCastingMesh(mesh);
+                    this.#renderPipelines.iblShadows.updateSceneBounds();
                 }
             });
 
@@ -584,15 +761,15 @@ export default class BabylonJSController {
                 if (material instanceof PBRMaterial) {
                     material.enableSpecularAntiAliasing = false;
                 }
-                iblShadowsRenderPipeline.addShadowReceivingMaterial(material);
+                this.#renderPipelines.iblShadows.addShadowReceivingMaterial(material);
             });
 
-            iblShadowsRenderPipeline.updateVoxelization();
-            this.#scene.postProcessRenderPipelineManager.update();
+            this.#renderPipelines.iblShadows.updateVoxelization();
+            pipelineManager.update();
             return true;
         } else {
-            iblShadowsRenderPipeline.dispose();
-            this.#scene.postProcessRenderPipelineManager.update();
+            this.#renderPipelines.iblShadows.dispose();
+            pipelineManager.update();
             return false;
         }
     }
@@ -626,7 +803,6 @@ export default class BabylonJSController {
      * @returns {void}
      */
     #initializeDefaultLightShadows() {
-        this.#shadowGen = [];
         if (!this.#dirLight) {
             return;
         }
@@ -692,6 +868,20 @@ export default class BabylonJSController {
         });
     }
 
+    /**
+     * Disposes every active shadow generator plus the IBL shadow pipeline to avoid stale casters across reloads.
+     * Clears the cached `#shadowGen` array so subsequent loads can rebuild fresh generators.
+     * @private
+     * @returns {void}
+     */
+    #disableShadows() {
+        this.#shadowGen.forEach((shadowGenerator) => {
+            shadowGenerator.dispose();
+        });
+        this.#shadowGen = [];
+        this.#disableIBLShadows();
+    }
+
     /**
      * Initializes shadows for the Babylon.js scene.
      * @private
@@ -839,7 +1029,6 @@ export default class BabylonJSController {
         this.#engine.dispose();
         this.#engine = this.#scene = this.#camera = null;
         this.#hemiLight = this.#dirLight = this.#cameraLight = null;
-        this.#shadowGen = [];
     }
 
     /**
@@ -1207,6 +1396,7 @@ export default class BabylonJSController {
      */
     #stopRender() {
         this.#engine.stopRenderLoop(this.#handlers.renderLoop);
+        this.#unloadCameraDependentEffects();
     }
     /**
      * Starts the Babylon.js render loop for the current scene.
@@ -1215,6 +1405,7 @@ export default class BabylonJSController {
      * @returns {Promise<void>}
      */
     async #startRender() {
+        this.#loadCameraDependentEffects();
         await this.#scene.whenReadyAsync();
         this.#engine.runRenderLoop(this.#handlers.renderLoop);
     }
@@ -1285,7 +1476,6 @@ export default class BabylonJSController {
      */
     async #loadContainers() {
         this.#stopRender();
-        this.#scene.postProcessRenderPipelineManager?.dispose();
 
         let oldModelMetadata = { ...(this.#containers.model?.state?.metadata ?? {}) };
         let newModelMetadata = {};
@@ -1311,6 +1501,13 @@ export default class BabylonJSController {
                             assetContainer.lights = [];
                             newModelMetadata = { ...(container.state.update.metadata ?? {}) };
                         }
+                        if (container.state.name === "model" || container.state.name === "environment") {
+                            assetContainer.cameras.forEach((camera) => {
+                                // To avoid conflicts when reloading the model we rename the id because Babylon.js caches the camera's SSAO effect by id.
+                                const sufix = "_" + Date.now();
+                                camera.id = `${camera.id || camera.name || "camera"}${sufix}`;
+                            });
+                        }
                         this.#replaceContainer(container, assetContainer);
                         container.state.setSuccess(true);
                     } else {
@@ -1336,7 +1533,6 @@ export default class BabylonJSController {
             .finally(async () => {
                 this.#checkModelMetadata(oldModelMetadata, newModelMetadata);
                 this.#setMaxSimultaneousLights();
-                this.#loadCameraDepentEffects();
                 this.#babylonJSAnimationController = new BabylonJSAnimationController(this.#containers.model.assetContainer);
                 this.#startRender();
             });
@@ -1349,12 +1545,24 @@ export default class BabylonJSController {
      * @private
      * @returns {void}
      */
-    #loadCameraDepentEffects() {
+    #loadCameraDependentEffects() {
         this.#initializeVisualImprovements();
         this.#initializeAmbientOcclussion();
         this.#initializeShadows();
     }
 
+    /**
+     * Shuts down every post-process tied to the active camera before stopping the render loop.
+     * Ensures AA, SSAO, and shadow resources detach cleanly so reloads rebuild from scratch.
+     * @private
+     * @returns {void}
+     */
+    #unloadCameraDependentEffects() {
+        this.#disableVisualImprovements();
+        this.#disableAmbientOcclusion();
+        this.#disableShadows();
+    }
+
     /**
      * Checks and applies model metadata changes after asset loading.
      * @private
@@ -1512,16 +1720,18 @@ export default class BabylonJSController {
             return;
         }
 
-        const header = "Download 3D Scene";
+        const locale = this.#prefViewer.culture;
+        const texts = translate("prefViewer.downloadDialog", locale ? { locale } : undefined) || {};
+        const header = texts.title || "Download 3D Scene";
         const content = `
             <form slot="content" id="download-dialog-form" style="display:flex;flex-direction:column;gap:16px;">
-                <h4>Content</h4>
+                <h4>${texts.sections?.content || "Content"}</h4>
                 <div style="display:flex;flex-direction:row;gap:16px;margin:0 8px 0 8px;">
-                    <label><input type="radio" name="content" value="1"> Model</label>
-                    <label><input type="radio" name="content" value="2"> Scene</label>
-                    <label><input type="radio" name="content" value="0" checked> Both</label>
+                    <label><input type="radio" name="content" value="1"> ${texts.options?.model || "Model"}</label>
+                    <label><input type="radio" name="content" value="2"> ${texts.options?.scene || "Scene"}</label>
+                    <label><input type="radio" name="content" value="0" checked> ${texts.options?.both || "Both"}</label>
                 </div>
-                <h4>Format</h4>
+                <h4>${texts.sections?.format || "Format"}</h4>
                 <div style="display:flex;flex-direction:row;gap:16px;margin:0 8px 0 8px;">
                 <label><input type="radio" name="format" value="gltf" checked> glTF (ZIP)</label>
                     <label><input type="radio" name="format" value="glb"> GLB</label>
@@ -1529,8 +1739,8 @@ export default class BabylonJSController {
                 </div>
             </form>`;
         const footer = `
-            <button type="button" class="primary" id="download-dialog-download">Download</button>
-            <button type="button" id="download-dialog-cancel">Cancel</button>`;
+            <button type="button" class="primary" id="download-dialog-download">${texts.buttons?.download || "Download"}</button>
+            <button type="button" id="download-dialog-cancel">${texts.buttons?.cancel || "Cancel"}</button>`;
 
         const dialog = this.#prefViewer.openDialog(header, content, footer);
 
@@ -1614,84 +1824,10 @@ export default class BabylonJSController {
         this.#disableInteraction();
         this.#disposeAnimationController();
         this.#disposeXRExperience();
+        this.#unloadCameraDependentEffects();
         this.#disposeEngine();
     }
 
-    /**
-     * Loads all asset containers (model, environment, materials, etc.) and adds them to the scene.
-     * Applies material and camera options, sets visibility, and initializes lights and shadows.
-     * @public
-     * @returns {Promise<boolean>} Resolves to true if loading succeeds, false otherwise.
-     */
-    async load() {
-        return await this.#loadContainers();
-    }
-
-    /**
-     * Applies camera options from the configuration to the active camera.
-     * Stops and restarts the render loop to apply changes.
-     * @public
-     * @returns {boolean} True if camera options were set successfully, false otherwise.
-     */
-    setCameraOptions() {
-        this.#stopRender();
-        const cameraOptionsSetted = this.#setOptions_Camera();
-        this.#loadCameraDepentEffects();
-        this.#startRender();
-        return cameraOptionsSetted;
-    }
-
-    /**
-     * Applies material options from the configuration to the relevant meshes.
-     * Stops and restarts the render loop to apply changes.
-     * @public
-     * @returns {boolean} True if material options were set successfully, false otherwise.
-     */
-    setMaterialOptions() {
-        this.#stopRender();
-        const materialsOptionsSetted = this.#setOptions_Materials();
-        this.#startRender();
-        return materialsOptionsSetted;
-    }
-
-    /**
-     * Reapplies image-based lighting configuration (HDR URL, intensity, shadow mode).
-     * Stops rendering, pushes pending IBL state into the scene, rebuilds camera-dependent effects, then resumes rendering.
-     * @public
-     * @returns {void}
-     */
-    setIBLOptions() {
-        this.#stopRender();
-        const IBLOptionsSetted = this.#setOptions_IBL();
-        this.#loadCameraDepentEffects();
-        this.#startRender();
-        return IBLOptionsSetted;
-    }
-
-    /**
-     * Sets the visibility of a container (model, environment, etc.) by name.
-     * Adds or removes the container from the scene and updates wall/floor visibility.
-     * Restarts the render loop to apply changes.
-     * @public
-     * @param {string} name - The name of the container to show or hide.
-     * @param {boolean} show - True to show the container, false to hide it.
-     * @returns {void}
-     */
-    setContainerVisibility(name, show) {
-        const container = this.#findContainerByName(name);
-        if (!container) {
-            return;
-        }
-        if (container.state.show === show && container.state.visible === show) {
-            return;
-        }
-        container.state.show = show;
-        this.#stopRender();
-        show ? this.#addContainer(container) : this.#removeContainer(container);
-        this.#setVisibilityOfWallAndFloorInModel();
-        this.#startRender();
-    }
-
     /**
      * Downloads the current scene, model, or environment as a GLB file.
      * @public
@@ -1794,4 +1930,116 @@ export default class BabylonJSController {
             }
         });
     }
+
+    /**
+     * Returns a shallow copy of the current render settings so callers can read the active state without mutating the controller internals.
+     * @public
+     * @returns {{antiAliasingEnabled:boolean, ambientOcclusionEnabled:boolean, iblEnabled:boolean, shadowsEnabled:boolean}}
+     */
+    getRenderSettings() {
+        return { ...this.#settings };
+    }
+
+    /**
+     * Loads all asset containers (model, environment, materials, etc.) and adds them to the scene.
+     * Applies material and camera options, sets visibility, and initializes lights and shadows.
+     * @public
+     * @returns {Promise<boolean>} Resolves to true if loading succeeds, false otherwise.
+     */
+    async load() {
+        return await this.#loadContainers();
+    }
+
+    /**
+     * Merges incoming render flags with the current configuration, persists them, and marks
+     * all dependent loaders/options as pending when something actually changed.
+     * @public
+     * @param {{antiAliasingEnabled?:boolean, ambientOcclusionEnabled?:boolean, iblEnabled?:boolean, shadowsEnabled?:boolean}} settings Partial set of render toggles to apply.
+     * @returns {{changed:boolean, settings:{antiAliasingEnabled:boolean, ambientOcclusionEnabled:boolean, iblEnabled:boolean, shadowsEnabled:boolean}}}
+     * @description
+     * Callers can inspect the `changed` flag to decide whether to trigger a reload with
+     * `reloadWithCurrentSettings()` or simply reuse the returned snapshot.
+     */
+    scheduleRenderSettingsReload(settings = {}) {
+        const changed = this.#applyRenderSettings(settings);
+        if (!changed) {
+            return { changed: false, settings: this.getRenderSettings() };
+        }
+        this.#markContainersForReload();
+        this.#markOptionsForReload();
+        return { changed: true, settings: this.getRenderSettings() };
+    }
+
+    /**
+     * Applies camera options from the configuration to the active camera.
+     * Stops and restarts the render loop to apply changes.
+     * @public
+     * @returns {boolean} True if camera options were set successfully, false otherwise.
+     */
+    setCameraOptions() {
+        this.#stopRender();
+        const cameraOptionsSetted = this.#setOptions_Camera();
+        this.#startRender();
+        return cameraOptionsSetted;
+    }
+
+    /**
+     * Applies material options from the configuration to the relevant meshes.
+     * Stops and restarts the render loop to apply changes.
+     * @public
+     * @returns {boolean} True if material options were set successfully, false otherwise.
+     */
+    setMaterialOptions() {
+        this.#stopRender();
+        const materialsOptionsSetted = this.#setOptions_Materials();
+        this.#startRender();
+        return materialsOptionsSetted;
+    }
+
+    /**
+     * Reapplies image-based lighting configuration (HDR URL, intensity, shadow mode).
+     * Stops rendering, pushes pending IBL state into the scene, rebuilds camera-dependent effects, then resumes rendering.
+     * @public
+     * @returns {void}
+     */
+    setIBLOptions() {
+        this.#stopRender();
+        const IBLOptionsSetted = this.#setOptions_IBL();
+        this.#startRender();
+        return IBLOptionsSetted;
+    }
+
+    /**
+     * Sets the visibility of a container (model, environment, etc.) by name.
+     * Adds or removes the container from the scene and updates wall/floor visibility.
+     * Restarts the render loop to apply changes.
+     * @public
+     * @param {string} name - The name of the container to show or hide.
+     * @param {boolean} show - True to show the container, false to hide it.
+     * @returns {void}
+     */
+    setContainerVisibility(name, show) {
+        const container = this.#findContainerByName(name);
+        if (!container) {
+            return;
+        }
+        if (container.state.show === show && container.state.visible === show) {
+            return;
+        }
+        container.state.show = show;
+        this.#stopRender();
+        show ? this.#addContainer(container) : this.#removeContainer(container);
+        this.#setVisibilityOfWallAndFloorInModel();
+        this.#startRender();
+    }
+
+    /**
+     * Reloads every asset container using the latest staged render settings.
+     * Intended to be called after `scheduleRenderSettingsReload()` marks data as pending.
+     * @public
+     * @returns {Promise<{success:boolean,error:any}>} Resolves with the same status object returned by `load()`.
+     */
+    async reloadWithCurrentSettings() {
+        return await this.#loadContainers();
+    }
 }