@woosh/meep-engine 3.38.0 → 3.40.0

package/src/shade/renderer/medium/water/water_iop_jerlov.js

@@ -0,0 +1,231 @@
+import { assert } from "../../../../core/assert.js";
+import {
+    water_iop_spectral_reference,
+    water_molecular_scattering,
+    water_pure_absorption,
+    WATER_SPECTRAL_WAVELENGTH_MIN
+} from "./water_iop_spectral_reference.js";
+
+/**
+ * @typedef {import("./water_iop_from_constituents.js").WaterSpectralIOP} WaterSpectralIOP
+ */
+
+/**
+ * The Jerlov water types Solonenko & Mobley tabulate: oceanic I to III, coastal 1C to 9C (odd only).
+ * @readonly
+ * @type {ReadonlyArray<string>}
+ */
+export const JERLOV_TYPES = Object.freeze(['I', 'IA', 'IB', 'II', 'III', '1C', '3C', '5C', '7C', '9C']);
+
+/**
+ * Wavelengths of the tables below, nm.
+ * @type {ReadonlyArray<number>}
+ */
+const TABLE_WAVELENGTHS = Object.freeze([375, 400, 425, 450, 475, 500, 525, 550, 575, 600, 625, 650, 675, 700]);
+
+/**
+ * Absorption a and scattering b, 1/m, of each Jerlov type, from Solonenko, M. G. and Mobley, C. D.
+ * (2015), "Inherent optical properties of Jerlov water types", Appl. Opt. 54(17), 5392–5401,
+ * https://dx.doi.org/10.1364/ao.54.005392, Tables 3–8; via the transcription
+ * https://raw.githubusercontent.com/tishibashi-cpu/jerlov/main/jerlov/data/solonenko2015_iop.csv
+ * (`value_per_m`), whose DATA.md lists the paper's errata. Handled here:
+ *
+ * - **3C at 675 and 700 nm, 5C from 600 to 700 nm** (DATA.md §1): the printed rows duplicate the
+ *   300–400 nm rows. `a` is unrecoverable and is `NaN` here; it is filled by holding the non-water
+ *   absorption of the last valid wavelength (see {@link water_iop_jerlov}). For comparison,
+ *   Williamson & Hollins 2022 interpolated 0.477, 0.592 (3C) and 0.259, 0.327, 0.367, 0.499, 0.598 (5C).
+ *   `b` at those rows is the transcription's reconstruction from the paper's own Eq. (8) and Table 3
+ *   with its small-particle coefficient 1.513 (`status = reconstructed`).
+ * - **Small-particle coefficient 1.513 against Haltrin's 1.151302** (DATA.md §6): the paper's b
+ *   column was computed with 1.513. The b column is used as published; it is internally consistent.
+ * - **Table 3 parameters for I and IA** (DATA.md §4) are wrong but not used; their b column, used
+ *   here, is the consistent one.
+ * - **Kd0 at 600 nm for I to II, 1C repeating III** (DATA.md §2, §3, §5) concern Jerlov's reference
+ *   Kd, which is not used.
+ *
+ * Solonenko & Mobley's b includes water itself with Haltrin's molecular law (0.005826 (400/λ)^4.322,
+ * lower than Morel's). For types I and IA their b is at or below Morel's sea water, so those types
+ * carry essentially no particle scattering here.
+ *
+ * @type {Readonly<Object<string, {a: ReadonlyArray<number>, b: ReadonlyArray<number>}>>}
+ */
+const SOLONENKO_MOBLEY_2015 = Object.freeze({
+    'I': Object.freeze({
+        a: Object.freeze([0.03, 0.022, 0.017, 0.018, 0.019, 0.026, 0.046, 0.062, 0.082, 0.228, 0.295, 0.334, 0.434, 0.582]),
+        b: Object.freeze([0.00811, 0.0062, 0.00482, 0.00381, 0.00306, 0.00249, 0.00205, 0.0017, 0.00143, 0.00122, 0.00104, 0.000899, 0.000782, 0.000685]),
+    }),
+    'IA': Object.freeze({
+        a: Object.freeze([0.0413, 0.0295, 0.0225, 0.0221, 0.0216, 0.0282, 0.0468, 0.0622, 0.0821, 0.228, 0.295, 0.334, 0.435, 0.582]),
+        b: Object.freeze([0.0114, 0.0092, 0.00755, 0.00631, 0.00536, 0.00461, 0.00402, 0.00354, 0.00315, 0.00283, 0.00256, 0.00234, 0.00214, 0.00198]),
+    }),
+    'IB': Object.freeze({
+        a: Object.freeze([0.0481, 0.0331, 0.0246, 0.0235, 0.0225, 0.0287, 0.0469, 0.0623, 0.0822, 0.2278, 0.296, 0.334, 0.435, 0.582]),
+        b: Object.freeze([0.0872, 0.0795, 0.0732, 0.068, 0.0635, 0.0597, 0.0565, 0.0536, 0.0511, 0.0488, 0.0468, 0.045, 0.0434, 0.042]),
+    }),
+    'II': Object.freeze({
+        a: Object.freeze([0.054, 0.0355, 0.0257, 0.0241, 0.0228, 0.0288, 0.0469, 0.0622, 0.0821, 0.228, 0.296, 0.334, 0.436, 0.582]),
+        b: Object.freeze([0.689, 0.616, 0.555, 0.504, 0.459, 0.421, 0.387, 0.358, 0.332, 0.309, 0.288, 0.27, 0.253, 0.238]),
+    }),
+    'III': Object.freeze({
+        a: Object.freeze([0.094, 0.0615, 0.0449, 0.0388, 0.0335, 0.0358, 0.0507, 0.0646, 0.0838, 0.229, 0.297, 0.336, 0.439, 0.583]),
+        b: Object.freeze([1.88, 1.69, 1.52, 1.38, 1.26, 1.152, 1.06, 0.98, 0.908, 0.845, 0.788, 0.737, 0.692, 0.65]),
+    }),
+    '1C': Object.freeze({
+        a: Object.freeze([0.386, 0.227, 0.147, 0.105, 0.077, 0.064, 0.068, 0.076, 0.092, 0.236, 0.304, 0.344, 0.455, 0.586]),
+        b: Object.freeze([0.704, 0.63, 0.567, 0.514, 0.469, 0.429, 0.395, 0.365, 0.338, 0.314, 0.293, 0.274, 0.257, 0.242]),
+    }),
+    '3C': Object.freeze({
+        a: Object.freeze([0.685, 0.388, 0.236, 0.154, 0.105, 0.081, 0.078, 0.082, 0.095, 0.239, 0.307, 0.346, NaN, NaN]),
+        b: Object.freeze([2.04, 1.83, 1.65, 1.5, 1.36, 1.25, 1.15, 1.06, 0.985, 0.916, 0.855, 0.8, 0.7542, 0.709]),
+    }),
+    '5C': Object.freeze({
+        a: Object.freeze([1.05, 0.66, 0.437, 0.297, 0.204, 0.151, 0.127, 0.117, 0.119, NaN, NaN, NaN, NaN, NaN]),
+        b: Object.freeze([2.55, 2.28, 2.06, 1.87, 1.71, 1.56, 1.44, 1.33, 1.23, 1.1468, 1.0702, 1.0014, 0.9395, 0.8834]),
+    }),
+    '7C': Object.freeze({
+        a: Object.freeze([1.45, 1.03, 0.753, 0.542, 0.388, 0.29, 0.233, 0.195, 0.175, 0.301, 0.367, 0.403, 0.559, 0.621]),
+        b: Object.freeze([4.49, 4.02, 3.63, 3.3, 3.01, 2.76, 2.54, 2.35, 2.18, 2.03, 1.89, 1.77, 1.66, 1.56]),
+    }),
+    '9C': Object.freeze({
+        a: Object.freeze([2.103, 1.613, 1.242, 0.943, 0.709, 0.543, 0.43, 0.348, 0.291, 0.39, 0.436, 0.456, 0.604, 0.651]),
+        b: Object.freeze([5.99, 5.36, 4.84, 4.39, 4.01, 3.67, 3.38, 3.12, 2.89, 2.69, 2.51, 2.35, 2.2, 2.07]),
+    }),
+});
+
+/**
+ * Particle backscatter fraction of the oceanic types I to III. Solonenko & Mobley's b does not
+ * constrain it (their Kd depends on b_b, which they took from Haltrin's two-population model, whose
+ * small/large split is a fitting device: DATA.md §10). The oceanic types are Case 1 waters, whose
+ * particles are biogenic: Morel & Maritorena 2001 Eq. (13) gives them a backscattering efficiency of
+ * 0.007 to 0.012 for chlorophyll from 1 down to 0.01 mg/m³ and argue it cannot reach 0.02; Boss et
+ * al. 2004 measured 0.006 where phytoplankton dominate. 0.01 is the round value inside that span.
+ * @type {number}
+ */
+const OCEANIC_BACKSCATTER_FRACTION = 0.01;
+
+/**
+ * Particle backscatter fraction of the coastal types 1C to 9C: Petzold's average, 0.0183 (Mobley,
+ * Sundman & Boss 2002, Appl. Opt. 41(6)), which lies between the 0.006 of phytoplankton-dominated
+ * and the 0.03 of mineral-dominated coastal water that Boss et al. 2004 measured on one shelf;
+ * coastal Jerlov water is a mixture of the two.
+ * @type {number}
+ */
+const COASTAL_BACKSCATTER_FRACTION = 0.0183;
+
+/**
+ * Pure-water absorption at a table wavelength. 375 nm lies below Pope & Fry's first value; their
+ * 380 nm value stands in for it (water's own absorption changes by well under its own size over those
+ * 5 nm, and it is under 30% of every type's total there).
+ *
+ * @param {number} wavelength
+ * @returns {number}
+ */
+function table_pure_absorption(wavelength) {
+    return water_pure_absorption({ wavelength: Math.max(wavelength, WATER_SPECTRAL_WAVELENGTH_MIN) });
+}
+
+/**
+ * Inherent optical properties of a Jerlov water type, on the water tools' 5 nm grid.
+ *
+ * - **Absorption.** Solonenko & Mobley's a is split into pure water (Pope & Fry, the engine's
+ *   reference) and the rest; the rest is interpolated linearly between their 25 nm points and added
+ *   back to the 5 nm pure-water spectrum, so water's own fine structure (the 600 nm edge) is kept.
+ *   Where their a falls below Pope & Fry's (650–700 nm for most types: their pure-water term was a
+ *   different one, up to 7% lower at 700 nm) the rest is zero. Beyond the last valid wavelength
+ *   (700 nm, or the errata gaps of 3C and 5C) the rest is held at its last value.
+ * - **Scattering.** Their b is interpolated as a power law between points (log-log linear),
+ *   continued past 700 nm with the 675–700 nm exponent. The molecular part is Morel's sea water
+ *   law; the particle part is b minus that, never negative.
+ * - **Particle backscatter fraction.** Not in the source; 0.01 for the oceanic types, 0.0183 for the
+ *   coastal ones (see the constants for the rationale).
+ *
+ * Measured consequence, reported rather than hidden: Gordon's K_d = 1.0395 (a + b_b)/cos θ_w of
+ * these IOPs, sun at zenith, reproduces Solonenko & Mobley's K_d for the particle-poor types I and IA
+ * (within 6% to 625 nm, 9% to 700 nm, where Pope & Fry's water absorbs more than theirs), but falls
+ * 25–55% short over 400–575 nm for II, III and the coastal types. Closing it with their a and b would
+ * need a particle backscatter fraction of 0.04–0.16 (depending on the sky, D0 from 1 to 1.197), above
+ * the 0.035 that Boss et al. 2004 measured at most: their fit put into backscattering what natural
+ * water holds in absorption. The spec pins both facts.
+ *
+ * @param {Object} options
+ * @param {string} options.type one of {@link JERLOV_TYPES}
+ * @returns {WaterSpectralIOP}
+ */
+export function water_iop_jerlov({ type }) {
+    assert.isOneOf(type, JERLOV_TYPES.slice(), 'type');
+
+    const table = SOLONENKO_MOBLEY_2015[type];
+    const table_count = TABLE_WAVELENGTHS.length;
+
+    // non-water absorption at the table's valid points
+    /** @type {number[]} */
+    const residual_wavelengths = [];
+    /** @type {number[]} */
+    const residual_values = [];
+
+    for (let i = 0; i < table_count; i++) {
+        const a = table.a[i];
+
+        if (Number.isNaN(a)) {
+            continue;
+        }
+
+        residual_wavelengths.push(TABLE_WAVELENGTHS[i]);
+        residual_values.push(a - table_pure_absorption(TABLE_WAVELENGTHS[i]));
+    }
+
+    const reference = water_iop_spectral_reference();
+    const wavelengths = reference.wavelengths;
+    const count = wavelengths.length;
+
+    const absorption = new Float64Array(count);
+    const particle_scattering = new Float64Array(count);
+    const molecular_scattering = reference.seawater_scattering;
+
+    const residual_last = residual_wavelengths.length - 1;
+
+    for (let i = 0; i < count; i++) {
+        const wavelength = wavelengths[i];
+
+        // absorption
+        let residual;
+
+        if (wavelength >= residual_wavelengths[residual_last]) {
+            residual = residual_values[residual_last];
+        } else {
+            let j = 0;
+
+            while (residual_wavelengths[j + 1] <= wavelength) {
+                j++;
+            }
+
+            const t = (wavelength - residual_wavelengths[j]) / (residual_wavelengths[j + 1] - residual_wavelengths[j]);
+
+            residual = residual_values[j] * (1 - t) + residual_values[j + 1] * t;
+        }
+
+        absorption[i] = reference.pure_water_absorption[i] + Math.max(0, residual);
+
+        // scattering, power law between the table's points
+        let k = 0;
+
+        while (k < table_count - 2 && TABLE_WAVELENGTHS[k + 1] <= wavelength) {
+            k++;
+        }
+
+        const exponent = Math.log(table.b[k + 1] / table.b[k]) / Math.log(TABLE_WAVELENGTHS[k + 1] / TABLE_WAVELENGTHS[k]);
+        const b = table.b[k] * Math.pow(wavelength / TABLE_WAVELENGTHS[k], exponent);
+
+        particle_scattering[i] = Math.max(0, b - water_molecular_scattering({ wavelength, water_kind: 'sea' }));
+    }
+
+    const oceanic = type === 'I' || type === 'IA' || type === 'IB' || type === 'II' || type === 'III';
+
+    return {
+        wavelengths,
+        absorption,
+        molecular_scattering,
+        particle_scattering,
+        particle_backscatter_fraction: oceanic ? OCEANIC_BACKSCATTER_FRACTION : COASTAL_BACKSCATTER_FRACTION,
+    };
+}

