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

package/src/babylonjs-view-cube-canvas-orbit-math.js

@@ -0,0 +1,220 @@
+/**
+ * Pure orbit and view math for the draggable view cube.
+ *
+ * Uses the Babylon.js ArcRotateCamera convention (Y-up): the camera sits at
+ * target + radius * (sin(beta) * cos(alpha), cos(beta), sin(beta) * sin(alpha)).
+ * A camera on +Z therefore has alpha = PI / 2 and beta = PI / 2. The module has no Babylon or DOM
+ * dependency, so it is safe to import from any environment.
+ */
+
+/**
+ * Orbit pose of a camera around its target, in radians.
+ * @typedef {Object} OrbitAngles
+ * @property {number} alpha - Longitude around the Y axis, atan2(z, x) convention.
+ * @property {number} beta - Polar angle measured from +Y, in [0, PI].
+ */
+
+/**
+ * Plain three-component vector.
+ * @typedef {Object} Vec3
+ * @property {number} x
+ * @property {number} y
+ * @property {number} z
+ */
+
+/**
+ * One of the 26 cube views.
+ * @typedef {Object} ViewCubeDirection
+ * @property {string} id - Signed-axis triple such as "0,0,1" (face), "1,0,1" (edge) or "1,1,1" (corner).
+ * @property {Vec3} direction - Normalized direction from the target towards the camera.
+ */
+
+/**
+ * Stateless orbit calculations and sizing policy for the Canvas ViewCube.
+ * All operations are static and pure; callers need no instance or disposal.
+ * Private constants own numerical tolerances and sizing; read-only getters expose
+ * the polar margin and immutable region directions required by consumers.
+ * This class has no Babylon.js or DOM dependency and never modifies input poses.
+ */
+export default class BabylonJSViewCubeCanvasOrbitMath {
+    /** Full revolution in radians, used for angle normalization. */
+    static #TWO_PI = Math.PI * 2;
+    /** Relative horizontal-length threshold below which longitude is undefined. */
+    static #POLE_EPSILON = 1e-9;
+
+    /**
+     * Safety margin, in radians, kept between beta and the poles to avoid gimbal flips.
+     * @type {number}
+     */
+    static #BETA_MARGIN = 0.05;
+
+    /**
+     * The 26 cube views: 6 faces, 12 edges and 8 corners.
+     * @type {ReadonlyArray<ViewCubeDirection>}
+     */
+    static #VIEW_CUBE_DIRECTIONS = Object.freeze(BabylonJSViewCubeCanvasOrbitMath.#createViewCubeDirections());
+
+    // Cube sizing, from an ergonomic evaluation of the 26-region cube. WCAG 2.2 sets a 24x24 CSS px minimum target
+    // size, and at the former fixed 100 px the corner spheres measure about 11 px and the edge bars about 4 px
+    // (0.26 and 0.09 over the +-1.15 orthographic extent). Finger-sized 44-48 px targets are unreachable with 26
+    // regions on one cube, so the cube grows with the viewer within a bounded range and the renderer adds a pick
+    // tolerance for small regions.
+    /** Share of the smaller viewer dimension used as the cube side before clamping. */
+    static #VIEW_CUBE_SIZE_RATIO = 0.22;
+    /** Smallest preferred cube side, in CSS pixels, applied before the viewer-share cap. */
+    static #VIEW_CUBE_MIN_SIDE = 96;
+    /** Largest cube side, in CSS pixels. */
+    static #VIEW_CUBE_MAX_SIDE = 180;
+    /** Hard cap: the cube never takes more than this share of the smaller viewer dimension. */
+    static #VIEW_CUBE_MAX_VIEWPORT_SHARE = 0.4;
+
+    /**
+     * Wraps an angle into the half-open interval (-PI, PI].
+     * @param {number} angle - Angle in radians; any magnitude.
+     * @returns {number} Equivalent angle in (-PI, PI].
+     */
+    static normalizeAngle(angle) {
+        return angle - BabylonJSViewCubeCanvasOrbitMath.#TWO_PI * Math.ceil((angle - Math.PI) / BabylonJSViewCubeCanvasOrbitMath.#TWO_PI);
+    }
+
+    /**
+     * Computes the signed shortest angular difference between two angles.
+     * @param {number} from - Start angle in radians.
+     * @param {number} to - End angle in radians.
+     * @returns {number} Signed difference in (-PI, PI]; positive means counter-clockwise growth of the angle.
+     */
+    static shortestDelta(from, to) {
+        return BabylonJSViewCubeCanvasOrbitMath.normalizeAngle(to - from);
+    }
+
+    /**
+     * Clamps beta to [BETA_MARGIN, PI - BETA_MARGIN].
+     * @param {number} beta - Polar angle in radians.
+     * @returns {number} Clamped polar angle.
+     */
+    static clampBeta(beta) {
+        return Math.min(Math.max(beta, BabylonJSViewCubeCanvasOrbitMath.#BETA_MARGIN), Math.PI - BabylonJSViewCubeCanvasOrbitMath.#BETA_MARGIN);
+    }
+
+    /**
+     * Converts orbit angles into the unit vector pointing from the target towards the camera.
+     * @param {OrbitAngles} pose - Orbit angles in radians.
+     * @returns {Vec3} Unit direction (sin(beta) * cos(alpha), cos(beta), sin(beta) * sin(alpha)).
+     */
+    static directionFromAngles({ alpha, beta }) {
+        const sinBeta = Math.sin(beta);
+        return { x: sinBeta * Math.cos(alpha), y: Math.cos(beta), z: sinBeta * Math.sin(alpha) };
+    }
+
+    /**
+     * Converts a direction from the target towards the camera into orbit angles.
+     * The vector need not be normalized. Beta retains the full [0, PI] range so camera synchronization
+     * can represent top and bottom without the drag safety margin. When the horizontal component vanishes alpha is undefined and
+     * fallbackAlpha is returned unchanged to avoid an arbitrary spin.
+     * A zero-length or non-finite vector has no direction: the function returns null instead of throwing.
+     * @param {Vec3} direction - Direction from the target towards the camera.
+     * @param {number} [fallbackAlpha=0] - Alpha to keep at the poles.
+     * @returns {OrbitAngles|null} Orbit angles, or null when the vector has no usable direction.
+     */
+    static anglesFromDirection({ x, y, z }, fallbackAlpha = 0) {
+        const length = Math.hypot(x, y, z);
+        if (!Number.isFinite(length) || length === 0) {
+            return null;
+        }
+        const beta = Math.acos(Math.min(Math.max(y / length, -1), 1));
+        const alpha = Math.hypot(x, z) / length < BabylonJSViewCubeCanvasOrbitMath.#POLE_EPSILON ? fallbackAlpha : Math.atan2(z, x);
+        return { alpha, beta };
+    }
+
+    /**
+     * Interpolates two orbit poses; alpha follows the shortest angular path, beta is linear.
+     * @param {OrbitAngles} a - Start pose.
+     * @param {OrbitAngles} b - End pose.
+     * @param {number} t - Interpolation factor, 0 gives a and 1 gives b (equivalent modulo 2*PI for alpha).
+     * @returns {OrbitAngles} New pose; inputs are not modified.
+     */
+    static lerpAngles(a, b, t) {
+        return {
+            alpha: a.alpha + BabylonJSViewCubeCanvasOrbitMath.shortestDelta(a.alpha, b.alpha) * t,
+            beta: a.beta + (b.beta - a.beta) * t,
+        };
+    }
+
+    /**
+     * Applies a drag increment to a pose. Alpha is not wrapped; beta is clamped away from the poles.
+     * @param {OrbitAngles} pose - Current pose.
+     * @param {number} dAlpha - Alpha increment in radians.
+     * @param {number} dBeta - Beta increment in radians.
+     * @returns {OrbitAngles} New pose; the input is not modified.
+     */
+    static applyDragDelta({ alpha, beta }, dAlpha, dBeta) {
+        return { alpha: alpha + dAlpha, beta: BabylonJSViewCubeCanvasOrbitMath.clampBeta(beta + dBeta) };
+    }
+
+    /**
+     * Builds the 26 signed-axis views in the same order as the cube controller: faces, edges, corners.
+     * Ids and directions equal those of BabylonJSViewCubeController.createViewCubeRegions(); a test
+     * guards against drift.
+     * @returns {ViewCubeDirection[]}
+     */
+    static #createViewCubeDirections() {
+        const axes = [];
+        for (let i = 0; i < 3; i++) {
+            for (const s of [-1, 1]) {
+                const axis = [0, 0, 0];
+                axis[i] = s;
+                axes.push(axis);
+            }
+        }
+        for (let i = 0; i < 3; i++) {
+            for (let j = i + 1; j < 3; j++) {
+                for (const s of [-1, 1]) {
+                    for (const t of [-1, 1]) {
+                        const axis = [0, 0, 0];
+                        axis[i] = s;
+                        axis[j] = t;
+                        axes.push(axis);
+                    }
+                }
+            }
+        }
+        for (const x of [-1, 1]) {
+            for (const y of [-1, 1]) {
+                for (const z of [-1, 1]) {
+                    axes.push([x, y, z]);
+                }
+            }
+        }
+        return axes.map((axis) => {
+            const length = Math.hypot(...axis);
+            const [x, y, z] = axis.map((c) => c / length);
+            return Object.freeze({ id: axis.join(","), direction: Object.freeze({ x, y, z }) });
+        });
+    }
+
+    /**
+     * Computes the side of the square view cube for a viewer.
+     * side = min(clamp(0.22 * m, 96, 180), 0.4 * m) where m is the smaller viewport dimension, rounded to an integer.
+     * @param {number} viewportWidth - Viewer width in CSS pixels.
+     * @param {number} viewportHeight - Viewer height in CSS pixels.
+     * @returns {number} Integer side in CSS pixels, or 0 when the viewport is empty or not finite.
+     */
+    static computeViewCubeSize(viewportWidth, viewportHeight) {
+        const smaller = Math.min(viewportWidth, viewportHeight);
+        if (!Number.isFinite(viewportWidth) || !Number.isFinite(viewportHeight) || smaller <= 0) {
+            return 0;
+        }
+        const preferred = Math.min(Math.max(BabylonJSViewCubeCanvasOrbitMath.#VIEW_CUBE_SIZE_RATIO * smaller, BabylonJSViewCubeCanvasOrbitMath.#VIEW_CUBE_MIN_SIDE), BabylonJSViewCubeCanvasOrbitMath.#VIEW_CUBE_MAX_SIDE);
+        return Math.round(Math.min(preferred, BabylonJSViewCubeCanvasOrbitMath.#VIEW_CUBE_MAX_VIEWPORT_SHARE * smaller));
+    }
+
+    /** @returns {number} Read-only polar safety margin in radians. */
+    static get BETA_MARGIN() {
+        return BabylonJSViewCubeCanvasOrbitMath.#BETA_MARGIN;
+    }
+
+    /** @returns {ReadonlyArray<ViewCubeDirection>} Shared deeply frozen face, edge and corner directions. */
+    static get VIEW_CUBE_DIRECTIONS() {
+        return BabylonJSViewCubeCanvasOrbitMath.#VIEW_CUBE_DIRECTIONS;
+    }
+}