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

package/src/babylonjs-camera-framing.js

@@ -0,0 +1,171 @@
+import { Matrix, Quaternion, Vector3 } from "@babylonjs/core/Maths/math.vector.js";
+import BabylonJSController from "./babylonjs-controller.js";
+
+/**
+ * Supported camera adapters; the host keeps ownership of their lifecycle.
+ * @typedef {import("@babylonjs/core").ArcRotateCamera|import("@babylonjs/core").FreeCamera|import("@babylonjs/core").UniversalCamera} FramingCamera
+ */
+
+/**
+ * Model-only world bounds used for framing.
+ * @typedef {Object} CameraFramingBounds
+ * @property {Vector3} center - World-space bounding-box center.
+ * @property {number} radius - Half the bounding-box diagonal.
+ * @property {Vector3[]} corners - Eight world-space bounding-box corners.
+ */
+
+/**
+ * Destination framing shared by the camera adapters.
+ * @typedef {Object} CameraFramingFit
+ * @property {Vector3} target - Model center in world space.
+ * @property {number} distance - Destination camera-to-target world distance.
+ * @property {Quaternion} rotation - Destination world orientation.
+ * @property {number} halfWidth - Orthographic horizontal half-extent.
+ * @property {number} halfHeight - Orthographic vertical half-extent.
+ * @property {number} radius - Model bounds radius used for clipping adjustments.
+ */
+
+/**
+ * BabylonJSCameraFraming - Calculates model-only world bounds and projection-aware camera fits.
+ *
+ * Stateless utilities shared by camera navigation controllers. Destination calculations preserve
+ * the camera and its projection; callers apply the returned pose and orthographic extents.
+ * Reads the shared camera margin at call time and does not own assets or rendering resources.
+ * @class
+ */
+export default class BabylonJSCameraFraming {
+
+    /**
+     * Checks that all three vector components are finite numbers.
+     * @private
+     * @static
+     * @param {Vector3|null|undefined} v - Candidate vector.
+     * @returns {boolean|null|undefined} True for usable coordinates; otherwise false or the absent input.
+     */
+    static #finiteVector(v) {
+        return v && [v.x, v.y, v.z].every(Number.isFinite);
+    }
+
+    /**
+     * Computes model-only world bounds from visible, enabled meshes with valid geometry.
+     * Updates mesh world matrices; never includes an environment container implicitly.
+     * @public
+     * @static
+     * @param {import("@babylonjs/core").AssetContainer|null|undefined} container - Model asset container.
+     * @returns {CameraFramingBounds|null} Bounds and eight corners, or null for missing/degenerate geometry.
+     */
+    static getModelBounds(container) {
+        let min = null;
+        let max = null;
+        for (const mesh of container?.meshes ?? []) {
+            if ((mesh?.getTotalVertices?.() ?? 0) <= 0 || mesh.isDisposed?.() || mesh.isEnabled?.() === false || mesh.isVisible === false || mesh.visibility <= 0) {
+                continue;
+            }
+            mesh.computeWorldMatrix(true);
+            const box = mesh.getBoundingInfo?.()?.boundingBox;
+            if (!BabylonJSCameraFraming.#finiteVector(box?.minimumWorld) || !BabylonJSCameraFraming.#finiteVector(box?.maximumWorld)) {
+                continue;
+            }
+            min = min ? Vector3.Minimize(min, box.minimumWorld) : box.minimumWorld.clone();
+            max = max ? Vector3.Maximize(max, box.maximumWorld) : box.maximumWorld.clone();
+        }
+        if (!min || !max) {
+            return null;
+        }
+        const radius = Vector3.Distance(min, max) / 2;
+        if (!Number.isFinite(radius) || radius <= 0) {
+            return null;
+        }
+        const corners = [];
+        for (const x of [min.x, max.x]) {
+            for (const y of [min.y, max.y]) {
+                for (const z of [min.z, max.z]) {
+                    corners.push(new Vector3(x, y, z));
+                }
+            }
+        }
+        return { center: Vector3.Center(min, max), radius, corners };
+    }
+
+    /**
+     * Checks whether the camera has a supported navigation adapter.
+     * @public
+     * @static
+     * @param {import("@babylonjs/core").Camera|null|undefined} camera - Camera to inspect.
+     * @returns {boolean} Whether it is an ArcRotateCamera, FreeCamera or UniversalCamera.
+     */
+    static isCameraSupported(camera) {
+        return ["ArcRotateCamera", "FreeCamera", "UniversalCamera"].includes(camera?.getClassName?.());
+    }
+
+    /**
+     * Builds a destination view basis using world +Y as up and the scene handedness.
+     * Applies a minimal horizontal offset at the poles to avoid a singular look-at matrix.
+     * @private
+     * @static
+     * @param {Vector3} direction - World-space direction from the target towards the camera.
+     * @param {boolean} rightHanded - Whether the scene uses right-handed coordinates.
+     * @returns {{view: Matrix, rotation: Quaternion}} View matrix and world orientation.
+     */
+    static #viewBasis(direction, rightHanded) {
+        // A tiny pole offset avoids a singular look-at while keeping world +Y as camera up.
+        const eye = direction.clone();
+        if (eye.x * eye.x + eye.z * eye.z < 1e-12) {
+            eye.z = 0.0001;
+        }
+        const view = (rightHanded ? Matrix.LookAtRH : Matrix.LookAtLH)(eye.normalize(), Vector3.Zero(), Vector3.Up());
+        const rotation = Quaternion.Identity();
+        view.clone().invert().decompose(undefined, rotation);
+        return { view, rotation };
+    }
+
+    /**
+     * Calculates destination framing from model corners without modifying the camera.
+     * Uses BabylonJSController.config.camera.fitMarginFactor as the total free viewport fraction.
+     * A factor of 0.1 leaves 90% available, reserving 5% at each opposing edge of the limiting axis.
+     * Preserves projection, including horizontal-fixed FOV. The factor must be finite and in [0, 0.5].
+     * Fits projected world-box corners; minimum near clearance can increase the requested inset.
+     * @public
+     * @static
+     * @param {FramingCamera} camera - Active supported camera.
+     * @param {CameraFramingBounds|null} bounds - Model-only world bounds.
+     * @param {Vector3} direction - Selected preset direction towards the observer.
+     * @param {{width: number, height: number}} viewport - Scene viewport dimensions in pixels.
+     * @returns {CameraFramingFit|null} Destination fit, or null when navigation inputs are unusable.
+     */
+    static calculateCameraFit(camera, bounds, direction, viewport) {
+        if (!bounds || !BabylonJSCameraFraming.isCameraSupported(camera) || !(viewport?.width > 0 && viewport?.height > 0)) {
+            return null;
+        }
+        const aspect = viewport.width / viewport.height;
+        const basis = BabylonJSCameraFraming.#viewBasis(direction, camera.getScene().useRightHandedSystem);
+        // Transform normals: discard the look-at matrix translation for offsets about the model center.
+        const points = bounds.corners.map((p) => Vector3.TransformNormal(p.subtract(bounds.center), basis.view));
+        const marginFactor = BabylonJSController.config.camera.fitMarginFactor;
+        if (!Number.isFinite(marginFactor) || marginFactor < 0 || marginFactor > 0.5) {
+            return null;
+        }
+        const available = 1 - marginFactor;
+        let distance = camera.mode === 1 ? bounds.radius * 1.01 : 0;
+        let halfWidth = 0;
+        let halfHeight = 0;
+        const tan = Math.tan(camera.fov / 2);
+        const tanX = camera.fovMode === 1 ? tan : tan * aspect;
+        const tanY = camera.fovMode === 1 ? tan / aspect : tan;
+        if (camera.mode !== 1 && (!(tanX > 0) || !(tanY > 0) || !Number.isFinite(tanX + tanY))) {
+            return null;
+        }
+        for (const p of points) {
+            halfWidth = Math.max(halfWidth, Math.abs(p.x) / available);
+            halfHeight = Math.max(halfHeight, Math.abs(p.y) / available);
+            // p.z is positive towards the observer in RH, negative in LH.
+            const towardObserver = camera.getScene().useRightHandedSystem ? p.z : -p.z;
+            if (camera.mode !== 1) {
+                distance = Math.max(distance, towardObserver + Math.max(bounds.radius * 0.001, 0.00001), towardObserver + Math.abs(p.x) / (tanX * available), towardObserver + Math.abs(p.y) / (tanY * available));
+            }
+        }
+        halfHeight = Math.max(halfHeight, halfWidth / aspect, bounds.radius * 0.001);
+        halfWidth = halfHeight * aspect;
+        return { target: bounds.center.clone(), distance, rotation: basis.rotation, halfWidth, halfHeight, radius: bounds.radius };
+    }
+}

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;
+    }
+}