@woosh/meep-engine 3.38.0 → 3.39.0

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

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

@@ -0,0 +1,145 @@
+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 { ParticipatingMedium } from "../ParticipatingMedium.js";
+import { PhaseFournierForand } from "../phase/PhaseFournierForand.js";
+import { PhaseWaterMolecular } from "../phase/PhaseWaterMolecular.js";
+import { water_rgb_from_spectral } from "./water_rgb_from_spectral.js";
+
+/**
+ * @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 = 0.039;
+
+/**
+ * @param {number[]} rgb
+ * @param {string} name
+ */
+function assert_rgb_coefficient(rgb, name) {
+    assert.isArrayLike(rgb, name);
+    assert.equal(rgb.length, 3, `${name}.length`);
+
+    for (let i = 0; i < 3; i++) {
+        assert.isFinite(rgb[i], `${name}[${i}]`);
+        assert.greaterThanOrEqual(rgb[i], 0, `${name}[${i}]`);
+    }
+}
+
+/**
+ * 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 }) {
+    assert.defined(iop, 'iop');
+    assert.isNumber(iop.particle_backscatter_fraction, 'iop.particle_backscatter_fraction');
+
+    const absorption = water_rgb_from_spectral({
+        wavelengths: iop.wavelengths,
+        coefficient: iop.absorption,
+        path_lengths,
+    });
+
+    const molecular_scattering = water_rgb_from_spectral({
+        wavelengths: iop.wavelengths,
+        coefficient: iop.molecular_scattering,
+        path_lengths,
+    });
+
+    const particle_scattering = water_rgb_from_spectral({
+        wavelengths: iop.wavelengths,
+        coefficient: iop.particle_scattering,
+        path_lengths,
+    });
+
+    return {
+        iop: {
+            absorption: absorption.coefficient,
+            molecular_scattering: molecular_scattering.coefficient,
+            particle_scattering: particle_scattering.coefficient,
+            particle_backscatter_fraction: iop.particle_backscatter_fraction,
+        },
+        residual: {
+            absorption: absorption.residual,
+            molecular_scattering: molecular_scattering.residual,
+            particle_scattering: particle_scattering.residual,
+        },
+    };
+}
+
+/**
+ * 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 }) {
+    assert.defined(iop, 'iop');
+    assert_rgb_coefficient(iop.absorption, 'iop.absorption');
+    assert_rgb_coefficient(iop.molecular_scattering, 'iop.molecular_scattering');
+    assert_rgb_coefficient(iop.particle_scattering, 'iop.particle_scattering');
+
+    const backscatter_fraction = iop.particle_backscatter_fraction;
+
+    assert.isNumber(backscatter_fraction, 'iop.particle_backscatter_fraction');
+    assert.greaterThanOrEqual(backscatter_fraction, FOURNIER_FORAND_BACKSCATTER_MIN, 'iop.particle_backscatter_fraction below what Fournier-Forand reaches');
+    assert.lessThanOrEqual(backscatter_fraction, FOURNIER_FORAND_BACKSCATTER_MAX, 'iop.particle_backscatter_fraction above what Fournier-Forand reaches');
+
+    const medium = new ParticipatingMedium();
+
+    medium.absorption = iop.absorption.slice();
+    medium.needsUpdate = true;
+
+    medium.add_lobe(iop.molecular_scattering, new PhaseWaterMolecular({ depolarization: WATER_MOLECULAR_DEPOLARIZATION }));
+    medium.add_lobe(iop.particle_scattering, new PhaseFournierForand({ backscatter_fraction }));
+
+    return medium;
+}
+
+/**
+ * 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 }) {
+    const fitted = water_rgb_iop_from_spectral({ iop, path_lengths });
+
+    return water_medium_from_rgb_iop({ iop: fitted.iop });
+}

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

@@ -0,0 +1,69 @@
+/**
+ * The spectral description of a preset.
+ *
+ * @param {Object} options
+ * @param {string} options.preset one of {@link WATER_PRESETS}
+ * @returns {WaterSpectralIOP}
+ */
+export function water_iop_preset({ preset }: {
+    preset: string;
+}): WaterSpectralIOP;
+/**
+ * The medium of a preset, fitted to RGB over {@link WATER_DEFAULT_PATH_LENGTHS}. Fitting takes tens
+ * of milliseconds; it is an authoring step, not something to call per frame.
+ *
+ * @param {Object} options
+ * @param {string} options.preset one of {@link WATER_PRESETS}
+ * @returns {ParticipatingMedium}
+ */
+export function water_medium_preset({ preset }: {
+    preset: string;
+}): ParticipatingMedium;
+/**
+ * The medium a `Water` body has unless told otherwise: clear natural open ocean, chlorophyll 0.3 mg/m³.
+ *
+ * @returns {ParticipatingMedium}
+ */
+export function water_medium_default(): ParticipatingMedium;
+/**
+ * @typedef {import("./water_iop_from_constituents.js").WaterSpectralIOP} WaterSpectralIOP
+ * @typedef {import("./water_medium_from_iop.js").WaterRgbIOP} WaterRgbIOP
+ * @typedef {import("../ParticipatingMedium.js").ParticipatingMedium} ParticipatingMedium
+ */
+/**
+ * The named water presets of the water optics plan (§7.4), each a physical description, never an
+ * art value:
+ *
+ * | Preset | Built from |
+ * |---|---|
+ * | `swimming_pool` | pure fresh water: no chlorophyll, CDOM or minerals |
+ * | `clear_ocean` | Jerlov IB |
+ * | `open_ocean` | chlorophyll 0.3 mg/m³ with CDOM a_g(440) 0.0055 1/m (Case 1: a fifth of the particles' absorption at 440 nm), sea; the `Water` default |
+ * | `coastal` | Jerlov 3C |
+ * | `tropical_lagoon` | Jerlov IB: the water is clear ocean water; what makes a lagoon (shallow, over sand) belongs to the scene |
+ * | `green_lake` | chlorophyll 5 mg/m³, CDOM a_g(440) 0.3 1/m, fresh |
+ * | `turbid_river` | minerals 30 g/m³, fresh |
+ *
+ * @readonly
+ * @type {ReadonlyArray<string>}
+ */
+export const WATER_PRESETS: ReadonlyArray<string>;
+/**
+ * The `Water` default, `open_ocean` fitted over {@link WATER_DEFAULT_PATH_LENGTHS},
+ * recorded so that making a water body does not run the fit. The spec checks these numbers against
+ * the fit itself, so a change to the data or the fit that moves them fails until they are
+ * re-recorded. Recorded 2026-10-03.
+ *
+ * @readonly
+ * @type {Readonly<{absorption: ReadonlyArray<number>, molecular_scattering: ReadonlyArray<number>, particle_scattering: ReadonlyArray<number>, particle_backscatter_fraction: number}>}
+ */
+export const WATER_DEFAULT_RGB_IOP: Readonly<{
+    absorption: ReadonlyArray<number>;
+    molecular_scattering: ReadonlyArray<number>;
+    particle_scattering: ReadonlyArray<number>;
+    particle_backscatter_fraction: number;
+}>;
+export type WaterSpectralIOP = import("./water_iop_from_constituents.js").WaterSpectralIOP;
+export type WaterRgbIOP = import("./water_medium_from_iop.js").WaterRgbIOP;
+export type ParticipatingMedium = import("../ParticipatingMedium.js").ParticipatingMedium;
+//# sourceMappingURL=water_presets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"water_presets.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/medium/water/water_presets.js"],"names":[],"mappings":"AAuCA;;;;;;GAMG;AACH;IAH2B,MAAM,EAAtB,MAAM;IACJ,gBAAgB,CA2B5B;AAED;;;;;;;GAOG;AACH;IAH2B,MAAM,EAAtB,MAAM;IACJ,mBAAmB,CAO/B;AAkBD;;;;GAIG;AACH,wCAFa,mBAAmB,CAW/B;AAhHD;;;;GAIG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,4BAFU,cAAc,MAAM,CAAC,CAU5B;AAmDH;;;;;;;;GAQG;AACH,oCAFU,SAAS;IAAC,UAAU,EAAE,cAAc,MAAM,CAAC,CAAC;IAAC,oBAAoB,EAAE,cAAc,MAAM,CAAC,CAAC;IAAC,mBAAmB,EAAE,cAAc,MAAM,CAAC,CAAC;IAAC,6BAA6B,EAAE,MAAM,CAAA;CAAC,CAAC,CAOpL;+BA/FU,OAAO,kCAAkC,EAAE,gBAAgB;0BAC3D,OAAO,4BAA4B,EAAE,WAAW;kCAChD,OAAO,2BAA2B,EAAE,mBAAmB"}

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

