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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preference-sl/pref-viewer",
-  "version": "2.11.0-beta.3",
+  "version": "2.11.0-beta.4",
   "description": "Web Component to preview GLTF models with Babylon.js",
   "author": "Alex Moreno Palacio <amoreno@preference.es>",
   "scripts": {
@@ -30,7 +30,6 @@
   "sideEffects": false,
   "files": [
     "src",
-    "src/images",
     "index.d.ts"
   ],
   "dependencies": {

package/src/babylonjs-animation-controller.js

@@ -1,382 +1,21 @@
-import { Color3, PointerEventTypes, HighlightLayer } from "@babylonjs/core";
-import { AdvancedDynamicTexture, StackPanel, Control, Button, Image } from "@babylonjs/gui";
-
-// https://doc.babylonjs.com/typedoc/classes/BABYLON.AnimationGroup
-class OpeningAnimationController {
-    static states = {
-        paused: 0,
-        closed: 1,
-        opened: 2,
-        opening: 3,
-        closing: 4,
-    };
-
-    #openAnimation = null;
-    #closeAnimation = null;
-
-    #nodes = [];
-    #state = OpeningAnimationController.states.closed;
-    #currentFrame = 0;
-    #startFrame = 0;
-    #endFrame = 0;
-    #speedRatio = 1.0;
-
-    #advancedDynamicTexture = null;
-    #menu = null;
-
-    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));
-    }
-
-    #getNodesFromAnimationGroups() {
-        [this.#openAnimation, this.#closeAnimation].forEach((animationGroup) => {
-            animationGroup._targetedAnimations.forEach((targetedAnimation) => {
-                if (!this.#nodes.includes(targetedAnimation.target.id)) {
-                    this.#nodes.push(targetedAnimation.target.id);
-                }
-            });
-        });
-    }
-
-    #onOpened() {
-        this.goToOpened();
-    }
-
-    #onClosed() {
-        this.goToClosed();
-    }
-
-    /**
-     * ---------------------------
-     * Public methods
-     * ---------------------------
-     */
-
-    isAnimationForNode(node) {
-        return this.#nodes.includes(node);
-    }
-
-    playOpen() {
-        if (this.#state === OpeningAnimationController.states.opening || this.#state === OpeningAnimationController.states.opened) {
-            return;
-        }
-        if (this.#state === OpeningAnimationController.states.closing) {
-            this.#currentFrame = this.#endFrame - this.#closeAnimation.getCurrentFrame();
-            this.#closeAnimation.pause();
-        }
-
-        if (this.#openAnimation._isStarted && this.#openAnimation._isPaused) {
-            this.#openAnimation.goToFrame(this.#currentFrame);
-            this.#openAnimation.restart();
-        } else {
-            this.#openAnimation.start(false, this.#speedRatio, this.#currentFrame, this.#endFrame, undefined);
-        }
-
-        this.#state = OpeningAnimationController.states.opening;
-        this.updateControls();
-    }
-
-    playClose() {
-        if (this.#state === OpeningAnimationController.states.closing || this.#state === OpeningAnimationController.states.closed) {
-            return;
-        }
-        if (this.#state === OpeningAnimationController.states.opening) {
-            this.#currentFrame = this.#openAnimation.getCurrentFrame();
-            this.#openAnimation.pause();
-        }
-
-        if (this.#closeAnimation._isStarted && this.#closeAnimation._isPaused) {
-            this.#closeAnimation.goToFrame(this.#endFrame - this.#currentFrame);
-            this.#closeAnimation.restart();
-        } else {
-            this.#closeAnimation.start(false, this.#speedRatio, this.#endFrame - this.#currentFrame, this.#endFrame, undefined);
-        }
-
-        this.#state = OpeningAnimationController.states.closing;
-        this.updateControls();
-    }
-
-    pause() {
-        if (this.#state === OpeningAnimationController.states.opening) {
-            this.#currentFrame = this.#openAnimation.getCurrentFrame();
-            this.#openAnimation.pause();
-        }
-        if (this.#state === OpeningAnimationController.states.closing) {
-            this.#currentFrame = this.#endFrame - this.#closeAnimation.getCurrentFrame();
-            this.#closeAnimation.pause();
-        }
-        this.#state = OpeningAnimationController.states.paused;
-        this.updateControls();
-    }
-
-    goToOpened() {
-        this.#currentFrame = this.#endFrame;
-
-        if (this.#openAnimation._isStarted) {
-            this.#openAnimation.start();
-        }
-        this.#openAnimation.pause();
-        this.#openAnimation.goToFrame(this.#endFrame);
-
-        if (!this.#closeAnimation._isStarted) {
-            this.#closeAnimation.start();
-        }
-        this.#closeAnimation.pause();
-        this.#closeAnimation.goToFrame(this.#startFrame);
-
-        this.#state = OpeningAnimationController.states.opened;
-        this.updateControls();
-    }
-
-    goToClosed() {
-        this.#currentFrame = this.#startFrame;
-        if (this.#openAnimation._isStarted) {
-            this.#openAnimation.start();
-        }
-        this.#openAnimation.pause();
-        this.#openAnimation.goToFrame(this.#startFrame);
-
-        if (this.#closeAnimation._isStarted) {
-            this.#closeAnimation.start();
-        }
-        this.#closeAnimation.pause();
-        this.#closeAnimation.goToFrame(this.#endFrame);
-
-        this.#state = OpeningAnimationController.states.closed;
-        this.updateControls();
-    }
-
-    showControls(advancedDynamicTexture, mesh) {
-        this.#advancedDynamicTexture = advancedDynamicTexture;
-        this.#advancedDynamicTexture.metadata = { name: this.name };
-        const controlCallbacks = {
-            onGoToOpened: () => {
-                if (this.#state === OpeningAnimationController.states.opened) {
-                    return;
-                }
-                this.goToOpened();
-                this.hideControls();
-            },
-            onOpen: () => {
-                if (this.#state === OpeningAnimationController.states.opened || this.#state === OpeningAnimationController.states.opening) {
-                    return;
-                }
-                this.playOpen();
-                this.hideControls();
-            },
-            onPause: () => {
-                if (this.#state === OpeningAnimationController.states.paused || this.#state === OpeningAnimationController.states.closed || this.#state === OpeningAnimationController.states.opened) {
-                    return;
-                }
-                this.pause();
-                this.hideControls();
-            },
-            onClose: () => {
-                if (this.#state === OpeningAnimationController.states.closed || this.#state === OpeningAnimationController.states.closing) {
-                    return;
-                }
-                this.playClose();
-                this.hideControls();
-            },
-            onGoToClosed: () => {
-                if (this.#state === OpeningAnimationController.states.closed) {
-                    return;
-                }
-                this.goToClosed();
-                this.hideControls();
-            },
-        };
-        this.#menu = new AnimationMenu(this.#advancedDynamicTexture, mesh, this.#state, controlCallbacks);
-    }
-
-    hideControls() {
-        if (!this.isControlsVisible()) {
-            return;
-        }
-        this.#advancedDynamicTexture.dispose();
-        this.#advancedDynamicTexture = null;
-    }
-
-    updateControls() {
-        if (!this.isControlsVisible()) {
-            return;
-        }
-        if (!this.#menu) {
-            return;
-        }
-        this.#menu.animationState = this.#state;
-    }
-
-    isControlsVisible() {
-        return this.#advancedDynamicTexture !== null || this.#advancedDynamicTexture?.metadata?.name === this.name;
-    }
-
-    /**
-     * ---------------------------
-     * Public properties
-     * ---------------------------
-     */
-
-    get state() {
-        return this.#state;
-    }
-}
-
-/**
- * AnimationMenu - Models and renders a popup menu for controlling animation playback in a Babylon.js 3D scene.
- *
- * Responsibilities:
- *  - Creates a Babylon.js GUI panel with buttons for animation actions (open, close, pause, go to opened/closed).
- *  - Handles button states (enabled/disabled, active/inactive) based on animation state.
- *  - Attaches the menu to a mesh and disposes it when an action is taken.
- *  - Allows external callbacks for each action.
- *
- * Usage:
- *  const menu = new AnimationMenu(advancedDynamicTexture, mesh, animationState, {
- *      onOpen: () => { ... },
- *      onClose: () => { ... },
- *      onPause: () => { ... },
- *      onGoToOpened: () => { ... },
- *      onGoToClosed: () => { ... }
- *  });
- *  menu.show();
- *  menu.hide();
- */
-
-class AnimationMenu {
-    #advancedDynamicTexture = null;
-    #animationState = OpeningAnimationController.states.closed;
-    #mesh = null;
-    #callbacks = null;
-    #panel = null;
-    #colorActive = "#6BA53A";
-    #colorEnabled = "#333333";
-    #colorDisabled = "#777777";
-
-    /**
-     * @param {AdvancedDynamicTexture} advancedDynamicTexture - Babylon.js GUI texture.
-     * @param {BABYLON.Mesh} mesh - Mesh to attach the menu to.
-     * @param {number} animationState - Current animation state (enum).
-     * @param {object} callbacks - Callback functions for menu actions.
-     */
-    constructor(advancedDynamicTexture, mesh, animationState, callbacks) {
-        this.#advancedDynamicTexture = advancedDynamicTexture;
-        this.#mesh = mesh;
-        this.#animationState = animationState;
-        this.#callbacks = callbacks;
-
-        this.#createMenu(animationState);
-    }
-
-    /**
-     * Renders the menu and attaches it to the mesh.
-     */
-    #createMenu() {
-        if (!this.#advancedDynamicTexture || !this.#mesh) {
-            return;
-        }
-        this.#panel = new StackPanel();
-        this.#panel.isVertical = false;
-        this.#panel.verticalAlignment = Control.VERTICAL_ALIGNMENT_BOTTOM;
-        this.#panel.left = 0;
-        this.#panel.top = 0;
-        this.#advancedDynamicTexture.addControl(this.#panel);
-        this.#panel.linkWithMesh(this.#mesh);
-
-        this.#createButtons();
-        this.#setButtonsState();
-    }
-
-    /**
-     * Internal helper to add a button to the menu.
-     * @private
-     */
-    #addButton(name, imageURL, callback) {
-        const button = Button.CreateImageOnlyButton(`button_animation_${name}`, imageURL);
-        button.image.stretch = Image.STRETCH_UNIFORM;
-        button.color = "white";
-        button.hoverCursor = "pointer";
-        button.width = "28px";
-        button.height = "28px";
-        button.cornerRadius = 0;
-        button.background = this.#colorEnabled;
-        button.onPointerUpObservable.add(() => {
-            if (callback) {
-                callback();
-            }
-        });
-        this.#panel.addControl(button);
-    }
-
-    #createButtons() {
-        this.#addButton("closed", "../src/images/icon-skip-backward.svg", this.#callbacks.onGoToClosed);
-        this.#addButton("close", "../src/images/icon-play-backwards.svg", this.#callbacks.onClose);
-        this.#addButton("pause", "../src/images/icon-pause.svg", this.#callbacks.onPause);
-        this.#addButton("open", "../src/images/icon-play.svg", this.#callbacks.onOpen);
-        this.#addButton("opened", "../src/images/icon-skip-forward.svg", this.#callbacks.onGoToOpened);
-    }
-
-    #setButtonState(name, enabled, active) {
-        const button = this.#advancedDynamicTexture.getControlByName(`button_animation_${name}`);
-        if (!button) {
-            return;
-        }
-        button.background = active ? this.#colorActive : enabled ? this.#colorEnabled : this.#colorDisabled;
-    }
-
-    #setButtonsState() {
-        const goToOpenedButtonEnabled = this.#animationState !== OpeningAnimationController.states.opened;
-        const goToOpenedButtonActive = false;
-        const openButtonEnabled = this.#animationState !== OpeningAnimationController.states.opened && this.#animationState !== OpeningAnimationController.states.opening;
-        const openButtonActive = this.#animationState === OpeningAnimationController.states.opening;
-        const pauseButtonEnabled = this.#animationState !== OpeningAnimationController.states.paused && this.#animationState !== OpeningAnimationController.states.closed && this.#animationState !== OpeningAnimationController.states.opened;
-        const pauseButtonActive = this.#animationState === OpeningAnimationController.states.paused;
-        const closeButtonEnabled = this.#animationState !== OpeningAnimationController.states.closed && this.#animationState !== OpeningAnimationController.states.closing;
-        const closeButtonActive = this.#animationState === OpeningAnimationController.states.closing;
-        const goToClosedButtonEnabled = this.#animationState !== OpeningAnimationController.states.closed;
-        const goToClosedButtonActive = false;
-
-        this.#setButtonState("opened", goToOpenedButtonEnabled, goToOpenedButtonActive);
-        this.#setButtonState("open", openButtonEnabled, openButtonActive);
-        this.#setButtonState("pause", pauseButtonEnabled, pauseButtonActive);
-        this.#setButtonState("close", closeButtonEnabled, closeButtonActive);
-        this.#setButtonState("closed", goToClosedButtonEnabled, goToClosedButtonActive);
-    }
-
-    set animationState(state) {
-        this.#animationState = state;
-        this.#setButtonsState();
-    }
-}
+import { Color3, HighlightLayer, Mesh, PickingInfo, PointerEventTypes, Scene } from "@babylonjs/core";
+import { AdvancedDynamicTexture } from "@babylonjs/gui";
+import { OpeningAnimation } from "./babylonjs-animation-opening.js";
 
 /**
  * BabylonJSAnimationController - Manages animation playback and interactive highlighting for model containers in Babylon.js scenes.
  *
  * Responsibilities:
- *  - Detects if the loaded model container contains animations.
- *  - Controls playback state: playing forward, playing backward, paused.
- *  - Tracks and manages animated transformation nodes.
- *  - Highlights animated nodes when hovered by the cursor.
- *  - Provides API for play, pause, reverse, and highlight operations.
+ *  - Detects and groups opening/closing animations in the scene.
+ *  - Tracks animated transformation nodes and their relationships to meshes.
+ *  - Highlights animated nodes and their child meshes when hovered.
+ *  - Displays and disposes the animation control menu (GUI) for animated nodes.
+ *  - Provides API for interaction and animation control.
+ *
+ * @class
  */
 export default class BabylonJSAnimationController {
     #scene = null;
-    #assetContainer = null;
     #animatedNodes = [];
     #highlightLayer = null;
     #highlightColor = new Color3(0, 1, 0); // Color para resaltar los elementos animados (Verde)
@@ -384,31 +23,33 @@ export default class BabylonJSAnimationController {
     #openingAnimations = [];
 
     /**
-     * @param {BABYLON.Scene} scene - The Babylon.js scene instance.
-     * @param {BABYLON.AssetContainer} assetContainer - The loaded asset container.
+     * Creates a new BabylonJSAnimationController for a Babylon.js scene.
+     * @param {Scene} scene - The Babylon.js scene instance.
      */
-    constructor(scene, assetContainer) {
+    constructor(scene) {
         this.#scene = scene;
-        this.#assetContainer = assetContainer;
         this.#initializeAnimations();
         this.#setupPointerObservers();
     }
 
     /**
-     * Detects and stores animatable objects and animated nodes in the model container.
+     * Detects and stores animatable objects and animated nodes in the scene.
      * @private
      */
     #initializeAnimations() {
-        if (!this.#assetContainer.animationGroups.length) {
+        if (!this.#scene.animationGroups.length) {
             return;
         }
-
         this.#getAnimatedNodes();
         this.#getOpeneingAnimations();
     }
 
+    /**
+     * Collects the IDs of all nodes targeted by any animation group in the scene.
+     * @private
+     */
     #getAnimatedNodes() {
-        this.#assetContainer.animationGroups.forEach((animationGroup) => {
+        this.#scene.animationGroups.forEach((animationGroup) => {
             if (!animationGroup._targetedAnimations.length) {
                 return;
             }
@@ -420,9 +61,15 @@ export default class BabylonJSAnimationController {
         });
     }
 
+    /**
+     * Groups opening and closing animations by node name and creates OpeningAnimation instances.
+     * @private
+     * @description
+     * Uses animation group names with the pattern "animation_open_<name>" and "animation_close_<name>".
+     */
     #getOpeneingAnimations() {
         const openings = {};
-        this.#assetContainer.animationGroups.forEach((animationGroup) => {
+        this.#scene.animationGroups.forEach((animationGroup) => {
             const match = animationGroup.name.match(/^animation_(open|close)_(.+)$/);
             if (!match) {
                 return;
@@ -439,21 +86,25 @@ export default class BabylonJSAnimationController {
         });
 
         Object.values(openings).forEach((opening) => {
-            this.#openingAnimations.push(new OpeningAnimationController(opening.name, opening.animationOpen, opening.animationClose));
+            this.#openingAnimations.push(new OpeningAnimation(opening.name, opening.animationOpen, opening.animationClose));
         });
     }
 