package/src/shade/renderer/medium/water/water_iop_spectral_reference.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Molecular scattering coefficient of pure water, 1/m.
+ *
+ * @param {Object} options
+ * @param {number} options.wavelength nm
+ * @param {string} options.water_kind one of {@link WATER_KINDS}
+ * @returns {number}
+ */
+export function water_molecular_scattering({ wavelength, water_kind }: {
+    wavelength: number;
+    water_kind: string;
+}): number;
+/**
+ * Absorption coefficient of pure water, 1/m: Pope & Fry 1997 from 380 to 700 nm, Smith & Baker
+ * 1981 above, linear between tabulated values.
+ *
+ * @param {Object} options
+ * @param {number} options.wavelength nm, within [{@link WATER_SPECTRAL_WAVELENGTH_MIN}, {@link WATER_SPECTRAL_WAVELENGTH_MAX}]
+ * @returns {number}
+ */
+export function water_pure_absorption({ wavelength }: {
+    wavelength: number;
+}): number;
+/**
+ * The wavelengths of the water tools' spectral grid, nm. A new array on every call.
+ *
+ * @returns {Float64Array}
+ */
+export function water_spectral_wavelengths(): Float64Array;
+/**
+ * The tabulated optics of water itself on the 5 nm grid: absorption of pure water and molecular
+ * scattering of pure sea water and of fresh water. New arrays on every call.
+ *
+ * @returns {{wavelengths: Float64Array, pure_water_absorption: Float64Array, seawater_scattering: Float64Array, fresh_water_scattering: Float64Array}}
+ * coefficients in 1/m, wavelengths in nm
+ */
+export function water_iop_spectral_reference(): {
+    wavelengths: Float64Array;
+    pure_water_absorption: Float64Array;
+    seawater_scattering: Float64Array;
+    fresh_water_scattering: Float64Array;
+};
+/**
+ * The spectral grid every water tool works on: 380 to 780 nm in 5 nm steps. That is the range the
+ * CIE 1931 colour matching functions carry visible weight over, and the range the Mie colour
+ * precedent (`compute_mie_particle_properties_rgb`) integrates, so the red end of the red channel is
+ * covered.
+ * @type {number}
+ */
+export const WATER_SPECTRAL_WAVELENGTH_MIN: number;
+/**
+ * @type {number}
+ */
+export const WATER_SPECTRAL_WAVELENGTH_MAX: number;
+/**
+ * @type {number}
+ */
+export const WATER_SPECTRAL_WAVELENGTH_STEP: number;
+/**
+ * What the water is, as far as its molecules are concerned: sea salt adds scattering, it does not
+ * change absorption in the visible.
+ * @readonly
+ * @type {ReadonlyArray<string>}
+ */
+export const WATER_KINDS: ReadonlyArray<string>;
+//# sourceMappingURL=water_iop_spectral_reference.d.ts.map

