@woosh/meep-engine 3.1.0 → 3.2.0

package/src/engine/graphics/texture/sampler/compare/flip/flip_compute_feature_difference.js

@@ -1,76 +1,76 @@
-import { assert } from "../../../../../../core/assert.js";
-import { max2 } from "../../../../../../core/math/max2.js";
-import { Sampler2D } from "../../Sampler2D.js";
-import {
-    FLIP_FEATURE_CHANNEL_COUNT,
-    FLIP_FEATURE_CHANNEL_EDGE_X,
-    FLIP_FEATURE_CHANNEL_EDGE_Y,
-    FLIP_FEATURE_CHANNEL_POINT_X,
-    FLIP_FEATURE_CHANNEL_POINT_Y
-} from "./flip_build_feature_kernel.js";
-import { FLIP_FEATURE_EXPONENT } from "./flip_constants.js";
-
-/**
- * Both detector responses are bounded by `sqrt(2)` once their lobes are normalized, so dividing by
- * it puts the difference in `[0, 1]` before the exponent is applied.
- * @type {number}
- */
-const NORMALIZATION = 1 / Math.SQRT2;
-
-/**
- * Per-pixel feature difference between two images, in `[0, 1]`.
- *
- * Takes the stronger of the two disagreements rather than combining them: an edge that moved and a
- * point that vanished are both total structural failures, and averaging them would let one mask the
- * other.
- *
- * @param {Sampler2D} reference 4 channels, from {@link flip_filter_feature}
- * @param {Sampler2D} test 4 channels, from {@link flip_filter_feature}
- * @returns {Sampler2D} 1 channel, float32
- */
-export function flip_compute_feature_difference(reference, test) {
-    assert.equal(reference.width, test.width, 'reference.width');
-    assert.equal(reference.height, test.height, 'reference.height');
-
-    const width = reference.width;
-    const height = reference.height;
-
-    const result = Sampler2D.float32(1, width, height);
-
-    const reference_data = reference.data;
-    const test_data = test.data;
-    const result_data = result.data;
-
-    const pixel_count = width * height;
-
-    for (let i = 0; i < pixel_count; i++) {
-        const address = i * FLIP_FEATURE_CHANNEL_COUNT;
-
-        const reference_edge = Math.hypot(
-            reference_data[address + FLIP_FEATURE_CHANNEL_EDGE_X],
-            reference_data[address + FLIP_FEATURE_CHANNEL_EDGE_Y]
-        );
-        const test_edge = Math.hypot(
-            test_data[address + FLIP_FEATURE_CHANNEL_EDGE_X],
-            test_data[address + FLIP_FEATURE_CHANNEL_EDGE_Y]
-        );
-
-        const reference_point = Math.hypot(
-            reference_data[address + FLIP_FEATURE_CHANNEL_POINT_X],
-            reference_data[address + FLIP_FEATURE_CHANNEL_POINT_Y]
-        );
-        const test_point = Math.hypot(
-            test_data[address + FLIP_FEATURE_CHANNEL_POINT_X],
-            test_data[address + FLIP_FEATURE_CHANNEL_POINT_Y]
-        );
-
-        const strongest = max2(
-            Math.abs(reference_edge - test_edge),
-            Math.abs(reference_point - test_point)
-        );
-
-        result_data[i] = Math.pow(NORMALIZATION * strongest, FLIP_FEATURE_EXPONENT);
-    }
-
-    return result;
-}
+import { assert } from "../../../../../../core/assert.js";
+import { max2 } from "../../../../../../core/math/max2.js";
+import { Sampler2D } from "../../Sampler2D.js";
+import {
+    FLIP_FEATURE_CHANNEL_COUNT,
+    FLIP_FEATURE_CHANNEL_EDGE_X,
+    FLIP_FEATURE_CHANNEL_EDGE_Y,
+    FLIP_FEATURE_CHANNEL_POINT_X,
+    FLIP_FEATURE_CHANNEL_POINT_Y
+} from "./flip_build_feature_kernel.js";
+import { FLIP_FEATURE_EXPONENT } from "./flip_constants.js";
+
+/**
+ * Both detector responses are bounded by `sqrt(2)` once their lobes are normalized, so dividing by
+ * it puts the difference in `[0, 1]` before the exponent is applied.
+ * @type {number}
+ */
+const NORMALIZATION = 1 / Math.SQRT2;
+
+/**
+ * Per-pixel feature difference between two images, in `[0, 1]`.
+ *
+ * Takes the stronger of the two disagreements rather than combining them: an edge that moved and a
+ * point that vanished are both total structural failures, and averaging them would let one mask the
+ * other.
+ *
+ * @param {Sampler2D} reference 4 channels, from {@link flip_filter_feature}
+ * @param {Sampler2D} test 4 channels, from {@link flip_filter_feature}
+ * @returns {Sampler2D} 1 channel, float32
+ */
+export function flip_compute_feature_difference(reference, test) {
+    assert.equal(reference.width, test.width, 'reference.width');
+    assert.equal(reference.height, test.height, 'reference.height');
+
+    const width = reference.width;
+    const height = reference.height;
+
+    const result = Sampler2D.float32(1, width, height);
+
+    const reference_data = reference.data;
+    const test_data = test.data;
+    const result_data = result.data;
+
+    const pixel_count = width * height;
+
+    for (let i = 0; i < pixel_count; i++) {
+        const address = i * FLIP_FEATURE_CHANNEL_COUNT;
+
+        const reference_edge = Math.hypot(
+            reference_data[address + FLIP_FEATURE_CHANNEL_EDGE_X],
+            reference_data[address + FLIP_FEATURE_CHANNEL_EDGE_Y]
+        );
+        const test_edge = Math.hypot(
+            test_data[address + FLIP_FEATURE_CHANNEL_EDGE_X],
+            test_data[address + FLIP_FEATURE_CHANNEL_EDGE_Y]
+        );
+
+        const reference_point = Math.hypot(
+            reference_data[address + FLIP_FEATURE_CHANNEL_POINT_X],
+            reference_data[address + FLIP_FEATURE_CHANNEL_POINT_Y]
+        );
+        const test_point = Math.hypot(
+            test_data[address + FLIP_FEATURE_CHANNEL_POINT_X],
+            test_data[address + FLIP_FEATURE_CHANNEL_POINT_Y]
+        );
+
+        const strongest = max2(
+            Math.abs(reference_edge - test_edge),
+            Math.abs(reference_point - test_point)
+        );
+
+        result_data[i] = Math.pow(NORMALIZATION * strongest, FLIP_FEATURE_EXPONENT);
+    }
+
+    return result;
+}