+    /**
+     * Finds the OpeningAnimation instance associated with a given node ID.
+     * @private
+     * @param {string} nodeId - The node identifier.
+     * @returns {OpeningAnimation|null} The matching OpeningAnimation instance or null.
+     */
     #getOpeningAnimationByNode(nodeId) {
         return this.#openingAnimations.find((openingAnimation) => openingAnimation.isAnimationForNode(nodeId));
     }
 
     /**
-     * Busca si una malla pertenece a un nodo que es objetivo de alguna animación
-     * @param {BABYLON.Mesh} mesh Malla
-     * @param {Array} targetNodeIds Array con los identificadores de los nodos que son objetivo de alguna animación
-     * @returns {Array} Array de 2 posiciones: [0] Identificador del nodo que es objetivo de alguna animación (o false si no lo es), [1] Array con las mallas hijas del nodo que es objetivo de alguna animación (o vacío si no lo es)
-     * @description
-     * El segundo elemento del array devuelto es se necesita para poder resaltar esas mallas hijas cuando el puntero del ratón está sobre alguna de ellas
+     * Determines if a mesh belongs to a node targeted by an animation.
+     * @private
+     * @param {Mesh} mesh - The mesh to check.
+     * @returns {string|false} The animated node ID if found, otherwise false.
      */
     #getNodeAnimatedByMesh = function (mesh) {
         let nodeId = false;