package/src/shade/renderer/medium/water/water_iop_spectral_reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"water_iop_spectral_reference.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/medium/water/water_iop_spectral_reference.js"],"names":[],"mappings":"AAqHA;;;;;;;GAOG;AACH;IAJ2B,UAAU,EAA1B,MAAM;IACU,UAAU,EAA1B,MAAM;IACJ,MAAM,CAclB;AAED;;;;;;;GAOG;AACH;IAH2B,UAAU,EAA1B,MAAM;IACJ,MAAM,CA8BlB;AAED;;;;GAIG;AACH,8CAFa,YAAY,CAWxB;AAED;;;;;;GAMG;AACH,gDAHa;IAAC,WAAW,EAAE,YAAY,CAAC;IAAC,qBAAqB,EAAE,YAAY,CAAC;IAAC,mBAAmB,EAAE,YAAY,CAAC;IAAC,sBAAsB,EAAE,YAAY,CAAA;CAAC,CAyBrJ;AA5ND;;;;;;GAMG;AACH,4CAFU,MAAM,CAEiC;AAEjD;;GAEG;AACH,4CAFU,MAAM,CAEiC;AAEjD;;GAEG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;;;GAKG;AACH,0BAFU,cAAc,MAAM,CAAC,CAE4B"}

package/src/shade/renderer/medium/water/water_iop_spectral_reference.js

