@woosh/meep-engine 3.37.0 → 3.39.0

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

@@ -0,0 +1,242 @@
+import { assert } from "../../../../core/assert.js";
+import { WATER_KINDS, water_iop_spectral_reference } from "./water_iop_spectral_reference.js";
+
+/**
+ * @typedef {Object} WaterSpectralIOP
+ * @property {Float64Array} wavelengths nm, strictly increasing
+ * @property {Float64Array} absorption total absorption a(λ), pure water included, 1/m
+ * @property {Float64Array} molecular_scattering scattering by the water itself b_w(λ), 1/m; its phase
+ * is the molecular one, so its backscatter fraction is 1/2
+ * @property {Float64Array} particle_scattering scattering by everything suspended b_p(λ), 1/m
+ * @property {number} particle_backscatter_fraction B_p, the share of b_p deflected by more than 90
+ * degrees; selects the Fournier-Forand phase of the particles
+ */
+
+/**
+ * Prieur & Sathyendranath's chlorophyll-specific absorption spectrum of phytoplankton, normalized
+ * to 1 at 440 nm, 380 to 700 nm in 10 nm steps.
+ *
+ * Prieur, L. and Sathyendranath, S. (1981), "An optical classification of coastal and oceanic
+ * waters based on the specific spectral absorption curves of phytoplankton pigments, dissolved
+ * organic matter, and other particulate materials", Limnol. Oceanogr. 26(4), 671–689; 400–700 nm.
+ * Transcription: https://omlc.org/spectra/water/data/prieur81.txt. The 380 and 390 nm values are
+ * that transcription's extension "by eye" (Mobley), not the paper's.
+ *
+ * Above 700 nm the spectrum is taken as zero: the red chlorophyll band peaking at 675 nm has fallen
+ * to 0.215 by 700 nm, and pure water absorbs more than 0.6 1/m there, so the term is under 2% of the
+ * total for chlorophyll below 1 mg/m³.
+ *
+ * @type {ReadonlyArray<number>}
+ */
+const PRIEUR_SATHYENDRANATH_1981 = Object.freeze([
+    0.610, 0.660, 0.687, 0.828, 0.913, 0.973, 1.000, 0.944, 0.917, 0.870, 0.798,
+    0.750, 0.668, 0.618, 0.528, 0.474, 0.416, 0.357, 0.294, 0.276, 0.291, 0.282,
+    0.236, 0.252, 0.276, 0.317, 0.334, 0.356, 0.441, 0.595, 0.502, 0.329, 0.215,
+]);
+
+const PRIEUR_SATHYENDRANATH_MIN_NM = 380;
+const PRIEUR_SATHYENDRANATH_MAX_NM = 700;
+const PRIEUR_SATHYENDRANATH_STEP_NM = 10;
+
+/**
+ * Phytoplankton absorption at 440 nm per chlorophyll to the 0.65: a_ph(λ) = 0.06 A_chl(λ) Chl^0.65.
+ * Morel & Maritorena 2001, Appendix B, Eq. (16), the corrected form of Morel 1991 Eqs. (20a, b);
+ * A_chl is Prieur & Sathyendranath's normalized spectrum.
+ *
+ * Morel, A. and Maritorena, S. (2001), "Bio-optical properties of oceanic waters: a reappraisal",
+ * J. Geophys. Res. 106(C4), 7163–7180.
+ * @type {number}
+ */
+const PHYTOPLANKTON_ABSORPTION_440 = 0.06;
+
+/**
+ * @type {number}
+ */
+const PHYTOPLANKTON_ABSORPTION_EXPONENT = 0.65;
+
+/**
+ * Spectral slope of CDOM absorption, 1/nm: a_g(λ) = a_g(440) exp(-S (λ - 440)). Bricaud, Morel &
+ * Prieur 1981 (Limnol. Oceanogr. 26, 43–53), the value Morel & Maritorena 2001 Eq. (17) use. Babin
+ * et al. 2003a measured 0.0176 ± 0.0020 over European coastal waters; 0.014 is kept because the
+ * phytoplankton model above is Morel & Maritorena's and they pair it with this slope.
+ * @type {number}
+ */
+const CDOM_SLOPE = 0.014;
+
+/**
+ * Mass-specific absorption of mineral particles at 443 nm, m²/g. Babin & Stramski 2004 ("Variations
+ * in the mass-specific absorption coefficient of mineral particles suspended in water", Limnol.
+ * Oceanogr. 49(3), 756–767) measured 0.03–0.1 for most natural mineral assemblages and 0.044 for
+ * the mineral-dominated Rhône plume, inside the regional means of non-algal absorption per dry mass
+ * (0.033–0.067) of Babin et al. 2003a (J. Geophys. Res. 108(C7), 3211, Table 5, as quoted by Babin &
+ * Stramski). The Rhône value is used.
+ * @type {number}
+ */
+const MINERAL_ABSORPTION_443 = 0.044;
+
+/**
+ * Spectral slope of non-algal particle absorption, 1/nm: a_m(λ) = a_m(443) exp(-S (λ - 443)).
+ * Babin et al. 2003a: 0.0123 nm⁻¹ (SD 0.0013) over about 350 European coastal stations.
+ * @type {number}
+ */
+const MINERAL_ABSORPTION_SLOPE = 0.0123;
+
+/**
+ * Mass-specific scattering of mineral particles at 555 nm, m²/g. Babin et al. 2003b ("Light
+ * scattering properties of marine particles in coastal and open ocean waters as related to the
+ * particle mass concentration", Limnol. Oceanogr. 48(2), 843–859): 0.51 m²/g averaged over 180 case 2
+ * samples, where minerals dominate, and about 0.5 for minerals with Junge slopes 3.8–4.0 by Mie
+ * theory.
+ * @type {number}
+ */
+const MINERAL_SCATTERING_555 = 0.51;
+
+/**
+ * Particle backscatter fraction of mineral particles. Boss et al. 2004 ("Particulate backscattering
+ * ratio at LEO 15 and its use to study particle composition and distribution", J. Geophys. Res. 109,
+ * C01014) measured 0.006 where phytoplankton dominate, rising with the inorganic share to above 0.03
+ * at shallow resuspension-dominated stations. 0.02 sits toward the mineral end of that span, close
+ * to Petzold's average 0.0183.
+ * @type {number}
+ */
+const MINERAL_BACKSCATTER_FRACTION = 0.02;
+
+/**
+ * Phytoplankton scattering at 550 nm, b_p(550) = 0.416 Chl^0.766 (Morel & Maritorena 2001 Eq. (12),
+ * from Loisel & Morel 1998), with the λ⁻¹ dependence Morel & Maritorena adopt to carry it from 660 to
+ * 550 nm.
+ * @type {number}
+ */
+const PHYTOPLANKTON_SCATTERING_550 = 0.416;
+
+/**
+ * @type {number}
+ */
+const PHYTOPLANKTON_SCATTERING_EXPONENT = 0.766;
+
+/**
+ * Backscatter fraction convention for water without particles: the Fournier-Forand lobe then
+ * carries no scattering, so its shape has no effect, and Petzold's average (Mobley et al. 2002) is
+ * the value written.
+ * @type {number}
+ */
+const PARTICLE_FREE_BACKSCATTER_FRACTION = 0.0183;
+
+/**
+ * @param {number} wavelength
+ * @returns {number}
+ */
+function phytoplankton_specific_absorption(wavelength) {
+    if (wavelength > PRIEUR_SATHYENDRANATH_MAX_NM) {
+        return 0;
+    }
+
+    const x = (wavelength - PRIEUR_SATHYENDRANATH_MIN_NM) / PRIEUR_SATHYENDRANATH_STEP_NM;
+    const i0 = Math.min(Math.floor(x), PRIEUR_SATHYENDRANATH_1981.length - 2);
+    const t = x - i0;
+
+    return PRIEUR_SATHYENDRANATH_1981[i0] * (1 - t) + PRIEUR_SATHYENDRANATH_1981[i0 + 1] * t;
+}
+
+/**
+ * Backscattering efficiency of Case 1 particles at 550 nm, Morel & Maritorena 2001 Eq. (13):
+ * 0.002 + 0.01 (0.5 - 0.25 log10 Chl). The chlorophyll-dependent term is the share of small detritus,
+ * which they cap so the efficiency stays below 0.02, as biogenic particles cannot reach it; it
+ * vanishes at 100 mg/m³ and is kept at zero beyond. Eq. (13)'s spectral factor (λ/550)^v is not
+ * carried: one Fournier-Forand lobe has one backscatter fraction, and the factor moves b_bp by about
+ * 10% across 450–550 nm.
+ *
+ * @param {number} chlorophyll mg/m³, positive
+ * @returns {number}
+ */
+function phytoplankton_backscatter_fraction(chlorophyll) {
+    return 0.002 + 0.01 * Math.max(0, 0.5 - 0.25 * Math.log10(chlorophyll));
+}
+
+/**
+ * Inherent optical properties of natural water built from what is in it: phytoplankton (by its
+ * chlorophyll), coloured dissolved organic matter (by its absorption at 440 nm) and suspended
+ * minerals (by their dry mass).
+ *
+ * - absorption = pure water (Pope & Fry 1997) + phytoplankton (Morel & Maritorena 2001 Eq. 16 with
+ *   Prieur & Sathyendranath's spectrum) + CDOM (exponential, slope 0.014 nm⁻¹) + minerals (Babin
+ *   2003a/2004: 0.044 m²/g at 443 nm, slope 0.0123 nm⁻¹);
+ * - molecular scattering = Morel's law for sea water, or 1/1.30 of it for fresh water;
+ * - particle scattering = phytoplankton (Morel & Maritorena 2001 Eq. 12, λ⁻¹) + minerals (Babin
+ *   2003b: 0.51 m²/g, spectrally flat, since case 2 particle scattering spectra are flatter than λ⁻¹
+ *   and nearly coincide over 550–600 nm);
+ * - particle backscatter fraction = the two populations' fractions (Morel & Maritorena Eq. 13 at
+ *   550 nm; 0.02 for minerals) weighted by their scattering at 550 nm.
+ *
+ * Morel & Maritorena's Case 1 model ties CDOM to chlorophyll (their Eq. 18,
+ * a_g(440) = 0.2 [a_w(440) + 0.06 Chl^0.65]); here CDOM is its own input, so that lakes and coasts,
+ * where it does not follow chlorophyll, can be described.
+ *
+ * @param {Object} options
+ * @param {number} options.chlorophyll chlorophyll a concentration, mg/m³, ≥ 0
+ * @param {number} options.cdom_440 absorption by CDOM at 440 nm, 1/m, ≥ 0
+ * @param {number} options.mineral suspended mineral mass concentration, g/m³, ≥ 0
+ * @param {string} options.water_kind one of {@link WATER_KINDS}
+ * @returns {WaterSpectralIOP}
+ */
+export function water_iop_from_constituents({ chlorophyll, cdom_440, mineral, water_kind }) {
+    assert.isNumber(chlorophyll, 'chlorophyll');
+    assert.isFinite(chlorophyll, 'chlorophyll');
+    assert.greaterThanOrEqual(chlorophyll, 0, 'chlorophyll');
+
+    assert.isNumber(cdom_440, 'cdom_440');
+    assert.isFinite(cdom_440, 'cdom_440');
+    assert.greaterThanOrEqual(cdom_440, 0, 'cdom_440');
+
+    assert.isNumber(mineral, 'mineral');
+    assert.isFinite(mineral, 'mineral');
+    assert.greaterThanOrEqual(mineral, 0, 'mineral');
+
+    assert.isOneOf(water_kind, WATER_KINDS.slice(), 'water_kind');
+
+    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 = water_kind === 'sea'
+        ? reference.seawater_scattering
+        : reference.fresh_water_scattering;
+
+    const phytoplankton_absorption_scale = PHYTOPLANKTON_ABSORPTION_440 * Math.pow(chlorophyll, PHYTOPLANKTON_ABSORPTION_EXPONENT);
+    const phytoplankton_scattering_550 = PHYTOPLANKTON_SCATTERING_550 * Math.pow(chlorophyll, PHYTOPLANKTON_SCATTERING_EXPONENT);
+    const mineral_scattering = MINERAL_SCATTERING_555 * mineral;
+
+    for (let i = 0; i < count; i++) {
+        const wavelength = wavelengths[i];
+
+        absorption[i] = reference.pure_water_absorption[i]
+            + phytoplankton_absorption_scale * phytoplankton_specific_absorption(wavelength)
+            + cdom_440 * Math.exp(-CDOM_SLOPE * (wavelength - 440))
+            + mineral * MINERAL_ABSORPTION_443 * Math.exp(-MINERAL_ABSORPTION_SLOPE * (wavelength - 443));
+
+        particle_scattering[i] = phytoplankton_scattering_550 * (550 / wavelength) + mineral_scattering;
+    }
+
+    const particle_scattering_550 = phytoplankton_scattering_550 + mineral_scattering;
+
+    let particle_backscatter_fraction = PARTICLE_FREE_BACKSCATTER_FRACTION;
+
+    if (particle_scattering_550 > 0) {
+        const phytoplankton_backscatter = chlorophyll > 0
+            ? phytoplankton_backscatter_fraction(chlorophyll) * phytoplankton_scattering_550
+            : 0;
+
+        particle_backscatter_fraction = (phytoplankton_backscatter + MINERAL_BACKSCATTER_FRACTION * mineral_scattering)
+            / particle_scattering_550;
+    }
+
+    return {
+        wavelengths,
+        absorption,
+        molecular_scattering,
+        particle_scattering,
+        particle_backscatter_fraction,
+    };
+}

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

@@ -0,0 +1,41 @@
+/**
+ * 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 }: {
+    type: string;
+}): WaterSpectralIOP;
+/**
+ * @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: ReadonlyArray<string>;
+export type WaterSpectralIOP = import("./water_iop_from_constituents.js").WaterSpectralIOP;
+//# sourceMappingURL=water_iop_jerlov.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"water_iop_jerlov.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/medium/water/water_iop_jerlov.js"],"names":[],"mappings":"AA8HA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAH2B,IAAI,EAApB,MAAM;IACJ,gBAAgB,CA+E5B;AA9ND;;GAEG;AAEH;;;;GAIG;AACH,2BAFU,cAAc,MAAM,CAAC,CAEyE;+BAR3F,OAAO,kCAAkC,EAAE,gBAAgB"}

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"}