@woosh/meep-engine 3.9.0 → 3.10.0

package/src/core/color/xyz/xyz_cmf_wyman.js

@@ -1,65 +1,74 @@
-/**
- * CIE 1931 2° XYZ color matching functions (analytic approximation)
- *
- * Implementation based on:
- * Wyman, Sloan, Shirley (2013), "Simple Analytic Approximations to the CIE 1931 XYZ Color Matching Functions"
- * JCGT 2(2), 2013. http://jcgt.org/published/0002/02/01/
- *
- * Valid primarily over 380–780 nm. Outside this range, the functions return 0.
- * Returns unweighted CMFs (no illuminant). Weighting by illuminant SPD (e.g., D65)
- * should be applied by the caller during spectral integration when needed.
- */
-
-// Helper for asymmetric Gaussian term from Wyman et al.
-function gaussAsym(w, w0, sigmaL, sigmaR) {
-    const t = (w - w0) * (w < w0 ? sigmaL : sigmaR);
-    return Math.exp(-0.5 * t * t);
-}
-
-/**
- * Color-Matching Function in CIE XYZ space.
- *
- * Compute CIE 1931 2° x̄(λ), ȳ(λ), z̄(λ) using Wyman et al. analytic fits.
- *
- * This is the "multi-lobe" fit. The absolute error magnitude is under 0.05 across the spectrum according to the paper.
- *
- * @param {number[]} out length>=3
- * @param {number} wavelength_nm wavelength in nanometers
- * @returns {number[]} out
- */
-export function xyz_cmf_wyman(out, wavelength_nm) {
-    const w = wavelength_nm;
-
-    // Return zeros outside the modeled range
-    if (w < 380 || w > 780) {
-
-        out[0] = 0;
-        out[1] = 0;
-        out[2] = 0;
-
-        return out;
-
-    }
-
-    // x̄(λ)
-    const x =
-        + 0.362 * gaussAsym(w, 442.0, 0.0624, 0.0374)
-        + 1.056 * gaussAsym(w, 599.8, 0.0264, 0.0323)
-        - 0.065 * gaussAsym(w, 501.1, 0.0490, 0.0382);
-
-    // ȳ(λ)
-    const y =
-        + 0.821 * gaussAsym(w, 568.8, 0.0213, 0.0247)
-        + 0.286 * gaussAsym(w, 530.9, 0.0613, 0.0322);
-
-    // z̄(λ)
-    const z =
-        + 1.217 * gaussAsym(w, 437.0, 0.0845, 0.0278)
-        + 0.681 * gaussAsym(w, 459.0, 0.0385, 0.0725);
-
-    out[0] = x;
-    out[1] = y;
-    out[2] = z;
-
-    return out;
-}
+import { assert } from "../../assert.js";
+
+/**
+ * CIE 1931 2° XYZ color matching functions (analytic approximation)
+ *
+ * Implementation based on:
+ * Wyman, Sloan, Shirley (2013), "Simple Analytic Approximations to the CIE 1931 XYZ Color Matching Functions"
+ * JCGT 2(2), 2013. http://jcgt.org/published/0002/02/01/
+ *
+ * Valid primarily over 380–780 nm. Outside this range, the functions return 0.
+ * Returns unweighted CMFs (no illuminant). Weighting by illuminant SPD (e.g., D65)
+ * should be applied by the caller during spectral integration when needed.
+ */
+
+// Helper for asymmetric Gaussian term from Wyman et al.
+function gaussAsym(w, w0, sigmaL, sigmaR) {
+    const t = (w - w0) * (w < w0 ? sigmaL : sigmaR);
+    return Math.exp(-0.5 * t * t);
+}
+
+/**
+ * Color-Matching Function in CIE XYZ space.
+ *
+ * Compute CIE 1931 2° x̄(λ), ȳ(λ), z̄(λ) using Wyman et al. analytic fits.
+ *
+ * This is the "multi-lobe" fit. The absolute error magnitude is under 0.05 across the spectrum according to the paper.
+ *
+ * Validates its wavelength, matching {@link xyz_cmf_tabulated} and {@link D65_spd_tabulated}: the package's
+ * rule is that a scalar which cannot produce a meaningful result is rejected, while a merely out-of-range one
+ * falls through to the documented 0 so an integration loop can sweep past the ends without branching.
+ *
+ * @param {number[]} out length>=3
+ * @param {number} wavelength_nm wavelength in nanometers
+ * @returns {number[]} out
+ */
+export function xyz_cmf_wyman(out, wavelength_nm) {
+    assert.isNumber(wavelength_nm, 'wavelength_nm');
+    assert.isFinite(wavelength_nm, 'wavelength_nm');
+
+    const w = wavelength_nm;
+
+    // Return zeros outside the modeled range
+    if (w < 380 || w > 780) {
+
+        out[0] = 0;
+        out[1] = 0;
+        out[2] = 0;
+
+        return out;
+
+    }
+
+    // x̄(λ)
+    const x =
+        + 0.362 * gaussAsym(w, 442.0, 0.0624, 0.0374)
+        + 1.056 * gaussAsym(w, 599.8, 0.0264, 0.0323)
+        - 0.065 * gaussAsym(w, 501.1, 0.0490, 0.0382);
+
+    // ȳ(λ)
+    const y =
+        + 0.821 * gaussAsym(w, 568.8, 0.0213, 0.0247)
+        + 0.286 * gaussAsym(w, 530.9, 0.0613, 0.0322);
+
+    // z̄(λ)
+    const z =
+        + 1.217 * gaussAsym(w, 437.0, 0.0845, 0.0278)
+        + 0.681 * gaussAsym(w, 459.0, 0.0385, 0.0725);
+
+    out[0] = x;
+    out[1] = y;
+    out[2] = z;
+
+    return out;
+}