package/src/engine/graphics/texture/sampler/compare/flip/flip_compute_pixels_per_degree.js

@@ -1,34 +1,34 @@
-import { assert } from "../../../../../../core/assert.js";
-
-/**
- * Radians per degree.
- * @type {number}
- */
-const DEGREE = Math.PI / 180;
-
-/**
- * How many pixels fall within one degree of the viewer's visual angle.
- *
- * This is the only free parameter of FLIP, and it is a property of the *viewing setup* rather than
- * of the images. It decides how wide the contrast sensitivity filter is in pixels, which is to say
- * how much of a difference gets blurred away before it is measured: the same image pair viewed on a
- * phone at arm's length and on a projector across a room genuinely does differ in how noticeable
- * its differences are.
- *
- * @param {number} viewing_distance distance from the eye to the display, in metres
- * @param {number} display_width physical width of the display, in metres
- * @param {number} display_width_pixels horizontal resolution of the display, in pixels
- * @returns {number}
- */
-export function flip_compute_pixels_per_degree(viewing_distance, display_width, display_width_pixels) {
-    assert.isNumber(viewing_distance, 'viewing_distance');
-    assert.greaterThan(viewing_distance, 0, 'viewing_distance');
-
-    assert.isNumber(display_width, 'display_width');
-    assert.greaterThan(display_width, 0, 'display_width');
-
-    assert.isNumber(display_width_pixels, 'display_width_pixels');
-    assert.greaterThan(display_width_pixels, 0, 'display_width_pixels');
-
-    return viewing_distance * (display_width_pixels / display_width) * DEGREE;
-}
+import { assert } from "../../../../../../core/assert.js";
+
+/**
+ * Radians per degree.
+ * @type {number}
+ */
+const DEGREE = Math.PI / 180;
+
+/**
+ * How many pixels fall within one degree of the viewer's visual angle.
+ *
+ * This is the only free parameter of FLIP, and it is a property of the *viewing setup* rather than
+ * of the images. It decides how wide the contrast sensitivity filter is in pixels, which is to say
+ * how much of a difference gets blurred away before it is measured: the same image pair viewed on a
+ * phone at arm's length and on a projector across a room genuinely does differ in how noticeable
+ * its differences are.
+ *
+ * @param {number} viewing_distance distance from the eye to the display, in metres
+ * @param {number} display_width physical width of the display, in metres
+ * @param {number} display_width_pixels horizontal resolution of the display, in pixels
+ * @returns {number}
+ */
+export function flip_compute_pixels_per_degree(viewing_distance, display_width, display_width_pixels) {
+    assert.isNumber(viewing_distance, 'viewing_distance');
+    assert.greaterThan(viewing_distance, 0, 'viewing_distance');
+
+    assert.isNumber(display_width, 'display_width');
+    assert.greaterThan(display_width, 0, 'display_width');
+
+    assert.isNumber(display_width_pixels, 'display_width_pixels');
+    assert.greaterThan(display_width_pixels, 0, 'display_width_pixels');
+
+    return viewing_distance * (display_width_pixels / display_width) * DEGREE;
+}

