@woosh/meep-engine 3.65.0 → 3.67.0

package/src/shade/renderer/shader/chunk/color/tonemap/purkinje/chunk_apply_purkinje_shift.js

@@ -0,0 +1,136 @@
+import { CodeChunk } from "../../../../compiler/CodeChunk.js";
+
+/**
+ * Rec.709 photopic luminance weights: what the cones see of a linear Rec.709 colour.
+ * @type {ReadonlyArray<number>}
+ */
+export const PURKINJE_REC709_PHOTOPIC = Object.freeze([0.2126, 0.7152, 0.0722]);
+
+/**
+ * Rec.709 scotopic luminance weights: what the rods see of a linear Rec.709 colour. They sum to 1, so a grey has the
+ * same scotopic luminance as photopic.
+ * @type {ReadonlyArray<number>}
+ */
+export const PURKINJE_REC709_SCOTOPIC = Object.freeze([0.0070, 0.5190, 0.4740]);
+
+/**
+ * "Rod blue": the colour the scotopic signal is carried by. Artistic: (0.3, 0.5, 0.9) mimics the sensation of the
+ * rods' 507 nm peak.
+ * @type {ReadonlyArray<number>}
+ */
+export const PURKINJE_NIGHT_TINT = Object.freeze([0.3, 0.5, 0.9]);
+
+/**
+ * CIE 191's mesopic range, cd/m²: rods alone below the lower bound (scotopic), cones alone above the upper (photopic).
+ */
+export const PURKINJE_MESOPIC_MIN_NITS = 0.005;
+export const PURKINJE_MESOPIC_MAX_NITS = 5;
+
+/**
+ * The least adaptation the share is read at, cd/m²: under it, the rods alone see, as they do at the bound itself.
+ */
+const ADAPTATION_FLOOR_NITS = 1e-5;
+
+/**
+ * How much of the eye's response is the rods', at an adaptation: 1 at and below {@link PURKINJE_MESOPIC_MIN_NITS}, 0 at
+ * and above {@link PURKINJE_MESOPIC_MAX_NITS}, linear in log luminance in between. The share `apply_purkinje_shift`
+ * blends by, for code that needs it on the CPU.
+ *
+ * @param {number} adaptation_luminance cd/m²
+ * @returns {number} 0 to 1
+ */
+export function purkinje_rod_share(adaptation_luminance) {
+    const low = Math.log(PURKINJE_MESOPIC_MIN_NITS);
+    const high = Math.log(PURKINJE_MESOPIC_MAX_NITS);
+    const t = (Math.log(Math.max(adaptation_luminance, ADAPTATION_FLOOR_NITS)) - low) / (high - low);
+
+    return 1 - Math.min(1, Math.max(0, t));
+}
+
+/**
+ * @param {number} value
+ * @returns {string} as a WGSL float literal, with a point
+ */
+function wgsl_float(value) {
+    const text = String(value);
+    return /[.e]/.test(text) ? text : `${text}.0`;
+}
+
+/**
+ * @param {ReadonlyArray<number>} v
+ * @returns {string}
+ */
+function wgsl_vec3(v) {
+    return `vec3<f32>(${v.map(wgsl_float).join(", ")})`;
+}
+
+/**
+ * Purkinje shift.
+ * Human vision system shifts color perception away from red in night-time conditions.
+ *
+ * ```wgsl
+ * fn apply_purkinje_shift(color_rec709: vec3<f32>, adaptation_luminance: f32) -> vec3<f32>
+ * fn purkinje_rod_share(adaptation_luminance: f32) -> f32
+ * ```
+ *
+ * `color_rec709` is scene-linear Rec.709; `adaptation_luminance` is the luminance the eye is adapted to, cd/m². Above
+ * 5 cd/m² the colour is returned as it is; below 0.005 cd/m² it is the rod response alone, its scotopic luminance
+ * carried by a blue tint; in between the two blend linearly in log luminance, by `purkinje_rod_share`. The shift is
+ * linear in the colour, so it gives the same result ahead of the exposure as after it.
+ *
+ * The constants are the module's exports ({@link PURKINJE_REC709_SCOTOPIC} and the rest), and
+ * {@link purkinje_rod_share} is the share on the CPU.
+ *
+ * NOTE: this should go before the tonemapper.
+ *
+ * Notes on deriving it from the rod and cone responses: PURKINJE_PHYSICAL_DERIVATION_NOTES.md, beside this file.
+ *
+ * @see J. Patry, "Real-Time Samurai Cinema: Lighting, Atmosphere, and Tonemapping in Ghost of Tsushima", Advances in
+ *      Real-Time Rendering in Games, SIGGRAPH 2021 — the primary reference.
+ *      https://www.advances.realtimerendering.com/s2021/jpatry_advances2021/index.html
+ * @see A. G. Kirk, J. F. O'Brien, "Perceptually based tone mapping for low-light conditions", ACM TOG 30(4), 2011.
+ *      https://www2.eecs.berkeley.edu/Pubs/TechRpts/2011/EECS-2011-91.pdf
+ * @see D. Cao, J. Pokorny, V. C. Smith, A. J. Zele, "Rod contributions to color perception: linear with rod
+ *      contrast", Vision Research 48(26), 2008.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_apply_purkinje_shift = CodeChunk.from(
+    //language=WGSL
+    `
+const PURKINJE_REC709_PHOTOPIC = ${wgsl_vec3(PURKINJE_REC709_PHOTOPIC)}; // Day (Cones)
+const PURKINJE_REC709_SCOTOPIC = ${wgsl_vec3(PURKINJE_REC709_SCOTOPIC)}; // Night (Rods) - Validated
+const PURKINJE_NIGHT_TINT = ${wgsl_vec3(PURKINJE_NIGHT_TINT)};
+const PURKINJE_MESOPIC_MIN_NITS = ${wgsl_float(PURKINJE_MESOPIC_MIN_NITS)}; // Rods dominate below this
+const PURKINJE_MESOPIC_MAX_NITS = ${wgsl_float(PURKINJE_MESOPIC_MAX_NITS)}; // Cones dominate above this
+
+// how much of the response is the rods', linear in log luminance across the mesopic range: a perceptually linear
+// transition
+fn purkinje_rod_share(adaptation_luminance: f32) -> f32 {
+    let logLum = log(max(adaptation_luminance, ${wgsl_float(ADAPTATION_FLOOR_NITS)}));
+
+    const logLow = log(PURKINJE_MESOPIC_MIN_NITS);
+    const logHigh = log(PURKINJE_MESOPIC_MAX_NITS);
+    const logDelta = logHigh - logLow;
+
+    return 1.0 - saturate( (logLum - logLow) / logDelta );
+}
+
+fn apply_purkinje_shift(
+    color_rec709: vec3<f32>,
+    adaptation_luminance: f32
+) -> vec3<f32>{
+    // 1. Calculate Rod Luminance (Night)
+    // Note: Red objects will have a near-zero Y_night, making them turn black.
+    // Blue objects will have a high Y_night, making them appear brighter.
+    let Y_night = dot(color_rec709, PURKINJE_REC709_SCOTOPIC);
+
+    // 2. Construct the Night Vision Image
+    // We treat the rod signal as a scalar intensity applied to our blue tint
+    let color_night = Y_night * PURKINJE_NIGHT_TINT;
+
+    // 3. Lerp from Day view to Night view, by the rods' share at the adaptation
+    return mix(color_rec709, color_night, purkinje_rod_share(adaptation_luminance));
+}
+    `
+);

package/src/shade/renderer/shader/chunk/color/tonemap/purkinjie/chunk_apply_purkinjie_shift.d.ts

@@ -1,11 +0,0 @@
-/**
- * Purkinjie shift.
- * Human vision system shifts color perception away from red in nigh-time conditions.
- *
- * NOTE: this should go before the tonemapper.
- *
- * @type {CodeChunk}
- */
-export const chunk_apply_purkinjie_shift: CodeChunk;
-import { CodeChunk } from "../../../../compiler/CodeChunk.js";
-//# sourceMappingURL=chunk_apply_purkinjie_shift.d.ts.map

