@woosh/meep-engine 3.23.0 → 3.25.0

package/src/engine/physics/cloth/playground/wind_main.js

@@ -0,0 +1,681 @@
+import { EntityComponentDataset } from "../../../ecs/EntityComponentDataset.js";
+import { FluidComponent } from "../../fluid/ecs/FluidComponent.js";
+import { fluid_build_world_to_grid } from "../../fluid/ecs/fluid_build_world_to_grid.js";
+import { CLOTH_DYNAMICS_BY_NAME } from "../ecs/cloth_dynamics_library.js";
+import { cloth_bend_ratio, cloth_drag_response } from "../ecs/cloth_dynamics_map.js";
+import { cloth_step } from "../solver/cloth_step.js";
+import { cloth_wind_accelerate } from "../solver/cloth_wind_accelerate.js";
+import { find_non_finite_cloth_state } from "../solver/find_non_finite_cloth_state.js";
+import { ClothFluidWind } from "../wind/ClothFluidWind.js";
+import { cloth_sample_air } from "../wind/cloth_sample_air.js";
+import { build_cloth_playground_scene } from "./cloth_playground_build.js";
+import { draw_cloth, PlaygroundCamera, project } from "./cloth_playground_draw.js";
+import { build_wind_tunnel, place_wind_post } from "./wind_build.js";
+
+/**
+ * # Cloth wind playground — M6
+ *
+ * `npm run dev --workspace @woosh/meep-engine`, then
+ * <http://localhost:5173/src/engine/physics/cloth/playground/wind.html>.
+ *
+ * §17 asks M6 for "a playground with a banner in a simulated wake", and the
+ * word that matters is **simulated**. There is no wind model on this page. There
+ * is a `FluidField`, a `FluidSimulator`, a `GlobalFluidEffector` driving the
+ * prevailing flow, and a solid post standing in it; the deficit and the turning
+ * behind the post are the incompressible projection's answer, and the banner
+ * reads them through exactly the `ClothFluidWind` and `cloth_sample_air` a game
+ * scene would use.
+ * That is §10's whole argument — this engine already has something better than a
+ * wind zone — put where it can be watched instead of read.
+ *
+ * Three things to watch rather than read, all of them measured in
+ * `MEASUREMENTS.md` §49:
+ *
+ * - **Turn the flow to 90° on "ambient only".** The banner goes limp at the
+ *   same wind speed — the mean drag acceleration falls from 43 m/s² to 0.08,
+ *   and the mean facing factor from 0.22 to 0.000. That is §10's normal-facing
+ *   factor, and the "drag accel" readout is it as a number.
+ * - **Do the same on the fluid field, and it does not go limp.** The factor
+ *   reads 0.22 at 0° and 0.28 at 90°. A wake has velocity in every direction,
+ *   so there is no orientation of a banner that is edge-on to one — which is
+ *   something the simulation knows and a wind zone could not have told it.
+ * - **Take the post away.** The air at the banner goes from 6.0 m/s to 8.7:
+ *   the post's deficit is a third of the free stream, and it is the
+ *   incompressible projection's answer rather than an authored falloff. What
+ *   the wake is *not*, at the grid a sixty-hertz page can afford, is a
+ *   shedding street — it is a steady deficit, and the free corner moves twelve
+ *   times as far per step with the post as without rather than fluttering.
+ *
+ * And **"ambient only"** is §10's fallback: a constant plus a band-limited
+ * gust, uniform over the whole banner, read through the same interface. It
+ * costs one sample for the whole cloth instead of one per particle, which the
+ * readout shows as the sample time dropping by a factor of twenty-five.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/** Display rate the fixed step is driven at. */
+const FIXED_STEP = 1 / 60;
+
+/** §17's target, for the budget bar. */
+const BUDGET_MS = 2;
+
+/** How many recent timings the readout averages. */
+const TIMING_WINDOW = 90;
+
+const element = (id) => document.getElementById(id);
+
+const canvas = element('view');
+const context = canvas.getContext('2d');
+
+const camera = new PlaygroundCamera();
+
+camera.target[1] = -0.35;
+camera.distance = 2.6;
+camera.yaw = 0.9;
+
+/** The cloth's frame is the world's on this page. */
+const FRAME_ORIGIN = new Float64Array(3);
+const FRAME_ROTATION = new Float64Array([0, 0, 0, 1]);
+
+/**
+ * Everything the page can change. `size`, `spacing` and `resolution` rebuild;
+ * everything else is read afresh every step.
+ */
+const control = {
+    fabric: 'SILK',
+    size: 16,
+    spacing: 0.045,
+    drag: CLOTH_DYNAMICS_BY_NAME.SILK.drag,
+    substeps: 2,
+    iterations: 4,
+    speed: 9,
+    yaw: 0,
+    gust: 1.5,
+    source: 'field',
+    post: true,
+    resolution: 18,
+    running: true,
+    show_field: true
+};
+
+/** @type {{state: ClothState, triangle: Int32Array}} */
+let cloth = null;
+
+/** @type {ReturnType<build_wind_tunnel>} */
+let tunnel = null;
+
+/** @type {ClothFluidWind} */
+const wind = new ClothFluidWind();
+
+/** The dataset the wind source reads its fields out of — one component in it. */
+const ecd = new EntityComponentDataset();
+
+ecd.setComponentTypeMap([FluidComponent]);
+
+let fluid_entity = -1;
+
+let time = 0;
+
+const cloth_timings = [];
+const fluid_timings = [];
+const sample_timings = [];
+
+const air_centre = new Float64Array(3);
+
+let sampled_per_particle = false;
+let mean_drag = 0;
+let tripwire = "";
+
+// ------------------------------------------------------------------- build
+
+function rebuild() {
+    const dynamics = CLOTH_DYNAMICS_BY_NAME[control.fabric];
+
+    cloth = build_cloth_playground_scene({
+        shape: 'sheet',
+        width: control.size,
+        height: control.size,
+        spacing: control.spacing,
+        mass: 0.4,
+        // The fabric row is hard, per §6 — a stretch stiffness an author could
+        // reach for is on the wrong side of the dissipative band.
+        stretch_stiffness: Infinity,
+        bend_modulus: cloth_bend_ratio(dynamics.bend) * 2e-5,
+        pinned: 'top',
+        flat: false
+    });
+
+    time = 0;
+
+    cloth_timings.length = 0;
+    fluid_timings.length = 0;
+    sample_timings.length = 0;
+
+    rebuild_tunnel();
+}
+
+function rebuild_tunnel() {
+    const cells = control.resolution;
+
+    // A volume that holds the banner with room upstream for a wake to form in.
+    const cell_size = 0.08;
+
+    const span_x = cells * cell_size;
+    const span_y = cells * cell_size;
+    const span_z = Math.round(cells * 1.6) * cell_size;
+
+    tunnel = build_wind_tunnel({
+        cell_size,
+        resolution: [cells, cells, Math.round(cells * 1.6)],
+        origin: [-span_x * 0.5, -span_y * 0.72, -span_z * 0.5]
+    });
+
+    if (fluid_entity >= 0) {
+        ecd.removeEntity(fluid_entity);
+    }
+
+    fluid_entity = ecd.createEntity();
+
+    ecd.addComponentToEntity(fluid_entity, tunnel.component);
+
+    refresh_post();
+}
+
+function refresh_post() {
+    const angle = control.yaw * Math.PI / 180;
+
+    // Upstream of the banner, along whichever way the air is blowing.
+    const distance = 0.55;
+
+    place_wind_post(tunnel, {
+        present: control.post,
+        x: -Math.sin(angle) * distance,
+        z: -Math.cos(angle) * distance,
+        radius: 0.12
+    });
+}
+
+// -------------------------------------------------------------------- step
+
+function step_once() {
+    const dynamics = CLOTH_DYNAMICS_BY_NAME[control.fabric];
+
+    time += FIXED_STEP;
+
+    const angle = control.yaw * Math.PI / 180;
+
+    tunnel.effector.wind[0] = Math.sin(angle) * control.speed;
+    tunnel.effector.wind[1] = 0;
+    tunnel.effector.wind[2] = Math.cos(angle) * control.speed;
+
+    wind.ambient.wind[0] = tunnel.effector.wind[0];
+    wind.ambient.wind[1] = 0;
+    wind.ambient.wind[2] = tunnel.effector.wind[2];
+
+    wind.ambient.gust = control.gust;
+    wind.ambient.period = 1.6;
+
+    // 1. The air. A real fluid step, with the post's wake in it.
+    const fluid_started = performance.now();
+
+    fluid_build_world_to_grid(tunnel.world_to_grid, tunnel.component);
+
+    tunnel.component.enabled = control.source === 'field';
+
+    if (tunnel.component.enabled) {
+        tunnel.simulator.step(
+            tunnel.component.field, FIXED_STEP, [tunnel.effector], tunnel.world_to_grid
+        );
+    }
+
+    record(fluid_timings, performance.now() - fluid_started);
+
+    // 2. The cloth reads it. `begin` once a step, then one sample per particle
+    //    — or one for the whole banner where no field reaches, which is what
+    //    "ambient only" turns this page into.
+    const sample_started = performance.now();
+
+    wind.begin(time, ecd);
+
+    sampled_per_particle = cloth_sample_air(
+        cloth.state, wind, FRAME_ORIGIN, FRAME_ROTATION, air_centre
+    );
+
+    record(sample_timings, performance.now() - sample_started);
+
+    // 3. The step, with §10's term in it.
+    const started = performance.now();
+
+    const response = cloth_drag_response(control.drag, FIXED_STEP);
+
+    if (response !== 0) {
+        cloth_wind_accelerate(cloth.state, response, 0, -9.81, 0);
+
+        cloth_step(
+            cloth.state, FIXED_STEP, 0, -9.81, 0,
+            control.substeps, control.iterations,
+            null, 0, undefined, cloth.state.external_acceleration
+        );
+    } else {
+        cloth_step(
+            cloth.state, FIXED_STEP, 0, -9.81, 0, control.substeps, control.iterations
+        );
+    }
+
+    record(cloth_timings, performance.now() - started);
+
+    tripwire = find_non_finite_cloth_state(cloth.state);
+
+    measure_drag(response);
+}
+
+/**
+ * The mean aerodynamic acceleration the banner is actually feeling — the
+ * external acceleration with gravity taken back out. It is the normal-facing
+ * factor made into a number: turn the flow ninety degrees at a fixed wind speed
+ * and watch it collapse.
+ *
+ * @param {number} response
+ */
+function measure_drag(response) {
+    if (response === 0) {
+        mean_drag = 0;
+
+        return;
+    }
+
+    const state = cloth.state;
+
+    let total = 0;
+    let free = 0;
+
+    for (let i = 0; i < state.particle_count; i++) {
+        if (state.mass_inverse[i] === 0) {
+            continue;
+        }
+
+        const p = i * 3;
+
+        total += Math.hypot(
+            state.external_acceleration[p],
+            state.external_acceleration[p + 1] + 9.81,
+            state.external_acceleration[p + 2]
+        );
+
+        free++;
+    }
+
+    mean_drag = free === 0 ? 0 : total / free;
+}
+
+/**
+ * @param {number[]} window
+ * @param {number} value
+ */
+function record(window, value) {
+    window.push(value);
+
+    if (window.length > TIMING_WINDOW) {
+        window.shift();
+    }
+}
+
+/**
+ * @param {number[]} window
+ * @returns {number}
+ */
+function mean(window) {
+    if (window.length === 0) {
+        return 0;
+    }
+
+    let total = 0;
+
+    for (const value of window) {
+        total += value;
+    }
+
+    return total / window.length;
+}
+
+// -------------------------------------------------------------------- draw
+
+/**
+ * The flow itself, on a horizontal slice through the banner's waist: one
+ * segment per cell, along the air, brighter where it is faster. The wake is the
+ * part that is not pointing downstream.
+ */
+function draw_field() {
+    if (!control.show_field || control.source !== 'field') {
+        return;
+    }
+
+    const component = tunnel.component;
+
+    const [res_x, res_y, res_z] = tunnel.resolution;
+
+    const cell_size = tunnel.cell_size;
+
+    const width = context.canvas.width;
+    const height = context.canvas.height;
+
+    const from = new Float64Array(2);
+    const to = new Float64Array(2);
+
+    const sample = new Float64Array(3);
+
+    const slice = Math.floor(res_y * 0.55);
+
+    const stride = res_x > 24 ? 2 : 1;
+
+    context.lineWidth = Math.max(1, width / 900);
+
+    for (let k = 0; k < res_z; k += stride) {
+        for (let i = 0; i < res_x; i += stride) {
+            const x = component.origin[0] + i * cell_size;
+            const y = component.origin[1] + slice * cell_size;
+            const z = component.origin[2] + k * cell_size;
+
+            if (component.field.solid[k * res_x * res_y + slice * res_x + i] !== 0) {
+                const depth = project(from, camera, x, y, z, width, height);
+
+                if (depth > 0) {
+                    context.fillStyle = '#e5533d';
+                    context.fillRect(from[0] - 2, from[1] - 2, 4, 4);
+                }
+
+                continue;
+            }
+
+            component.sampleVelocityAtWorld(sample, x, y, z);
+
+            // Cells a second to metres a second, the same conversion
+            // `ClothFluidWind` makes and for the same reason.
+            const vx = sample[0] * cell_size;
+            const vz = sample[2] * cell_size;
+
+            const speed = Math.hypot(vx, sample[1] * cell_size, vz);
+
+            if (speed < 1e-3) {
+                continue;
+            }
+
+            const scale = 0.045 / Math.max(speed, 1e-3);
+
+            const depth = project(from, camera, x, y, z, width, height);
+
+            project(to, camera, x + vx * scale, y + sample[1] * cell_size * scale, z + vz * scale, width, height);
+
+            if (depth <= 0) {
+                continue;
+            }
+
+            const t = Math.min(1, speed / Math.max(control.speed, 0.01));
+
+            context.strokeStyle = `rgba(${Math.round(80 + 140 * t)}, ${Math.round(150 + 60 * t)}, 220, ${0.25 + 0.5 * t})`;
+
+            context.beginPath();
+            context.moveTo(from[0], from[1]);
+            context.lineTo(to[0], to[1]);
+            context.stroke();
+        }
+    }
+}
+
+function refresh_readout() {
+    const cloth_ms = mean(cloth_timings);
+
+    element('ms').textContent = cloth_ms.toFixed(3);
+    element('fluid_ms').textContent = mean(fluid_timings).toFixed(3);
+    element('sample_us').textContent = (mean(sample_timings) * 1000).toFixed(1);
+
+    element('sample_mode').textContent = sampled_per_particle
+        ? `per particle (${cloth.state.particle_count})`
+        : 'once for the cloth';
+
+    element('counts').textContent = `${cloth.state.particle_count} / ${cloth.state.stretch_count}`;
+
+    element('air').textContent =
+        `${Math.hypot(air_centre[0], air_centre[1], air_centre[2]).toFixed(2)} m/s`;
+
+    element('drag_accel').textContent = `${mean_drag.toFixed(2)} m/s²`;
+
+    const tripwire_element = element('tripwire');
+
+    tripwire_element.textContent = tripwire === "" ? 'ok' : tripwire;
+    tripwire_element.className = tripwire === "" ? 'good' : 'bad';
+
+    const budget = element('budget');
+
+    budget.classList.toggle('over', cloth_ms > BUDGET_MS);
+    budget.firstElementChild.style.width = `${Math.min(100, 100 * cloth_ms / BUDGET_MS)}%`;
+}
+
+function frame() {
+    if (control.running) {
+        step_once();
+    }
+
+    draw_cloth(context, camera, cloth.state, cloth.triangle, {
+        view: 'shaded',
+        colour_of_particle: null,
+        grabbed: -1
+    });
+
+    draw_field();
+
+    refresh_readout();
+
+    requestAnimationFrame(frame);
+}
+
+// ---------------------------------------------------------------- controls
+
+const fabric_select = element('fabric');
+
+for (const name of Object.keys(CLOTH_DYNAMICS_BY_NAME)) {
+    const option = document.createElement('option');
+
+    option.value = name;
+    option.textContent = name.toLowerCase();
+
+    fabric_select.append(option);
+}
+
+fabric_select.value = control.fabric;
+
+fabric_select.addEventListener('change', () => {
+    control.fabric = fabric_select.value;
+    control.drag = CLOTH_DYNAMICS_BY_NAME[control.fabric].drag;
+
+    refresh_inputs();
+    rebuild();
+});
+
+/**
+ * @param {string} id
+ * @param {string} key
+ * @param {function(number): string} format
+ * @param {boolean} [rebuilds]
+ */
+function slider(id, key, format, rebuilds = false) {
+    const input = element(id);
+    const output = element(`${id}_out`);
+
+    input.value = String(control[key]);
+    output.textContent = format(control[key]);
+
+    input.addEventListener('input', () => {
+        control[key] = Number(input.value);
+
+        output.textContent = format(control[key]);
+
+        if (rebuilds) {
+            rebuild();
+        } else if (key === 'yaw') {
+            refresh_post();
+        }
+    });
+
+    return { input, output, format };
+}
+
+const SLIDERS = [
+    slider('size', 'size', v => `${v}²`, true),
+    slider('spacing', 'spacing', v => `${(v * 100).toFixed(1)} cm`, true),
+    slider('drag', 'drag', v => v.toFixed(2)),
+    slider('substeps', 'substeps', v => String(v)),
+    slider('iterations', 'iterations', v => String(v)),
+    slider('speed', 'speed', v => `${v.toFixed(1)} m/s`),
+    slider('yaw', 'yaw', v => `${v}°`),
+    slider('gust', 'gust', v => `${v.toFixed(1)} m/s`),
+    slider('resolution', 'resolution', v => `${v}³-ish`, true)
+];
+
+function refresh_inputs() {
+    for (const entry of SLIDERS) {
+        const key = entry.input.id;
+
+        entry.input.value = String(control[key]);
+        entry.output.textContent = entry.format(control[key]);
+    }
+}
+
+const source_select = element('source');
+
+source_select.value = control.source;
+
+source_select.addEventListener('change', () => {
+    control.source = source_select.value;
+});
+
+const post_button = element('post');
+
+post_button.classList.toggle('on', control.post);
+
+post_button.addEventListener('click', () => {
+    control.post = !control.post;
+
+    post_button.classList.toggle('on', control.post);
+
+    refresh_post();
+});
+
+const field_button = element('show_field');
+
+field_button.classList.toggle('on', control.show_field);
+
+field_button.addEventListener('click', () => {
+    control.show_field = !control.show_field;
+
+    field_button.classList.toggle('on', control.show_field);
+});
+
+element('pause').addEventListener('click', (event) => {
+    control.running = !control.running;
+
+    event.currentTarget.textContent = control.running ? 'pause' : 'resume';
+});
+
+element('single').addEventListener('click', step_once);
+element('reset').addEventListener('click', rebuild);
+
+// ------------------------------------------------------------------ camera
+
+let drag = null;
+
+canvas.addEventListener('pointerdown', (event) => {
+    canvas.setPointerCapture(event.pointerId);
+    canvas.classList.add('grabbing');
+
+    drag = {
+        x: event.clientX,
+        y: event.clientY,
+        pan: event.shiftKey || event.button === 2
+    };
+});
+
+canvas.addEventListener('pointermove', (event) => {
+    if (drag === null) {
+        return;
+    }
+
+    const dx = event.clientX - drag.x;
+    const dy = event.clientY - drag.y;
+
+    drag.x = event.clientX;
+    drag.y = event.clientY;
+
+    if (!drag.pan) {
+        camera.yaw -= dx * 0.006;
+        camera.pitch = Math.max(-1.4, Math.min(1.4, camera.pitch + dy * 0.006));
+
+        return;
+    }
+
+    const scale = camera.distance * 0.0016;
+
+    camera.target[0] -= dx * Math.cos(camera.yaw) * scale;
+    camera.target[2] += dx * Math.sin(camera.yaw) * scale;
+    camera.target[1] += dy * scale;
+});
+
+function release(event) {
+    drag = null;
+
+    canvas.classList.remove('grabbing');
+
+    if (event !== undefined && canvas.hasPointerCapture(event.pointerId)) {
+        canvas.releasePointerCapture(event.pointerId);
+    }
+}
+
+canvas.addEventListener('pointerup', release);
+canvas.addEventListener('pointercancel', release);
+canvas.addEventListener('contextmenu', (event) => event.preventDefault());
+
+canvas.addEventListener('wheel', (event) => {
+    event.preventDefault();
+
+    camera.distance = Math.max(0.2, Math.min(30, camera.distance * Math.exp(event.deltaY * 0.0012)));
+}, { passive: false });
+
+// ------------------------------------------------------------------- start
+
+function resize() {
+    const ratio = Math.min(2, window.devicePixelRatio || 1);
+
+    canvas.width = Math.round(canvas.clientWidth * ratio);
+    canvas.height = Math.round(canvas.clientHeight * ratio);
+}
+
+window.addEventListener('resize', resize);
+
+resize();
+rebuild();
+
+requestAnimationFrame(frame);
+
+// A handle for a driver script — `requestAnimationFrame` does not fire while the
+// pane is hidden, so a driver steps the page itself.
+globalThis.cloth_wind_playground = {
+    control,
+    camera,
+    rebuild,
+    step_once,
+    refresh_post,
+    get cloth() { return cloth; },
+    get tunnel() { return tunnel; },
+    get wind() { return wind; },
+    get air_centre() { return air_centre; },
+    get sampled_per_particle() { return sampled_per_particle; },
+    get mean_drag() { return mean_drag; },
+    get tripwire() { return tripwire; },
+    timings: {
+        get cloth() { return mean(cloth_timings); },
+        get fluid() { return mean(fluid_timings); },
+        get sample() { return mean(sample_timings); }
+    }
+};