@@ -468,8 +119,9 @@ export default class BabylonJSAnimationController {
     };
 
     /**
-     * Ilumina las mallas que son objetivo de alguna animación si el puntero del ratón está sobre una de ellas
-     * @param {BABYLON.PickingInfo} pickingInfo Información del trazado del rayo desde la cámara activa hasta el puntero del ratón
+     * Highlights meshes that are children of an animated node when hovered.
+     * @private
+     * @param {PickingInfo} pickingInfo - Raycast info from pointer position.
      */
     #hightlightMeshesForAnimation(pickingInfo) {
         if (!this.#highlightLayer) {
@@ -494,7 +146,7 @@ export default class BabylonJSAnimationController {
     }
 
     /**
-     * Sets up pointer observers to highlight animated nodes on hover.
+     * Sets up pointer observers to highlight animated nodes on hover and show the animation menu on click.
      * @private
      */
     #setupPointerObservers() {
@@ -504,7 +156,7 @@ export default class BabylonJSAnimationController {
                 this.#hightlightMeshesForAnimation(pickingInfo);
             }
             if (pointerInfo.type === PointerEventTypes.POINTERUP) {
-                // Eliminar cualquier Babylon GUI que se haya creado anteriormente
+                // Remove any previously created Babylon GUI
                 if (this.#advancedDynamicTexture) {
                     this.#advancedDynamicTexture.dispose();
                     this.#advancedDynamicTexture = null;
@@ -515,6 +167,13 @@ export default class BabylonJSAnimationController {
         });
     }
 
+    /**
+     * Displays the animation control menu for the animated node under the pointer.
+     * @private
+     * @param {PickingInfo} pickingInfo - Raycast info from pointer position.
+     * @description
+     * Creates the GUI if needed and invokes OpeningAnimation.showControls.
+     */
     #showMenu(pickingInfo) {
         if (!pickingInfo?.hit && !pickingInfo?.pickedMesh) {
             return;
@@ -531,6 +190,6 @@ export default class BabylonJSAnimationController {
         if (!this.#advancedDynamicTexture) {
             this.#advancedDynamicTexture = AdvancedDynamicTexture.CreateFullscreenUI("UI_Animation");
         }
-        openingAnimation.showControls(this.#advancedDynamicTexture, pickingInfo.pickedMesh);
+        openingAnimation.showControls(this.#advancedDynamicTexture);
     }
 }