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

package/src/babylonjs-controller.js

@@ -0,0 +1,932 @@
+import { Engine, Scene, ArcRotateCamera, Vector3, Color4, HemisphericLight, DirectionalLight, PointLight, ShadowGenerator, LoadAssetContainerAsync, Tools, WebXRSessionManager, WebXRDefaultExperience, MeshBuilder, WebXRFeatureName, HDRCubeTexture, IblShadowsRenderPipeline } from "@babylonjs/core";
+import { DracoCompression } from "@babylonjs/core/Meshes/Compression/dracoCompression";
+import "@babylonjs/loaders";
+import "@babylonjs/loaders/glTF/2.0/Extensions/KHR_draco_mesh_compression";
+import { USDZExportAsync, GLTF2Export } from "@babylonjs/serializers";
+import GLTFResolver from "./gltf-resolver.js";
+
+/**
+ * BabylonJSController - Main controller for managing Babylon.js 3D scenes, assets, and interactions.
+ *
+ * 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 and USDZ formats.
+ *  - Manages camera and material options, container visibility, and user interactions.
+ *  - Observes canvas resize events and updates the engine accordingly.
+ *
+ * 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.downloadModelGLB(), controller.downloadModelUSDZ(), etc.
+ *  - Disable rendering: controller.disable();
+ *
+ * Public Methods:
+ *  - enable(): Initializes engine, scene, camera, lights, XR, and starts rendering.
+ *  - disable(): Disposes engine and disconnects resize observer.
+ *  - load(): Loads all asset containers and adds them to the scene.
+ *  - setCameraOptions(): Applies camera options from configuration.
+ *  - setMaterialOptions(): Applies material options from configuration.
+ *  - setContainerVisibility(name, show): Shows or hides a container by name.
+ *  - downloadModelGLB(), downloadModelUSDZ(), downloadModelAndSceneGLB(), downloadModelAndSceneUSDZ(): Downloads assets.
+ *
+ * Private Methods:
+ *  - #configureDracoCompression(): Sets up Draco mesh compression.
+ *  - #createCamera(), #createLights(), #initializeEnvironmentTexture(), #initializeIBLShadows(), #initializeShadows(): Scene setup.
+ *  - #setupInteraction(): Sets up canvas interaction handlers.
+ *  - #disposeEngine(): Disposes engine and resources.
+ *  - #setOptionsMaterial(), #setOptions_Materials(), #setOptions_Camera(): Applies material/camera options.
+ *  - #findContainerByName(), #addContainer(), #removeContainer(), #replaceContainer(): Container management.
+ *  - #setVisibilityOfWallAndFloorInModel(): Controls wall/floor mesh visibility.
+ *  - #stopRender(), #startRender(): Render loop control.
+ *  - #loadAssetContainer(), #loadContainers(): Asset loading.
+ *  - #addStylesToARButton(): Styles AR button.
+ *  - #createXRExperience(): Initializes WebXR AR experience.
+ *
+ * Notes:
+ *  - Designed for integration with PrefViewer and GLTFResolver.
+ *  - Supports advanced Babylon.js features for product visualization and configurators.
+ *  - All resource management and rendering operations are performed asynchronously for performance.
+ */
+export default class BabylonJSController {
+    // Canvas HTML element
+    #canvas = null;
+
+    // References to parent custom elements
+    #prefViewer3D = undefined;
+    #prefViewer = undefined;
+
+    // Babylon.js core objects
+    #engine = null;
+    #scene = null;
+    #camera = null;
+    #hemiLight = null;
+    #dirLight = null;
+    #cameraLight = null;
+    #shadowGen = null;
+    #XRExperience = null;
+    #canvasResizeObserver = null;
+
+    #containers = {};
+    #options = {};
+
+    #gltfResolver = null; // GLTFResolver instance
+
+    /**
+     * Constructs a new BabylonJSController instance.
+     * Initializes the canvas, asset containers, and options for the Babylon.js scene.
+     * @public
+     * @param {HTMLCanvasElement|null} canvas - The canvas element to render the scene on.
+     * @param {object} containers - An object containing container states for model, environment, materials, etc.
+     * @param {object} options - Configuration options for the Babylon.js scene and assets.
+     * @returns {BabylonJSController}
+     * @description
+     *   - Assigns the provided canvas to the controller.
+     *   - Initializes each container with its state and sets assetContainer to null.
+     *   - Stores the provided options for later use in scene setup and asset loading.
+     */
+    constructor(canvas = null, containers = {}, options = {}) {
+        this.#canvas = canvas;
+        Object.keys(containers).forEach((key) => {
+            this.#containers[key] = {
+                assetContainer: null,
+                state: containers[key],
+            };
+        });
+        this.#options = options;
+    }
+
+    /**
+     * Configures the Draco mesh compression decoder for Babylon.js.
+     * @private
+     * @returns {void}
+     */
+    #configureDracoCompression() {
+        // Point to whichever version you packaged or want to use:
+        const DRACO_BASE = "https://www.gstatic.com/draco/versioned/decoders/1.5.7";
+        DracoCompression.Configuration.decoder = {
+            // loader for the “wrapper” that pulls in the real WASM
+            wasmUrl: `${DRACO_BASE}/draco_wasm_wrapper_gltf.js`,
+            // the raw WebAssembly binary
+            wasmBinaryUrl: `${DRACO_BASE}/draco_decoder_gltf.wasm`,
+            // JS fallback if WASM isn’t available
+            fallbackUrl: `${DRACO_BASE}/draco_decoder_gltf.js`,
+        };
+    }
+
+    /**
+     * Render loop callback for Babylon.js.
+     * @private
+     * @returns {void}
+     * @description
+     * Continuously renders the current scene if it exists.
+     * Used by the engine's runRenderLoop method to update the view.
+     */
+    #renderLoop() {
+        this.#scene && this.#scene.render();
+    }
+
+    /**
+     * Adds custom CSS styles to the Babylon.js AR button for consistent appearance and interaction.
+     * @private
+     * @returns {void}
+     */
+    #addStylesToARButton() {
+        const css = '.babylonVRicon { color: #868686; border-color: #868686; border-style: solid; margin-left: 10px; height: 50px; width: 80px; background-color: rgba(51,51,51,0.7); background-image: url(data:image/svg+xml;charset=UTF-8,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20width%3D%222048%22%20height%3D%221152%22%20viewBox%3D%220%200%202048%201152%22%20version%3D%221.1%22%3E%3Cpath%20transform%3D%22rotate%28180%201024%2C576.0000000000001%29%22%20d%3D%22m1109%2C896q17%2C0%2030%2C-12t13%2C-30t-12.5%2C-30.5t-30.5%2C-12.5l-170%2C0q-18%2C0%20-30.5%2C12.5t-12.5%2C30.5t13%2C30t30%2C12l170%2C0zm-85%2C256q59%2C0%20132.5%2C-1.5t154.5%2C-5.5t164.5%2C-11.5t163%2C-20t150%2C-30t124.5%2C-41.5q23%2C-11%2042%2C-24t38%2C-30q27%2C-25%2041%2C-61.5t14%2C-72.5l0%2C-257q0%2C-123%20-47%2C-232t-128%2C-190t-190%2C-128t-232%2C-47l-81%2C0q-37%2C0%20-68.5%2C14t-60.5%2C34.5t-55.5%2C45t-53%2C45t-53%2C34.5t-55.5%2C14t-55.5%2C-14t-53%2C-34.5t-53%2C-45t-55.5%2C-45t-60.5%2C-34.5t-68.5%2C-14l-81%2C0q-123%2C0%20-232%2C47t-190%2C128t-128%2C190t-47%2C232l0%2C257q0%2C68%2038%2C115t97%2C73q54%2C24%20124.5%2C41.5t150%2C30t163%2C20t164.5%2C11.5t154.5%2C5.5t132.5%2C1.5zm939%2C-298q0%2C39%20-24.5%2C67t-58.5%2C42q-54%2C23%20-122%2C39.5t-143.5%2C28t-155.5%2C19t-157%2C11t-148.5%2C5t-129.5%2C1.5q-59%2C0%20-130%2C-1.5t-148%2C-5t-157%2C-11t-155.5%2C-19t-143.5%2C-28t-122%2C-39.5q-34%2C-14%20-58.5%2C-42t-24.5%2C-67l0%2C-257q0%2C-106%2040.5%2C-199t110%2C-162.5t162.5%2C-109.5t199%2C-40l81%2C0q27%2C0%2052%2C14t50%2C34.5t51%2C44.5t55.5%2C44.5t63.5%2C34.5t74%2C14t74%2C-14t63.5%2C-34.5t55.5%2C-44.5t51%2C-44.5t50%2C-34.5t52%2C-14l14%2C0q37%2C0%2070%2C0.5t64.5%2C4.5t63.5%2C12t68%2C23q71%2C30%20128.5%2C78.5t98.5%2C110t63.5%2C133.5t22.5%2C149l0%2C257z%22%20fill%3D%22white%22%20/%3E%3C/svg%3E%0A); background-size: 80%; background-repeat:no-repeat; background-position: center; border: none; outline: none; transition: transform 0.125s ease-out } .babylonVRicon:hover { transform: scale(1.05) } .babylonVRicon:active {background-color: rgba(51,51,51,1) } .babylonVRicon:focus {background-color: rgba(51,51,51,1) }.babylonVRicon.vrdisplaypresenting { background-image: none;} .vrdisplaypresenting::after { content: "EXIT"} .xr-error::after { content: "ERROR"}';
+        let style = this.#canvas.parentElement.parentElement.querySelector("style");
+        if (!style) {
+            style = document.createElement("style");
+            this.#canvas.parentElement.parentElement.appendChild(style);
+        }
+        style.appendChild(document.createTextNode(css));
+    }
+
+    /**
+     * Creates and initializes the Babylon.js WebXR experience for augmented reality (AR).
+     * @private
+     * @returns {Promise<boolean|void>} Resolves to true if XR experience is created, false if not supported, or void on error.
+     * @description
+     * Checks for AR session support, creates a hidden ground mesh, and configures session and UI options.
+     * Enables teleportation feature and sets the initial XR camera pose when the session starts.
+     * Adds custom styles to the AR button for consistent appearance.
+     * If AR is not supported or initialization fails, logs a warning and sets XRExperience to null.
+     */
+    async #createXRExperience() {
+        if (this.#XRExperience) {
+            return true;
+        }
+
+        const sessionMode = "immersive-ar";
+        const sessionSupported = await WebXRSessionManager.IsSessionSupportedAsync(sessionMode);
+        if (!sessionSupported) {
+            console.info("PrefViewer: WebXR in mode AR is not supported");
+            return false;
+        }
+
+        try {
+            const ground = MeshBuilder.CreateGround("ground", { width: 1000, height: 1000 }, this.#scene);
+            ground.isVisible = false;
+
+            const options = {
+                floorMeshes: [ground],
+                uiOptions: {
+                    sessionMode: sessionMode,
+                    renderTarget: "xrLayer",
+                    referenceSpaceType: "local",
+                },
+                optionalFeatures: true,
+            };
+
+            this.#XRExperience = await WebXRDefaultExperience.CreateAsync(this.#scene, options);
+
+            const featuresManager = this.#XRExperience.baseExperience.featuresManager;
+            featuresManager.enableFeature(WebXRFeatureName.TELEPORTATION, "stable", {
+                xrInput: this.#XRExperience.input,
+                floorMeshes: [ground],
+                timeToTeleport: 1500,
+            });
+
+            this.#XRExperience.baseExperience.sessionManager.onXRReady.add(() => {
+                // Set the initial position of xrCamera: use nonVRCamera, which contains a copy of the original this.#scene.activeCamera before entering XR
+                this.#XRExperience.baseExperience.camera.setTransformationFromNonVRCamera(this.#XRExperience.baseExperience._nonVRCamera);
+                this.#XRExperience.baseExperience.camera.setTarget(Vector3.Zero());
+                this.#XRExperience.baseExperience.onInitialXRPoseSetObservable.notifyObservers(this.#XRExperience.baseExperience.camera);
+            });
+
+            this.#addStylesToARButton();
+        } catch (error) {
+            console.warn("PrefViewer: failed to create WebXR experience", error);
+            this.#XRExperience = null;
+        }
+    }
+
+    /**
+     * Creates and configures the main ArcRotateCamera for the Babylon.js scene.
+     * @private
+     * @returns {void}
+     */
+    #createCamera() {
+        this.#camera = new ArcRotateCamera("camera", (3 * Math.PI) / 2, Math.PI * 0.47, 10, Vector3.Zero(), this.#scene);
+        this.#camera.upperBetaLimit = Math.PI * 0.48;
+        this.#camera.lowerBetaLimit = Math.PI * 0.25;
+        this.#camera.lowerRadiusLimit = 5;
+        this.#camera.upperRadiusLimit = 20;
+        this.#camera.metadata = { locked: false };
+        this.#camera.attachControl(this.#canvas, true);
+        this.#scene.activeCamera = this.#camera;
+    }
+
+    /**
+     * Creates and configures the main lights for the Babylon.js scene.
+     * Initializes the environment texture if needed.
+     * Adds a hemispheric ambient light, a directional light for shadows, a shadow generator, and a camera-attached point light.
+     * Sets light intensities and shadow properties for realistic rendering.
+     * @private
+     * @returns {void}
+     */
+    #createLights() {
+        this.#initializeEnvironmentTexture();
+
+        if (this.#scene.environmentTexture) {
+            return true;
+        }
+
+        // 1) Stronger ambient fill
+        this.#hemiLight = new HemisphericLight("hemiLight", new Vector3(-10, 10, -10), this.#scene);
+        this.#hemiLight.intensity = 0.6;
+
+        // 2) Directional light from the front-right, angled slightly down
+        this.#dirLight = new DirectionalLight("dirLight", new Vector3(-10, 10, -10), this.#scene);
+        this.#dirLight.position = new Vector3(5, 4, 5); // light is IN FRONT + ABOVE + to the RIGHT
+        this.#dirLight.intensity = 0.6;
+
+        // // 3) Soft shadows
+        this.#shadowGen = new ShadowGenerator(1024, this.#dirLight);
+        this.#shadowGen.useBlurExponentialShadowMap = true;
+        this.#shadowGen.blurKernel = 16;
+        this.#shadowGen.darkness = 0.5;
+
+        // 4) Camera‐attached headlight
+        this.#cameraLight = new PointLight("pl", this.#camera.position, this.#scene);
+        this.#cameraLight.parent = this.#camera;
+        this.#cameraLight.intensity = 0.3;
+    }
+
+    /**
+     * Initializes the environment texture for the Babylon.js scene.
+     * Loads an HDR texture from a predefined URI and assigns it to the scene's environmentTexture property.
+     * Configures gamma space, mipmaps, and intensity level for realistic lighting.
+     * @private
+     * @returns {boolean}
+     */
+    #initializeEnvironmentTexture() {
+        return false;
+        if (this.#scene.environmentTexture) {
+            return;
+        }
+        const hdrTextureURI = "../src/environments/noon_grass.hdr";
+        const hdrTexture = new HDRCubeTexture(hdrTextureURI, this.#scene, 128);
+        hdrTexture.gammaSpace = true;
+        hdrTexture._noMipmap = false;
+        hdrTexture.level = 2.0;
+        this.#scene.environmentTexture = hdrTexture;
+    }
+
+    /**
+     * 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.
+     * Configures pipeline options for resolution, sampling, opacity, and debugging.
+     * Only applies if the scene has an environment texture set.
+     * @private
+     * @returns {void|false} Returns false if no environment texture is set; otherwise void.
+     */
+    #initializeIBLShadows() {
+        if (!this.#scene.environmentTexture) {
+            return false;
+        }
+
+        let createIBLShadowPipeline = function (scene) {
+            const pipeline = new IblShadowsRenderPipeline(
+                "iblShadowsPipeline",
+                scene,
+                {
+                    resolutionExp: 7,
+                    sampleDirections: 2,
+                    ssShadowsEnabled: true,
+                    shadowRemanence: 0.8,
+                    triPlanarVoxelization: true,
+                    shadowOpacity: 0.8,
+                },
+                [scene.activeCamera]
+            );
+            pipeline.allowDebugPasses = false;
+            pipeline.gbufferDebugEnabled = true;
+            pipeline.importanceSamplingDebugEnabled = false;
+            pipeline.voxelDebugEnabled = false;
+            pipeline.voxelDebugDisplayMip = 1;
+            pipeline.voxelDebugAxis = 2;
+            pipeline.voxelTracingDebugEnabled = false;
+            pipeline.spatialBlurPassDebugEnabled = false;
+            pipeline.accumulationPassDebugEnabled = false;
+            return pipeline;
+        };
+
+        let iblShadowsPipeline = createIBLShadowPipeline(this.#scene);
+
+        this.#scene.meshes.forEach((mesh) => {
+            if (mesh.id.startsWith("__root__") || mesh.name === "hdri") {
+                return false;
+            }
+            iblShadowsPipeline.addShadowCastingMesh(mesh);
+            iblShadowsPipeline.updateSceneBounds();
+        });
+
+        this.#scene.materials.forEach((material) => {
+            iblShadowsPipeline.addShadowReceivingMaterial(material);
+        });
+    }
+
+    /**
+     * Initializes shadows for the Babylon.js scene.
+     * @private
+     * @returns {void|true} Returns true if IBL shadows are initialized, otherwise void.
+     * @description
+     * If no environment texture is set, initializes IBL shadows.
+     * Otherwise, sets up shadow casting and receiving for all relevant meshes using the shadow generator.
+     */
+    #initializeShadows() {
+        if (!this.#scene.environmentTexture) {
+            this.#initializeIBLShadows();
+            return true;
+        }
+
+        this.#scene.meshes.forEach((mesh) => {
+            if (mesh.id.startsWith("__root__")) {
+                return false;
+            }
+            mesh.receiveShadows = true;
+            if (!mesh.name === "hdri") {
+                this.#shadowGen.addShadowCaster(mesh, true);
+            }
+        });
+    }
+
+    /**
+     * Sets the maximum number of simultaneous lights for all materials in the scene.
+     * Counts enabled lights and updates the maxSimultaneousLights property for each material.
+     * @private
+     * @returns {void}
+     */
+    #setMaxSimultaneousLights() {
+        let lightsNumber = 1; // Como mínimo una luz correspondiente a la textura de environmentTexture
+        this.#scene.lights.forEach((light) => {
+            if (light.isEnabled()) {
+                ++lightsNumber;
+            }
+        });
+        if (this.#scene.materials) {
+            this.#scene.materials.forEach((material) => (material.maxSimultaneousLights = lightsNumber));
+        }
+    }
+
+    /**
+     * Sets up interaction handlers for the Babylon.js canvas.
+     * Adds a wheel event listener to control camera zoom based on mouse wheel input.
+     * Prevents zoom if the active camera is locked.
+     * @private
+     * @returns {void}
+     */
+    #setupInteraction() {
+        this.#canvas.addEventListener("wheel", (event) => {
+            if (!this.#scene || !this.#camera) {
+                return false;
+            }
+            //const pick = this.#scene.pick(this.#scene.pointerX, this.#scene.pointerY);
+            //this.#camera.target = pick.hit ? pick.pickedPoint.clone() : this.#camera.target;
+            if (!this.#scene.activeCamera.metadata?.locked) {
+                this.#scene.activeCamera.inertialRadiusOffset -= event.deltaY * this.#scene.activeCamera.wheelPrecision * 0.001;
+            }
+            event.preventDefault();
+        });
+    }
+
+    /**
+     * Disposes the Babylon.js engine and releases all associated resources.
+     * @private
+     * @returns {void}
+     */
+    #disposeEngine() {
+        if (!this.#engine) {
+            return;
+        }
+        this.#engine.dispose();
+        this.#engine = this.#scene = this.#camera = null;
+        this.#hemiLight = this.#dirLight = this.#cameraLight = null;
+        this.#shadowGen = null;
+        this.#XRExperience = null;
+    }
+
+    /**
+     * Applies material options from the configuration to the relevant meshes.
+     * @private
+     * @param {object} optionMaterial - Material option containing value, nodePrefixes, nodeNames, and state.
+     * @returns {boolean} True if any mesh material was set, false otherwise.
+     */
+    #setOptionsMaterial(optionMaterial) {
+        if (!optionMaterial || !(optionMaterial.value || (optionMaterial.isPending && optionMaterial.update.value)) || !(optionMaterial.nodePrefixes.length || optionMaterial.nodeNames.length)) {
+            return false;
+        }
+
+        const materialContainer = this.#containers.materials;
+        const materialName = optionMaterial.isPending && optionMaterial.update.value ? optionMaterial.update.value : optionMaterial.value;
+
+        const material = materialContainer.assetContainer?.materials.find((mat) => mat.name === materialName) || null;
+        if (!material) {
+            return false;
+        }
+
+        const assetContainersToProcess = [];
+        Object.values(this.#containers).forEach((container) => {
+            if (container.state.name === "materials") {
+                return;
+            }
+            if (container.assetContainer && (container.isPending || materialContainer.isPending || optionMaterial.isPending)) {
+                assetContainersToProcess.push(container.assetContainer);
+            }
+        });
+        if (assetContainersToProcess.length === 0) {
+            return false;
+        }
+
+        let someSetted = false;
+        assetContainersToProcess.forEach((assetContainer) =>
+            assetContainer.meshes
+                .filter((meshToFilter) => optionMaterial.nodePrefixes.some((prefix) => meshToFilter.name.startsWith(prefix)) || optionMaterial.nodeNames.includes(meshToFilter.name))
+                .forEach((mesh) => {
+                    mesh.material = material;
+                    someSetted = true;
+                })
+        );
+
+        if (someSetted) {
+            optionMaterial.setSuccess(true);
+        } else if (optionMaterial.isPending) {
+            optionMaterial.setSuccess(false);
+        }
+
+        return someSetted;
+    }
+
+    /**
+     * Applies all material options from the configuration to the relevant meshes.
+     * Iterates through each material option and applies it using #setOptionsMaterial.
+     * @private
+     * @returns {boolean} True if any material option was set, false otherwise.
+     */
+    #setOptions_Materials() {
+        let someSetted = false;
+        Object.values(this.#options.materials).forEach((material) => {
+            let settedMaterial = this.#setOptionsMaterial(material);
+            someSetted = someSetted || settedMaterial;
+        });
+        return someSetted;
+    }
+
+    /**
+     * Applies camera options from the configuration to the active camera.
+     * @private
+     * @returns {boolean} True if camera options were set successfully, false otherwise.
+     */
+    #setOptions_Camera() {
+        const cameraState = this.#options.camera;
+        const modelContainer = this.#containers.model;
+        const environmentContainer = this.#containers.environment;
+
+        if (!cameraState.isPending && !modelContainer.isPending && !environmentContainer.isPending) {
+            return false;
+        }
+
+        const cameraName = cameraState.isPending ? cameraState.update.value : cameraState.value;
+        let camera = null;
+        if (cameraName !== null) {
+            camera = modelContainer.assetContainer?.cameras.find((thisCamera) => thisCamera.name === cameraName) || environmentContainer.assetContainer?.cameras.find((thisCamera) => thisCamera.name === cameraName) || null;
+        } else {
+            camera = this.#camera;
+        }
+
+        if (!camera) {
+            // If a new camera (different from the default) was tried and not found, search for the current one
+            if (cameraState.isPending && cameraState.update.value !== null && cameraState.value !== null && cameraState.update.value !== cameraState.value) {
+                camera = modelContainer.assetContainer?.cameras.find((thisCamera) => thisCamera.name === cameraState.value) || environmentContainer.assetContainer?.cameras.find((thisCamera) => thisCamera.name === cameraState.value) || null;
+            }
+            if (camera) {
+                // If the current camera (different from the default) was found, use it
+                camera.metadata = { locked: cameraState.locked };
+                cameraState.setSuccess(false);
+            } else {
+                // If no camera was found, use the default camera
+                camera = this.#camera;
+                cameraState.value = null;
+                cameraState.locked = this.#camera.metadata.locked;
+                cameraState.setSuccess(false);
+            }
+        } else {
+            // If the requested camera was found, use it
+            if (cameraName !== null) {
+                camera.metadata = { locked: cameraState.isPending ? cameraState.update.locked : cameraState.locked };
+            } else {
+                // If it's the default camera, maintain its lock state
+                if (cameraState.isPending) {
+                    cameraState.update.locked = this.#camera.metadata.locked;
+                } else {
+                    cameraState.locked = this.#camera.metadata.locked;
+                }
+            }
+            if (cameraState.isPending) {
+                cameraState.setSuccess(true);
+            }
+        }
+        if (!cameraState.locked && cameraState.value !== null) {
+            camera.attachControl(this.#canvas, true);
+        }
+        this.#scene.activeCamera = camera;
+        return true;
+    }
+
+    /**
+     * Finds and returns the asset container object by its name.
+     * @private
+     * @param {string} name - The name of the container to find.
+     * @returns {object|null} The matching container object, or null if not found.
+     */
+    #findContainerByName(name) {
+        return Object.values(this.#containers).find((container) => container.state.name === name) || null;
+    }
+
+    /**
+     * Caches and retrieves the parent custom element "PREF-VIEWER-3D" for efficient access.
+     * @private
+     * @returns {void}
+     */
+    #getPrefViewer3DComponent() {
+        if (this.#prefViewer3D === undefined) {
+            const grandParentElement = this.#canvas.parentElement.parentElement;
+            this.#prefViewer3D = grandParentElement && grandParentElement.nodeName === "PREF-VIEWER-3D" ? grandParentElement : null;
+        }
+    }
+
+    /**
+     * Caches and retrieves the parent custom element "PREF-VIEWER" for efficient access.
+     * @private
+     * @returns {void}
+     */
+    #getPrefViewerComponent() {
+        if (this.#prefViewer === undefined) {
+            const rootNode = this.#prefViewer3D ? this.#prefViewer3D.getRootNode().host : null;
+            this.#prefViewer = rootNode && rootNode.nodeName === "PREF-VIEWER" ? rootNode : null;
+        }
+    }
+
+    /**
+     * Updates the visibility attributes "show-model" or "show-scene" of parent custom elements ("PREF-VIEWER-3D" and "PREF-VIEWER") based on the container name and visibility state.
+     * @private
+     * @param {string} name - The name of the container ("model" or "environment").
+     * @param {boolean} isVisible - True to show the container, false to hide it.
+     * @returns {void}
+     */
+    #updateVisibilityAttributeInComponentes(name, isVisible) {
+        // Cache references to parent custom elements
+        this.#getPrefViewer3DComponent();
+        this.#getPrefViewerComponent();
+        if (name === "model") {
+            this.#prefViewer3D?.setAttribute("show-model", isVisible ? "true" : "false");
+            this.#prefViewer?.setAttribute("show-model", isVisible ? "true" : "false");
+        } else if (name === "environment") {
+            this.#prefViewer3D?.setAttribute("show-scene", isVisible ? "true" : "false");
+            this.#prefViewer?.setAttribute("show-scene", isVisible ? "true" : "false");
+        }
+    }
+
+    /**
+     * Adds the asset container to the Babylon.js scene if it should be shown and is not already visible.
+     * @private
+     * @param {object} container - The container object containing asset state and metadata.
+     * @returns {boolean} True if the container was added, false otherwise.
+     */
+    #addContainer(container) {
+        if (!container.assetContainer || container.state.isVisible || !container.state.mustBeShown) {
+            return false;
+        }
+        this.#updateVisibilityAttributeInComponentes(container.state.name, true);
+        container.assetContainer.addAllToScene();
+        container.state.visible = true;
+        return true;
+    }
+
+    /**
+     * Removes the asset container from the Babylon.js scene if it is currently visible.
+     * @private
+     * @param {object} container - The container object containing asset state and metadata.
+     * @returns {boolean} True if the container was removed, false otherwise.
+     */
+    #removeContainer(container) {
+        if (!container.assetContainer || !container.state.isVisible) {
+            return false;
+        }
+        this.#updateVisibilityAttributeInComponentes(container.state.name, false);
+        container.assetContainer.removeAllFromScene();
+        container.state.visible = false;
+        return true;
+    }
+
+    /**
+     * Replaces the asset container in the Babylon.js scene with a new one.
+     * @private
+     * @param {object} container - The container object containing asset state and metadata.
+     * @param {object} newAssetContainer - The new asset container to add to the scene.
+     * @returns {boolean} True if the container was replaced, false otherwise.
+     */
+    #replaceContainer(container, newAssetContainer) {
+        if (container.assetContainer) {
+            this.#removeContainer(container);
+            container.assetContainer.dispose();
+            container.assetContainer = null;
+        }
+        this.#scene.getEngine().releaseEffects();
+        container.assetContainer = newAssetContainer;
+        this.#addContainer(container);
+        return true;
+    }
+    /**
+     * Sets the visibility of wall and floor meshes in the model container based on the provided value or environment visibility.
+     * @private
+     * @param {boolean} [show] - Optional. True to show wall/floor meshes, false to hide. Defaults to environment visibility.
+     * @returns {void|false} Returns false if the model container is not available or not visible; otherwise void.
+     */
+    #setVisibilityOfWallAndFloorInModel(show) {
+        if (!this.#containers.model.assetContainer || !this.#containers.model.state.isVisible) {
+            return false;
+        }
+        show = show !== undefined ? show : this.#containers.environment.state.isVisible;
+        const nodePrefixes = Object.values(this.#options.materials).flatMap((material) => material.nodePrefixes);
+        const nodeNames = Object.values(this.#options.materials).flatMap((material) => material.nodeNames);
+        this.#containers.model.assetContainer.meshes.filter((meshToFilter) => nodePrefixes.some((prefix) => meshToFilter.name.startsWith(prefix)) || nodeNames.includes(meshToFilter.name)).forEach((mesh) => mesh.setEnabled(show));
+    }
+
+    /**
+     * Stops the Babylon.js render loop for the current scene.
+     * @private
+     * @returns {void}
+     */
+    #stopR;
+    #stopRender() {
+        this.#engine.stopRenderLoop(this.#renderLoop.bind(this));
+    }
+    /**
+     * Starts the Babylon.js render loop for the current scene.
+     * Waits until the scene is ready before beginning continuous rendering.
+     * @private
+     * @returns {Promise<void>}
+     */
+    async #startRender() {
+        await this.#scene.whenReadyAsync();
+        this.#engine.runRenderLoop(this.#renderLoop.bind(this));
+    }
+
+    /**
+     * Loads an asset container (model, environment, materials, etc.) using the provided container state.
+     * @private
+     * @param {object} container - The container object containing asset state and metadata.
+     * @returns {Promise<[object, AssetContainer|boolean]>} Resolves to an array with the container and the loaded asset container, or false if loading fails.
+     * @description
+     * Resolves the asset source using GLTFResolver, prepares plugin options, and loads the asset into the Babylon.js scene.
+     * Updates the container's cache data and returns the container along with the loaded asset container or false if loading fails.
+     */
+    async #loadAssetContainer(container) {
+        if (container?.state?.update?.storage === undefined || container?.state?.size === undefined || container?.state?.timeStamp === undefined) {
+            return [container, false];
+        }
+
+        if (container.state.isPending === false) {
+            return [container, false];
+        }
+
+        if (!this.#gltfResolver) {
+            this.#gltfResolver = new GLTFResolver();
+        }
+
+        let sourceData = await this.#gltfResolver.getSource(container.state.update.storage, container.state.size, container.state.timeStamp);
+        if (!sourceData) {
+            return [container, false];
+        }
+
+        container.state.setPendingCacheData(sourceData.size, sourceData.timeStamp);
+
+        // https://doc.babylonjs.com/typedoc/interfaces/BABYLON.LoadAssetContainerOptions
+        let options = {
+            pluginExtension: sourceData.extension,
+            pluginOptions: {
+                gltf: {
+                    compileMaterials: true,
+                    loadAllMaterials: true,
+                    loadOnlyMaterials: container.state.name === "materials",
+                },
+            },
+        };
+
+        return [container, await LoadAssetContainerAsync(sourceData.source, this.#scene, options)];
+    }
+
+    /**
+     * Loads all asset containers (model, environment, materials, etc.) and adds them to the scene.
+     * @private
+     * @returns {Promise<{success: boolean, error: any}>} Resolves to an object indicating if loading succeeded and any error encountered.
+     * @description
+     * Waits for all containers to load in parallel, then replaces or adds them to the scene as needed.
+     * Applies material and camera options, sets wall/floor visibility, and initializes lights and shadows.
+     * Returns an object with success status and error details.
+     */
+    async #loadContainers() {
+        this.#stopRender();
+
+        const promiseArray = [];
+        Object.values(this.#containers).forEach((container) => {
+            promiseArray.push(this.#loadAssetContainer(container));
+        });
+
+        let detail = {
+            success: false,
+            error: null,
+        };
+
+        await Promise.allSettled(promiseArray)
+            .then((values) => {
+                values.forEach((result) => {
+                    const container = result.value ? result.value[0] : null;
+                    const assetContainer = result.value ? result.value[1] : null;
+                    if (result.status === "fulfilled" && assetContainer) {
+                        if (container.state.name === "model") {
+                            assetContainer.lights = [];
+                        }
+                        this.#replaceContainer(container, assetContainer);
+                        container.state.setSuccess(true);
+                    } else {
+                        if (container.assetContainer && container.state.mustBeShown !== container.state.isVisible && container.state.name === "materials") {
+                            container.state.mustBeShown ? this.#addContainer(container) : this.#removeContainer(container);
+                        }
+                        container.state.setSuccess(false);
+                    }
+                });
+
+                this.#setOptions_Materials();
+                this.#setOptions_Camera();
+                this.#setVisibilityOfWallAndFloorInModel();
+                detail.success = true;
+            })
+            .catch((error) => {
+                this.loaded = true;
+                console.error("PrefViewer: failed to load model", error);
+                detail.success = false;
+                detail.error = error;
+            })
+            .finally(async () => {
+                this.#setMaxSimultaneousLights();
+                this.#initializeShadows();
+                this.#startRender();
+            });
+
+        return detail;
+    }
+
+    /**
+     * ---------------------------
+     * Public methods
+     * ---------------------------
+     */
+
+    /**
+     * Initializes the Babylon.js engine, scene, camera, lights, and interaction handlers.
+     * Configures Draco compression, sets up XR experience, and starts the render loop.
+     * Observes canvas resize events to update the engine.
+     * @public
+     * @returns {Promise<void>}
+     */
+    async enable() {
+        this.#configureDracoCompression();
+        this.#engine = new Engine(this.#canvas, true, { alpha: true });
+        this.#engine.disableUniformBuffers = true;
+        this.#scene = new Scene(this.#engine);
+        this.#scene.clearColor = new Color4(1, 1, 1, 1);
+        this.#createCamera();
+        this.#createLights();
+        this.#setupInteraction();
+        await this.#createXRExperience();
+        this.#startRender();
+        this.#canvasResizeObserver = new ResizeObserver(() => this.#engine && this.#engine.resize());
+        this.#canvasResizeObserver.observe(this.#canvas);
+    }
+
+    /**
+     * Disposes the Babylon.js engine and disconnects the canvas resize observer.
+     * Cleans up all scene, camera, light, and XR resources.
+     * @public
+     * @returns {void}
+     */
+    disable() {
+        this.#disposeEngine();
+        this.#canvasResizeObserver.disconnect();
+    }
+
+    /**
+     * 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.#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;
+    }
+
+    /**
+     * 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();
+    }
+
+    /**
+     * Initiates download of the current model as a GLB file.
+     * @public
+     * @returns {void}
+     */
+    downloadModelGLB() {
+        const fileName = "model";
+        GLTF2Export.GLBAsync(this.#containers.model.assetContainer, fileName, { exportWithoutWaitingForScene: true }).then((glb) => glb.downloadFiles());
+    }
+
+    /**
+     * Initiates download of the current model as a USDZ file.
+     * @public
+     * @returns {void}
+     */
+    downloadModelUSDZ() {
+        const fileName = "model";
+        USDZExportAsync(this.#containers.model.assetContainer).then((response) => {
+            if (response) {
+                Tools.Download(new Blob([response], { type: "model/vnd.usdz+zip" }), `${fileName}.usdz`);
+            }
+        });
+    }
+
+    /**
+     * Initiates download of the entire scene (model and environment) as a USDZ file.
+     * @public
+     * @returns {void}
+     */
+    downloadModelAndSceneUSDZ() {
+        const fileName = "scene";
+        USDZExportAsync(this.#scene).then((response) => {
+            if (response) {
+                Tools.Download(new Blob([response], { type: "model/vnd.usdz+zip" }), `${fileName}.usdz`);
+            }
+        });
+    }
+
+    /**
+     * Initiates download of the entire scene (model and environment) as a GLB file.
+     * @public
+     * @returns {void}
+     */
+    downloadModelAndSceneGLB() {
+        const fileName = "scene";
+        GLTF2Export.GLBAsync(this.#scene, fileName, { exportWithoutWaitingForScene: true }).then((glb) => glb.downloadFiles());
+    }
+}