@xeokit/xeokit-sdk 2.4.2-beta-14 → 2.4.2-beta-15

package/dist/xeokit-sdk.cjs.js

@@ -6653,6 +6653,8 @@ const kdTreeDimLength$1 = new Float32Array(3);
  * Automatically indexes a {@link Viewer}'s {@link Entity}s in a 3D k-d tree
  * to support fast collision detection with 3D World-space axis-aligned boundaries (AABBs) and frustums.
  *
+ * See {@link MarqueePicker} for usage example.
+ *
  * An ObjectsKdTree3 is configured with a Viewer, and will then automatically
  * keep itself populated with k-d nodes that contain the Viewer's Entitys.
  *
@@ -8581,6 +8583,87 @@ function frustumIntersectsAABB3(frustum, aabb) {
 
 /**
  * Picks a {@link Viewer}'s {@link Entity}s with a canvas-space 2D marquee box.
+ *
+ * [<img src="https://xeokit.github.io/xeokit-sdk/assets/images/MarqueeSelect.gif">](https://xeokit.github.io/xeokit-sdk/examples/picking/#marqueePick_select)
+ *
+ * * [[Example 1: Select Objects with Marquee](https://xeokit.github.io/xeokit-sdk/examples/picking/#marqueePick_select)]
+ * * [[Example 2: View-Fit Objects with Marquee](https://xeokit.github.io/xeokit-sdk/examples/picking/#marqueePick_viewFit)]
+ *
+ * # Usage
+ *
+ * In the example below, we
+ *
+ * 1. Create a {@link Viewer}, arrange the {@link Camera}
+ * 2. Use an {@link XKTLoaderPlugin} to load a BIM model,
+ * 3. Create a {@link ObjectsKdTree3} to automatically index the `Viewer's` {@link Entity}s for fast spatial lookup,
+ * 4. Create a `MarqueePicker` to pick {@link Entity}s in the {@link Viewer}, using the {@link ObjectsKdTree3} to accelerate picking
+ * 5. Create a {@link MarqueePickerMouseControl} to perform the marquee-picking with the `MarqueePicker`, using mouse input to draw the marquee box on the `Viewer's` canvas.
+ *
+ * When the {@link MarqueePickerMouseControl} is active:
+ *
+ * * Long-click, drag and release on the canvas to define a marque box that picks {@link Entity}s.
+ * * Drag left-to-right to pick {@link Entity}s that intersect the box.
+ * * Drag right-to-left to pick {@link Entity}s that are fully inside the box.
+ * * On release, the `MarqueePicker` will fire a "picked" event with IDs of the picked {@link Entity}s, if any.
+ * * Handling that event, we mark the {@link Entity}s as selected.
+ * * Hold down CTRL to multi-pick.
+ *
+ * ````javascript
+ * import {
+ *         Viewer,
+ *         XKTLoaderPlugin,
+ *         ObjectsKdTree3,
+ *         MarqueePicker,
+ *         MarqueePickerMouseControl
+ * } from "xeokit-sdk.es.js";
+ *
+ * // 1
+ *
+ * const viewer = new Viewer({
+ *     canvasId: "myCanvas"
+ * });
+ *
+ * viewer.scene.camera.eye = [14.9, 14.3, 5.4];
+ * viewer.scene.camera.look = [6.5, 8.3, -4.1];
+ * viewer.scene.camera.up = [-0.28, 0.9, -0.3];
+ *
+ * // 2
+ *
+ * const xktLoader = new XKTLoaderPlugin(viewer);
+ *
+ * const sceneModel = xktLoader.load({
+ *     id: "myModel",
+ *     src: "../../assets/models/xkt/v8/ifc/HolterTower.ifc.xkt"
+ * });
+ *
+ * // 3
+ *
+ * const objectsKdTree3 = new ObjectsKdTree3({viewer});
+ *
+ * // 4
+ *
+ * const marqueePicker = new MarqueePicker({viewer, objectsKdTree3});
+ *
+ * // 5
+ *
+ * const marqueePickerMouseControl = new MarqueePickerMouseControl({marqueePicker});
+ *
+ * marqueePicker.on("clear", () => {
+ *     viewer.scene.setObjectsSelected(viewer.scene.selectedObjectIds, false);
+ * });
+ *
+ * marqueePicker.on("picked", (objectIds) => {
+ *     viewer.scene.setObjectsSelected(objectIds, true);
+ * });
+ *
+ * marqueePickerMouseControl.setActive(true);
+ * ````
+ *
+ * # Design Notes
+ *
+ * * The {@link ObjectsKdTree3} can be shared with any other components that want to use it to spatially search for {@link Entity}s.
+ * * The {@link MarqueePickerMouseControl} can be replaced with other types of controllers (i.e. touch), or used alongside them.
+ * * The `MarqueePicker` has no input handlers of its own, and provides an API through which to programmatically control marquee picking. By firing the "picked" events, `MarqueePicker` implements the *Blackboard Pattern*.
  */
 class MarqueePicker extends Component {
 
@@ -8850,6 +8933,8 @@ MarqueePicker.PICK_MODE_INSIDE = 1;
 /**
  * Controls a {@link MarqueePicker} with mouse input.
  *
+ * See {@link MarqueePicker} for usage example.
+ *
  * When the MarqueePickerMouseControl is active:
  *
  * * Long-click, drag and release on the canvas to define a marque box that picks {@link Entity}s.
@@ -20018,23 +20103,31 @@ class Input extends Component {
             }
         });
 
+        const tickifedMouseMoveFn = this.scene.tickify(
+            () => this.fire("mousemove", this.mouseCanvasPos, true)
+        );
+
         this.element.addEventListener("mousemove", this._mouseMoveListener = (e) => {
             if (!this.enabled) {
                 return;
             }
             this._getMouseCanvasPos(e);
-            this.fire("mousemove", this.mouseCanvasPos, true);
+            tickifedMouseMoveFn();  
             if (this.mouseover) {
                 e.preventDefault();
             }
         });
 
+        const tickifiedMouseWheelFn = this.scene.tickify(
+            (delta) => { this.fire("mousewheel", delta, true); }
+        );
+
         this.element.addEventListener("wheel", this._mouseWheelListener = (e, d) => {
             if (!this.enabled) {
                 return;
             }
             const delta = Math.max(-1, Math.min(1, -e.deltaY * 40));
-            this.fire("mousewheel", delta, true);
+            tickifiedMouseWheelFn(delta);
         }, {passive: true});
 
         // mouseclicked
@@ -27858,6 +27951,11 @@ class Scene extends Component {
             throw "Mandatory config expected: valid canvasId or canvasElement";
         }
 
+        /**
+         * @type {{[key: string]: {wrapperFunc: Function, tickSubId: string}}}
+         */
+        this._tickifiedFunctions = {};
+
         const transparent = (!!cfg.transparent);
         const alphaDepthMask = (!!cfg.alphaDepthMask);
 
@@ -30020,6 +30118,63 @@ class Scene extends Component {
         return changed;
     }
 
+    /**
+     * This method will "tickify" the provided `cb` function.
+     * 
+     * This means, the function will be wrapped so:
+     * 
+     * - it runs time-aligned to scene ticks
+     * - it runs maximum once per scene-tick
+     * 
+     * @param {Function} cb The function to tickify
+     * @returns {Function)}
+     */
+    tickify(cb) {
+        const cbString = cb.toString();
+
+        /**
+         * Check if the function is already tickified, and if so return the cached one.
+         */
+        if (cbString in this._tickifiedFunctions) {
+            return this._tickifiedFunctions[cbString].wrapperFunc;
+        }
+
+        let alreadyRun = 0;
+        let needToRun = 0;
+
+        let lastArgs;
+
+        /**
+         * The provided `cb` function is replaced with a "set-dirty" function
+         * 
+         * @type {Function}
+         */
+        const wrapperFunc = function (...args) {
+            lastArgs = args;
+            needToRun++;
+        };
+
+        /**
+         * An each scene tick, if the "dirty-flag" is set, run the `cb` function.
+         * 
+         * This will make it run time-aligned to the scene tick.
+         */
+        const tickSubId = this.on("tick", () => {
+            const tmp = needToRun;
+            if (tmp > alreadyRun) {
+                alreadyRun = tmp;
+                cb(...lastArgs);
+            }
+        });
+
+        /**
+         * And, store the list of subscribers.
+         */
+        this._tickifiedFunctions[cbString] = { tickSubId, wrapperFunc };
+
+        return wrapperFunc;
+    }
+
     /**
      * Destroys this Scene.
      */
@@ -87287,29 +87442,12 @@ class PickController {
         this._lastPickedEntityId = null;
 
         this._needFireEvents = 0;
-
-        this._needToUpdate = false;
-
-        this._tickSub = this._scene.on("tick", () => {
-            this.runUpdate();
-        });
-    }
-
-    update() {
-        this._needToUpdate = true;
     }
 
     /**
      * Immediately attempts a pick, if scheduled.
      */
-    runUpdate() {
-
-        if (!this._needToUpdate) {
-            return;
-        }
-
-        this._needToUpdate = false;
-
+    update() {
         if (!this._configs.pointerEnabled) {
             return;
         }
@@ -87484,10 +87622,6 @@ class PickController {
 
         this._needFireEvents = 0;
     }
-
-    destroy() {
-        this._scene.off(this._tickSub);
-    }
 }
 
 /**
@@ -87982,75 +88116,78 @@ class MousePickHandler {
             }
         };
 
-        canvas.addEventListener("mousemove", this._canvasMouseMoveHandler = (e) => {
+        const tickifiedMouseMoveFn = scene.tickify (
+            this._canvasMouseMoveHandler = (e) => {
+                if (!(configs.active && configs.pointerEnabled)) {
+                    return;
+                }
 
-            if (!(configs.active && configs.pointerEnabled)) {
-                return;
-            }
+                if (leftDown || rightDown) {
+                    return;
+                }
 
-            if (leftDown || rightDown) {
-                return;
-            }
+                const hoverSubs = cameraControl.hasSubs("hover");
+                const hoverEnterSubs = cameraControl.hasSubs("hoverEnter");
+                const hoverOutSubs = cameraControl.hasSubs("hoverOut");
+                const hoverOffSubs = cameraControl.hasSubs("hoverOff");
+                const hoverSurfaceSubs = cameraControl.hasSubs("hoverSurface");
+                const hoverSnapOrSurfaceSubs = cameraControl.hasSubs("hoverSnapOrSurface");
 
-            const hoverSubs = cameraControl.hasSubs("hover");
-            const hoverEnterSubs = cameraControl.hasSubs("hoverEnter");
-            const hoverOutSubs = cameraControl.hasSubs("hoverOut");
-            const hoverOffSubs = cameraControl.hasSubs("hoverOff");
-            const hoverSurfaceSubs = cameraControl.hasSubs("hoverSurface");
-            const hoverSnapOrSurfaceSubs = cameraControl.hasSubs("hoverSnapOrSurface");
+                if (hoverSubs || hoverEnterSubs || hoverOutSubs || hoverOffSubs || hoverSurfaceSubs || hoverSnapOrSurfaceSubs) {
 
-            if (hoverSubs || hoverEnterSubs || hoverOutSubs || hoverOffSubs || hoverSurfaceSubs || hoverSnapOrSurfaceSubs) {
+                    pickController.pickCursorPos = states.pointerCanvasPos;
+                    pickController.schedulePickEntity = true;
+                    pickController.schedulePickSurface = hoverSurfaceSubs;
+                    pickController.scheduleSnapOrPick = hoverSnapOrSurfaceSubs;
 
-                pickController.pickCursorPos = states.pointerCanvasPos;
-                pickController.schedulePickEntity = true;
-                pickController.schedulePickSurface = hoverSurfaceSubs;
-                pickController.scheduleSnapOrPick = hoverSnapOrSurfaceSubs;
+                    pickController.update();
 
-                pickController.update();
+                    if (pickController.pickResult) {
 
-                if (pickController.pickResult) {
+                        if (pickController.pickResult.entity) {
+                            const pickedEntityId = pickController.pickResult.entity.id;
+
+                            if (this._lastPickedEntityId !== pickedEntityId) {
 
-                    if (pickController.pickResult.entity) {
-                        const pickedEntityId = pickController.pickResult.entity.id;
+                                if (this._lastPickedEntityId !== undefined) {
 
-                        if (this._lastPickedEntityId !== pickedEntityId) {
+                                    cameraControl.fire("hoverOut", { // Hovered off an entity
+                                        entity: scene.objects[this._lastPickedEntityId]
+                                    }, true);
+                                }
 
-                            if (this._lastPickedEntityId !== undefined) {
+                                cameraControl.fire("hoverEnter", pickController.pickResult, true); // Hovering over a new entity
 
-                                cameraControl.fire("hoverOut", { // Hovered off an entity
-                                    entity: scene.objects[this._lastPickedEntityId]
-                                }, true);
+                                this._lastPickedEntityId = pickedEntityId;
                             }
+                        }
 
-                            cameraControl.fire("hoverEnter", pickController.pickResult, true); // Hovering over a new entity
+                        cameraControl.fire("hover", pickController.pickResult, true);
 
-                            this._lastPickedEntityId = pickedEntityId;
+                        if (pickController.pickResult.worldPos || pickController.pickResult.snappedWorldPos) { // Hovering the surface of an entity
+                            cameraControl.fire("hoverSurface", pickController.pickResult, true);
                         }
-                    }
 
-                    cameraControl.fire("hover", pickController.pickResult, true);
+                    } else {
 
-                    if (pickController.pickResult.worldPos || pickController.pickResult.snappedWorldPos) { // Hovering the surface of an entity
-                        cameraControl.fire("hoverSurface", pickController.pickResult, true);
-                    }
+                        if (this._lastPickedEntityId !== undefined) {
 
-                } else {
+                            cameraControl.fire("hoverOut", { // Hovered off an entity
+                                entity: scene.objects[this._lastPickedEntityId]
+                            }, true);
 
-                    if (this._lastPickedEntityId !== undefined) {
+                            this._lastPickedEntityId = undefined;
+                        }
 
-                        cameraControl.fire("hoverOut", { // Hovered off an entity
-                            entity: scene.objects[this._lastPickedEntityId]
+                        cameraControl.fire("hoverOff", { // Not hovering on any entity
+                            canvasPos: pickController.pickCursorPos
                         }, true);
-
-                        this._lastPickedEntityId = undefined;
                     }
-
-                    cameraControl.fire("hoverOff", { // Not hovering on any entity
-                        canvasPos: pickController.pickCursorPos
-                    }, true);
                 }
             }
-        });
+        );
+
+        canvas.addEventListener("mousemove", tickifiedMouseMoveFn);
 
         canvas.addEventListener('mousedown', this._canvasMouseDownHandler = (e) => {