@woosh/meep-engine 3.38.0 → 3.40.0

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

@@ -0,0 +1,174 @@
+import { assert } from "../../../../core/assert.js";
+import {
+    FOURNIER_FORAND_BACKSCATTER_MAX,
+    FOURNIER_FORAND_BACKSCATTER_MIN
+} from "../../shader/chunk/atmosphere/phase/ff/fournier_forand_parameters_from_backscatter.js";
+import { WATER_DEFAULT_PATH_LENGTHS } from "./WATER_DEFAULT_PATH_LENGTHS.js";
+import { WATER_KINDS, water_iop_spectral_reference } from "./water_iop_spectral_reference.js";
+import { water_rgb_from_spectral } from "./water_rgb_from_spectral.js";
+
+/**
+ * @typedef {import("./water_medium_from_iop.js").WaterRgbIOP} WaterRgbIOP
+ */
+
+/**
+ * Coefficients of the deep-water reflectance relation r_rs = g0 u + g1 u², u = b_b / (a + b_b),
+ * the sub-surface remote-sensing reflectance of optically deep water (Gordon et al. 1988, as used by
+ * the Quasi-Analytical Algorithm: Lee et al., QAA v6, IOCCG 2014,
+ * https://ioccg.org/wp-content/uploads/2020/11/qaa_v6_202011.pdf, step 0: g0 = 0.089, g1 = 0.1245).
+ * The water optics plan uses the same relation as the closure target of its multiple scattering
+ * (§4.4), so a body built from this inversion is rendered with the colour it was asked for.
+ */
+const QAA_G0 = 0.089;
+const QAA_G1 = 0.1245;
+
+/**
+ * Horizontal sighting range of a black target times the photopic beam attenuation coefficient:
+ * 4.8 (Davies-Colley 1988, "Measuring water clarity with a black disk", Limnol. Oceanogr. 33(4),
+ * 616–623); Zaneveld & Pegau 2003 ("Robust underwater visibility parameter", Opt. Express 11(23),
+ * 2997–3009) find it within 10% over a wide range of coastal and inland waters and viewing
+ * conditions.
+ * @type {number}
+ */
+const BLACK_DISK_VISIBILITY_TIMES_ATTENUATION = 4.8;
+
+/**
+ * Relative slack on the pure-water floor, so that a colour computed from pure water itself is
+ * accepted despite the round trip through floating point.
+ * @type {number}
+ */
+const FLOOR_TOLERANCE = 1e-9;
+
+/**
+ * Index of the channel whose beam attenuation the clarity distance sets.
+ * @type {number}
+ */
+const GREEN = 1;
+
+/**
+ * u from r_rs, the positive root of g1 u² + g0 u - r_rs = 0 (QAA v6 step 0).
+ *
+ * @param {number} rrs
+ * @returns {number}
+ */
+function u_from_rrs(rrs) {
+    return (-QAA_G0 + Math.sqrt(QAA_G0 * QAA_G0 + 4 * QAA_G1 * rrs)) / (2 * QAA_G1);
+}
+
+/**
+ * Inherent optical properties, in RGB, of water that looks a given colour when deep and lets one see
+ * a given distance.
+ *
+ * **The colour** is the sub-surface remote-sensing reflectance r_rs of optically deep water, per
+ * linear RGB channel, sr⁻¹ (radiance just below the surface over downwelling irradiance; above the
+ * surface it is about 0.52 of that, QAA's Rrs = 0.52 r_rs / (1 - 1.7 r_rs)). The presets give a
+ * scale: pure fresh water (0.0001, 0.0014, 0.030), Jerlov IB (0.0002, 0.0027, 0.013), Jerlov 3C
+ * (0.0039, 0.024, 0.018), the green lake (0.0020, 0.0040, 0.0022). Inverting QAA's relation gives
+ * u = b_b / (a + b_b) per channel, which fixes absorption relative to backscattering,
+ * a = b_b (1 - u) / u, but not their size.
+ *
+ * **The distance** fixes the size. It is the horizontal sighting range of a black target, 4.8 / c
+ * (Davies-Colley 1988), and it sets the beam attenuation c = a + b of the green channel. Zaneveld &
+ * Pegau 2003 state the law for "a green light attenuation coefficient" as well as for the photopic
+ * one, and green is the RGB channel at the photopic peak. A luminance-weighted c would instead count
+ * the red that the first metres of water have already removed from the light a diver sees by: it
+ * would cap pure water at 45 m, while its green c (0.049 1/m) gives 98 m.
+ *
+ * **The assumption that closes it**: particle scattering is the same in all three channels. Babin et
+ * al. 2003b found spectral variations in particle scattering "on average, small in all investigated
+ * waters", case 1 and case 2. Molecular scattering is the water's own, with its λ^-4.32 law (Morel
+ * 1974; fresh water 1/1.30 of sea water). With b_p one unknown, each channel's backscattering is
+ * b_w/2 + B_p b_p, each channel's absorption follows from its u, and the clarity equation is linear
+ * in b_p.
+ *
+ * **Rejected inputs** (asserted): a non-positive reflectance, or one at or above 0.2135 sr⁻¹ (u = 1);
+ * a clarity that would need negative particle scattering (water's own scattering, plus the green
+ * absorption the colour implies for water's own backscattering, already attenuates more than
+ * 4.8 / distance); or a channel whose absorption would fall below pure water's (no water absorbs
+ * less than water; typically a reddish or very bright colour at a long clarity).
+ *
+ * @param {Object} options
+ * @param {number[]} options.deep_colour_rrs sub-surface remote-sensing reflectance of deep water, linear RGB, sr⁻¹, each in (0, 0.2135)
+ * @param {number} options.clarity_distance horizontal sighting range of a black target, m, > 0
+ * @param {number} options.particle_backscatter_fraction B_p of the particles, within the Fournier-Forand range; Petzold's average is 0.0183
+ * @param {string} options.water_kind one of {@link WATER_KINDS}
+ * @returns {WaterRgbIOP}
+ */
+export function water_iop_from_appearance({ deep_colour_rrs, clarity_distance, particle_backscatter_fraction, water_kind }) {
+    assert.isArrayLike(deep_colour_rrs, 'deep_colour_rrs');
+    assert.equal(deep_colour_rrs.length, 3, 'deep_colour_rrs.length');
+
+    for (let c = 0; c < 3; c++) {
+        assert.isFinite(deep_colour_rrs[c], `deep_colour_rrs[${c}]`);
+        assert.greaterThan(deep_colour_rrs[c], 0, `deep_colour_rrs[${c}]`);
+        // u < 1: an infinitely deep body cannot backscatter more than it receives
+        assert.lessThan(deep_colour_rrs[c], QAA_G0 + QAA_G1, `deep_colour_rrs[${c}] is brighter than any water: u would reach 1`);
+    }
+
+    assert.isFinite(clarity_distance, 'clarity_distance');
+    assert.greaterThan(clarity_distance, 0, 'clarity_distance');
+
+    assert.isNumber(particle_backscatter_fraction, 'particle_backscatter_fraction');
+    assert.greaterThanOrEqual(particle_backscatter_fraction, FOURNIER_FORAND_BACKSCATTER_MIN, 'particle_backscatter_fraction');
+    assert.lessThanOrEqual(particle_backscatter_fraction, FOURNIER_FORAND_BACKSCATTER_MAX, 'particle_backscatter_fraction');
+
+    assert.isOneOf(water_kind, WATER_KINDS.slice(), 'water_kind');
+
+    const reference = water_iop_spectral_reference();
+
+    const pure_absorption = water_rgb_from_spectral({
+        wavelengths: reference.wavelengths,
+        coefficient: reference.pure_water_absorption,
+        path_lengths: WATER_DEFAULT_PATH_LENGTHS,
+    }).coefficient;
+
+    const molecular_scattering = water_rgb_from_spectral({
+        wavelengths: reference.wavelengths,
+        coefficient: water_kind === 'sea' ? reference.seawater_scattering : reference.fresh_water_scattering,
+        path_lengths: WATER_DEFAULT_PATH_LENGTHS,
+    }).coefficient;
+
+    // a_c = k_c b_b,c with k_c = (1 - u_c) / u_c
+    const k = [0, 0, 0];
+
+    for (let c = 0; c < 3; c++) {
+        const u = u_from_rrs(deep_colour_rrs[c]);
+
+        k[c] = (1 - u) / u;
+    }
+
+    // c_G = a_G + b_w,G + b_p with a_G = k_G (b_w,G / 2 + B_p b_p): linear in b_p
+    const attenuation = BLACK_DISK_VISIBILITY_TIMES_ATTENUATION / clarity_distance;
+
+    const particle_unclamped = (attenuation - molecular_scattering[GREEN] * (1 + k[GREEN] / 2))
+        / (1 + particle_backscatter_fraction * k[GREEN]);
+
+    assert.greaterThanOrEqual(
+        particle_unclamped,
+        -FLOOR_TOLERANCE * attenuation,
+        `clarity_distance ${clarity_distance} m is clearer than this colour allows: water's own scattering already attenuates more`
+    );
+
+    // pure water's own colour and clarity land on zero up to rounding
+    const particle = Math.max(0, particle_unclamped);
+
+    const absorption = [0, 0, 0];
+    const particle_scattering = [particle, particle, particle];
+
+    for (let c = 0; c < 3; c++) {
+        absorption[c] = k[c] * (molecular_scattering[c] / 2 + particle_backscatter_fraction * particle);
+
+        assert.greaterThanOrEqual(
+            absorption[c] * (1 + FLOOR_TOLERANCE),
+            pure_absorption[c],
+            `channel ${c} would absorb less than pure water (${absorption[c]} < ${pure_absorption[c]} 1/m): the colour is too bright there for this clarity`
+        );
+    }
+
+    return {
+        absorption,
+        molecular_scattering,
+        particle_scattering,
+        particle_backscatter_fraction,
+    };
+}

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

