@woosh/meep-engine 3.38.0 → 3.39.0

package/src/shade/renderer/medium/phase/PhaseJendersieDeon.js

@@ -0,0 +1,66 @@
+import { assert } from "../../../../core/assert.js";
+import {
+    FOG_PARAMETERS_JENDERSIE_DEON_PARTICLE_DIAMETER_MAX
+} from "../../shader/chunk/atmosphere/phase/jd/FOG_PARAMETERS_JENDERSIE_DEON_PARTICLE_DIAMETER_MAX.js";
+import {
+    FOG_PARAMETERS_JENDERSIE_DEON_PARTICLE_DIAMETER_MIN
+} from "../../shader/chunk/atmosphere/phase/jd/FOG_PARAMETERS_JENDERSIE_DEON_PARTICLE_DIAMETER_MIN.js";
+import { get_fog_params_jendersie_deon } from "../../shader/chunk/atmosphere/phase/jd/get_fog_params_jendersie_deon.js";
+import { MEDIUM_PHASE_LOBE_KIND } from "../MEDIUM_PHASE_LOBE_KIND.js";
+import { MediumPhaseFunction } from "./MediumPhaseFunction.js";
+
+/**
+ * Jendersie and d'Eon's fit to Mie scattering by water droplets of one diameter: a
+ * Henyey-Greenstein lobe and a Draine lobe, mixed. For fog and cloud droplets. It reduces to two GPU
+ * lobes, the mixture weight going into how the scattering is shared between them, so the fit's
+ * lookup texture is not needed.
+ *
+ * @see Jendersie, d'Eon, "An Approximate Mie Scattering Function for Fog and Cloud Rendering", SIGGRAPH 2023
+ */
+export class PhaseJendersieDeon extends MediumPhaseFunction {
+    /**
+     * droplet diameter, micrometres
+     * @type {number}
+     */
+    diameter_micron = 10;
+
+    /**
+     * @param {Object} options
+     * @param {number} options.diameter_micron within the fit's range, 0.01 to 50
+     */
+    constructor({ diameter_micron }) {
+        super();
+
+        assert.isNumber(diameter_micron, 'diameter_micron');
+        assert.greaterThanOrEqual(diameter_micron, FOG_PARAMETERS_JENDERSIE_DEON_PARTICLE_DIAMETER_MIN, 'diameter_micron');
+        assert.lessThanOrEqual(diameter_micron, FOG_PARAMETERS_JENDERSIE_DEON_PARTICLE_DIAMETER_MAX, 'diameter_micron');
+
+        this.diameter_micron = diameter_micron;
+    }
+
+    get gpu_lobe_count() {
+        return 2;
+    }
+
+    write_gpu_lobes(scattering, output) {
+        const parameters = [];
+
+        get_fog_params_jendersie_deon(parameters, this.diameter_micron);
+
+        const [g_hg, g_draine, alpha, weight_draine] = parameters;
+
+        output.push({
+            scattering: scattering.map(s => s * (1 - weight_draine)),
+            kind: MEDIUM_PHASE_LOBE_KIND.Draine,
+            p0: g_hg,
+            p1: 0,
+        });
+
+        output.push({
+            scattering: scattering.map(s => s * weight_draine),
+            kind: MEDIUM_PHASE_LOBE_KIND.Draine,
+            p0: g_draine,
+            p1: alpha,
+        });
+    }
+}

package/src/shade/renderer/medium/phase/PhaseRayleigh.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Rayleigh: scattering by particles much smaller than the wavelength, (3 / 16 pi)(1 + mu²).
+ * The clear sky's phase function. Takes no parameters, so it is constructed without arguments.
+ */
+export class PhaseRayleigh extends MediumPhaseFunction {
+    write_gpu_lobes(scattering: any, output: any): void;
+}
+import { MediumPhaseFunction } from "./MediumPhaseFunction.js";
+//# sourceMappingURL=PhaseRayleigh.d.ts.map

package/src/shade/renderer/medium/phase/PhaseRayleigh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PhaseRayleigh.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/medium/phase/PhaseRayleigh.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH;IAKI,oDAOC;CACJ;oCAnBmC,0BAA0B"}

package/src/shade/renderer/medium/phase/PhaseRayleigh.js

@@ -0,0 +1,21 @@
+import { MEDIUM_PHASE_LOBE_KIND } from "../MEDIUM_PHASE_LOBE_KIND.js";
+import { MediumPhaseFunction } from "./MediumPhaseFunction.js";
+
+/**
+ * Rayleigh: scattering by particles much smaller than the wavelength, (3 / 16 pi)(1 + mu²).
+ * The clear sky's phase function. Takes no parameters, so it is constructed without arguments.
+ */
+export class PhaseRayleigh extends MediumPhaseFunction {
+    get gpu_lobe_count() {
+        return 1;
+    }
+
+    write_gpu_lobes(scattering, output) {
+        output.push({
+            scattering: scattering.slice(),
+            kind: MEDIUM_PHASE_LOBE_KIND.Draine,
+            p0: 0,
+            p1: 1,
+        });
+    }
+}

