@preference-sl/pref-viewer 2.11.0-beta.3 → 2.11.0-beta.4

package/src/babylonjs-animation-opening.js

@@ -0,0 +1,496 @@
+import { AdvancedDynamicTexture } from "@babylonjs/gui";
+import { OpeningAnimationMenu } from "./babylonjs-animation-opening-menu.js";
+
+/**
+ * OpeningAnimation - Manages open/close animations for a model part (e.g., a door) in a Babylon.js scene.
+ *
+ * Responsibilities:
+ *  - Controls playback of opening and closing AnimationGroups.
+ *  - Tracks animation state (paused, closed, opened, opening, closing).
+ *  - Synchronizes animation progress and UI controls.
+ *  - Handles loop mode and progress threshold logic.
+ *  - Provides methods for play, pause, go to opened/closed, and progress control.
+ *  - Manages the animation control menu (OpeningAnimationMenu) and its callbacks.
+ *
+ * Public Methods:
+ *  - isAnimationForNode(node): Checks if the animation affects the given node.
+ *  - playOpen(): Starts the opening animation.
+ *  - playClose(): Starts the closing animation.
+ *  - pause(): Pauses the current animation.
+ *  - goToOpened(): Moves animation to the fully opened state.
+ *  - goToClosed(): Moves animation to the fully closed state.
+ *  - showControls(advancedDynamicTexture): Displays the animation control menu.
+ *  - hideControls(): Hides the animation control menu.
+ *  - isControlsVisible(): Returns true if the control menu is visible for this animation.
+ *
+ * Public Properties:
+ *  - state: Returns the current animation state.
+ *
+ * Private Methods:
+ *  - #getNodesFromAnimationGroups(): Collects node IDs affected by the animation groups.
+ *  - #onOpened(): Handles end of opening animation.
+ *  - #onClosed(): Handles end of closing animation.
+ *  - #goToOpened(useLoop): Sets state to opened and optionally loops to close.
+ *  - #goToClosed(useLoop): Sets state to closed and optionally loops to open.
+ *  - #goToFrameAndPause(frame): Moves to a specific frame and pauses.
+ *  - #getCurrentFrame(): Gets the current frame based on state.
+ *  - #getFrameFromProgress(progress): Calculates frame from progress value.
+ *  - #getProgress(): Calculates progress (0-1) from current frame.
+ *  - #checkProgress(progress): Applies threshold logic to progress.
+ *  - #updateControlsSlider(): Updates the slider in the control menu.
+ *  - #updateControls(): Updates all controls in the menu.
+ *
+ * Usage Example:
+ *  const anim = new OpeningAnimation("door", openGroup, closeGroup);
+ *  anim.playOpen();
+ *  anim.pause();
+ *  anim.goToClosed();
+ *  anim.showControls(adt);
+ *  anim.hideControls();
+ */
+export class OpeningAnimation {
+    static states = {
+        paused: 0,
+        closed: 1,
+        opened: 2,
+        opening: 3,
+        closing: 4,
+    };
+
+    #openAnimation = null;
+    #closeAnimation = null;
+
+    #nodes = [];
+    #state = OpeningAnimation.states.closed;
+    #lastPausedFrame = 0;
+    #startFrame = 0;
+    #endFrame = 0;
+    #speedRatio = 1.0;
+    #loop = false;
+
+    #advancedDynamicTexture = null;
+    #menu = null;
+    #progressThreshold = 0.025;
+
+    /**
+     * Creates a new OpeningAnimation instance for managing open/close animations of a model part.
+     * @param {string} name - The identifier for this animation (e.g., door name).
+     * @param {AnimationGroup} openAnimationGroup - Babylon.js AnimationGroup for the opening animation.
+     * @param {AnimationGroup} closeAnimationGroup - Babylon.js AnimationGroup for the closing animation.
+     * @description
+     * Initializes internal state, sets up frame ranges, collects affected nodes, and attaches end-of-animation observers.
+     */
+    constructor(name, openAnimationGroup, closeAnimationGroup) {
+        this.name = name;
+        this.#openAnimation = openAnimationGroup;
+        this.#closeAnimation = closeAnimationGroup;
+
+        this.#openAnimation.stop();
+        this.#openAnimation._loopAnimation = false;
+        this.#closeAnimation.stop();
+        this.#closeAnimation._loopAnimation = false;
+
+        this.#startFrame = this.#openAnimation.from;
+        this.#endFrame = this.#openAnimation.to;
+        this.#speedRatio = this.#openAnimation.speedRatio || 1.0;
+
+        this.#getNodesFromAnimationGroups();
+        this.#openAnimation.onAnimationGroupEndObservable.add(this.#onOpened.bind(this));
+        this.#closeAnimation.onAnimationGroupEndObservable.add(this.#onClosed.bind(this));
+    }
+
+    /**
+     * Collects node IDs affected by the opening and closing animation groups.
+     * Populates the #nodes array with unique node identifiers.
+     * @private
+     */
+    #getNodesFromAnimationGroups() {
+        [this.#openAnimation, this.#closeAnimation].forEach((animationGroup) => {
+            animationGroup._targetedAnimations.forEach((targetedAnimation) => {
+                if (!this.#nodes.includes(targetedAnimation.target.id)) {
+                    this.#nodes.push(targetedAnimation.target.id);
+                }
+            });
+        });
+    }
+
+    /**
+     * Handles the end of the opening animation group.
+     * @private
+     */
+    #onOpened() {
+        this.#goToOpened(true);
+    }
+
+    /**
+     * Handles the end of the closing animation group.
+     * @private
+     */
+    #onClosed() {
+        this.#goToClosed(true);
+    }
+
+    /**
+     * Moves the animation to the fully opened state, optionally looping to close.
+     * @private
+     * @param {boolean} useLoop - If true, starts closing animation after opening.
+     */
+    #goToOpened(useLoop = false) {
+        this.#lastPausedFrame = this.#endFrame;
+
+        if (this.#openAnimation._isStarted && !this.#openAnimation._isPaused) {
+            this.#openAnimation.pause();
+        }
+        this.#openAnimation.goToFrame(this.#endFrame);
+
+        this.#closeAnimation.pause();
+        this.#closeAnimation.goToFrame(this.#startFrame);
+
+        this.#state = OpeningAnimation.states.opened;
+        this.#updateControls();
+
+        if (this.#loop && useLoop) {
+            this.playClose();
+        }
+    }
+
+    /**
+     * Moves the animation to the fully closed state, optionally looping to open.
+     * @private
+     * @param {boolean} useLoop - If true, starts opening animation after closing.
+     */
+    #goToClosed(useLoop = false) {
+        this.#lastPausedFrame = this.#startFrame;
+
+        if (this.#closeAnimation._isStarted && !this.#closeAnimation._isPaused) {
+            this.#closeAnimation.pause();
+        }
+        this.#closeAnimation.goToFrame(this.#endFrame - this.#startFrame);
+
+        this.#openAnimation.pause();
+        this.#openAnimation.goToFrame(this.#startFrame);
+
+        this.#state = OpeningAnimation.states.closed;
+        this.#updateControls();
+
+        if (this.#loop && useLoop) {
+            this.playOpen();
+        }
+    }
+
+    /**
+     * Moves the animation to a specific frame and pauses.
+     * @private
+     * @param {number} frame - The frame to go to and pause.
+     */
+    #goToFrameAndPause(frame) {
+        if (!frame) {
+            return;
+        }
+
+        if (this.#state === OpeningAnimation.states.opening) {
+            this.#openAnimation.pause();
+        }
+        if (this.#state === OpeningAnimation.states.closing) {
+            this.#closeAnimation.pause();
+        }
+
+        if (this.#openAnimation._isStarted && this.#openAnimation._isPaused) {
+            this.#openAnimation.goToFrame(frame);
+        } else {
+            this.#openAnimation.start();
+            this.#openAnimation.pause();
+            this.#openAnimation.goToFrame(frame);
+        }
+
+        this.#lastPausedFrame = frame;
+        this.#state = OpeningAnimation.states.paused;
+        this.#updateControls();
+    }
+
+    /**
+     * Gets the current frame of the animation based on its state.
+     * @private
+     * @returns {number} The current frame.
+     */
+    #getCurrentFrame() {
+        let currentFrame;
+        if (this.#state === OpeningAnimation.states.opening) {
+            currentFrame = this.#openAnimation.getCurrentFrame();
+        } else if (this.#state === OpeningAnimation.states.closing) {
+            currentFrame = this.#endFrame - this.#closeAnimation.getCurrentFrame();
+        } else {
+            currentFrame = this.#lastPausedFrame;
+        }
+
+        // Ensure currentFrame is within startFrame and endFrame
+        if (currentFrame < this.#startFrame) {
+            currentFrame = this.#startFrame;
+        } else if (currentFrame > this.#endFrame) {
+            currentFrame = this.#endFrame;
+        }
+
+        return currentFrame;
+    }
+
+    /**
+     * Calculates the frame number from a normalized progress value (0-1).
+     * @private
+     * @param {number} progress - Progress value between 0 and 1.
+     * @returns {number} The corresponding frame.
+     */
+    #getFrameFromProgress(progress) {
+        const frame = this.#startFrame + (this.#endFrame - this.#startFrame) * progress;
+        return frame;
+    }
+
+    /**
+     * Calculates the normalized progress (0-1) from the current frame.
+     * @private
+     * @returns {number} Progress value.
+     */
+    #getProgress() {
+        const currentFrame = this.#getCurrentFrame();
+        const progress = (currentFrame - this.#startFrame) / (this.#endFrame - this.#startFrame);
+        return progress;
+    }
+
+    /**
+     * Applies threshold logic to the progress value to snap to 0 or 1 if near the ends.
+     * Prevents floating point errors from leaving the animation in an in-between state.
+     * @private
+     * @param {number} progress - Progress value.
+     * @returns {number} Thresholded progress.
+     */
+    #checkProgress(progress) {
+        if (progress <= this.#progressThreshold) {
+            progress = 0;
+        } else if (progress >= 1 - this.#progressThreshold) {
+            progress = 1;
+        }
+        return progress;
+    }
+
+    /**
+     * Updates the slider value in the animation control menu to match the current progress.
+     * @private
+     */
+    #updateControlsSlider() {
+        if (!this.isControlsVisible()) {
+            return;
+        }
+        this.#menu.animationProgress = this.#getProgress();
+    }
+
+    /**
+     * Updates all controls in the animation menu (buttons, slider) to reflect the current state and progress.
+     * @private
+     */
+    #updateControls() {
+        if (!this.isControlsVisible()) {
+            return;
+        }
+        if (!this.#menu) {
+            return;
+        }
+        this.#menu.animationState = this.#state;
+        this.#menu.animationProgress = this.#getProgress();
+    }
+
+    /**
+     * ---------------------------
+     * Public methods
+     * ---------------------------
+     */
+
+    /**
+     * Checks if the animation affects the given node.
+     * @param {string} node - Node identifier.
+     * @returns {boolean}
+     */
+    isAnimationForNode(node) {
+        return this.#nodes.includes(node);
+    }
+
+    /**
+     * Starts the opening animation.
+     * @public
+     */
+    playOpen() {
+        if (this.#state === OpeningAnimation.states.opening || this.#state === OpeningAnimation.states.opened) {
+            return;
+        }
+        if (this.#state === OpeningAnimation.states.closing) {
+            this.#lastPausedFrame = this.#endFrame - this.#closeAnimation.getCurrentFrame();
+            this.#closeAnimation.pause();
+        }
+
+        if (this.#openAnimation._isStarted && this.#openAnimation._isPaused) {
+            this.#openAnimation.goToFrame(this.#lastPausedFrame);
+            this.#openAnimation.restart();
+        } else {
+            this.#openAnimation.start(false, this.#speedRatio, this.#lastPausedFrame, this.#endFrame, undefined);
+        }
+
+        this.#state = OpeningAnimation.states.opening;
+        this.#updateControls();
+    }
+
+    /**
+     * Starts the closing animation.
+     * @public
+     */
+    playClose() {
+        if (this.#state === OpeningAnimation.states.closing || this.#state === OpeningAnimation.states.closed) {
+            return;
+        }
+        if (this.#state === OpeningAnimation.states.opening) {
+            this.#lastPausedFrame = this.#openAnimation.getCurrentFrame();
+            this.#openAnimation.pause();
+        }
+
+        if (this.#closeAnimation._isStarted && this.#closeAnimation._isPaused) {
+            this.#closeAnimation.goToFrame(this.#endFrame - this.#lastPausedFrame);
+            this.#closeAnimation.restart();
+        } else {
+            this.#closeAnimation.start(false, this.#speedRatio, this.#endFrame - this.#lastPausedFrame, this.#endFrame, undefined);
+        }
+
+        this.#state = OpeningAnimation.states.closing;
+        this.#updateControls();
+    }
+
+    /**
+     * Pauses the current animation.
+     * @public
+     */
+    pause() {
+        if (this.#state === OpeningAnimation.states.opening) {
+            this.#lastPausedFrame = this.#openAnimation.getCurrentFrame();
+            this.#openAnimation.pause();
+        }
+        if (this.#state === OpeningAnimation.states.closing) {
+            this.#lastPausedFrame = this.#endFrame - this.#closeAnimation.getCurrentFrame();
+            this.#closeAnimation.pause();
+        }
+        this.#state = OpeningAnimation.states.paused;
+        this.#updateControls();
+    }
+
+    /**
+     * Moves animation to the fully opened state.
+     * @public
+     */
+    goToOpened() {
+        this.#goToOpened(false);
+    }
+
+    /**
+     * Moves animation to the fully closed state.
+     * @public
+     */
+    goToClosed() {
+        this.#goToClosed(false);
+    }
+
+    /**
+     * Displays the animation control menu and sets up callbacks.
+     * Synchronizes slider and button states with animation.
+     * @public
+     * @param {AdvancedDynamicTexture} advancedDynamicTexture - Babylon.js GUI texture.
+     */
+    showControls(advancedDynamicTexture) {
+        this.#advancedDynamicTexture = advancedDynamicTexture;
+        this.#advancedDynamicTexture.metadata = { animationName: this.name };
+        const controlCallbacks = {
+            onGoToOpened: () => {
+                if (this.#state === OpeningAnimation.states.opened) {
+                    return;
+                }
+                this.goToOpened();
+            },
+            onOpen: () => {
+                if (this.#state === OpeningAnimation.states.opened || this.#state === OpeningAnimation.states.opening) {
+                    return;
+                }
+                this.playOpen();
+            },
+            onPause: () => {
+                if (this.#state === OpeningAnimation.states.paused || this.#state === OpeningAnimation.states.closed || this.#state === OpeningAnimation.states.opened) {
+                    return;
+                }
+                this.pause();
+            },
+            onClose: () => {
+                if (this.#state === OpeningAnimation.states.closed || this.#state === OpeningAnimation.states.closing) {
+                    return;
+                }
+                this.playClose();
+            },
+            onGoToClosed: () => {
+                if (this.#state === OpeningAnimation.states.closed) {
+                    return;
+                }
+                this.goToClosed();
+            },
+            onSetAnimationProgress: (progress) => {
+                progress = this.#checkProgress(progress);
+                if (progress === 0) {
+                    this.goToClosed();
+                } else if (progress === 1) {
+                    this.goToOpened();
+                } else {
+                    const frame = this.#getFrameFromProgress(progress);
+                    this.#goToFrameAndPause(frame);
+                }
+            },
+            onToggleLoop: () => {
+                this.#loop = !this.#loop;
+                this.#menu.animationLoop = this.#loop;
+            },
+        };
+        this.#menu = new OpeningAnimationMenu(this.#advancedDynamicTexture, this.#state, this.#getProgress(), this.#loop, controlCallbacks);
+
+        // Attach to Babylon.js scene render loop for real-time updates
+        this.#openAnimation._scene.onBeforeRenderObservable.add(this.#updateControlsSlider.bind(this));
+    }
+
+    /**
+     * Hides the animation control menu and removes observers.
+     * @public
+     */
+    hideControls() {
+        if (!this.isControlsVisible()) {
+            return;
+        }
+        // Remove the observer when controls are hidden
+        this.#openAnimation._scene.onBeforeRenderObservable.removeCallback(this.#updateControlsSlider.bind(this));
+        this.#advancedDynamicTexture.dispose();
+        this.#advancedDynamicTexture = null;
+    }
+
+    /**
+     * Checks if the animation controls menu is currently visible for this animation instance.
+     * @public
+     * @returns {boolean} True if controls are visible for this animation; otherwise, false.
+     */
+    isControlsVisible() {
+        return !!(this.#advancedDynamicTexture && this.#advancedDynamicTexture.metadata?.animationName === this.name && this.#menu);
+    }
+
+    /**
+     * ---------------------------
+     * Public properties
+     * ---------------------------
+     */
+
+    /**
+     * Returns the current animation state.
+     * @public
+     * @returns {number}
+     */
+
+    get state() {
+        return this.#state;
+    }
+}