@@ -0,0 +1,223 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * The spectral grid every water tool works on: 380 to 780 nm in 5 nm steps. That is the range the
+ * CIE 1931 colour matching functions carry visible weight over, and the range the Mie colour
+ * precedent (`compute_mie_particle_properties_rgb`) integrates, so the red end of the red channel is
+ * covered.
+ * @type {number}
+ */
+export const WATER_SPECTRAL_WAVELENGTH_MIN = 380;
+
+/**
+ * @type {number}
+ */
+export const WATER_SPECTRAL_WAVELENGTH_MAX = 780;
+
+/**
+ * @type {number}
+ */
+export const WATER_SPECTRAL_WAVELENGTH_STEP = 5;
+
+/**
+ * What the water is, as far as its molecules are concerned: sea salt adds scattering, it does not
+ * change absorption in the visible.
+ * @readonly
+ * @type {ReadonlyArray<string>}
+ */
+export const WATER_KINDS = Object.freeze(['sea', 'fresh']);
+
+/**
+ * Absorption coefficient of pure water, 380 to 700 nm in 2.5 nm steps, in 1/cm exactly as printed.
+ *
+ * Pope, R. M. and Fry, E. S. (1997), "Absorption spectrum (380–700 nm) of pure water. II. Integrating
+ * cavity measurements", Appl. Opt. 36(33), 8710–8723. Transcription:
+ * https://omlc.org/spectra/water/data/pope97.txt (checked: 450, 550 and 650 nm give 0.00922, 0.0565
+ * and 0.340 1/m, the anchors the water optics plan quotes). That transcription also lists values from
+ * 702.5 to 727.5 nm; they are not used, because the paper's stated range ends at 700 nm, and Smith &
+ * Baker take over there.
+ *
+ * Mason, Cone & Fry 2016 (Appl. Opt. 55(25)) remeasured below 550 nm and found lower values in the
+ * violet. Their table was not obtained, so Pope & Fry is used down to 380 nm; in natural water the
+ * dissolved and particulate absorption there is larger than either.
+ *
+ * @type {ReadonlyArray<number>}
+ */
+const POPE_FRY_1997_PER_CM = Object.freeze([
+    0.0001137, 0.0001044, 0.0000941, 0.0000917, 0.0000851, 0.0000829, 0.0000813, 0.0000775,
+    0.0000663, 0.0000579, 0.000053, 0.0000503, 0.0000473, 0.0000452, 0.0000444, 0.0000442,
+    0.0000454, 0.0000474, 0.0000478, 0.0000482, 0.0000495, 0.0000504, 0.000053, 0.000058,
+    0.0000635, 0.0000696, 0.0000751, 0.000083, 0.0000922, 0.0000969, 0.0000962, 0.0000957,
+    0.0000979, 0.0001005, 0.0001011, 0.000102, 0.000106, 0.000109, 0.000114, 0.000121,
+    0.000127, 0.000131, 0.000136, 0.000144, 0.00015, 0.000162, 0.000173, 0.000191,
+    0.000204, 0.000228, 0.000256, 0.00028, 0.000325, 0.000372, 0.000396, 0.000399,
+    0.000409, 0.000416, 0.000417, 0.000428, 0.000434, 0.000447, 0.000452, 0.000466,
+    0.000474, 0.000489, 0.000511, 0.000537, 0.000565, 0.000593, 0.000596, 0.000606,
+    0.000619, 0.00064, 0.000642, 0.000672, 0.000695, 0.000733, 0.000772, 0.000836,
+    0.000896, 0.000989, 0.0011, 0.00122, 0.001351, 0.001516, 0.001672, 0.001925,
+    0.002224, 0.00247, 0.002577, 0.002629, 0.002644, 0.002665, 0.002678, 0.002707,
+    0.002755, 0.00281, 0.002834, 0.002904, 0.002916, 0.002995, 0.003012, 0.003077,
+    0.003108, 0.00322, 0.00325, 0.00335, 0.0034, 0.00358, 0.00371, 0.00393,
+    0.0041, 0.00424, 0.00429, 0.00436, 0.00439, 0.00448, 0.00448, 0.00461,
+    0.00465, 0.00478, 0.00486, 0.00502, 0.00516, 0.00538, 0.00559, 0.00592,
+    0.00624,
+]);
+
+const POPE_FRY_MIN_NM = 380;
+const POPE_FRY_MAX_NM = 700;
+const POPE_FRY_STEP_NM = 2.5;
+
+/**
+ * Absorption coefficient of the clearest natural water, 710 to 800 nm in 10 nm steps, in 1/cm
+ * exactly as printed. Used above Pope & Fry's 700 nm.
+ *
+ * Smith, R. C. and Baker, K. S. (1981), "Optical properties of the clearest natural waters
+ * (200–800 nm)", Appl. Opt. 20(2), 177–184. Transcription:
+ * https://omlc.org/spectra/water/data/smith81.txt
+ *
+ * Between Pope & Fry's last value (700 nm) and Smith & Baker's first used one (710 nm) the two are
+ * joined linearly. At 700 nm the sources differ by 4% (0.624 against 0.65 1/m), small beside the
+ * 0.6 1/m itself: nothing red survives a metre or two there anyway.
+ *
+ * @type {ReadonlyArray<number>}
+ */
+const SMITH_BAKER_1981_PER_CM = Object.freeze([
+    0.00839, 0.01169, 0.01799, 0.0238, 0.0247, 0.0255, 0.0251, 0.0236, 0.0216, 0.0207,
+]);
+
+const SMITH_BAKER_MIN_NM = 710;
+const SMITH_BAKER_STEP_NM = 10;
+
+/**
+ * Scattering coefficient of pure sea water at 500 nm, 1/m, and the exponent of its wavelength
+ * dependence: b_w(λ) = 0.00288 (λ / 500)^-4.32.
+ *
+ * Morel, A. (1974), "Optical properties of pure water and pure sea water", in Optical Aspects of
+ * Oceanography, Jerlov & Steemann Nielsen (eds.), 1–24; as given by Mobley's lecture "Scattering
+ * models" (https://misclab.umeoce.maine.edu/ftp/classes/OO2011/Lectures/Mobley_Lec7_Scattering_Models.pdf),
+ * b_w(λ) = 75.5e-4 (λ / 400)^-4.32, which is the same law (0.00755 · 1.25^-4.32 = 0.00288).
+ * @type {number}
+ */
+const SEAWATER_SCATTERING_500 = 0.00288;
+
+/**
+ * @type {number}
+ */
+const MOLECULAR_SCATTERING_EXPONENT = -4.32;
+
+/**
+ * How much more sea water scatters than fresh water. Morel measured natural sea water of salinity
+ * 38.4 at five wavelengths from 366 to 578 nm and found it scattered on average 30% more than pure
+ * water (Zhang, Hu & He 2009, "Scattering by pure seawater: effect of salinity", Opt. Express 17(7),
+ * 5698–5710, which also confirms Morel's measurement to 1% with an independent theory). Fresh water
+ * therefore scatters 1 / 1.30 of sea water, with the same wavelength law.
+ * @type {number}
+ */
+const SEAWATER_OVER_FRESH_WATER_SCATTERING = 1.3;
+
+/**
+ * Molecular scattering coefficient of pure water, 1/m.
+ *
+ * @param {Object} options
+ * @param {number} options.wavelength nm
+ * @param {string} options.water_kind one of {@link WATER_KINDS}
+ * @returns {number}
+ */
+export function water_molecular_scattering({ wavelength, water_kind }) {
+    assert.isNumber(wavelength, 'wavelength');
+    assert.greaterThan(wavelength, 0, 'wavelength');
+    assert.isOneOf(water_kind, WATER_KINDS.slice(), 'water_kind');
+
+    const sea = SEAWATER_SCATTERING_500 * Math.pow(wavelength / 500, MOLECULAR_SCATTERING_EXPONENT);
+
+    if (water_kind === 'sea') {
+        return sea;
+    }
+
+    return sea / SEAWATER_OVER_FRESH_WATER_SCATTERING;
+}
+
+/**
+ * Absorption coefficient of pure water, 1/m: Pope & Fry 1997 from 380 to 700 nm, Smith & Baker
+ * 1981 above, linear between tabulated values.
+ *
+ * @param {Object} options
+ * @param {number} options.wavelength nm, within [{@link WATER_SPECTRAL_WAVELENGTH_MIN}, {@link WATER_SPECTRAL_WAVELENGTH_MAX}]
+ * @returns {number}
+ */
+export function water_pure_absorption({ wavelength }) {
+    assert.isNumber(wavelength, 'wavelength');
+    assert.greaterThanOrEqual(wavelength, WATER_SPECTRAL_WAVELENGTH_MIN, 'wavelength');
+    assert.lessThanOrEqual(wavelength, WATER_SPECTRAL_WAVELENGTH_MAX, 'wavelength');
+
+    let per_cm;
+
+    if (wavelength <= POPE_FRY_MAX_NM) {
+        const x = (wavelength - POPE_FRY_MIN_NM) / POPE_FRY_STEP_NM;
+        const i0 = Math.min(Math.floor(x), POPE_FRY_1997_PER_CM.length - 2);
+        const t = x - i0;
+
+        per_cm = POPE_FRY_1997_PER_CM[i0] * (1 - t) + POPE_FRY_1997_PER_CM[i0 + 1] * t;
+    } else if (wavelength < SMITH_BAKER_MIN_NM) {
+        // the seam: Pope & Fry's 700 nm to Smith & Baker's 710 nm
+        const t = (wavelength - POPE_FRY_MAX_NM) / (SMITH_BAKER_MIN_NM - POPE_FRY_MAX_NM);
+
+        per_cm = POPE_FRY_1997_PER_CM[POPE_FRY_1997_PER_CM.length - 1] * (1 - t) + SMITH_BAKER_1981_PER_CM[0] * t;
+    } else {
+        const x = (wavelength - SMITH_BAKER_MIN_NM) / SMITH_BAKER_STEP_NM;
+        const i0 = Math.min(Math.floor(x), SMITH_BAKER_1981_PER_CM.length - 2);
+        const t = x - i0;
+
+        per_cm = SMITH_BAKER_1981_PER_CM[i0] * (1 - t) + SMITH_BAKER_1981_PER_CM[i0 + 1] * t;
+    }
+
+    // 1/cm to 1/m
+    return per_cm * 100;
+}
+
+/**
+ * The wavelengths of the water tools' spectral grid, nm. A new array on every call.
+ *
+ * @returns {Float64Array}
+ */
+export function water_spectral_wavelengths() {
+    const count = (WATER_SPECTRAL_WAVELENGTH_MAX - WATER_SPECTRAL_WAVELENGTH_MIN) / WATER_SPECTRAL_WAVELENGTH_STEP + 1;
+    const wavelengths = new Float64Array(count);
+
+    for (let i = 0; i < count; i++) {
+        wavelengths[i] = WATER_SPECTRAL_WAVELENGTH_MIN + i * WATER_SPECTRAL_WAVELENGTH_STEP;
+    }
+
+    return wavelengths;
+}
+
+/**
+ * The tabulated optics of water itself on the 5 nm grid: absorption of pure water and molecular
+ * scattering of pure sea water and of fresh water. New arrays on every call.
+ *
+ * @returns {{wavelengths: Float64Array, pure_water_absorption: Float64Array, seawater_scattering: Float64Array, fresh_water_scattering: Float64Array}}
+ * coefficients in 1/m, wavelengths in nm
+ */
+export function water_iop_spectral_reference() {
+    const wavelengths = water_spectral_wavelengths();
+    const count = wavelengths.length;
+
+    const pure_water_absorption = new Float64Array(count);
+    const seawater_scattering = new Float64Array(count);
+    const fresh_water_scattering = new Float64Array(count);
+
+    for (let i = 0; i < count; i++) {
+        const wavelength = wavelengths[i];
+
+        pure_water_absorption[i] = water_pure_absorption({ wavelength });
+        seawater_scattering[i] = water_molecular_scattering({ wavelength, water_kind: 'sea' });
+        fresh_water_scattering[i] = water_molecular_scattering({ wavelength, water_kind: 'fresh' });
+    }
+
+    return {
+        wavelengths,
+        pure_water_absorption,
+        seawater_scattering,
+        fresh_water_scattering,
+    };
+}

