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

package/src/babylonjs-camera-zoom-controller.js

@@ -0,0 +1,272 @@
+import { Camera } from "@babylonjs/core/Cameras/camera.js";
+import { ArcRotateCamera } from "@babylonjs/core/Cameras/arcRotateCamera.js";
+import { Ray } from "@babylonjs/core/Culling/ray.js";
+import { Vector3 } from "@babylonjs/core/Maths/math.vector.js";
+
+/**
+ * Maintains a geometry-dependent orbital zoom floor without moving the camera target.
+ * Checks only visible, enabled, pickable meshes in the current model asset container.
+ * The host owns camera selection, rendering and assets; dispose restores authored limits.
+ * Samples the near-plane footprint after orbital input, including parent-space conversion.
+ * The host may opt its default camera into adaptive positive near clipping; authored clipping remains unchanged.
+ * This is sampled ray protection, not continuous volume collision or target-motion constraints.
+ * @class
+ */
+export default class BabylonJSCameraZoomController {
+    #getModelContainer;
+    #isLocked;
+    #isTransitioning;
+    #canAdjustClipping;
+    #camera = null;
+    #observer = null;
+    #originalLimit = null;
+    #previousDistance = 0;
+    #margin = 0.05;
+    #minimum = 0.01;
+
+    /**
+     * Creates the model-only zoom guard; setCamera attaches it to a supported orbital camera.
+     * Callbacks resolve the current visible model and host lock/transition policy on every update.
+     * @public
+     * @param {function(): (import("@babylonjs/core").AssetContainer|null)} getModelContainer - Current model container; excludes environment assets.
+     * @param {function(import("@babylonjs/core").Camera): boolean} isLocked - Navigation lock/XR policy.
+     * @param {function(): boolean} isTransitioning - Whether explicit ViewCube framing is in progress.
+     * @param {function(import("@babylonjs/core").Camera): boolean} [canAdjustClipping] - Allows adaptive near clipping for host-owned cameras; authored cameras default to preservation.
+     */
+    constructor(getModelContainer, isLocked, isTransitioning, canAdjustClipping = () => false) {
+        this.#getModelContainer = getModelContainer;
+        this.#isLocked = isLocked;
+        this.#isTransitioning = isTransitioning;
+        this.#canAdjustClipping = canAdjustClipping;
+    }
+
+    /**
+     * Computes world coordinates and the radius-to-world conversion for parented cameras.
+     * @private
+     * @returns {{target: Vector3, direction: Vector3, distance: number, scale: number}|null} Current ray basis.
+     */
+    #basis() {
+        const camera = this.#camera;
+        camera.getViewMatrix(true);
+        const parent = camera.parent?.getWorldMatrix();
+        const target = parent ? Vector3.TransformCoordinates(camera.target, parent) : camera.target.clone();
+        const direction = camera.globalPosition.subtract(target);
+        const distance = direction.length();
+        if (!Number.isFinite(distance) || distance <= 0 || !Number.isFinite(camera.radius) || camera.radius === 0) {
+            return null;
+        }
+        direction.scaleInPlace(1 / distance);
+        if (camera.radius < 0) {
+            direction.scaleInPlace(-1);
+        }
+        return { target, direction, distance, scale: distance / Math.abs(camera.radius) };
+    }
+
+    /**
+     * Brings the default camera's near plane closer to its eye as orbital zoom approaches the target.
+     * Keeps a positive plane distance, retains smaller existing values and leaves authored cameras unchanged.
+     * Requires a model container; neither its bounds nor environment geometry determine this projection cap.
+     * @private
+     * @returns {void}
+     */
+    #adjustNearClipping() {
+        const camera = this.#camera;
+        if (!this.#canAdjustClipping(camera) || !this.#getModelContainer()?.meshes?.length) {
+            return;
+        }
+        const cap = Math.max(0.00001, Math.abs(camera.radius) * 0.001);
+        const current = camera.minZ > 0 ? camera.minZ : Infinity;
+        const near = Math.min(current, cap);
+        if (camera.minZ !== near) {
+            camera.minZ = near;
+            camera.getProjectionMatrix(true);
+        }
+    }
+
+    /**
+     * Samples the near-plane footprint in world space instead of only the optical axis.
+     * Projection matrix scales account for FOV/aspect; the inverse view handles camera parents.
+     * Perspective uses the center, four edge midpoints and four corners; orthographic uses only the center.
+     * Orthographic radius does not change image scale, so this method does not sample its full footprint.
+     * @private
+     * @returns {{offsets: Vector3[], clearance: number}} Probe offsets and surface clearance.
+     */
+    #nearPlane() {
+        const camera = this.#camera;
+        const inverseView = camera.getViewMatrix(true).clone().invert();
+        const near = Math.max(0, camera.minZ);
+        const depth = Vector3.TransformNormal(new Vector3(0, 0, near), inverseView).length();
+        const offsets = [Vector3.Zero()];
+        if (camera.mode === Camera.PERSPECTIVE_CAMERA && near > 0) {
+            const projection = camera.getProjectionMatrix(true);
+            const right = Vector3.TransformNormal(new Vector3(near / projection.m[0], 0, 0), inverseView);
+            const up = Vector3.TransformNormal(new Vector3(0, near / projection.m[5], 0), inverseView);
+            for (const x of [-1, 0, 1]) {
+                for (const y of [-1, 0, 1]) {
+                    if (x !== 0 || y !== 0) {
+                        offsets.push(right.scale(x).add(up.scale(y)));
+                    }
+                }
+            }
+        }
+        return { offsets, clearance: depth + this.#margin };
+    }
+
+    /**
+     * Finds an outward exit when a checked near-plane point is already inside a closed model mesh.
+     * The bounding box only limits the probe; triangle crossings distinguish solids from empty gaps.
+     * Advances beyond each crossing to avoid counting both triangles of the same face twice.
+     * This recovery assumes closed geometry; open/non-manifold surfaces retain sampled-ray limitations.
+     * @private
+     * @param {import("@babylonjs/core").AbstractMesh} mesh - Eligible mesh from the model container only.
+     * @param {Vector3} point - Checked near-plane point in world coordinates.
+     * @param {Vector3} direction - Unit outward camera direction in world coordinates.
+     * @returns {number} World distance to the first exit for an interior point, or zero otherwise.
+     */
+    #escapeDistance(mesh, point, direction) {
+        const bounds = mesh.getBoundingInfo().boundingBox;
+        if (!bounds.intersectsPoint(point)) {
+            return 0;
+        }
+        const length = Math.max(...bounds.vectorsWorld.map((vertex) => Vector3.Dot(vertex.subtract(point), direction))) + this.#margin;
+        if (!Number.isFinite(length) || length <= 0) {
+            return 0;
+        }
+        const epsilon = Math.max(1e-6, length * 1e-8);
+        let travelled = 0, crossings = 0, firstExit = 0;
+        while (travelled < length) {
+            const ray = new Ray(point.add(direction.scale(travelled)), direction, length - travelled);
+            const hit = ray.intersectsMesh(mesh, false);
+            if (!hit.hit || !Number.isFinite(hit.distance) || hit.distance < 0) {
+                break;
+            }
+            const distance = travelled + hit.distance;
+            if (crossings === 0) {
+                firstExit = distance;
+            }
+            crossings++;
+            travelled = distance + epsilon;
+        }
+        return crossings % 2 === 1 ? firstExit : 0;
+    }
+
+    /**
+     * Finds current model triangle surfaces along the sampled near-plane footprint.
+     * Filters disposed/ineligible meshes and refreshes only model matrices; environment meshes are never visited.
+     * Reverse rays protect camera-facing surfaces when the target lies beyond a solid.
+     * Interior near-plane probes recover through actual exits even when both segment endpoints are inside.
+     * @private
+     * @param {{target: Vector3, direction: Vector3, distance: number, scale: number}} basis - World-space target, outward unit direction, distance and world-distance/local-radius ratio.
+     * @param {number} length - Probe distance including the previous zoom position.
+     * @returns {number} Sampled world-distance floor including near-plane clearance; 0.01 when no model hit exists.
+     */
+    #minimumDistance(basis, length) {
+        const meshes = (this.#getModelContainer()?.meshes ?? []).filter((mesh) =>
+            !mesh.isDisposed() && mesh.isPickable && mesh.isEnabled() && mesh.isVisible && mesh.visibility > 0);
+        if (meshes.length === 0) {
+            return this.#minimum;
+        }
+        for (const mesh of meshes) {
+            mesh.computeWorldMatrix(true);
+        }
+        const { offsets, clearance } = this.#nearPlane();
+        let minimum = this.#minimum;
+        for (const offset of offsets) {
+            const origin = basis.target.add(offset);
+            const outward = new Ray(origin, basis.direction, length);
+            const inward = new Ray(origin.add(basis.direction.scale(length)), basis.direction.negate(), length);
+            const hit = outward.intersectsMeshes(meshes, false)[0];
+            const reverseHit = inward.intersectsMeshes(meshes, false)[0];
+            if (hit?.hit && Number.isFinite(hit.distance)) {
+                minimum = Math.max(minimum, hit.distance + clearance);
+            }
+            if (reverseHit?.hit && Number.isFinite(reverseHit.distance)) {
+                minimum = Math.max(minimum, length - reverseHit.distance + clearance);
+            }
+            const probeDistance = Math.max(0, basis.distance - clearance);
+            const point = origin.add(basis.direction.scale(probeDistance));
+            for (const mesh of meshes) {
+                const exit = this.#escapeDistance(mesh, point, basis.direction);
+                if (exit > 0) {
+                    minimum = Math.max(minimum, probeDistance + exit + clearance);
+                }
+            }
+        }
+        return minimum;
+    }
+
+    /**
+     * Binds post-input updates for ArcRotateCamera and releases the previous subscription.
+     * Captures its authored floor; other camera types remain unbound and selecting the same camera is a no-op.
+     * @public
+     * @param {import("@babylonjs/core").Camera|null} camera - Effective active camera.
+     * @returns {void}
+     */
+    setCamera(camera) {
+        if (camera === this.#camera) {
+            return;
+        }
+        this.dispose();
+        if (!(camera instanceof ArcRotateCamera)) {
+            return;
+        }
+        this.#camera = camera;
+        this.#originalLimit = camera.lowerRadiusLimit;
+        this.#previousDistance = this.#basis()?.distance ?? 0;
+        this.#observer = camera.onAfterCheckInputsObservable.add(() => this.update());
+    }
+
+    /**
+     * Resolves the current visible model and updates lowerRadiusLimit after input, before drawing.
+     * Missing/empty models use the unobstructed floor; environment geometry never supplies a floor.
+     * Combines the geometry floor with authored limits; skips updates for locked cameras and active XR.
+     * Temporarily restores the captured authored floor during explicit ViewCube fitting.
+     * Clamps an insufficient radius, recovers checked points inside closed model meshes and cancels inward zoom inertia on contact; outward zoom remains available.
+     * Converts sampled world clearance to the parent-local radius; never changes target, orientation or projection mode.
+     * Adapts the host-owned default camera near plane before computing its footprint; authored cameras retain clipping.
+     * @public
+     * @returns {void}
+     */
+    update() {
+        const camera = this.#camera;
+        if (!camera || this.#isLocked(camera)) {
+            return;
+        }
+        const basis = this.#basis();
+        if (!basis) {
+            return;
+        }
+        if (this.#isTransitioning()) {
+            camera.lowerRadiusLimit = this.#originalLimit;
+            this.#previousDistance = basis.distance;
+            return;
+        }
+        this.#adjustNearClipping();
+        const length = Math.max(basis.distance, this.#previousDistance);
+        const minimum = Math.max(this.#originalLimit ?? 0, this.#minimumDistance(basis, length) / basis.scale);
+        camera.lowerRadiusLimit = minimum;
+        if (camera.radius < minimum) {
+            camera.radius = minimum;
+            if (camera.inertialRadiusOffset > 0) {
+                camera.inertialRadiusOffset = 0;
+            }
+            camera.getViewMatrix(true);
+        }
+        this.#previousDistance = Math.abs(camera.radius) * basis.scale;
+    }
+
+    /**
+     * Unsubscribes and restores the selected camera's original lower radius limit.
+     * @public
+     * @returns {void}
+     */
+    dispose() {
+        if (this.#camera) {
+            this.#camera.onAfterCheckInputsObservable.remove(this.#observer);
+            this.#camera.lowerRadiusLimit = this.#originalLimit;
+        }
+        this.#camera = null;
+        this.#observer = null;
+        this.#previousDistance = 0;
+    }
+}