package/src/babylonjs-controller.js

@@ -1,10 +1,11 @@
-import { Engine, Scene, ArcRotateCamera, Vector3, Color4, HemisphericLight, DirectionalLight, PointLight, ShadowGenerator, LoadAssetContainerAsync, Tools, WebXRSessionManager, WebXRDefaultExperience, MeshBuilder, WebXRFeatureName, HDRCubeTexture, IblShadowsRenderPipeline } from "@babylonjs/core";
+import { ArcRotateCamera, AssetContainer, Color4, DirectionalLight, Engine, HDRCubeTexture, HemisphericLight, IblShadowsRenderPipeline, LoadAssetContainerAsync, MeshBuilder, PointLight, Scene, ShadowGenerator, Tools, Vector3, WebXRDefaultExperience, WebXRFeatureName, WebXRSessionManager } 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";
+import { ContainerData, MaterialData } from "./pref-viewer-3d-data.js";
 import BabylonJSAnimationController from "./babylonjs-animation-controller.js";
 
 /**
@@ -417,7 +418,7 @@ export default class BabylonJSController {
     /**
      * Applies material options from the configuration to the relevant meshes.
      * @private
-     * @param {object} optionMaterial - Material option containing value, nodePrefixes, nodeNames, and state.
+     * @param {MaterialData} optionMaterial - Material option containing value, nodePrefixes, nodeNames, and state.
      * @returns {boolean} True if any mesh material was set, false otherwise.
      */
     #setOptionsMaterial(optionMaterial) {