package/src/shade/renderer/shader/chunk/color/tonemap/purkinjie/chunk_apply_purkinjie_shift.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"chunk_apply_purkinjie_shift.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/shade/renderer/shader/chunk/color/tonemap/purkinjie/chunk_apply_purkinjie_shift.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,0CAFU,SAAS,CA+ClB;0BAvDyB,mCAAmC"}

package/src/shade/renderer/shader/chunk/color/tonemap/purkinjie/chunk_apply_purkinjie_shift.js

@@ -1,56 +0,0 @@
-import { CodeChunk } from "../../../../compiler/CodeChunk.js";
-
-/**
- * Purkinjie shift.
- * Human vision system shifts color perception away from red in nigh-time conditions.
- *
- * NOTE: this should go before the tonemapper.
- *
- * @type {CodeChunk}
- */
-export const chunk_apply_purkinjie_shift = CodeChunk.from(
-    //language=WGSL
-    `
-fn apply_purkinjie_shift(
-    color_rec709: vec3<f32>,
-    adaptation_luminance: f32
-) -> vec3<f32>{
-   // --- Constants for Rec.709 / sRGB ---
-    const  kRec709Photopic = vec3(0.2126, 0.7152, 0.0722); // Day (Cones)
-    const  kRec709Scotopic = vec3(0.0070, 0.5190, 0.4740); // Night (Rods) - Validated
-    
-    // "Rod Blue" - The color we tint the scotopic signal towards
-    // This is artistic, but (0.3, 0.5, 0.9) mimics the 507nm peak sensation
-    const  kNightTint = vec3(0.3, 0.5, 0.9);
-       
-    // 1. Calculate Standard Luminance (Day)
-    let Y_day = dot(color_rec709, kRec709Photopic);
-
-    // 2. Calculate Rod Luminance (Night)
-    // Note: Red objects will have a near-zero Y_night, making them turn black.
-    // Blue objects will have a high Y_night, making them appear brighter.
-    let Y_night = dot(color_rec709, kRec709Scotopic);
-
-    // 3. Construct the Night Vision Image
-    // We treat the rod signal as a scalar intensity applied to our blue tint
-    let color_night = Y_night * kNightTint;
-
-    // 4. Blend based on Adaptation
-    const MESOPIC_MIN_NITS = 0.005; // Rods dominate below this
-    const MESOPIC_MAX_NITS = 5.0; // Cones dominate above this
-    
-    let logLum = log(max(adaptation_luminance, 1e-5));
-    
-    const logLow = log(MESOPIC_MIN_NITS);
-    const logHigh = log(MESOPIC_MAX_NITS);
-    const logDelta = logHigh - logLow;
-
-    // 2. Calculate Blend Factor in Log Space
-    // This creates a perceptually linear transition
-    let t = 1.0 - saturate( (logLum - logLow) / logDelta );
-    
-    // Lerp from Day view to Night view
-    return mix(color_rec709, color_night, t);
-}
-    `
-)