package/src/shade/renderer/medium/phase/PhaseWaterMolecular.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Scattering by water itself, by density fluctuations of its molecules: Rayleigh's shape, with the
+ * mu² term weakened by the molecules' depolarization,
+ *
+ *      p(psi) proportional to 1 + k cos² psi,   k = (1 - depolarization) / (1 + depolarization)
+ *
+ * which is Draine with g = 0 and alpha = k. The water optics plan uses depolarization 0.039
+ * (Zhang et al. 2009); older sources, after Morel 1974, use 0.09.
+ *
+ * @see Mobley, Ocean Optics Web Book, "Optical constituents of the ocean: water"
+ */
+export class PhaseWaterMolecular extends MediumPhaseFunction {
+    /**
+     * @param {Object} options
+     * @param {number} options.depolarization
+     */
+    constructor({ depolarization }: {
+        depolarization: number;
+    });
+    /**
+     * depolarization ratio, in [0, 1)
+     * @type {number}
+     */
+    depolarization: number;
+    write_gpu_lobes(scattering: any, output: any): void;
+}
+import { MediumPhaseFunction } from "./MediumPhaseFunction.js";
+//# sourceMappingURL=PhaseWaterMolecular.d.ts.map

package/src/shade/renderer/medium/phase/PhaseWaterMolecular.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PhaseWaterMolecular.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/medium/phase/PhaseWaterMolecular.js"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AACH;IAOI;;;OAGG;IACH;QAF2B,cAAc,EAA9B,MAAM;OAUhB;IAlBD;;;OAGG;IACH,gBAFU,MAAM,CAEG;IAoBnB,oDAOC;CACJ;oCA9CmC,0BAA0B"}

package/src/shade/renderer/medium/phase/PhaseWaterMolecular.js

@@ -0,0 +1,49 @@
+import { assert } from "../../../../core/assert.js";
+import { MEDIUM_PHASE_LOBE_KIND } from "../MEDIUM_PHASE_LOBE_KIND.js";
+import { MediumPhaseFunction } from "./MediumPhaseFunction.js";
+
+/**
+ * Scattering by water itself, by density fluctuations of its molecules: Rayleigh's shape, with the
+ * mu² term weakened by the molecules' depolarization,
+ *
+ *      p(psi) proportional to 1 + k cos² psi,   k = (1 - depolarization) / (1 + depolarization)
+ *
+ * which is Draine with g = 0 and alpha = k. The water optics plan uses depolarization 0.039
+ * (Zhang et al. 2009); older sources, after Morel 1974, use 0.09.
+ *
+ * @see Mobley, Ocean Optics Web Book, "Optical constituents of the ocean: water"
+ */
+export class PhaseWaterMolecular extends MediumPhaseFunction {
+    /**
+     * depolarization ratio, in [0, 1)
+     * @type {number}
+     */
+    depolarization = 0;
+
+    /**
+     * @param {Object} options
+     * @param {number} options.depolarization
+     */
+    constructor({ depolarization }) {
+        super();
+
+        assert.isNumber(depolarization, 'depolarization');
+        assert.greaterThanOrEqual(depolarization, 0, 'depolarization');
+        assert.lessThan(depolarization, 1, 'depolarization');
+
+        this.depolarization = depolarization;
+    }
+
+    get gpu_lobe_count() {
+        return 1;
+    }
+
+    write_gpu_lobes(scattering, output) {
+        output.push({
+            scattering: scattering.slice(),
+            kind: MEDIUM_PHASE_LOBE_KIND.Draine,
+            p0: 0,
+            p1: (1 - this.depolarization) / (1 + this.depolarization),
+        });
+    }
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Path lengths, metres, over which the water tools fit RGB coefficients to spectral ones: 16 values
+ * log-spaced from 0.1 to 50 m, the range of the water optics plan (§7.3). 0.1 m is about the
+ * thinnest water whose tint registers; at 50 m even the clearest ocean has removed nearly all red and
+ * most green, so longer paths add nothing visible.
+ * @readonly
+ * @type {ReadonlyArray<number>}
+ */
+export const WATER_DEFAULT_PATH_LENGTHS: ReadonlyArray<number>;
+//# sourceMappingURL=WATER_DEFAULT_PATH_LENGTHS.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WATER_DEFAULT_PATH_LENGTHS.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/medium/water/WATER_DEFAULT_PATH_LENGTHS.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,yCAFU,cAAc,MAAM,CAAC,CAE0D"}

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

@@ -0,0 +1,25 @@
+/**
+ * Path lengths, metres, over which the water tools fit RGB coefficients to spectral ones: 16 values
+ * log-spaced from 0.1 to 50 m, the range of the water optics plan (§7.3). 0.1 m is about the
+ * thinnest water whose tint registers; at 50 m even the clearest ocean has removed nearly all red and
+ * most green, so longer paths add nothing visible.
+ * @readonly
+ * @type {ReadonlyArray<number>}
+ */
+export const WATER_DEFAULT_PATH_LENGTHS = Object.freeze(build_path_lengths(0.1, 50, 16));
+
+/**
+ * @param {number} min
+ * @param {number} max
+ * @param {number} count
+ * @returns {number[]}
+ */
+function build_path_lengths(min, max, count) {
+    const result = [];
+
+    for (let i = 0; i < count; i++) {
+        result.push(min * Math.pow(max / min, i / (count - 1)));
+    }
+
+    return result;
+}

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

@@ -0,0 +1,47 @@
+/**
+ * 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 }: {
+    deep_colour_rrs: number[];
+    clarity_distance: number;
+    particle_backscatter_fraction: number;
+    water_kind: string;
+}): WaterRgbIOP;
+export type WaterRgbIOP = import("./water_medium_from_iop.js").WaterRgbIOP;
+//# sourceMappingURL=water_iop_from_appearance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"water_iop_from_appearance.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/medium/water/water_iop_from_appearance.js"],"names":[],"mappings":"AAyDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH;IAN6B,eAAe,EAAjC,MAAM,EAAE;IACQ,gBAAgB,EAAhC,MAAM;IACU,6BAA6B,EAA7C,MAAM;IACU,UAAU,EAA1B,MAAM;IACJ,WAAW,CA+EvB;0BAnKY,OAAO,4BAA4B,EAAE,WAAW"}

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