package/src/engine/graphics/texture/sampler/compare/flip/flip_constants.js

@@ -1,77 +1,77 @@
-/**
- * Model parameters of the FLIP image difference metric.
- *
- * These are fitted values from the published model, not tunables. Changing any of them produces a
- * metric that is no longer FLIP and no longer agrees with the perceptual experiments the fits came
- * from.
- *
- * @see Andersson et al., "FLIP: A Difference Evaluator for Alternating Images",
- * Proceedings of the ACM on Computer Graphics and Interactive Techniques (HPG), 2020.
- */
-
-/**
- * Amplitude of the first gaussian of the contrast sensitivity filter, per opponent channel
- * (achromatic, red-green, blue-yellow).
- * @type {Float64Array}
- */
-export const FLIP_CSF_A1 = new Float64Array([1, 1, 34.1]);
-
-/**
- * Spatial extent of the first gaussian of the contrast sensitivity filter, per opponent channel.
- * @type {Float64Array}
- */
-export const FLIP_CSF_B1 = new Float64Array([0.0047, 0.0053, 0.04]);
-
-/**
- * Amplitude of the second gaussian of the contrast sensitivity filter, per opponent channel.
- *
- * Zero for the achromatic and red-green channels — only the blue-yellow channel needs two lobes to
- * fit its measured sensitivity, and that is what stops the filter being separable as a single
- * kernel.
- * @type {Float64Array}
- */
-export const FLIP_CSF_A2 = new Float64Array([0, 0, 13.5]);
-
-/**
- * Spatial extent of the second gaussian of the contrast sensitivity filter, per opponent channel.
- * @type {Float64Array}
- */
-export const FLIP_CSF_B2 = new Float64Array([1e-5, 1e-5, 0.025]);
-
-/**
- * Width of the point and edge detectors, in degrees of visual angle.
- * @type {number}
- */
-export const FLIP_FEATURE_WIDTH = 0.082;
-
-/**
- * Exponent applied to the colour difference before redistribution.
- * @type {number}
- */
-export const FLIP_COLOR_EXPONENT = 0.7;
-
-/**
- * Exponent applied to the feature difference.
- * @type {number}
- */
-export const FLIP_FEATURE_EXPONENT = 0.5;
-
-/**
- * Fraction of the maximum colour difference below which the redistribution is linear.
- * @type {number}
- */
-export const FLIP_REDISTRIBUTION_PIVOT = 0.4;
-
-/**
- * Output value that the pivot maps to. Most of the output range is spent on the lower 40% of the
- * input range, because that is where the differences a viewer would actually notice live.
- * @type {number}
- */
-export const FLIP_REDISTRIBUTION_PIVOT_VALUE = 0.95;
-
-/**
- * How many standard deviations of a gaussian to keep before truncating it. Beyond three the tail
- * carries under 0.3% of the mass.
- * @type {number}
- */
-export const FLIP_FILTER_EXTENT_DEVIATIONS = 3;
+/**
+ * Model parameters of the FLIP image difference metric.
+ *
+ * These are fitted values from the published model, not tunables. Changing any of them produces a
+ * metric that is no longer FLIP and no longer agrees with the perceptual experiments the fits came
+ * from.
+ *
+ * @see Andersson et al., "FLIP: A Difference Evaluator for Alternating Images",
+ * Proceedings of the ACM on Computer Graphics and Interactive Techniques (HPG), 2020.
+ */
+
+/**
+ * Amplitude of the first gaussian of the contrast sensitivity filter, per opponent channel
+ * (achromatic, red-green, blue-yellow).
+ * @type {Float64Array}
+ */
+export const FLIP_CSF_A1 = new Float64Array([1, 1, 34.1]);
+
+/**
+ * Spatial extent of the first gaussian of the contrast sensitivity filter, per opponent channel.
+ * @type {Float64Array}
+ */
+export const FLIP_CSF_B1 = new Float64Array([0.0047, 0.0053, 0.04]);
+
+/**
+ * Amplitude of the second gaussian of the contrast sensitivity filter, per opponent channel.
+ *
+ * Zero for the achromatic and red-green channels — only the blue-yellow channel needs two lobes to
+ * fit its measured sensitivity, and that is what stops the filter being separable as a single
+ * kernel.
+ * @type {Float64Array}
+ */
+export const FLIP_CSF_A2 = new Float64Array([0, 0, 13.5]);
+
+/**
+ * Spatial extent of the second gaussian of the contrast sensitivity filter, per opponent channel.
+ * @type {Float64Array}
+ */
+export const FLIP_CSF_B2 = new Float64Array([1e-5, 1e-5, 0.025]);
+
+/**
+ * Width of the point and edge detectors, in degrees of visual angle.
+ * @type {number}
+ */
+export const FLIP_FEATURE_WIDTH = 0.082;
+
+/**
+ * Exponent applied to the colour difference before redistribution.
+ * @type {number}
+ */
+export const FLIP_COLOR_EXPONENT = 0.7;
+
+/**
+ * Exponent applied to the feature difference.
+ * @type {number}
+ */
+export const FLIP_FEATURE_EXPONENT = 0.5;
+
+/**
+ * Fraction of the maximum colour difference below which the redistribution is linear.
+ * @type {number}
+ */
+export const FLIP_REDISTRIBUTION_PIVOT = 0.4;
+
+/**
+ * Output value that the pivot maps to. Most of the output range is spent on the lower 40% of the
+ * input range, because that is where the differences a viewer would actually notice live.
+ * @type {number}
+ */
+export const FLIP_REDISTRIBUTION_PIVOT_VALUE = 0.95;
+
+/**
+ * How many standard deviations of a gaussian to keep before truncating it. Beyond three the tail
+ * carries under 0.3% of the mass.
+ * @type {number}
+ */
+export const FLIP_FILTER_EXTENT_DEVIATIONS = 3;

