@preference-sl/pref-viewer 2.16.0-beta.1 → 2.16.0-beta.11

package/src/render-math.js

@@ -0,0 +1,127 @@
+/**
+ * Pure math utilities used by the lighting cycle and hardware scaling logic.
+ * No Babylon.js imports — safe to use in Node/SSR environments and in tests without mocks.
+ */
+
+/**
+ * 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.
+ * @param {number} value - The value to clamp.
+ * @returns {number} A number in [0, 1].
+ */
+export function clamp01(value) {
+    if (!Number.isFinite(value)) {
+        return 0.5;
+    }
+    return Math.min(1, Math.max(0, value));
+}
+
+/**
+ * Linearly interpolates between two values.
+ * The interpolation amount is clamped to [0, 1] before use.
+ * @param {number} from - Start value (returned when amount ≤ 0).
+ * @param {number} to - End value (returned when amount ≥ 1).
+ * @param {number} amount - Blend factor in [0, 1].
+ * @returns {number} Interpolated value between `from` and `to`.
+ */
+export function lerp(from, to, amount) {
+    const t = clamp01(amount);
+    return from + (to - from) * t;
+}
+
+/**
+ * Evaluates a bell-curve (half sine arc) over [0, 1].
+ * Returns 0 at both endpoints and 1 at the midpoint (x = 0.5).
+ * Used to model the intensity rise and fall of sunlight across the day.
+ * @param {number} x - Input in [0, 1]; clamped internally.
+ * @returns {number} Bell-curve output in [0, 1].
+ */
+function bellCurve(x) {
+    const clamped = clamp01(x);
+    return Math.sin(clamped * Math.PI);
+}
+
+/**
+ * Returns a unit vector for the given (x, y, z) direction.
+ * Falls back to the original vector with length 1 when the input is the zero vector.
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {{x: number, y: number, z: number}} Normalized direction vector.
+ */
+function normalizeDirection(x, y, z) {
+    const length = Math.hypot(x, y, z) || 1;
+    return {
+        x: x / length,
+        y: y / length,
+        z: z / length,
+    };
+}
+
+/**
+ * Computes the Babylon.js `hardwareScalingLevel` needed to render at the requested base
+ * resolution on a HiDPI display.
+ *
+ * Babylon's hardware scaling is the inverse of the device pixel ratio: a level of 0.5 on a
+ * 2× display renders at native resolution. This helper applies the base scaling factor (which
+ * may already downscale for performance on low-end hardware) on top of the device pixel ratio.
+ *
+ * Both inputs are validated and fall back to 1 when zero, negative, or non-finite.
+ * @param {number} [baseScaling=1] - Desired base scaling level (1 = full resolution, >1 = downscaled).
+ * @param {number} [pixelRatio=1] - Device pixel ratio (`window.devicePixelRatio`).
+ * @returns {number} Hardware scaling level to pass to `engine.setHardwareScalingLevel()`.
+ */
+export function getAdaptiveHardwareScalingLevel(baseScaling = 1, pixelRatio = 1) {
+    const safeBaseScaling = Number.isFinite(baseScaling) && baseScaling > 0 ? baseScaling : 1;
+    const safePixelRatio = Number.isFinite(pixelRatio) && pixelRatio > 0 ? pixelRatio : 1;
+    return safeBaseScaling / safePixelRatio;
+}
+
+/**
+ * Computes a lighting profile for a given time of day, used to drive the scene's directional
+ * lights, environment intensity, and tonemapping curve.
+ *
+ * The model follows a simplified solar arc: sunrise at 06:15 and sunset at 20:15 (fractional
+ * hours). Day factor peaks at solar noon and falls to zero outside daylight hours. Sun and moon
+ * directions are antipodal unit vectors derived from the sun phase angle.
+ * @param {number} [timeOfDay=0.5] - Normalized time in [0, 1] where 0 = midnight and 1 = next midnight.
+ *   Values outside [0, 1] are clamped.
+ * @returns {{
+ *   timeOfDay: number,
+ *   timeHours: number,
+ *   sunPhase: number,
+ *   solarAzimuth: number,
+ *   solarElevation: number,
+ *   dayFactor: number,
+ *   nightFactor: number,
+ *   sunDirection: {x: number, y: number, z: number},
+ *   moonDirection: {x: number, y: number, z: number}
+ * }} Lighting profile snapshot for the requested time.
+ */
+export function getLightingCycleProfile(timeOfDay = 0.5) {
+    const normalizedTime = clamp01(timeOfDay);
+    const timeHours = normalizedTime * 24;
+    const sunriseHour = 6.25;
+    const sunsetHour = 20.25;
+    const daylightProgress = clamp01((timeHours - sunriseHour) / (sunsetHour - sunriseHour));
+    const dayFactor = timeHours >= sunriseHour && timeHours <= sunsetHour ? Math.pow(bellCurve(daylightProgress), 0.88) : 0;
+    const nightFactor = 1 - dayFactor;
+    const solarArc = dayFactor > 0 ? Math.pow(dayFactor, 0.72) : 0;
+    const solarAzimuth = lerp(-Math.PI * 0.82, Math.PI * 0.82, daylightProgress);
+    const solarElevation = lerp(-0.18, 1.18, solarArc);
+    const sunPhase = normalizedTime * Math.PI * 2 - Math.PI / 2;
+    const sunDirection = normalizeDirection(-Math.cos(sunPhase), -Math.sin(sunPhase), -0.35);
+    const moonDirection = normalizeDirection(-sunDirection.x, -sunDirection.y, -sunDirection.z);
+
+    return {
+        timeOfDay: normalizedTime,
+        timeHours,
+        sunPhase,
+        solarAzimuth,
+        solarElevation,
+        dayFactor,
+        nightFactor,
+        sunDirection,
+        moonDirection,
+    };
+}