package/src/shade/renderer/medium/water/water_medium_from_iop.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Fit each spectral coefficient of a water description to RGB with {@link water_rgb_from_spectral},
+ * one at a time: absorption, molecular scattering and particle scattering. Each is fitted on its
+ * own because each becomes its own field of the medium. The fit is not linear, so the sum of the
+ * three fits is not the fit of the summed beam attenuation: for Jerlov II they agree within 1% in
+ * green and 2% in blue, and the sum is 8% higher in red.
+ *
+ * @param {Object} options
+ * @param {WaterSpectralIOP} options.iop
+ * @param {ArrayLike<number>} options.path_lengths metres
+ * @returns {{iop: WaterRgbIOP, residual: {absorption: number, molecular_scattering: number, particle_scattering: number}}}
+ * the RGB description, and each fit's worst ΔE*ab over the path lengths
+ */
+export function water_rgb_iop_from_spectral({ iop, path_lengths }: {
+    iop: WaterSpectralIOP;
+    path_lengths: ArrayLike<number>;
+}): {
+    iop: WaterRgbIOP;
+    residual: {
+        absorption: number;
+        molecular_scattering: number;
+        particle_scattering: number;
+    };
+};
+/**
+ * Build the engine's medium from an RGB water description: the absorption, then the water's own
+ * scattering with the molecular phase (depolarization 0.039), then the particles' scattering with
+ * the Fournier-Forand phase of their backscatter fraction. Both lobes are always present, a zero
+ * coefficient included, so every water medium has the same shape.
+ *
+ * @param {Object} options
+ * @param {WaterRgbIOP} options.iop
+ * @returns {ParticipatingMedium}
+ */
+export function water_medium_from_rgb_iop({ iop }: {
+    iop: WaterRgbIOP;
+}): ParticipatingMedium;
+/**
+ * Build the engine's medium from a spectral water description, fitting it to RGB over the given
+ * path lengths ({@link water_rgb_iop_from_spectral}, then {@link water_medium_from_rgb_iop}).
+ *
+ * @param {Object} options
+ * @param {WaterSpectralIOP} options.iop
+ * @param {ArrayLike<number>} options.path_lengths metres; `WATER_DEFAULT_PATH_LENGTHS` unless there
+ * is a reason to weigh other distances
+ * @returns {ParticipatingMedium}
+ */
+export function water_medium_from_iop({ iop, path_lengths }: {
+    iop: WaterSpectralIOP;
+    path_lengths: ArrayLike<number>;
+}): ParticipatingMedium;
+/**
+ * @typedef {import("./water_iop_from_constituents.js").WaterSpectralIOP} WaterSpectralIOP
+ */
+/**
+ * The inherent optical properties of a water body in the engine's linear RGB working space, what a
+ * {@link ParticipatingMedium} is built from.
+ *
+ * @typedef {Object} WaterRgbIOP
+ * @property {number[]} absorption total absorption a, RGB, 1/m
+ * @property {number[]} molecular_scattering scattering by the water itself b_w, RGB, 1/m
+ * @property {number[]} particle_scattering scattering by suspended particles b_p, RGB, 1/m
+ * @property {number} particle_backscatter_fraction B_p of the particles' Fournier-Forand phase
+ */
+/**
+ * Depolarization ratio of water's molecular scattering, which fixes the shape of its phase function
+ * (1 + 0.925 cos²ψ): 0.039, Farinato & Rowell 1976, as adopted by Zhang et al. 2009 (Opt. Express
+ * 17(7)) and the water optics plan (§3.2).
+ * @type {number}
+ */
+export const WATER_MOLECULAR_DEPOLARIZATION: number;
+export type WaterSpectralIOP = import("./water_iop_from_constituents.js").WaterSpectralIOP;
+/**
+ * The inherent optical properties of a water body in the engine's linear RGB working space, what a
+ * {@link ParticipatingMedium } is built from.
+ */
+export type WaterRgbIOP = {
+    /**
+     * total absorption a, RGB, 1/m
+     */
+    absorption: number[];
+    /**
+     * scattering by the water itself b_w, RGB, 1/m
+     */
+    molecular_scattering: number[];
+    /**
+     * scattering by suspended particles b_p, RGB, 1/m
+     */
+    particle_scattering: number[];
+    /**
+     * B_p of the particles' Fournier-Forand phase
+     */
+    particle_backscatter_fraction: number;
+};
+import { ParticipatingMedium } from "../ParticipatingMedium.js";
+//# sourceMappingURL=water_medium_from_iop.d.ts.map