package/src/engine/graphics/texture/sampler/compare/flip/flip_filter_feature.js

@@ -1,48 +1,48 @@
-import { Sampler2D } from "../../Sampler2D.js";
-import { sampler2d_channel_linear_transform } from "../../sampler2d_channel_linear_transform.js";
-import { sampler2d_convolve_separable } from "../../filter/sampler2d_convolve_separable.js";
-import { sampler2d_copy_channel_data } from "../../sampler2d_copy_channel_data.js";
-import {
-    FLIP_FEATURE_CHANNEL_COUNT,
-    FLIP_FEATURE_CHANNEL_EDGE_X,
-    FLIP_FEATURE_CHANNEL_EDGE_Y,
-    FLIP_FEATURE_CHANNEL_POINT_X,
-    FLIP_FEATURE_CHANNEL_POINT_Y
-} from "./flip_build_feature_kernel.js";
-
-/**
- * Run the point and edge detectors over the achromatic channel.
- *
- * The detectors read the *unfiltered* signal on purpose. The contrast sensitivity filter exists to
- * decide how visible a colour difference is; feature detection is asking a different question —
- * where the structure a viewer would fixate on actually is — and blurring the image first would
- * erase exactly the answer.
- *
- * @param {Sampler2D} ycxcz 3 channels, float32, as produced by {@link flip_srgb_to_ycxcz}
- * @param {SeparableKernel} kernel from {@link flip_build_feature_kernel}
- * @returns {Sampler2D} 4 channels, float32, `[edge X, edge Y, point X, point Y]`
- */
-export function flip_filter_feature(ycxcz, kernel) {
-    const width = ycxcz.width;
-    const height = ycxcz.height;
-
-    const source = Sampler2D.float32(FLIP_FEATURE_CHANNEL_COUNT, width, height);
-
-    // the achromatic channel runs 0..100; the detectors are calibrated against a 0..1 signal
-    sampler2d_channel_linear_transform(
-        source, ycxcz,
-        FLIP_FEATURE_CHANNEL_EDGE_X, 0,
-        1 / 116, 16 / 116
-    );
-
-    // every detector reads the same signal and differs only in its kernel
-    sampler2d_copy_channel_data(source, FLIP_FEATURE_CHANNEL_EDGE_X, source, FLIP_FEATURE_CHANNEL_EDGE_Y);
-    sampler2d_copy_channel_data(source, FLIP_FEATURE_CHANNEL_EDGE_X, source, FLIP_FEATURE_CHANNEL_POINT_X);
-    sampler2d_copy_channel_data(source, FLIP_FEATURE_CHANNEL_EDGE_X, source, FLIP_FEATURE_CHANNEL_POINT_Y);
-
-    const result = Sampler2D.float32(FLIP_FEATURE_CHANNEL_COUNT, width, height);
-
-    sampler2d_convolve_separable(result, source, kernel);
-
-    return result;
-}
+import { Sampler2D } from "../../Sampler2D.js";
+import { sampler2d_channel_linear_transform } from "../../sampler2d_channel_linear_transform.js";
+import { sampler2d_convolve_separable } from "../../filter/sampler2d_convolve_separable.js";
+import { sampler2d_copy_channel_data } from "../../sampler2d_copy_channel_data.js";
+import {
+    FLIP_FEATURE_CHANNEL_COUNT,
+    FLIP_FEATURE_CHANNEL_EDGE_X,
+    FLIP_FEATURE_CHANNEL_EDGE_Y,
+    FLIP_FEATURE_CHANNEL_POINT_X,
+    FLIP_FEATURE_CHANNEL_POINT_Y
+} from "./flip_build_feature_kernel.js";
+
+/**
+ * Run the point and edge detectors over the achromatic channel.
+ *
+ * The detectors read the *unfiltered* signal on purpose. The contrast sensitivity filter exists to
+ * decide how visible a colour difference is; feature detection is asking a different question —
+ * where the structure a viewer would fixate on actually is — and blurring the image first would
+ * erase exactly the answer.
+ *
+ * @param {Sampler2D} ycxcz 3 channels, float32, as produced by {@link flip_srgb_to_ycxcz}
+ * @param {SeparableKernel} kernel from {@link flip_build_feature_kernel}
+ * @returns {Sampler2D} 4 channels, float32, `[edge X, edge Y, point X, point Y]`
+ */
+export function flip_filter_feature(ycxcz, kernel) {
+    const width = ycxcz.width;
+    const height = ycxcz.height;
+
+    const source = Sampler2D.float32(FLIP_FEATURE_CHANNEL_COUNT, width, height);
+
+    // the achromatic channel runs 0..100; the detectors are calibrated against a 0..1 signal
+    sampler2d_channel_linear_transform(
+        source, ycxcz,
+        FLIP_FEATURE_CHANNEL_EDGE_X, 0,
+        1 / 116, 16 / 116
+    );
+
+    // every detector reads the same signal and differs only in its kernel
+    sampler2d_copy_channel_data(source, FLIP_FEATURE_CHANNEL_EDGE_X, source, FLIP_FEATURE_CHANNEL_EDGE_Y);
+    sampler2d_copy_channel_data(source, FLIP_FEATURE_CHANNEL_EDGE_X, source, FLIP_FEATURE_CHANNEL_POINT_X);
+    sampler2d_copy_channel_data(source, FLIP_FEATURE_CHANNEL_EDGE_X, source, FLIP_FEATURE_CHANNEL_POINT_Y);
+
+    const result = Sampler2D.float32(FLIP_FEATURE_CHANNEL_COUNT, width, height);
+
+    sampler2d_convolve_separable(result, source, kernel);
+
+    return result;
+}

