@woosh/meep-engine 2.138.20 → 2.139.0

package/src/engine/physics/fluid/SliceVisualiser.js

@@ -1,165 +1,190 @@
-import { float_to_uint8 } from "../../../core/binary/float_to_uint8.js";
-import { max2 } from "../../../core/math/max2.js";
-import { CanvasView } from "../../../view/elements/CanvasView.js";
-import EmptyView from "../../../view/elements/EmptyView.js";
-import { Sampler2D } from "../../graphics/texture/sampler/Sampler2D.js";
-
-export class SliceVisualiser extends EmptyView {
-
-    #data = null;
-    #views = [];
-    #slices = [];
-    #resolution = [0, 0, 0];
-    #imageData = null;
-    #channelCount = 1
-    #drawMethod = (out, out_offset, sample, channelCount) => {
-        let i = 0;
-
-        for (; i < channelCount; i++) {
-            out[out_offset + i] = float_to_uint8(sample[i])
-        }
-
-        if (channelCount < 4) {
-            out[out_offset + 3] = 255;
-        }
-
-    }
-
-
-    /**
-     *
-     */
-    constructor() {
-        super({ classList: ['slice-visualizer'] });
-
-
-        this.on.linked.add(this.layout, this);
-        this.size.onChanged.add(this.layout, this);
-    }
-
-    draw() {
-
-        const resolution_x = this.#resolution[0];
-        const resolution_y = this.#resolution[1];
-        const resolution_z = this.#resolution[2];
-
-        const imageData = this.#imageData;
-
-        const slice_size = resolution_x * resolution_y;
-
-        const data = this.#data;
-
-        const sample = new Float32Array(this.#channelCount);
-
-        for (let i = 0; i < resolution_z; i++) {
-            const view = this.#views[i];
-
-            for (let j = 0; j < slice_size; j++) {
-                const j4 = j * 4;
-
-                for (let k = 0; k < this.#channelCount; k++) {
-                    const channel = data[slice_size * k + j];
-
-                    sample[k] = channel;
-                }
-
-                this.#drawMethod(imageData.data, j4, sample, this.#channelCount);
-
-            }
-
-            view.context2d.putImageData(imageData, 0, 0);
-        }
-    }
-
-    layout() {
-
-        const resolution_x = this.#resolution[0];
-        const resolution_y = this.#resolution[1];
-        const resolution_z = this.#resolution[2];
-
-        const width = this.size.x;
-
-        const grid_width = max2(1, Math.floor(width / resolution_x));
-
-        for (let i = 0; i < resolution_z; i++) {
-            const view = this.#views[i];
-
-            const grid_x = i % grid_width;
-            const grid_y = Math.floor(i / grid_width);
-
-            view.position.set(grid_x * resolution_x, grid_y * resolution_y);
-        }
-    }
-
-    /**
-     *
-     * @param {ArrayBuffer} data
-     * @param {number[]} resolution
-     */
-    setData(
-        data,
-        resolution) {
-        this.#data = new Float32Array(data);
-        this.#resolution = resolution;
-
-
-        const resolution_x = this.#resolution[0];
-        const resolution_y = this.#resolution[1];
-        const resolution_z = this.#resolution[2];
-
-        const slice_size = resolution_x * resolution_y;
-
-        /**
-         *
-         * @type {ImageData|null}
-         */
-        this.#imageData = null;
-
-        let slice_index = 0;
-
-        for (; slice_index < resolution_z; slice_index++) {
-            this.#slices[slice_index] = new Sampler2D(new Float32Array(data, slice_index * slice_size * 4, slice_size), 1, resolution_x, resolution_y);
-
-            let child;
-            if (slice_index + 1 >= this.#views.length) {
-                child = new CanvasView();
-                this.#views[slice_index] = child
-                this.addChild(child);
-            } else {
-                child = this.#views[slice_index];
-            }
-
-            child.size.set(resolution_x, resolution_y);
-
-            if (this.#imageData === null) {
-                this.#imageData = child.context2d.getImageData(0, 0, resolution_x, resolution_y);
-            }
-
-            child.css({
-                position: "absolute",
-                left: 0,
-                top: 0
-            });
-
-            this.#views[slice_index] = child;
-
-            this.addChild(child);
-        }
-
-        //remove left-overs
-
-        for (; slice_index < this.#slices.length; slice_index++) {
-
-            this.#slices.splice(slice_index, 1);
-            const view = this.#views.splice(slice_index, 1)[0];
-
-            this.removeChild(view);
-
-            slice_index--;
-
-        }
-
-        this.layout();
-    }
-
-}
+import { assert } from "../../../core/assert.js";
+import { float_to_uint8 } from "../../../core/binary/float_to_uint8.js";
+import { max2 } from "../../../core/math/max2.js";
+import { CanvasView } from "../../../view/elements/CanvasView.js";
+import EmptyView from "../../../view/elements/EmptyView.js";
+
+/**
+ * Debug view: renders each z-slice of a 3D field as a 2D canvas tile, with up to four
+ * channels mapped to RGBA. Used by {@link prototype.js}; not a production runtime view.
+ *
+ * The visualiser is data-agnostic — it takes an array of one to four Float32Array
+ * channels, each of length `res_x * res_y * res_z`, and a per-channel mapping to colour
+ * via {@link setDrawMethod}. Default mapping clamps to `[0, 1]` per channel and writes
+ * opaque pixels.
+ */
+export class SliceVisualiser extends EmptyView {
+
+    /**
+     * @type {Float32Array[]}
+     */
+    #channels = [];
+
+    /**
+     * @type {CanvasView[]}
+     */
+    #views = [];
+
+    /**
+     * @type {[number, number, number]}
+     */
+    #resolution = [0, 0, 0];
+
+    /**
+     * @type {ImageData|null}
+     */
+    #imageData = null;
+
+    /**
+     * Per-pixel transform. Receives the destination RGBA buffer, the byte offset of the
+     * current pixel, a Float32Array of channel samples for that pixel, and the channel
+     * count.
+     * @type {(out: Uint8ClampedArray, out_offset: number, sample: Float32Array, channel_count: number) => void}
+     */
+    #drawMethod = (out, out_offset, sample, channel_count) => {
+        for (let i = 0; i < channel_count; i++) {
+            out[out_offset + i] = float_to_uint8(sample[i]);
+        }
+        if (channel_count < 4) {
+            out[out_offset + 3] = 255;
+        }
+    };
+
+    constructor() {
+        super({ classList: ['slice-visualizer'] });
+
+        this.on.linked.add(this.layout, this);
+        this.size.onChanged.add(this.layout, this);
+    }
+
+    /**
+     * Replace the per-pixel transform. The function receives the destination RGBA
+     * `Uint8ClampedArray`, the byte offset of the current pixel within it, a Float32Array
+     * of channel samples for that pixel, and the configured channel count.
+     * @param {(out: Uint8ClampedArray, out_offset: number, sample: Float32Array, channel_count: number) => void} fn
+     */
+    setDrawMethod(fn) {
+        this.#drawMethod = fn;
+    }
+
+    /**
+     * Attach the channels and resolution to visualise. Recomputes the layout and
+     * rebuilds the per-slice canvases (creating or destroying child views as needed).
+     *
+     * @param {Float32Array[]} channels   1-4 channels; each length = res_x * res_y * res_z.
+     * @param {number[]} resolution       `[res_x, res_y, res_z]`
+     */
+    setChannels(channels, resolution) {
+        assert.isArray(channels, "channels");
+        assert.greaterThanOrEqual(channels.length, 1, "channels.length");
+        assert.lessThanOrEqual(channels.length, 4, "channels.length");
+        assert.equal(resolution.length, 3, "resolution must have 3 entries");
+
+        const res_x = resolution[0];
+        const res_y = resolution[1];
+        const res_z = resolution[2];
+        const cell_count = res_x * res_y * res_z;
+
+        for (let i = 0; i < channels.length; i++) {
+            assert.equal(channels[i].length, cell_count,
+                `channel[${i}] sized to resolution`);
+        }
+
+        this.#channels = channels.slice();
+        this.#resolution[0] = res_x;
+        this.#resolution[1] = res_y;
+        this.#resolution[2] = res_z;
+
+        // Add canvases for new slices.
+        while (this.#views.length < res_z) {
+            const view = new CanvasView();
+            view.size.set(res_x, res_y);
+            view.css({ position: "absolute", left: 0, top: 0 });
+            this.#views.push(view);
+            this.addChild(view);
+        }
+
+        // Drop canvases for removed slices.
+        while (this.#views.length > res_z) {
+            const view = this.#views.pop();
+            this.removeChild(view);
+        }
+
+        // Resize existing canvases if resolution changed.
+        for (let i = 0; i < res_z; i++) {
+            const view = this.#views[i];
+            if (view.size.x !== res_x || view.size.y !== res_y) {
+                view.size.set(res_x, res_y);
+            }
+        }
+
+        // Recreate the shared ImageData buffer at the new slice size.
+        if (res_z > 0) {
+            this.#imageData = this.#views[0].context2d.getImageData(0, 0, res_x, res_y);
+        } else {
+            this.#imageData = null;
+        }
+
+        this.layout();
+    }
+
+    /**
+     * Render the current channel data into each per-slice canvas. Cheap to call every
+     * frame for small grids; expensive at high resolutions.
+     */
+    draw() {
+        if (this.#imageData === null) {
+            return;
+        }
+
+        const res_x = this.#resolution[0];
+        const res_y = this.#resolution[1];
+        const res_z = this.#resolution[2];
+        const slice_size = res_x * res_y;
+        const channels = this.#channels;
+        const channel_count = channels.length;
+
+        const out = this.#imageData.data;
+        const sample = new Float32Array(channel_count);
+
+        for (let z = 0; z < res_z; z++) {
+            const view = this.#views[z];
+            const z_off = z * slice_size;
+
+            for (let p = 0; p < slice_size; p++) {
+                const c = z_off + p;
+                for (let k = 0; k < channel_count; k++) {
+                    sample[k] = channels[k][c];
+                }
+                this.#drawMethod(out, p * 4, sample, channel_count);
+            }
+
+            view.context2d.putImageData(this.#imageData, 0, 0);
+        }
+    }
+
+    /**
+     * Reflow the per-slice canvases into a 2D grid that fits the view's current width.
+     * Called automatically on link and on size change; safe to invoke manually.
+     */
+    layout() {
+        const res_x = this.#resolution[0];
+        const res_y = this.#resolution[1];
+        const res_z = this.#resolution[2];
+
+        if (res_x === 0 || res_z === 0) {
+            return;
+        }
+
+        const width = this.size.x;
+        const grid_width = max2(1, Math.floor(width / res_x));
+
+        for (let i = 0; i < res_z; i++) {
+            const view = this.#views[i];
+            const grid_x = i % grid_width;
+            const grid_y = Math.floor(i / grid_width);
+
+            view.position.set(grid_x * res_x, grid_y * res_y);
+        }
+    }
+}

