@woosh/meep-engine 3.38.0 → 3.40.0

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,
+        },
+    });
+}

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

@@ -0,0 +1,69 @@
+/**
+ * Fit an RGB coefficient (1/m), in the engine's linear working space (Rec.709 primaries, D65
+ * white), to a spectral one, so that a white (D65) target seen through a path d of exp(-σ_c d) per
+ * channel looks as it does through exp(-σ(λ) d) per wavelength, over the given path lengths.
+ *
+ * **Target.** For each path d, D65 is attenuated wavelength by wavelength and integrated against the
+ * CIE 1931 2° colour matching functions (trapezoid rule over `wavelengths`), normalized so the
+ * unattenuated illuminant has Y = 1. The candidate is the illuminant's own RGB scaled per channel by
+ * exp(-σ_c d), taken back to XYZ. A wavelength-independent coefficient therefore fits exactly.
+ *
+ * **Error metric.** Least squares on CIELAB ΔE*ab (CIE 15:2004) between candidate and target, summed
+ * over the paths; ΔE*ab of about 1 is a just-noticeable difference. Comparing in Lab rather than in
+ * RGB matters for water: after a few metres the light left is a saturated blue-green outside the
+ * Rec.709 gamut (its red channel is negative), so an RGB target would first have to be clipped or
+ * desaturated, which is a choice about colour, not physics. Lab compares against the real colour and
+ * the part RGB cannot show stays in the residual. It also weighs each path by how visible its error
+ * is: linear transmittance would let the short paths decide everything (a factor of two in the few
+ * percent of green left after 50 m is invisible to a linear fit), and optical depth would let the
+ * longest paths decide everything, where nothing is left to see.
+ *
+ * **Why not a per-band mean.** Averaging σ(λ) over a channel's sensitivity, as one would a colour
+ * (and as `compute_mie_particle_properties_rgb` does for its coefficients), gives the channel's
+ * attenuation over vanishingly short paths only. Over a long path the wavelengths absorbed least are
+ * the ones left, so a channel's effective coefficient falls with distance (Akkaynak & Treibitz
+ * 2018, "A revised underwater image formation model", CVPR, show the same for camera bands).
+ * Measured on pure water (the spec pins these): weighted by luminance its mean absorption is
+ * 0.097 1/m, while the luminance left after 50 m has been attenuated at 0.047 1/m, a 2.1x
+ * overestimate. How large depends on how the band is cut: a 500–600 nm box gives 1.5x, the
+ * positive lobe of the sRGB green 1.3x, and an earlier figure of about 4x was not reproduced. With the
+ * signed sRGB sensitivities a band mean can even come out negative, as pure water's blue does
+ * (-0.0006 1/m), a channel that would brighten with distance. Over 0.1–50 m the band means' worst
+ * ΔE*ab is 16 for pure water and 19 for Jerlov II, against this fit's 11 and 12, nearly all of which
+ * is the Rec.709 gamut itself: the clipped target alone is 12 and 13 ΔE*ab from the real colour.
+ *
+ * **Solver.** A per-channel start from a coarse log scan with the other channels clear, then
+ * coordinate descent: each channel in turn is minimized with the others held (log scan within a
+ * factor of 8 around the current value, golden section, zero as a candidate), until a sweep moves no
+ * coefficient by more than 1e-10 relatively.
+ *
+ * @param {Object} options
+ * @param {ArrayLike<number>} options.wavelengths nm, strictly increasing, at least 2
+ * @param {ArrayLike<number>} options.coefficient σ(λ) at those wavelengths, 1/m, ≥ 0
+ * @param {ArrayLike<number>} options.path_lengths metres, > 0, at least 1
+ * @returns {{coefficient: number[], residual: number}} the RGB coefficient, 1/m, and the largest
+ * ΔE*ab over the path lengths between the fit and the spectral target
+ */
+export function water_rgb_from_spectral({ wavelengths, coefficient, path_lengths }: {
+    wavelengths: ArrayLike<number>;
+    coefficient: ArrayLike<number>;
+    path_lengths: ArrayLike<number>;
+}): {
+    coefficient: number[];
+    residual: number;
+};
+/**
+ * Everything the error of a candidate coefficient needs, computed once per fit.
+ */
+export type FitProblem = {
+    path_lengths: ArrayLike<number>;
+    /**
+     * RGB of the illuminant, whose XYZ has Y = 1
+     */
+    white_rgb: number[];
+    /**
+     * L*, a*, b* of the spectrally attenuated illuminant, per path
+     */
+    target_lab: Float64Array;
+};
+//# sourceMappingURL=water_rgb_from_spectral.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"water_rgb_from_spectral.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/medium/water/water_rgb_from_spectral.js"],"names":[],"mappings":"AA8IA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH;IANsC,WAAW,EAAtC,UAAU,MAAM,CAAC;IACU,WAAW,EAAtC,UAAU,MAAM,CAAC;IACU,YAAY,EAAvC,UAAU,MAAM,CAAC;IACf;IAAC,WAAW,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CA2JrD;;;;;kBA3Ta,UAAU,MAAM,CAAC;;;;eACjB,MAAM,EAAE;;;;gBACR,YAAY"}