package/src/core/color/xyz/xyz_to_hpe.d.ts

@@ -0,0 +1,18 @@
+/**
+ * CIE linear XYZ model to Hunt-Pointer-Estévez (HPE) cone response.
+ *
+ * In-place safe: all three inputs are read before the first write.
+ *
+ * Takes the offset form `(out, out_offset, input, input_offset)` like the rest of the modern layer; the
+ * original `(out, input)` form still works and is detected by the type of the second argument. See
+ * {@link rgb_to_xyz} for why both exist.
+ *
+ * @param {number[]} out
+ * @param {number|number[]} out_offset offset into `out`, or `input` for the legacy 2-argument form
+ * @param {number[]} [input]
+ * @param {number} [input_offset]
+ *
+ * @see hpe_to_xyz
+ */
+export function xyz_to_hpe(out: number[], out_offset: number | number[], input?: number[], input_offset?: number): void;
+//# sourceMappingURL=xyz_to_hpe.d.ts.map

package/src/core/color/xyz/xyz_to_hpe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xyz_to_hpe.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/xyz/xyz_to_hpe.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,gCAPW,MAAM,EAAE,cACR,MAAM,GAAC,MAAM,EAAE,UACf,MAAM,EAAE,iBACR,MAAM,QAoBhB"}

package/src/core/color/xyz/xyz_to_hpe.js

@@ -0,0 +1,33 @@
+/**
+ * CIE linear XYZ model to Hunt-Pointer-Estévez (HPE) cone response.
+ *
+ * In-place safe: all three inputs are read before the first write.
+ *
+ * Takes the offset form `(out, out_offset, input, input_offset)` like the rest of the modern layer; the
+ * original `(out, input)` form still works and is detected by the type of the second argument. See
+ * {@link rgb_to_xyz} for why both exist.
+ *
+ * @param {number[]} out
+ * @param {number|number[]} out_offset offset into `out`, or `input` for the legacy 2-argument form
+ * @param {number[]} [input]
+ * @param {number} [input_offset]
+ *
+ * @see hpe_to_xyz
+ */
+export function xyz_to_hpe(out, out_offset, input, input_offset){
+
+    if (typeof out_offset !== "number") {
+        // legacy (out, input) form
+        input = out_offset;
+        out_offset = 0;
+        input_offset = 0;
+    }
+
+    const x = input[input_offset];
+    const y = input[input_offset + 1];
+    const z = input[input_offset + 2];
+
+    out[out_offset] = 0.38971 * x + 0.68898 * y  -0.07868 * z;
+    out[out_offset + 1] = -0.22981 * x + 1.18340 * y + 0.04641 * z;
+    out[out_offset + 2] = z;
+}

package/src/core/color/xyz/xyz_to_rgb.d.ts

@@ -2,8 +2,23 @@
  * CIE color model to linear RGB
  * Assumes D65 standard illuminant
  * @see https://www.image-engineering.de/library/technotes/958-how-to-convert-between-srgb-and-ciexyz
+ *
+ * ## Two call forms
+ *
+ * The offset form `(out, out_offset, input, input_offset)` is the package's standard, shared with
+ * `linear_to_sRGB`, `xyz_to_lab`, `xyz_to_ycxcz`, `tonemap_aces` and the rest of the modern layer. It is what
+ * lets a caller work straight out of a packed buffer instead of copying a triple in and out - which matters
+ * here more than anywhere else, since these two are the most-imported conversions in the package and chaining
+ * them with `xyz_to_lab` previously required remembering that one side had offsets and the other did not.
+ *
+ * The original `(out, input)` form still works and is detected by the type of the second argument. It is kept
+ * because this is a library and its callers are not all in this repository; new code should use the offset
+ * form.
+ *
  * @param {number[]|Float32Array|Float64Array} out