package/src/shade/renderer/medium/water/water_medium_from_iop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"water_medium_from_iop.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/medium/water/water_medium_from_iop.js"],"names":[],"mappings":"AA+CA;;;;;;;;;;;;GAYG;AACH;IALqC,GAAG,EAA7B,gBAAgB;IACW,YAAY,EAAvC,UAAU,MAAM,CAAC;IACf;IAAC,GAAG,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,oBAAoB,EAAE,MAAM,CAAC;QAAC,mBAAmB,EAAE,MAAM,CAAA;KAAC,CAAA;CAAC,CAsCzH;AAED;;;;;;;;;GASG;AACH;IAHgC,GAAG,EAAxB,WAAW;IACT,mBAAmB,CAuB/B;AAED;;;;;;;;;GASG;AACH;IALqC,GAAG,EAA7B,gBAAgB;IACW,YAAY,EAAvC,UAAU,MAAM,CAAC;IAEf,mBAAmB,CAM/B;AAtID;;GAEG;AAEH;;;;;;;;;GASG;AAEH;;;;;GAKG;AACH,6CAFU,MAAM,CAEoC;+BApBvC,OAAO,kCAAkC,EAAE,gBAAgB;;;;;;;;;gBAQ1D,MAAM,EAAE;;;;0BACR,MAAM,EAAE;;;;yBACR,MAAM,EAAE;;;;mCACR,MAAM;;oCAjBgB,2BAA2B"}