package/src/engine/physics/fluid/ecs/FluidComponent.d.ts

@@ -0,0 +1,154 @@
+/**
+ * ECS component representing a fluid volume — one {@link FluidField} plus its placement
+ * in world space.
+ *
+ * Behaviour (stepping the simulation, dispatching effectors, re-anchoring on Transform
+ * motion) lives on {@link FluidSystem}, not here. This component is pure data.
+ *
+ * World ↔ grid mapping is uniform and axis-aligned: cell `(0,0,0)`'s center sits at
+ * {@link origin}, and cells are spaced {@link cell_size} world-units apart along each
+ * axis. For non-uniform or oriented volumes, use multiple components.
+ *
+ * **Static placement**: leave the entity without a `Transform`. Set {@link origin}
+ * directly and the system never touches it.
+ *
+ * **Moving placement**: pair the entity with a `Transform`. The system re-anchors the
+ * grid on every fixedUpdate to `quantize(transform.position, cell_size) + offset`, and
+ * when the quantization changes shifts the field by the integer cell delta (carrying
+ * fluid data along with the grid so the fluid appears to stay put in world space) and
+ * patches the newly exposed edges with a Neumann zero-gradient extrapolation. {@link
+ * origin} becomes system-managed in this case.
+ *
+ * NOTE on layout: sibling physics ECS code lives under `engine/ecs/*` (see
+ * `engine/ecs/ik/InverseKinematicsSystem.js`). This component is placed inside the
+ * fluid package because edits to the ECS folder were out-of-scope when it was first
+ * written. Moving it under `engine/ecs/fluid/` later is a pure relocation.
+ */
+export class FluidComponent {
+    /**
+     * @type {FluidField}
+     */
+    field: FluidField;
+    /**
+     * World position of grid cell `(0,0,0)`'s center. For static placement (no
+     * `Transform` on the entity) the user sets this directly. For moving placement
+     * (with `Transform`) {@link FluidSystem} owns it — every fixedUpdate it computes
+     * the desired origin from the transform and either snaps on first sync or shifts
+     * the field by the integer cell delta.
+     * @type {[number, number, number]}
+     */
+    origin: [number, number, number];
+    /**
+     * World-space offset added to the quantized `Transform.position` when computing
+     * the grid centre. Use to place the grid asymmetrically relative to the entity —
+     * e.g. `[-2, 0, 0]` puts the centre 2 world units behind the entity.
+     *
+     * Only consulted when a `Transform` is present (otherwise `origin` is fully
+     * user-controlled).
+     * @type {[number, number, number]}
+     */
+    offset: [number, number, number];
+    /**
+     * Uniform world-space spacing between adjacent cell centers.
+     * @type {number}
+     */
+    cell_size: number;
+    /**
+     * Half-cell extra margin (in cells) the Transform must cross before the field
+     * re-quantizes to the next cell. Without it, a Transform jittering right on the
+     * boundary between two cells would re-shift every frame, repeatedly clearing the
+     * solid mask and patching velocity edges — visible as flicker in the fluid and
+     * thrashing in any solid-voxelizer downstream of the shift.
+     *
+     * Mechanism: the system keeps the current quantized cell `q` and only re-quantizes
+     * when `|transform.position / cell_size - q| > 0.5 + hysteresis`. Crossing the
+     * threshold snaps to the new nearest cell — not the threshold position — so motion
+     * past the deadband still produces a single discrete shift.
+     *
+     * Range `[0, 0.5)`. `0` disables (snap on any boundary crossing). Default `0.1`
+     * gives a ~10%-of-a-cell deadband on each side, killing jitter while staying
+     * imperceptible at typical cell sizes.
+     *
+     * Only consulted when a `Transform` is present.
+     * @type {number}
+     */
+    hysteresis: number;
+    /**
+     * If false, {@link FluidSystem} skips this volume's step. Use to pause fluid for
+     * culled or off-screen volumes.
+     * @type {boolean}
+     */
+    enabled: boolean;
+    /**
+     * Set by {@link FluidSystem} on the first reanchor — distinguishes "snap origin
+     * to the desired position without shifting" (first sync) from "shift the field
+     * by the integer cell delta" (subsequent syncs). User code should not touch this.
+     * @type {boolean}
+     */
+    anchored: boolean;
+    /**
+     * Convert a world-space point to fractional grid coordinates.
+     * @param {Float32Array|number[]} out  length-3 destination
+     * @param {number} wx
+     * @param {number} wy
+     * @param {number} wz
+     * @return {Float32Array|number[]} `out`, for chaining.
+     */
+    worldToGrid(out: Float32Array | number[], wx: number, wy: number, wz: number): Float32Array | number[];
+    /**
+     * Convert fractional grid coordinates to a world-space point.
+     * @param {Float32Array|number[]} out  length-3 destination
+     * @param {number} gx
+     * @param {number} gy
+     * @param {number} gz
+     * @return {Float32Array|number[]} `out`, for chaining.
+     */
+    gridToWorld(out: Float32Array | number[], gx: number, gy: number, gz: number): Float32Array | number[];
+    /**
+     * Sample velocity at a world-space point. The velocity values stored in the field
+     * are in "grid cells per second"; this method does NOT rescale them, on the
+     * assumption that callers (vegetation sway, dust drift) interpret the field as a
+     * direction × magnitude wind and want consistent strength regardless of the
+     * underlying cell size.
+     *
+     * If you need world-units-per-second velocity, multiply the result by `cell_size`.
+     *
+     * @param {Float32Array|number[]} out  length-3 destination
+     * @param {number} wx
+     * @param {number} wy
+     * @param {number} wz
+     * @return {Float32Array|number[]} `out`, for chaining.
+     */
+    sampleVelocityAtWorld(out: Float32Array | number[], wx: number, wy: number, wz: number): Float32Array | number[];
+    /**
+     * Sample a passive scalar at a world-space point.
+     * @param {string} name
+     * @param {number} wx
+     * @param {number} wy
+     * @param {number} wz
+     * @return {number}
+     */
+    sampleScalarAtWorld(name: string, wx: number, wy: number, wz: number): number;
+    /**
+     * @param {FluidComponent} other
+     * @return {boolean}
+     */
+    equals(other: FluidComponent): boolean;
+    /**
+     * @return {number}
+     */
+    hash(): number;
+    /**
+     * Write the field's world-space axis-aligned bounding box into `out`. Used by
+     * {@link FluidSystem} as a broad-phase target when filtering effectors. The box
+     * spans cell `(0, 0, 0)` (centred at `origin`) to cell `(res_x-1, res_y-1, res_z-1)`
+     * plus a `cell_size` margin on the far side, so a point exactly on the field's
+     * boundary cells lies inside the AABB.
+     *
+     * @param {AABB3} out
+     */
+    getBoundingBox(out: AABB3): void;
+    isFluidComponent: boolean;
+}
+import { FluidField } from "../FluidField.js";
+//# sourceMappingURL=FluidComponent.d.ts.map

package/src/engine/physics/fluid/ecs/FluidComponent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FluidComponent.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidComponent.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAEI;;OAEG;IACH,OAFU,UAAU,CAEK;IAEzB;;;;;;;OAOG;IACH,QAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEf;IAEnB;;;;;;;;OAQG;IACH,QAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEf;IAEnB;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,SAFU,OAAO,CAEF;IAEf;;;;;OAKG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;OAOG;IACH,iBANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAQhC;IAED;;;;;;;OAOG;IACH,iBANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAOhC;IAED;;;;;;;;;;;;;;OAcG;IACH,2BANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAQhC;IAED;;;;;;;OAOG;IACH,0BANW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACL,MAAM,CAQjB;IAED;;;OAGG;IACH,cAHW,cAAc,GACb,OAAO,CAoBlB;IAED;;OAEG;IACH,QAFY,MAAM,CAgBjB;IAED;;;;;;;;OAQG;IACH,iCAYC;IAGL,0BAAyC;CAFxC;2BAzO0B,kBAAkB"}