- * @param {number[]|Float32Array|Float64Array} input
+ * @param {number|number[]|Float32Array|Float64Array} out_offset offset into `out`, or `input` for the legacy 2-argument form
+ * @param {number[]|Float32Array|Float64Array} [input]
+ * @param {number} [input_offset]
  */
-export function xyz_to_rgb(out: number[] | Float32Array | Float64Array, input: number[] | Float32Array | Float64Array): void;
+export function xyz_to_rgb(out: number[] | Float32Array | Float64Array, out_offset: number | number[] | Float32Array | Float64Array, input?: number[] | Float32Array | Float64Array, input_offset?: number): void;
 //# sourceMappingURL=xyz_to_rgb.d.ts.map

package/src/core/color/xyz/xyz_to_rgb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"xyz_to_rgb.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/xyz/xyz_to_rgb.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,gCAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,SAClC,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,QAU5C"}
+{"version":3,"file":"xyz_to_rgb.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/xyz/xyz_to_rgb.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,gCALW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,GAAC,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,UACzC,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,QAkBhB"}

package/src/core/color/xyz/xyz_to_rgb.js

@@ -1,16 +1,39 @@
-/**
- * CIE color model to linear RGB
- * Assumes D65 standard illuminant
- * @see https://www.image-engineering.de/library/technotes/958-how-to-convert-between-srgb-and-ciexyz
- * @param {number[]|Float32Array|Float64Array} out
- * @param {number[]|Float32Array|Float64Array} input
- */
-export function xyz_to_rgb(out, input) {
-    const x = input[0];
-    const y = input[1];
-    const z = input[2];
-
-    out[0] = 3.24096994190452134377 * x - 1.53738317757009345794 * y - 0.49861076029300328366 * z;
-    out[1] = (-0.96924363628087982613) * x + 1.87596750150772066772 * y + 0.04155505740717561247 * z;
-    out[2] = 0.05563007969699360846 * x - 0.20397695888897656435 * y + 1.05697151424287856072 * z;
-}
+/**
+ * CIE color model to linear RGB
+ * Assumes D65 standard illuminant
+ * @see https://www.image-engineering.de/library/technotes/958-how-to-convert-between-srgb-and-ciexyz
+ *
+ * ## Two call forms
+ *
+ * The offset form `(out, out_offset, input, input_offset)` is the package's standard, shared with
+ * `linear_to_sRGB`, `xyz_to_lab`, `xyz_to_ycxcz`, `tonemap_aces` and the rest of the modern layer. It is what
+ * lets a caller work straight out of a packed buffer instead of copying a triple in and out - which matters
+ * here more than anywhere else, since these two are the most-imported conversions in the package and chaining
+ * them with `xyz_to_lab` previously required remembering that one side had offsets and the other did not.
+ *
+ * The original `(out, input)` form still works and is detected by the type of the second argument. It is kept
+ * because this is a library and its callers are not all in this repository; new code should use the offset
+ * form.
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number|number[]|Float32Array|Float64Array} out_offset offset into `out`, or `input` for the legacy 2-argument form
+ * @param {number[]|Float32Array|Float64Array} [input]
+ * @param {number} [input_offset]
+ */
+export function xyz_to_rgb(out, out_offset, input, input_offset) {
+
+    if (typeof out_offset !== "number") {
+        // legacy (out, input) form
+        input = out_offset;
+        out_offset = 0;
+        input_offset = 0;
+    }
+
+    const x = input[input_offset];
+    const y = input[input_offset + 1];
+    const z = input[input_offset + 2];
+
+    out[out_offset] = 3.24096994190452134377 * x - 1.53738317757009345794 * y - 0.49861076029300328366 * z;
+    out[out_offset + 1] = (-0.96924363628087982613) * x + 1.87596750150772066772 * y + 0.04155505740717561247 * z;
+    out[out_offset + 2] = 0.05563007969699360846 * x - 0.20397695888897656435 * y + 1.05697151424287856072 * z;
+}

package/src/core/color/ycxcz/xyz_to_ycxcz.d.ts

@@ -7,8 +7,13 @@
  * applying it needs a representation where a weighted average of colours is still meaningful.
  * CIELab is not that representation — averaging cube roots is not the cube root of the average.
  *