@@ -0,0 +1,57 @@
+/**
+ * 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 }: {
+    chlorophyll: number;
+    cdom_440: number;
+    mineral: number;
+    water_kind: string;
+}): WaterSpectralIOP;
+export type WaterSpectralIOP = {
+    /**
+     * nm, strictly increasing
+     */
+    wavelengths: Float64Array;
+    /**
+     * total absorption a(λ), pure water included, 1/m
+     */
+    absorption: Float64Array;
+    /**
+     * scattering by the water itself b_w(λ), 1/m; its phase
+     * is the molecular one, so its backscatter fraction is 1/2
+     */
+    molecular_scattering: Float64Array;
+    /**
+     * scattering by everything suspended b_p(λ), 1/m
+     */
+    particle_scattering: Float64Array;
+    /**
+     * B_p, the share of b_p deflected by more than 90
+     * degrees; selects the Fournier-Forand phase of the particles
+     */
+    particle_backscatter_fraction: number;
+};
+//# sourceMappingURL=water_iop_from_constituents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"water_iop_from_constituents.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/medium/water/water_iop_from_constituents.js"],"names":[],"mappings":"AA2JA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAN2B,WAAW,EAA3B,MAAM;IACU,QAAQ,EAAxB,MAAM;IACU,OAAO,EAAvB,MAAM;IACU,UAAU,EAA1B,MAAM;IACJ,gBAAgB,CA8D5B;;;;;iBA5Oa,YAAY;;;;gBACZ,YAAY;;;;;0BACZ,YAAY;;;;yBAEZ,YAAY;;;;;mCACZ,MAAM"}

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