@woosh/meep-engine 3.21.0 → 3.22.0

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

@@ -0,0 +1,519 @@
+/**
+ * # Drawing the cloth, on a 2D canvas
+ *
+ * M0 is a solver and nothing else — it has no renderer, no ECS and no
+ * `Transform64`, and it will not have them until M1 and M3. So this page draws
+ * the particle positions itself, with an orbit camera and a painter's-algorithm
+ * pass over a `CanvasRenderingContext2D`. That is enough to see a drape, and it
+ * keeps the page honest about what it is exercising: everything on screen came
+ * out of `ClothState#position` and nothing else.
+ *
+ * Three views, because they answer different questions. **Shaded** shows the
+ * drape and, through a different tint on back faces, shows folds. **Wireframe**
+ * shows the stretch rows, which is where over-stretch is visible as a stretched
+ * quad rather than as a number. **Colours** paints each particle by its graph
+ * colour, which is the one M0 artefact that has no other way of being looked at.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Vertical field of view, radians.
+ * @type {number}
+ */
+const FIELD_OF_VIEW = 0.9;
+
+/**
+ * Nothing closer than this to the eye is drawn — it is behind the viewer or
+ * about to divide by zero.
+ * @type {number}
+ */
+const NEAR = 0.02;
+
+/**
+ * Distinct hues for the graph colouring. A garment runs to eight or ten
+ * colours (§5.4), so ten is enough to never wrap on anything this page builds.
+ * @type {string[]}
+ */
+const COLOUR_WHEEL = [
+    '#e5533d', '#e5a13d', '#c8e53d', '#5ae53d', '#3de58c',
+    '#3de5d8', '#3d9ae5', '#5a3de5', '#c83de5', '#e53d8c'
+];
+
+export class PlaygroundCamera {
+    /** @type {number} radians, about the world Y axis */
+    yaw = 0.5;
+
+    /** @type {number} radians, positive tips the eye upwards */
+    pitch = 0.25;
+
+    /** @type {number} metres from the target */
+    distance = 1.2;
+
+    /** @type {Float64Array} what the camera looks at, world space */
+    target = new Float64Array(3);
+}
+
+/**
+ * Project a world point to canvas pixels.
+ *
+ * Writes `(x, y)` to `out[0..1]` and returns the eye-space depth — positive in
+ * front of the camera, and the value {@link unproject} needs to put the point
+ * back where it came from.
+ *
+ * @param {Float64Array} out
+ * @param {PlaygroundCamera} camera
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} width canvas width, pixels
+ * @param {number} height canvas height, pixels
+ * @returns {number} eye-space depth
+ */
+export function project(out, camera, x, y, z, width, height) {
+    const dx = x - camera.target[0];
+    const dy = y - camera.target[1];
+    const dz = z - camera.target[2];
+
+    const cos_yaw = Math.cos(camera.yaw);
+    const sin_yaw = Math.sin(camera.yaw);
+
+    const rx = dx * cos_yaw - dz * sin_yaw;
+    const rz = dx * sin_yaw + dz * cos_yaw;
+
+    const cos_pitch = Math.cos(camera.pitch);
+    const sin_pitch = Math.sin(camera.pitch);
+
+    const ry = dy * cos_pitch - rz * sin_pitch;
+    const rz_pitched = dy * sin_pitch + rz * cos_pitch;
+
+    const depth = rz_pitched + camera.distance;
+
+    const focal = 0.5 * height / Math.tan(FIELD_OF_VIEW * 0.5);
+
+    out[0] = width * 0.5 + focal * rx / depth;
+    out[1] = height * 0.5 - focal * ry / depth;
+
+    return depth;
+}
+
+/**
+ * The inverse of {@link project} at a known depth — which is what dragging a
+ * particle needs: the cursor moves it in the plane through its own depth,
+ * perpendicular to the view axis, so it tracks the mouse without sliding
+ * towards or away from the eye.
+ *
+ * @param {Float64Array} out world position
+ * @param {PlaygroundCamera} camera
+ * @param {number} screen_x
+ * @param {number} screen_y
+ * @param {number} depth from {@link project}
+ * @param {number} width
+ * @param {number} height
+ */
+export function unproject(out, camera, screen_x, screen_y, depth, width, height) {
+    const focal = 0.5 * height / Math.tan(FIELD_OF_VIEW * 0.5);
+
+    const rx = (screen_x - width * 0.5) * depth / focal;
+    const ry = -(screen_y - height * 0.5) * depth / focal;
+
+    const rz_pitched = depth - camera.distance;
+
+    const cos_pitch = Math.cos(camera.pitch);
+    const sin_pitch = Math.sin(camera.pitch);
+
+    const dy = ry * cos_pitch + rz_pitched * sin_pitch;
+    const rz = -ry * sin_pitch + rz_pitched * cos_pitch;
+
+    const cos_yaw = Math.cos(camera.yaw);
+    const sin_yaw = Math.sin(camera.yaw);
+
+    out[0] = (rx * cos_yaw + rz * sin_yaw) + camera.target[0];
+    out[1] = dy + camera.target[1];
+    out[2] = (-rx * sin_yaw + rz * cos_yaw) + camera.target[2];
+}
+
+/**
+ * The particle nearest a screen position, or `-1` if none is within `radius`
+ * pixels of it. Ties break towards the camera, so a click on a fold picks the
+ * side facing the viewer.
+ *
+ * @param {ClothState} state
+ * @param {PlaygroundCamera} camera
+ * @param {number} screen_x
+ * @param {number} screen_y
+ * @param {number} width
+ * @param {number} height
+ * @param {number} radius pixels
+ * @returns {number}
+ */
+export function pick_particle(state, camera, screen_x, screen_y, width, height, radius) {
+    const position = state.position;
+
+    const projected = new Float64Array(2);
+
+    let best = -1;
+    let best_depth = Infinity;
+
+    const radius_squared = radius * radius;
+
+    for (let i = 0; i < state.particle_count; i++) {
+        const depth = project(projected, camera, position[i * 3], position[i * 3 + 1], position[i * 3 + 2], width, height);
+
+        if (depth <= NEAR) {
+            continue;
+        }
+
+        const dx = projected[0] - screen_x;
+        const dy = projected[1] - screen_y;
+
+        if (dx * dx + dy * dy > radius_squared) {
+            continue;
+        }
+
+        if (depth < best_depth) {
+            best = i;
+            best_depth = depth;
+        }
+    }
+
+    return best;
+}
+
+/**
+ * Scratch, reused across frames. A draw allocates nothing per particle.
+ * @type {{screen: Float32Array, depth: Float32Array, order: Int32Array, key: Float32Array}}
+ * @private
+ */
+let scratch = null;
+
+/**
+ * @param {number} particle_count
+ * @param {number} face_count
+ * @private
+ */
+function ensure_scratch(particle_count, face_count) {
+    if (scratch !== null
+        && scratch.screen.length >= particle_count * 2
+        && scratch.order.length >= face_count) {
+        return scratch;
+    }
+
+    scratch = {
+        screen: new Float32Array(Math.max(particle_count, 1) * 2),
+        depth: new Float32Array(Math.max(particle_count, 1)),
+        order: new Int32Array(Math.max(face_count, 1)),
+        key: new Float32Array(Math.max(face_count, 1))
+    };
+
+    return scratch;
+}
+
+/**
+ * @param {CanvasRenderingContext2D} context
+ * @param {PlaygroundCamera} camera
+ * @param {ClothState} state
+ * @param {Int32Array} triangle
+ * @param {object} options
+ * @param {'shaded'|'wire'|'colours'} options.view
+ * @param {Uint32Array|null} options.colour_of_particle
+ * @param {number} options.grabbed particle held by the cursor, or -1
+ */
+export function draw_cloth(context, camera, state, triangle, { view, colour_of_particle, grabbed }) {
+    const width = context.canvas.width;
+    const height = context.canvas.height;
+
+    context.clearRect(0, 0, width, height);
+
+    const particle_count = state.particle_count;
+    const face_count = triangle.length / 3;
+
+    const { screen, depth, order, key } = ensure_scratch(particle_count, face_count);
+
+    const position = state.position;
+
+    const projected = new Float64Array(2);
+
+    for (let i = 0; i < particle_count; i++) {
+        depth[i] = project(
+            projected, camera,
+            position[i * 3], position[i * 3 + 1], position[i * 3 + 2],
+            width, height
+        );
+
+        screen[i * 2] = projected[0];
+        screen[i * 2 + 1] = projected[1];
+    }
+
+    draw_ground(context, camera, state, width, height);
+
+    if (view === 'shaded' && face_count > 0) {
+        draw_faces(context, state, triangle, screen, depth, order, key, face_count);
+    } else {
+        draw_rows(context, state, screen, depth, view === 'colours' ? 0.25 : 1);
+    }
+
+    if (view === 'colours') {
+        draw_particles_by_colour(context, state, screen, depth, colour_of_particle);
+    } else {
+        draw_pinned(context, state, screen, depth);
+    }
+
+    if (grabbed >= 0 && grabbed < particle_count && depth[grabbed] > NEAR) {
+        context.beginPath();
+        context.arc(screen[grabbed * 2], screen[grabbed * 2 + 1], 7, 0, Math.PI * 2);
+        context.strokeStyle = '#ffffff';
+        context.lineWidth = 2;
+        context.stroke();
+    }
+}
+
+/**
+ * A faint grid on the y = 0 plane. It is the only fixed thing on screen, and
+ * without it an orbiting camera around a symmetrical sheet gives no sense of
+ * which way is down.
+ *
+ * @private
+ */
+function draw_ground(context, camera, state, width, height) {
+    const extent = Math.max(0.4, camera.distance);
+    const step = extent / 5;
+
+    const a = new Float64Array(2);
+    const b = new Float64Array(2);
+
+    context.strokeStyle = 'rgba(120, 132, 150, 0.16)';
+    context.lineWidth = 1;
+
+    const centre_x = camera.target[0];
+    const centre_z = camera.target[2];
+
+    for (let i = -5; i <= 5; i++) {
+        const offset = i * step;
+
+        const depth_a = project(a, camera, centre_x + offset, 0, centre_z - extent, width, height);
+        const depth_b = project(b, camera, centre_x + offset, 0, centre_z + extent, width, height);
+
+        if (depth_a > NEAR && depth_b > NEAR) {
+            context.beginPath();
+            context.moveTo(a[0], a[1]);
+            context.lineTo(b[0], b[1]);
+            context.stroke();
+        }
+
+        const depth_c = project(a, camera, centre_x - extent, 0, centre_z + offset, width, height);
+        const depth_d = project(b, camera, centre_x + extent, 0, centre_z + offset, width, height);
+
+        if (depth_c > NEAR && depth_d > NEAR) {
+            context.beginPath();
+            context.moveTo(a[0], a[1]);
+            context.lineTo(b[0], b[1]);
+            context.stroke();
+        }
+    }
+}
+
+/**
+ * Filled triangles, far ones first. There is no depth buffer on a 2D canvas, so
+ * the order *is* the visibility, and sorting by the average of the three
+ * vertices' depths is the whole of it — good enough for a surface that does not
+ * intersect itself, which is the only kind M0 can produce (self-collision is
+ * M4).
+ *
+ * @private
+ */
+function draw_faces(context, state, triangle, screen, depth, order, key, face_count) {
+    const position = state.position;
+
+    let visible = 0;
+
+    for (let face = 0; face < face_count; face++) {
+        const a = triangle[face * 3];
+        const b = triangle[face * 3 + 1];
+        const c = triangle[face * 3 + 2];
+
+        const mean = (depth[a] + depth[b] + depth[c]) / 3;
+
+        if (mean <= NEAR) {
+            continue;
+        }
+
+        order[visible] = face;
+        key[face] = mean;
+
+        visible++;
+    }
+
+    const list = order.subarray(0, visible);
+
+    // Painter's algorithm: farthest first.
+    Array.prototype.sort.call(list, (x, y) => key[y] - key[x]);
+
+    context.lineWidth = 1;
+
+    for (let i = 0; i < visible; i++) {
+        const face = list[i];
+
+        const a = triangle[face * 3];
+        const b = triangle[face * 3 + 1];
+        const c = triangle[face * 3 + 2];
+
+        const ax = screen[a * 2], ay = screen[a * 2 + 1];
+        const bx = screen[b * 2], by = screen[b * 2 + 1];
+        const cx = screen[c * 2], cy = screen[c * 2 + 1];
+
+        // Screen-space winding tells us which side we are looking at without a
+        // world-space normal comparison.
+        const facing = (bx - ax) * (cy - ay) - (by - ay) * (cx - ax);
+
+        const shade = lambert(position, a, b, c);
+
+        const level = Math.round(40 + shade * 150);
+
+        context.fillStyle = facing < 0
+            ? `rgb(${level}, ${Math.round(level * 0.86)}, ${Math.round(level * 0.62)})`
+            : `rgb(${Math.round(level * 0.52)}, ${Math.round(level * 0.66)}, ${level})`;
+
+        context.beginPath();
+        context.moveTo(ax, ay);
+        context.lineTo(bx, by);
+        context.lineTo(cx, cy);
+        context.closePath();
+        context.fill();
+
+        // A hairline of the fill colour over the seam: canvas anti-aliases every
+        // edge, and without it a filled mesh shows the background through every
+        // shared edge as a lattice of pale cracks.
+        context.strokeStyle = context.fillStyle;
+        context.stroke();
+    }
+}
+
+/**
+ * @private
+ */
+function lambert(position, a, b, c) {
+    const ax = position[b * 3] - position[a * 3];
+    const ay = position[b * 3 + 1] - position[a * 3 + 1];
+    const az = position[b * 3 + 2] - position[a * 3 + 2];
+
+    const bx = position[c * 3] - position[a * 3];
+    const by = position[c * 3 + 1] - position[a * 3 + 1];
+    const bz = position[c * 3 + 2] - position[a * 3 + 2];
+
+    const nx = ay * bz - az * by;
+    const ny = az * bx - ax * bz;
+    const nz = ax * by - ay * bx;
+
+    const length = Math.hypot(nx, ny, nz);
+
+    if (length === 0) {
+        return 0.5;
+    }
+
+    // A fixed light over the viewer's shoulder, and a wrap term so a face
+    // turned away is dim rather than black.
+    const cosine = (nx * 0.35 + ny * 0.78 + nz * 0.52) / length;
+
+    return 0.35 + 0.65 * Math.abs(cosine);
+}
+
+/**
+ * The stretch rows, tinted by how far each is from its rest length: taut rows
+ * warm, compressed rows cool. On a cloth that is over-stretching this reads
+ * before any number does.
+ *
+ * @private
+ */
+function draw_rows(context, state, screen, depth, alpha) {
+    const count = state.stretch_count;
+
+    const particle = state.stretch_particle;
+    const rest = state.stretch_rest;
+    const position = state.position;
+
+    context.lineWidth = 1;
+
+    for (let row = 0; row < count; row++) {
+        const a = particle[row * 2];
+        const b = particle[row * 2 + 1];
+
+        if (depth[a] <= NEAR || depth[b] <= NEAR) {
+            continue;
+        }
+
+        const length = Math.hypot(
+            position[a * 3] - position[b * 3],
+            position[a * 3 + 1] - position[b * 3 + 1],
+            position[a * 3 + 2] - position[b * 3 + 2]
+        );
+
+        const reference = rest[row];
+
+        // ±20% maps to the ends of the ramp; beyond that it saturates.
+        const strain = reference > 0
+            ? Math.max(-1, Math.min(1, (length - reference) / (reference * 0.2)))
+            : 0;
+
+        const red = Math.round(130 + 110 * Math.max(0, strain));
+        const green = Math.round(140 - 60 * Math.abs(strain));
+        const blue = Math.round(150 + 90 * Math.max(0, -strain));
+
+        context.strokeStyle = `rgba(${red}, ${green}, ${blue}, ${alpha})`;
+
+        context.beginPath();
+        context.moveTo(screen[a * 2], screen[a * 2 + 1]);
+        context.lineTo(screen[b * 2], screen[b * 2 + 1]);
+        context.stroke();
+    }
+}
+
+/**
+ * @private
+ */
+function draw_particles_by_colour(context, state, screen, depth, colour_of_particle) {
+    if (colour_of_particle === null) {
+        return;
+    }
+
+    for (let i = 0; i < state.particle_count; i++) {
+        if (depth[i] <= NEAR) {
+            continue;
+        }
+
+        context.fillStyle = COLOUR_WHEEL[colour_of_particle[i] % COLOUR_WHEEL.length];
+
+        context.beginPath();
+        context.arc(screen[i * 2], screen[i * 2 + 1], 3, 0, Math.PI * 2);
+        context.fill();
+    }
+}
+
+/**
+ * Pinned particles, so it is obvious what is holding the cloth up.
+ *
+ * @private
+ */
+function draw_pinned(context, state, screen, depth) {
+    context.fillStyle = '#e5b54a';
+
+    for (let i = 0; i < state.particle_count; i++) {
+        if (state.mass_inverse[i] !== 0 || depth[i] <= NEAR) {
+            continue;
+        }
+
+        context.beginPath();
+        context.arc(screen[i * 2], screen[i * 2 + 1], 2.5, 0, Math.PI * 2);
+        context.fill();
+    }
+}
+
+/**
+ * The hues {@link draw_cloth} paints graph colours with, so the legend can
+ * match them.
+ * @returns {string[]}
+ */
+export function colour_wheel() {
+    return COLOUR_WHEEL;
+}