- * The achromatic channel is `0` for black and `100` for reference white; the chromatic channels
- * are signed and roughly `+/-150` over the sRGB gamut.
+ * The achromatic channel is `100` for reference white and **`-16` for black**, not 0. That offset is
+ * CIELab's, and in CIELab the compression function's `4/29` intercept cancels it so black lands on 0; drop
+ * the compression, as this space deliberately does, and nothing cancels it. The channel is still linear in
+ * luminance and still exactly invertible, which is the property that matters here — but it is not `L*`, and
+ * anything treating it as a 0-to-100 lightness will be wrong at the dark end.
+ *
+ * The chromatic channels are signed and roughly `+/-150` over the sRGB gamut.
  *
  * @param {number[]|Float32Array|Float64Array} output
  * @param {number} output_offset

package/src/core/color/ycxcz/xyz_to_ycxcz.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"xyz_to_ycxcz.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/ycxcz/xyz_to_ycxcz.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,qCALW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,SACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,gBAClC,MAAM,QAUhB"}
+{"version":3,"file":"xyz_to_ycxcz.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/ycxcz/xyz_to_ycxcz.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qCALW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,SACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,gBAClC,MAAM,QAUhB"}

package/src/core/color/ycxcz/xyz_to_ycxcz.js

@@ -1,28 +1,33 @@
-import { D65_TRISTIMULUS_XYZ } from "../illuminant/D65_TRISTIMULUS_XYZ.js";
-
-/**
- * CIE XYZ to YyCxCz, a colour-opponent space that separates an achromatic channel from a
- * red-green and a blue-yellow one.
- *
- * It is CIELab's opponent structure without the cube-root compression, which makes it the space
- * to filter in: the human contrast sensitivity function is measured per opponent channel, and
- * applying it needs a representation where a weighted average of colours is still meaningful.
- * CIELab is not that representation — averaging cube roots is not the cube root of the average.
- *
- * The achromatic channel is `0` for black and `100` for reference white; the chromatic channels
- * are signed and roughly `+/-150` over the sRGB gamut.
- *
- * @param {number[]|Float32Array|Float64Array} output
- * @param {number} output_offset
- * @param {number[]|Float32Array|Float64Array} input
- * @param {number} input_offset
- */
-export function xyz_to_ycxcz(output, output_offset, input, input_offset) {
-    const x = input[input_offset] / D65_TRISTIMULUS_XYZ[0];
-    const y = input[input_offset + 1] / D65_TRISTIMULUS_XYZ[1];
-    const z = input[input_offset + 2] / D65_TRISTIMULUS_XYZ[2];
-
-    output[output_offset] = 116 * y - 16;
-    output[output_offset + 1] = 500 * (x - y);
-    output[output_offset + 2] = 200 * (y - z);
-}
+import { D65_TRISTIMULUS_XYZ } from "../illuminant/D65_TRISTIMULUS_XYZ.js";
+
+/**
+ * CIE XYZ to YyCxCz, a colour-opponent space that separates an achromatic channel from a
+ * red-green and a blue-yellow one.
+ *
+ * It is CIELab's opponent structure without the cube-root compression, which makes it the space
+ * to filter in: the human contrast sensitivity function is measured per opponent channel, and
+ * applying it needs a representation where a weighted average of colours is still meaningful.
+ * CIELab is not that representation — averaging cube roots is not the cube root of the average.
+ *
+ * The achromatic channel is `100` for reference white and **`-16` for black**, not 0. That offset is
+ * CIELab's, and in CIELab the compression function's `4/29` intercept cancels it so black lands on 0; drop
+ * the compression, as this space deliberately does, and nothing cancels it. The channel is still linear in
+ * luminance and still exactly invertible, which is the property that matters here — but it is not `L*`, and
+ * anything treating it as a 0-to-100 lightness will be wrong at the dark end.
+ *
+ * The chromatic channels are signed and roughly `+/-150` over the sRGB gamut.
+ *
+ * @param {number[]|Float32Array|Float64Array} output
+ * @param {number} output_offset
+ * @param {number[]|Float32Array|Float64Array} input
+ * @param {number} input_offset
+ */
+export function xyz_to_ycxcz(output, output_offset, input, input_offset) {
+    const x = input[input_offset] / D65_TRISTIMULUS_XYZ[0];
+    const y = input[input_offset + 1] / D65_TRISTIMULUS_XYZ[1];
+    const z = input[input_offset + 2] / D65_TRISTIMULUS_XYZ[2];
+
+    output[output_offset] = 116 * y - 16;
+    output[output_offset + 1] = 500 * (x - y);
+    output[output_offset + 2] = 200 * (y - z);
+}