@preference-sl/pref-viewer 2.16.2 → 2.17.0-beta.1

package/src/babylonjs-selection-controller.js

@@ -0,0 +1,215 @@
+/**
+ * Applies semantic selection state to Babylon model meshes using non-destructive overlays.
+ * Retains the semantic snapshot across model replacements and restores original overlays on cleanup.
+ * @class BabylonJSSelectionController
+ */
+export default class BabylonJSSelectionController {
+    #getModelMeshes;
+    #requestRender;
+    #selectableColor;
+    #selectedColor;
+    #overlayAlpha;
+    #originalOverlays = new Map();
+    #state = {};
+
+    /**
+     * Removes the glTF loader suffix from a mesh id while preserving every other id shape.
+     * @public
+     * @static
+     * @param {unknown} value - Mesh id candidate.
+     * @returns {string} Normalized semantic id, or an empty string when unusable.
+     */
+    static normalizeMeshId(value) {
+        return typeof value === "string" ? value.replace(/_primitive\d+$/, "") : "";
+    }
+
+    /**
+     * Determines whether a completed pointer gesture represents a primary click.
+     * @public
+     * @static
+     * @param {{x:number,y:number,button:number,pointerId?:number,dragged?:boolean}|null} start - Pointer-down snapshot.
+     * @param {{x:number,y:number,button:number,pointerId?:number}|null} end - Pointer-up snapshot.
+     * @param {number} maxDistancePx - Maximum Euclidean movement in CSS pixels.
+     * @returns {boolean} Whether the gesture is a click.
+     */
+    static isPrimaryClickGesture(start, end, maxDistancePx) {
+        if (!start || !end || start.button !== 0 || end.button !== 0 || start.dragged || start.pointerId !== end.pointerId) {
+            return false;
+        }
+        return Math.hypot(end.x - start.x, end.y - start.y) <= maxDistancePx;
+    }
+
+    /**
+     * Checks that a model mesh has geometry and can participate in semantic picking.
+     * Explicit ray predicates bypass Babylon's default visibility and pickability checks.
+     * @public
+     * @static
+     * @param {object} mesh - Babylon mesh considered by the picking predicate.
+     * @param {Set<object>} modelMeshes - Mesh references belonging to the model container.
+     * @returns {boolean} Whether the mesh is visible, enabled, pickable and has vertices.
+     */
+    static isPickableModelMesh(mesh, modelMeshes) {
+        return modelMeshes.has(mesh) && mesh.isVisible !== false && mesh.visibility !== 0
+            && mesh.isPickable !== false && mesh.isEnabled?.() !== false
+            && (mesh.getTotalVertices?.() ?? 0) > 0;
+    }
+
+    /**
+     * Builds the set of model meshes accepted by picking, including Babylon instances owned by them.
+     * @public
+     * @static
+     * @param {Array<object>} meshes - Meshes from the model AssetContainer.
+     * @returns {Set<object>} Accepted model mesh references.
+     */
+    static getModelMeshSet(meshes = []) {
+        const result = new Set();
+        for (const mesh of meshes ?? []) {
+            if (!mesh) {
+                continue;
+            }
+            result.add(mesh);
+            for (const instance of mesh.instances ?? []) {
+                result.add(instance);
+            }
+        }
+        return result;
+    }
+
+    /**
+     * Converts ordered Babylon ray hits into the public semantic mesh-id list.
+     * @public
+     * @static
+     * @param {Array<object>} picks - Babylon PickingInfo results.
+     * @param {Array<object>} modelMeshes - Meshes belonging to the model container.
+     * @returns {string[]} Stable, distance-ordered, deduplicated semantic ids.
+     */
+    static collectPickedMeshIds(picks = [], modelMeshes = []) {
+        const acceptedMeshes = BabylonJSSelectionController.getModelMeshSet(modelMeshes);
+        const ids = [];
+        const seen = new Set();
+        [...(picks ?? [])]
+            .filter((pick) => pick?.hit === true && acceptedMeshes.has(pick.pickedMesh))
+            .sort((left, right) => (left.distance ?? Number.POSITIVE_INFINITY) - (right.distance ?? Number.POSITIVE_INFINITY))
+            .forEach((pick) => {
+                const id = BabylonJSSelectionController.normalizeMeshId(pick.pickedMesh?.id);
+                if (id && !seen.has(id)) {
+                    seen.add(id);
+                    ids.push(id);
+                }
+            });
+        return ids;
+    }
+
+    /**
+     * Creates a controller with a live model-mesh provider and selection presentation settings.
+     * @public
+     * @param {function(): Array<object>} getModelMeshes - Returns current model meshes.
+     * @param {{selectableColor:object,selectedColor:object,overlayAlpha:number,requestRender?:function():void}} options - Overlay configuration.
+     */
+    constructor(getModelMeshes, options) {
+        this.#getModelMeshes = getModelMeshes;
+        this.#selectableColor = options.selectableColor;
+        this.#selectedColor = options.selectedColor;
+        this.#overlayAlpha = options.overlayAlpha;
+        this.#requestRender = options.requestRender ?? (() => {});
+    }
+
+    /**
+     * Applies a complete selection snapshot to every matching model mesh.
+     * @public
+     * @param {{selectableIds?:string[],selectedIds?:string[],selectedItems?:Array<{id:string,highlights?:string[]}>}} state - Canonical selection state.
+     * @returns {void}
+     */
+    applySelectionState(state = {}) {
+        this.#state = state;
+        this.refresh();
+    }
+
+    /**
+     * Reapplies the retained snapshot after model meshes are replaced.
+     * Restores removed meshes, gives selected ids priority and requests rendering only on changes.
+     * @public
+     * @returns {void}
+     */
+    refresh() {
+        const selectableIds = new Set(this.#state.selectableIds ?? []);
+        const selectedIds = new Set(this.#state.selectedIds ?? []);
+        for (const item of this.#state.selectedItems ?? []) {
+            if (item?.id) {
+                selectedIds.add(item.id);
+            }
+            for (const id of item?.highlights ?? []) {
+                selectedIds.add(id);
+            }
+        }
+
+        const currentMeshes = new Set(BabylonJSSelectionController.getModelMeshSet(this.#getModelMeshes?.() ?? []));
+        let changed = false;
+        for (const mesh of this.#originalOverlays.keys()) {
+            if (!currentMeshes.has(mesh)) {
+                changed = this.#restoreMesh(mesh) || changed;
+            }
+        }
+
+        for (const mesh of currentMeshes) {
+            const id = BabylonJSSelectionController.normalizeMeshId(mesh?.id);
+            const color = selectedIds.has(id)
+                ? this.#selectedColor
+                : (selectableIds.has(id) ? this.#selectableColor : null);
+            if (color) {
+                if (!this.#originalOverlays.has(mesh)) {
+                    this.#originalOverlays.set(mesh, {
+                        renderOverlay: mesh.renderOverlay,
+                        overlayColor: mesh.overlayColor,
+                        overlayAlpha: mesh.overlayAlpha,
+                    });
+                }
+                if (mesh.renderOverlay !== true || mesh.overlayColor !== color || mesh.overlayAlpha !== this.#overlayAlpha) {
+                    mesh.renderOverlay = true;
+                    mesh.overlayColor = color;
+                    mesh.overlayAlpha = this.#overlayAlpha;
+                    changed = true;
+                }
+            } else {
+                changed = this.#restoreMesh(mesh) || changed;
+            }
+        }
+
+        if (changed) {
+            this.#requestRender();
+        }
+    }
+
+    /**
+     * Restores all meshes changed by this controller and releases their saved overlay properties.
+     * @public
+     * @returns {void}
+     */
+    dispose() {
+        let changed = false;
+        for (const mesh of [...this.#originalOverlays.keys()]) {
+            changed = this.#restoreMesh(mesh) || changed;
+        }
+        if (changed) {
+            this.#requestRender();
+        }
+    }
+
+    /**
+     * Restores a mesh's saved overlay properties and removes its restoration snapshot.
+     * @private
+     * @param {object} mesh - Mesh previously updated by this controller.
+     * @returns {boolean} Whether a saved overlay was restored.
+     */
+    #restoreMesh(mesh) {
+        const original = this.#originalOverlays.get(mesh);
+        if (!original) {
+            return false;
+        }
+        mesh.renderOverlay = original.renderOverlay;
+        mesh.overlayColor = original.overlayColor;
+        mesh.overlayAlpha = original.overlayAlpha;
+        this.#originalOverlays.delete(mesh);
+        return true;
+    }
+}