@@ -0,0 +1,119 @@
+import { assert } from "../../../../core/assert.js";
+import { WATER_DEFAULT_PATH_LENGTHS } from "./WATER_DEFAULT_PATH_LENGTHS.js";
+import { water_iop_from_constituents } from "./water_iop_from_constituents.js";
+import { water_iop_jerlov } from "./water_iop_jerlov.js";
+import { water_medium_from_iop, water_medium_from_rgb_iop } from "./water_medium_from_iop.js";
+
+/**
+ * @typedef {import("./water_iop_from_constituents.js").WaterSpectralIOP} WaterSpectralIOP
+ * @typedef {import("./water_medium_from_iop.js").WaterRgbIOP} WaterRgbIOP
+ * @typedef {import("../ParticipatingMedium.js").ParticipatingMedium} ParticipatingMedium
+ */
+
+/**
+ * The named water presets of the water optics plan (§7.4), each a physical description, never an
+ * art value:
+ *
+ * | Preset | Built from |
+ * |---|---|
+ * | `swimming_pool` | pure fresh water: no chlorophyll, CDOM or minerals |
+ * | `clear_ocean` | Jerlov IB |
+ * | `open_ocean` | chlorophyll 0.3 mg/m³ with CDOM a_g(440) 0.0055 1/m (Case 1: a fifth of the particles' absorption at 440 nm), sea; the `Water` default |
+ * | `coastal` | Jerlov 3C |
+ * | `tropical_lagoon` | Jerlov IB: the water is clear ocean water; what makes a lagoon (shallow, over sand) belongs to the scene |
+ * | `green_lake` | chlorophyll 5 mg/m³, CDOM a_g(440) 0.3 1/m, fresh |
+ * | `turbid_river` | minerals 30 g/m³, fresh |
+ *
+ * @readonly
+ * @type {ReadonlyArray<string>}
+ */
+export const WATER_PRESETS = Object.freeze([
+    'swimming_pool',
+    'clear_ocean',
+    'open_ocean',
+    'coastal',
+    'tropical_lagoon',
+    'green_lake',
+    'turbid_river',
+]);
+
+/**
+ * The spectral description of a preset.
+ *
+ * @param {Object} options
+ * @param {string} options.preset one of {@link WATER_PRESETS}
+ * @returns {WaterSpectralIOP}
+ */
+export function water_iop_preset({ preset }) {
+    assert.isOneOf(preset, WATER_PRESETS.slice(), 'preset');
+
+    switch (preset) {
+        case 'swimming_pool':
+            return water_iop_from_constituents({ chlorophyll: 0, cdom_440: 0, mineral: 0, water_kind: 'fresh' });
+        case 'clear_ocean':
+            return water_iop_jerlov({ type: 'IB' });
+        case 'open_ocean':
+            // Not Jerlov II: its tables pair near-pure-water absorption with large scattering, which
+            // Gordon's relation cannot reconcile with its own diffuse attenuation for any measured
+            // particle backscatter fraction, and which reads murky (beam attenuation 0.42 1/m in
+            // green). The bio-optical model meets Morel & Maritorena's measured attenuation within 11%.
+            return water_iop_from_constituents({ chlorophyll: 0.3, cdom_440: 0.0055, mineral: 0, water_kind: 'sea' });
+        case 'coastal':
+            return water_iop_jerlov({ type: '3C' });
+        case 'tropical_lagoon':
+            return water_iop_jerlov({ type: 'IB' });
+        case 'green_lake':
+            return water_iop_from_constituents({ chlorophyll: 5, cdom_440: 0.3, mineral: 0, water_kind: 'fresh' });
+        case 'turbid_river':
+            return water_iop_from_constituents({ chlorophyll: 0, cdom_440: 0, mineral: 30, water_kind: 'fresh' });
+        default:
+            throw new Error(`unhandled preset '${preset}'`);
+    }
+}
+
+/**
+ * The medium of a preset, fitted to RGB over {@link WATER_DEFAULT_PATH_LENGTHS}. Fitting takes tens
+ * of milliseconds; it is an authoring step, not something to call per frame.
+ *
+ * @param {Object} options
+ * @param {string} options.preset one of {@link WATER_PRESETS}
+ * @returns {ParticipatingMedium}
+ */
+export function water_medium_preset({ preset }) {
+    return water_medium_from_iop({
+        iop: water_iop_preset({ preset }),
+        path_lengths: WATER_DEFAULT_PATH_LENGTHS,
+    });
+}
+
+/**
+ * The `Water` default, `open_ocean` fitted over {@link WATER_DEFAULT_PATH_LENGTHS},
+ * recorded so that making a water body does not run the fit. The spec checks these numbers against
+ * the fit itself, so a change to the data or the fit that moves them fails until they are
+ * re-recorded. Recorded 2026-10-03.
+ *
+ * @readonly
+ * @type {Readonly<{absorption: ReadonlyArray<number>, molecular_scattering: ReadonlyArray<number>, particle_scattering: ReadonlyArray<number>, particle_backscatter_fraction: number}>}
+ */
+export const WATER_DEFAULT_RGB_IOP = Object.freeze({
+    absorption: Object.freeze([0.335154, 0.0584947, 0.0358503]),
+    molecular_scattering: Object.freeze([0.000883043, 0.00196275, 0.00481488]),
+    particle_scattering: Object.freeze([0.141817, 0.16761, 0.206582]),
+    particle_backscatter_fraction: 0.008307196863200843,
+});
+
+/**
+ * The medium a `Water` body has unless told otherwise: clear natural open ocean, chlorophyll 0.3 mg/m³.
+ *
+ * @returns {ParticipatingMedium}
+ */
+export function water_medium_default() {
+    return water_medium_from_rgb_iop({
+        iop: {
+            absorption: WATER_DEFAULT_RGB_IOP.absorption.slice(),
+            molecular_scattering: WATER_DEFAULT_RGB_IOP.molecular_scattering.slice(),
+            particle_scattering: WATER_DEFAULT_RGB_IOP.particle_scattering.slice(),
+            particle_backscatter_fraction: WATER_DEFAULT_RGB_IOP.particle_backscatter_fraction,
+        },
+    });
+}