@@ -545,7 +546,7 @@ export default class BabylonJSController {
      * 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.
+     * @returns {ContainerData|null} The matching container object, or null if not found.
      */
     #findContainerByName(name) {
         return Object.values(this.#containers).find((container) => container.state.name === name) || null;
@@ -598,7 +599,7 @@ export default class BabylonJSController {
     /**
      * 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.
+     * @param {ContainerData} container - The container object containing asset state and metadata.
      * @returns {boolean} True if the container was added, false otherwise.
      */
     #addContainer(container) {
@@ -614,7 +615,7 @@ export default class BabylonJSController {
     /**
      * 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.
+     * @param {ContainerData} container - The container object containing asset state and metadata.
      * @returns {boolean} True if the container was removed, false otherwise.
      */
     #removeContainer(container) {
@@ -630,8 +631,8 @@ export default class BabylonJSController {
     /**
      * 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.
+     * @param {ContainerData} container - The container object containing asset state and metadata.
+     * @param {AssetContainer} newAssetContainer - The new asset container to add to the scene.
      * @returns {boolean} True if the container was replaced and added, false otherwise.
      */
     #replaceContainer(container, newAssetContainer) {
@@ -682,8 +683,8 @@ export default class BabylonJSController {
     /**
      * 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.
+     * @param {ContainerData} container - The container object containing asset state and metadata.
+     * @returns {Promise<[ContainerData, 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.
@@ -756,7 +757,7 @@ export default class BabylonJSController {
                         }
                         const replacedAndAdded = this.#replaceContainer(container, assetContainer);
                         if (replacedAndAdded && container.state.name === "model") {
-                            this.#babylonJSAnimationController = new BabylonJSAnimationController(this.#scene, assetContainer);
+                            this.#babylonJSAnimationController = new BabylonJSAnimationController(this.#scene);
                         }
                         container.state.setSuccess(true);
                     } else {

package/src/pref-viewer-3d.js

@@ -1,4 +1,4 @@
-import { ContainerData, MaterialData, CameraData } from "./pref-viewer-3d-data.js";
+import { CameraData, ContainerData, MaterialData } from "./pref-viewer-3d-data.js";
 import BabylonJSController from "./babylonjs-controller.js";
 
 /**

package/src/images/icon-pause.svg

@@ -1 +0,0 @@
-<svg id="pause" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#ffffff"><path d="M14,19H18V5H14M6,19H10V5H6V19Z" /></svg>

package/src/images/icon-play-backwards.svg

@@ -1 +0,0 @@
-<svg id="play_backwards" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#ffffff"><path d="M16,18.86V4.86l-11,7,11,7Z" /></svg>

package/src/images/icon-play.svg

@@ -1 +0,0 @@
-<svg id="play" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#ffffff"><path d="M8,5.14v14l11-7-11-7Z" /></svg>

package/src/images/icon-skip-backward.svg

@@ -1 +0,0 @@
-<svg id="skip-backward" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#ffffff"><path d="M20,5V19L13,12M6,5V19H4V5M13,5V19L6,12" /></svg>

package/src/images/icon-skip-forward.svg

@@ -1 +0,0 @@
-<svg id="skip-forward" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#ffffff"><path d="M4,5V19L11,12M18,5V19H20V5M11,5V19L18,12" /></svg>