package/src/engine/graphics/texture/sampler/compare/flip/flip_filter_spatial.js

@@ -1,86 +1,86 @@
-import { saturate } from "../../../../../../core/math/clamp01.js";
-import { lab_apply_hunt_adjustment } from "../../../../../../core/color/lab/lab_apply_hunt_adjustment.js";
-import { xyz_to_lab } from "../../../../../../core/color/lab/xyz_to_lab.js";
-import { rgb_to_xyz } from "../../../../../../core/color/xyz/rgb_to_xyz.js";
-import { xyz_to_rgb } from "../../../../../../core/color/xyz/xyz_to_rgb.js";
-import { ycxcz_to_xyz } from "../../../../../../core/color/ycxcz/ycxcz_to_xyz.js";
-import { Sampler2D } from "../../Sampler2D.js";
-import { sampler2d_convolve_separable } from "../../filter/sampler2d_convolve_separable.js";
-import { sampler2d_copy_channel_data } from "../../sampler2d_copy_channel_data.js";
-import {
-    FLIP_SPATIAL_CHANNEL_ACHROMATIC,
-    FLIP_SPATIAL_CHANNEL_BLUE_YELLOW_0,
-    FLIP_SPATIAL_CHANNEL_BLUE_YELLOW_1,
-    FLIP_SPATIAL_CHANNEL_COUNT,
-    FLIP_SPATIAL_CHANNEL_RED_GREEN
-} from "./flip_build_spatial_kernel.js";
-
-const temp_ycxcz = new Float64Array(3);
-const temp_xyz = new Float64Array(3);
-const temp_rgb = new Float64Array(3);
-const temp_lab = new Float64Array(3);
-
-/**
- * Apply the contrast sensitivity filter, then move the result into the space differences are
- * measured in.
- *
- * The filter is what makes FLIP a perceptual metric rather than an arithmetic one: it discards the
- * spatial frequencies the eye cannot resolve at the assumed viewing distance, so a difference that
- * is invisible in practice arrives at the comparison already erased.
- *
- * @param {Sampler2D} ycxcz 3 channels, float32, as produced by {@link flip_srgb_to_ycxcz}
- * @param {SeparableKernel} kernel from {@link flip_build_spatial_kernel}
- * @returns {Sampler2D} 3 channels, float32, Hunt-adjusted CIELab
- */
-export function flip_filter_spatial(ycxcz, kernel) {
-    const width = ycxcz.width;
-    const height = ycxcz.height;
-
-    // the blue-yellow channel rides in two slots; see `flip_build_spatial_kernel`
-    const source = Sampler2D.float32(FLIP_SPATIAL_CHANNEL_COUNT, width, height);
-
-    sampler2d_copy_channel_data(ycxcz, 0, source, FLIP_SPATIAL_CHANNEL_ACHROMATIC);
-    sampler2d_copy_channel_data(ycxcz, 1, source, FLIP_SPATIAL_CHANNEL_RED_GREEN);
-    sampler2d_copy_channel_data(ycxcz, 2, source, FLIP_SPATIAL_CHANNEL_BLUE_YELLOW_0);
-    sampler2d_copy_channel_data(ycxcz, 2, source, FLIP_SPATIAL_CHANNEL_BLUE_YELLOW_1);
-
-    const filtered = Sampler2D.float32(FLIP_SPATIAL_CHANNEL_COUNT, width, height);
-
-    sampler2d_convolve_separable(filtered, source, kernel);
-
-    const result = Sampler2D.float32(3, width, height);
-
-    const filtered_data = filtered.data;
-    const result_data = result.data;
-
-    const pixel_count = width * height;
-
-    for (let i = 0; i < pixel_count; i++) {
-        const address = i * FLIP_SPATIAL_CHANNEL_COUNT;
-
-        temp_ycxcz[0] = filtered_data[address + FLIP_SPATIAL_CHANNEL_ACHROMATIC];
-        temp_ycxcz[1] = filtered_data[address + FLIP_SPATIAL_CHANNEL_RED_GREEN];
-        temp_ycxcz[2] = filtered_data[address + FLIP_SPATIAL_CHANNEL_BLUE_YELLOW_0]
-            + filtered_data[address + FLIP_SPATIAL_CHANNEL_BLUE_YELLOW_1];
-
-        ycxcz_to_xyz(temp_xyz, 0, temp_ycxcz, 0);
-
-        // filtering can push a colour outside the gamut the display can actually produce, and what
-        // a viewer sees is the clamped version. The clamp has to happen in linear RGB, where the
-        // gamut is the unit cube, which is why the value goes back through XYZ afterwards rather
-        // than straight into CIELab
-        xyz_to_rgb(temp_rgb, temp_xyz);
-
-        temp_rgb[0] = saturate(temp_rgb[0]);
-        temp_rgb[1] = saturate(temp_rgb[1]);
-        temp_rgb[2] = saturate(temp_rgb[2]);
-
-        rgb_to_xyz(temp_xyz, temp_rgb);
-
-        xyz_to_lab(temp_lab, 0, temp_xyz, 0);
-
-        lab_apply_hunt_adjustment(result_data, i * 3, temp_lab, 0);
-    }
-
-    return result;
-}
+import { saturate } from "../../../../../../core/math/clamp01.js";
+import { lab_apply_hunt_adjustment } from "../../../../../../core/color/lab/lab_apply_hunt_adjustment.js";
+import { xyz_to_lab } from "../../../../../../core/color/lab/xyz_to_lab.js";
+import { rgb_to_xyz } from "../../../../../../core/color/xyz/rgb_to_xyz.js";
+import { xyz_to_rgb } from "../../../../../../core/color/xyz/xyz_to_rgb.js";
+import { ycxcz_to_xyz } from "../../../../../../core/color/ycxcz/ycxcz_to_xyz.js";
+import { Sampler2D } from "../../Sampler2D.js";
+import { sampler2d_convolve_separable } from "../../filter/sampler2d_convolve_separable.js";
+import { sampler2d_copy_channel_data } from "../../sampler2d_copy_channel_data.js";
+import {
+    FLIP_SPATIAL_CHANNEL_ACHROMATIC,
+    FLIP_SPATIAL_CHANNEL_BLUE_YELLOW_0,
+    FLIP_SPATIAL_CHANNEL_BLUE_YELLOW_1,
+    FLIP_SPATIAL_CHANNEL_COUNT,
+    FLIP_SPATIAL_CHANNEL_RED_GREEN
+} from "./flip_build_spatial_kernel.js";
+
+const temp_ycxcz = new Float64Array(3);
+const temp_xyz = new Float64Array(3);
+const temp_rgb = new Float64Array(3);
+const temp_lab = new Float64Array(3);
+
+/**
+ * Apply the contrast sensitivity filter, then move the result into the space differences are
+ * measured in.
+ *
+ * The filter is what makes FLIP a perceptual metric rather than an arithmetic one: it discards the
+ * spatial frequencies the eye cannot resolve at the assumed viewing distance, so a difference that
+ * is invisible in practice arrives at the comparison already erased.
+ *
+ * @param {Sampler2D} ycxcz 3 channels, float32, as produced by {@link flip_srgb_to_ycxcz}
+ * @param {SeparableKernel} kernel from {@link flip_build_spatial_kernel}
+ * @returns {Sampler2D} 3 channels, float32, Hunt-adjusted CIELab
+ */
+export function flip_filter_spatial(ycxcz, kernel) {
+    const width = ycxcz.width;
+    const height = ycxcz.height;
+
+    // the blue-yellow channel rides in two slots; see `flip_build_spatial_kernel`
+    const source = Sampler2D.float32(FLIP_SPATIAL_CHANNEL_COUNT, width, height);
+
+    sampler2d_copy_channel_data(ycxcz, 0, source, FLIP_SPATIAL_CHANNEL_ACHROMATIC);
+    sampler2d_copy_channel_data(ycxcz, 1, source, FLIP_SPATIAL_CHANNEL_RED_GREEN);
+    sampler2d_copy_channel_data(ycxcz, 2, source, FLIP_SPATIAL_CHANNEL_BLUE_YELLOW_0);
+    sampler2d_copy_channel_data(ycxcz, 2, source, FLIP_SPATIAL_CHANNEL_BLUE_YELLOW_1);
+
+    const filtered = Sampler2D.float32(FLIP_SPATIAL_CHANNEL_COUNT, width, height);
+
+    sampler2d_convolve_separable(filtered, source, kernel);
+
+    const result = Sampler2D.float32(3, width, height);
+
+    const filtered_data = filtered.data;
+    const result_data = result.data;
+
+    const pixel_count = width * height;
+
+    for (let i = 0; i < pixel_count; i++) {
+        const address = i * FLIP_SPATIAL_CHANNEL_COUNT;
+
+        temp_ycxcz[0] = filtered_data[address + FLIP_SPATIAL_CHANNEL_ACHROMATIC];
+        temp_ycxcz[1] = filtered_data[address + FLIP_SPATIAL_CHANNEL_RED_GREEN];
+        temp_ycxcz[2] = filtered_data[address + FLIP_SPATIAL_CHANNEL_BLUE_YELLOW_0]
+            + filtered_data[address + FLIP_SPATIAL_CHANNEL_BLUE_YELLOW_1];
+
+        ycxcz_to_xyz(temp_xyz, 0, temp_ycxcz, 0);
+
+        // filtering can push a colour outside the gamut the display can actually produce, and what
+        // a viewer sees is the clamped version. The clamp has to happen in linear RGB, where the
+        // gamut is the unit cube, which is why the value goes back through XYZ afterwards rather
+        // than straight into CIELab
+        xyz_to_rgb(temp_rgb, temp_xyz);
+
+        temp_rgb[0] = saturate(temp_rgb[0]);
+        temp_rgb[1] = saturate(temp_rgb[1]);
+        temp_rgb[2] = saturate(temp_rgb[2]);
+
+        rgb_to_xyz(temp_xyz, temp_rgb);
+
+        xyz_to_lab(temp_lab, 0, temp_xyz, 0);
+
+        lab_apply_hunt_adjustment(result_data, i * 3, temp_lab, 0);
+    }
+
+    return result;
+}