@preference-sl/pref-viewer 2.17.0-beta.4 → 2.17.0-beta.6

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

@@ -0,0 +1,199 @@
+/**
+ * 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.
+ */
+
+const TWO_PI = Math.PI * 2;
+const POLE_EPSILON = 1e-9;
+
+/**
+ * Safety margin, in radians, kept between beta and the poles to avoid gimbal flips.
+ * @type {number}
+ */
+export const BETA_MARGIN = 0.05;
+
+/**
+ * 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].
+ */
+export function normalizeAngle(angle) {
+    return angle - TWO_PI * Math.ceil((angle - Math.PI) / 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.
+ */
+export function shortestDelta(from, to) {
+    return normalizeAngle(to - from);
+}
+
+/**
+ * Clamps beta to [BETA_MARGIN, PI - BETA_MARGIN].
+ * @param {number} beta - Polar angle in radians.
+ * @returns {number} Clamped polar angle.
+ */
+export function clampBeta(beta) {
+    return Math.min(Math.max(beta, BETA_MARGIN), Math.PI - 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)).
+ */
+export function 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 is clamped with clampBeta(), so pole directions map to
+ * the nearest allowed pose. When the horizontal component vanishes (pole) 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.
+ */
+export function anglesFromDirection({ x, y, z }, fallbackAlpha = 0) {
+    const length = Math.hypot(x, y, z);
+    if (!Number.isFinite(length) || length === 0) {
+        return null;
+    }
+    const beta = clampBeta(Math.acos(Math.min(Math.max(y / length, -1), 1)));
+    const alpha = Math.hypot(x, z) / length < 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.
+ */
+export function lerpAngles(a, b, t) {
+    return {
+        alpha: a.alpha + 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.
+ */
+export function applyDragDelta({ alpha, beta }, dAlpha, dBeta) {
+    return { alpha: alpha + dAlpha, beta: 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[]}
+ */
+function 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 }) });
+    });
+}
+
+/**
+ * The 26 cube views: 6 faces, 12 edges and 8 corners.
+ * @type {ReadonlyArray<ViewCubeDirection>}
+ */
+export const VIEW_CUBE_DIRECTIONS = Object.freeze(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. */
+export const VIEW_CUBE_SIZE_RATIO = 0.22;
+/** Smallest preferred cube side, in CSS pixels, applied before the viewer-share cap. */
+export const VIEW_CUBE_MIN_SIDE = 96;
+/** Largest cube side, in CSS pixels. */
+export const VIEW_CUBE_MAX_SIDE = 180;
+/** Hard cap: the cube never takes more than this share of the smaller viewer dimension. */
+export const VIEW_CUBE_MAX_VIEWPORT_SHARE = 0.4;
+
+/**
+ * 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.
+ */
+export function 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(VIEW_CUBE_SIZE_RATIO * smaller, VIEW_CUBE_MIN_SIDE), VIEW_CUBE_MAX_SIDE);
+    return Math.round(Math.min(preferred, VIEW_CUBE_MAX_VIEWPORT_SHARE * smaller));
+}