@preference-sl/pref-viewer 2.18.0-beta.1 → 3.0.0-beta.0

package/src/babylonjs-orbital-pointers-input.js

@@ -0,0 +1,186 @@
+import BabylonJSCameraWheelMotion from "./babylonjs-camera-wheel-motion.js";
+import { ArcRotateCameraPointersInput } from "@babylonjs/core/Cameras/Inputs/arcRotateCameraPointersInput.js";
+
+/**
+ * Separates orbital pinch and pan using accumulated CSS-pixel motion instead of a per-event threshold.
+ * Batches pointer updates until camera input processing so separately delivered finger events are compared together.
+ * Defers ambiguous input, locks the recognized mode until release, and delegates movement to Babylon's native maths.
+ * Focal-enabled cameras share wheel surface/plane focus at the touch midpoint and coupled inertia.
+ * The camera input manager owns attachment/disposal; no independent DOM listeners or timers are installed.
+ */
+export default class BabylonJSOrbitalPointersInput extends ArcRotateCameraPointersInput {
+    static #thresholds = { pinch: 3, pan: 6, dominance: 0.8, confirmationMs: 32 };
+    #origin = null;
+    #applied = null;
+    #pending = null;
+    #mode = null;
+    #candidate = null;
+    #candidateSince = 0;
+
+    /**
+     * Replaces a detached native pointers input once, preserving its public sensitivity/interaction settings.
+     * Uses the same pointers slot and inherited input class name so camera attachment remains native.
+     * @param {import("@babylonjs/core").ArcRotateCamera} camera - Camera before controls are attached.
+     * @returns {ArcRotateCameraPointersInput|undefined} Installed input, or undefined when no pointers input exists.
+     */
+    static install(camera) {
+        const original = camera.inputs.attached.pointers;
+        if (!original || original instanceof BabylonJSOrbitalPointersInput) {
+            return original;
+        }
+        const replacement = new BabylonJSOrbitalPointersInput();
+        for (const key of Object.keys(original)) {
+            if (key !== "camera" && !key.startsWith("_")) {
+                replacement[key] = original[key];
+            }
+        }
+        camera.inputs.remove(original);
+        camera.inputs.add(replacement);
+        return replacement;
+    }
+
+    /**
+     * Captures the latest pair geometry; movement is applied at most once per camera-input frame.
+     * Pending gestures do not mutate the camera, and loss of either finger ends the current classification.
+     * @param {object|null} pointA - First native pointer position.
+     * @param {object|null} pointB - Second native pointer position.
+     * @param {number} previousSquared - Previous squared finger separation in CSS pixels.
+     * @param {number} squared - Current squared finger separation; zero marks gesture end.
+     * @param {{x:number, y:number}|null} previousCenter - Previous pair midpoint.
+     * @param {{x:number, y:number}|null} center - Current pair midpoint in client CSS pixels; null marks gesture end.
+     * @returns {void}
+     */
+    onMultiTouch(pointA, pointB, previousSquared, squared, previousCenter, center) {
+        if (!squared || !center) {
+            this.#finish();
+            return;
+        }
+        if (!Number.isFinite(squared) || squared < 0 || !Number.isFinite(center.x + center.y)) {
+            return;
+        }
+        if (!this.#origin) {
+            this.#origin = {
+                squared: previousSquared > 0 ? previousSquared : squared,
+                center: { ...(previousCenter ?? center) },
+            };
+            this.#applied = this.#origin;
+        }
+        this.#pending = { squared, center: { ...center } };
+    }
+
+    /**
+     * Classifies accumulated movement after both pointer updates can arrive, then applies only the selected mode.
+     * A short confirmation window avoids interpreting the first finger's asynchronous pan event as a pinch.
+     * Recognizing a new pan cancels prior coupled focal inertia without changing the zoom preference.
+     * @returns {void}
+     */
+    checkInputs() {
+        if (!this.#pending) {
+            return;
+        }
+        if (!this.#mode) {
+            const pinch = Math.abs(Math.sqrt(this.#pending.squared) - Math.sqrt(this.#origin.squared));
+            const pan = Math.hypot(this.#pending.center.x - this.#origin.center.x,
+                this.#pending.center.y - this.#origin.center.y);
+            const thresholds = BabylonJSOrbitalPointersInput.#thresholds;
+            let candidate = null;
+            if (this.pinchZoom && pinch >= thresholds.pinch && pinch >= pan * thresholds.dominance) {
+                candidate = "zoom";
+            } else if (this.multiTouchPanning && pan >= thresholds.pan && pinch < pan * 0.35) {
+                candidate = "pan";
+            }
+            if (candidate !== this.#candidate) {
+                this.#candidate = candidate;
+                this.#candidateSince = Date.now();
+            }
+            if (!candidate || Date.now() - this.#candidateSince < thresholds.confirmationMs) {
+                return;
+            }
+            this.#mode = candidate;
+            if (candidate === "zoom") {
+                this.camera.inertialPanningX = this.camera.inertialPanningY = 0;
+                this.camera.movement.panAccumulatedPixels.setAll(0);
+            } else {
+                BabylonJSCameraWheelMotion.cancel(this.camera);
+                this.camera.inertialRadiusOffset = 0;
+                this.camera.movement.zoomAccumulatedPixels = 0;
+            }
+        }
+        this.#applyPending();
+    }
+
+    /**
+     * Delegates pair motion to native pan or proportional pinch. Focal-enabled pinch transfers only its new
+     * radial increment to wheel-owned coupled inertia at the current client midpoint, avoiding duplicate zoom.
+     * @private
+     * @returns {void}
+     */
+    #applyPending() {
+        if (!this.#pending || !this.#mode) {
+            return;
+        }
+        if (this.#mode === "zoom") {
+            const accumulated = this.camera.movement.zoomAccumulatedPixels;
+            this._computePinchZoom(this.#applied.squared, this.#pending.squared);
+            const delta = this.camera.movement.zoomAccumulatedPixels - accumulated;
+            if (BabylonJSCameraWheelMotion.zoomAtClientPoint(this.camera, delta, this.#pending.center)) {
+                this.camera.movement.zoomAccumulatedPixels = accumulated;
+            }
+        } else {
+            this._computeMultiTouchPanning(this.#applied.center, this.#pending.center);
+        }
+        this.#applied = this.#pending;
+        this.#pending = null;
+    }
+
+    /**
+     * Flushes recognized motion and resets the gesture; unrecognized motion is discarded.
+     * @private
+     * @returns {void}
+     */
+    #finish() {
+        this.#applyPending();
+        this.#reset();
+    }
+
+    /**
+     * Clears pair state without moving the camera or changing input settings.
+     * @private
+     * @returns {void}
+     */
+    #reset() {
+        this.#origin = this.#applied = this.#pending = null;
+        this.#mode = this.#candidate = null;
+        this.#candidateSince = 0;
+    }
+
+    /**
+     * Ends pair ownership when a finger is lifted and preserves native mouse/pointer cleanup.
+     * @param {PointerEvent} event - Released pointer event.
+     * @returns {void}
+     */
+    onButtonUp(event) {
+        this.#finish();
+        super.onButtonUp(event);
+    }
+
+    /**
+     * Discards pending gesture motion and cancels coupled focal inertia on focus loss before native pointer cleanup.
+     * @returns {void}
+     */
+    onLostFocus() {
+        BabylonJSCameraWheelMotion.cancel(this.camera);
+        this.#reset();
+        super.onLostFocus();
+    }
+
+    /**
+     * Discards pending pair motion and coupled focal inertia before the input manager detaches native event listeners.
+     * @returns {void}
+     */
+    detachControl() {
+        BabylonJSCameraWheelMotion.cancel(this.camera);
+        this.#reset();
+        super.detachControl();
+    }
+}

package/src/{render-math.js → babylonjs-render-math.js}

@@ -1,8 +1,8 @@
 /**
  * Pure lighting and hardware-scaling calculations without Babylon.js dependencies.
- * @class RenderMath
+ * @class BabylonJSRenderMath
  */
-export default class RenderMath {
+export default class BabylonJSRenderMath {
     /**
      * Clamps a number to the [0, 1] range.
      * Returns 0.5 for non-finite inputs (NaN, ±Infinity) so callers get a safe mid-point fallback.
@@ -29,7 +29,7 @@ export default class RenderMath {
      * @returns {number} Interpolated value between `from` and `to`.
      */
     static lerp(from, to, amount) {
-        const t = RenderMath.clamp01(amount);
+        const t = BabylonJSRenderMath.clamp01(amount);
         return from + (to - from) * t;
     }
 
@@ -43,7 +43,7 @@ export default class RenderMath {
      * @returns {number} Bell-curve output in [0, 1].
      */
     static #bellCurve(x) {
-        const clamped = RenderMath.clamp01(x);
+        const clamped = BabylonJSRenderMath.clamp01(x);
         return Math.sin(clamped * Math.PI);
     }
 
@@ -111,19 +111,19 @@ export default class RenderMath {
      * }} Lighting profile snapshot for the requested time.
      */
     static getLightingCycleProfile(timeOfDay = 0.5) {
-        const normalizedTime = RenderMath.clamp01(timeOfDay);
+        const normalizedTime = BabylonJSRenderMath.clamp01(timeOfDay);
         const timeHours = normalizedTime * 24;
         const sunriseHour = 6.25;
         const sunsetHour = 20.25;
-        const daylightProgress = RenderMath.clamp01((timeHours - sunriseHour) / (sunsetHour - sunriseHour));
-        const dayFactor = timeHours >= sunriseHour && timeHours <= sunsetHour ? Math.pow(RenderMath.#bellCurve(daylightProgress), 0.88) : 0;
+        const daylightProgress = BabylonJSRenderMath.clamp01((timeHours - sunriseHour) / (sunsetHour - sunriseHour));
+        const dayFactor = timeHours >= sunriseHour && timeHours <= sunsetHour ? Math.pow(BabylonJSRenderMath.#bellCurve(daylightProgress), 0.88) : 0;
         const nightFactor = 1 - dayFactor;
         const solarArc = dayFactor > 0 ? Math.pow(dayFactor, 0.72) : 0;
-        const solarAzimuth = RenderMath.lerp(-Math.PI * 0.82, Math.PI * 0.82, daylightProgress);
-        const solarElevation = RenderMath.lerp(-0.18, 1.18, solarArc);
+        const solarAzimuth = BabylonJSRenderMath.lerp(-Math.PI * 0.82, Math.PI * 0.82, daylightProgress);
+        const solarElevation = BabylonJSRenderMath.lerp(-0.18, 1.18, solarArc);
         const sunPhase = normalizedTime * Math.PI * 2 - Math.PI / 2;
-        const sunDirection = RenderMath.#normalizeDirection(-Math.cos(sunPhase), -Math.sin(sunPhase), -0.35);
-        const moonDirection = RenderMath.#normalizeDirection(-sunDirection.x, -sunDirection.y, -sunDirection.z);
+        const sunDirection = BabylonJSRenderMath.#normalizeDirection(-Math.cos(sunPhase), -Math.sin(sunPhase), -0.35);
+        const moonDirection = BabylonJSRenderMath.#normalizeDirection(-sunDirection.x, -sunDirection.y, -sunDirection.z);
 
         return {
             timeOfDay: normalizedTime,

package/src/babylonjs-selection-controller.js

@@ -58,7 +58,7 @@ export default class BabylonJSSelectionController {
      * 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.
+     * @param {Array<object>} [meshes=[]] - Meshes from the model AssetContainer.
      * @returns {Set<object>} Accepted model mesh references.
      */
     static getModelMeshSet(meshes = []) {
@@ -79,8 +79,8 @@ export default class BabylonJSSelectionController {
      * 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.
+     * @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 = []) {
@@ -117,7 +117,7 @@ export default class BabylonJSSelectionController {
     /**
      * 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.
+     * @param {{selectableIds?:string[],selectedIds?:string[],selectedItems?:Array<{id:string,highlights?:string[]}>}} [state={}] - Canonical selection state.
      * @returns {void}
      */
     applySelectionState(state = {}) {