@buley/hexgrid-3d 3.1.0 → 3.2.0

package/dist/algorithms/FluidSimulation3D.js

@@ -0,0 +1,464 @@
+/**
+ * 3D Stable Fluids Implementation
+ *
+ * Based on Jos Stam's "Stable Fluids" paper (SIGGRAPH 1999)
+ * Extended to 3D for the Pensieve particle visualization.
+ *
+ * Key operations:
+ * 1. Add sources (density, velocity)
+ * 2. Diffuse (spread quantities)
+ * 3. Advect (move quantities along velocity field)
+ * 4. Project (make velocity field divergence-free)
+ */
+import { Vector3 } from '../math/Vector3';
+/**
+ * 3D Stable Fluids solver for realistic fluid dynamics
+ */
+export class StableFluids3D {
+    constructor(config) {
+        this.width = Math.max(1, Math.round(config.width));
+        this.height = Math.max(1, Math.round(config.height));
+        this.depth = Math.max(1, Math.round(config.depth));
+        this.size = this.width * this.height * this.depth;
+        this.viscosity = config.viscosity;
+        this.diffusion = config.diffusion;
+        this.iterations = config.iterations ?? 4;
+        // Allocate arrays
+        this.density = new Float32Array(this.size);
+        this.velocityX = new Float32Array(this.size);
+        this.velocityY = new Float32Array(this.size);
+        this.velocityZ = new Float32Array(this.size);
+        this.density0 = new Float32Array(this.size);
+        this.velocityX0 = new Float32Array(this.size);
+        this.velocityY0 = new Float32Array(this.size);
+        this.velocityZ0 = new Float32Array(this.size);
+    }
+    /**
+     * Add density at a point with radius falloff
+     */
+    addDensity(x, y, z, amount, radius) {
+        const r2 = radius * radius;
+        const ix0 = Math.max(0, Math.floor(x - radius));
+        const ix1 = Math.min(this.width - 1, Math.ceil(x + radius));
+        const iy0 = Math.max(0, Math.floor(y - radius));
+        const iy1 = Math.min(this.height - 1, Math.ceil(y + radius));
+        const iz0 = Math.max(0, Math.floor(z - radius));
+        const iz1 = Math.min(this.depth - 1, Math.ceil(z + radius));
+        for (let iz = iz0; iz <= iz1; iz++) {
+            for (let iy = iy0; iy <= iy1; iy++) {
+                for (let ix = ix0; ix <= ix1; ix++) {
+                    const dx = ix - x;
+                    const dy = iy - y;
+                    const dz = iz - z;
+                    const dist2 = dx * dx + dy * dy + dz * dz;
+                    if (dist2 < r2) {
+                        const falloff = 1 - dist2 / r2;
+                        const idx = this.indexFor(ix, iy, iz);
+                        this.density[idx] += amount * falloff;
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Add force at a point with radius falloff
+     */
+    addForce(pos, force, radius) {
+        const r2 = radius * radius;
+        const ix0 = Math.max(0, Math.floor(pos.x - radius));
+        const ix1 = Math.min(this.width - 1, Math.ceil(pos.x + radius));
+        const iy0 = Math.max(0, Math.floor(pos.y - radius));
+        const iy1 = Math.min(this.height - 1, Math.ceil(pos.y + radius));
+        const iz0 = Math.max(0, Math.floor(pos.z - radius));
+        const iz1 = Math.min(this.depth - 1, Math.ceil(pos.z + radius));
+        for (let iz = iz0; iz <= iz1; iz++) {
+            for (let iy = iy0; iy <= iy1; iy++) {
+                for (let ix = ix0; ix <= ix1; ix++) {
+                    const dx = ix - pos.x;
+                    const dy = iy - pos.y;
+                    const dz = iz - pos.z;
+                    const dist2 = dx * dx + dy * dy + dz * dz;
+                    if (dist2 < r2) {
+                        const falloff = 1 - dist2 / r2;
+                        const idx = this.indexFor(ix, iy, iz);
+                        this.velocityX[idx] += force.x * falloff;
+                        this.velocityY[idx] += force.y * falloff;
+                        this.velocityZ[idx] += force.z * falloff;
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Step the simulation forward by dt seconds
+     */
+    step(dt) {
+        // Velocity step
+        this.velocityStep(dt);
+        // Density step
+        this.densityStep(dt);
+    }
+    /**
+     * Get velocity at a point (with trilinear interpolation)
+     */
+    getVelocityAt(pos) {
+        return new Vector3(this.sampleField(this.velocityX, pos.x, pos.y, pos.z), this.sampleField(this.velocityY, pos.x, pos.y, pos.z), this.sampleField(this.velocityZ, pos.x, pos.y, pos.z));
+    }
+    /**
+     * Get density at a point (with trilinear interpolation)
+     */
+    getDensityAt(pos) {
+        return this.sampleField(this.density, pos.x, pos.y, pos.z);
+    }
+    /**
+     * Get the raw velocity fields for direct access
+     */
+    getVelocityFields() {
+        return { x: this.velocityX, y: this.velocityY, z: this.velocityZ };
+    }
+    /**
+     * Get the raw density field
+     */
+    getDensityField() {
+        return this.density;
+    }
+    /**
+     * Get grid dimensions
+     */
+    getDimensions() {
+        return { width: this.width, height: this.height, depth: this.depth };
+    }
+    /**
+     * Clear all fields
+     */
+    clear() {
+        this.density.fill(0);
+        this.velocityX.fill(0);
+        this.velocityY.fill(0);
+        this.velocityZ.fill(0);
+    }
+    // =========================================================================
+    // PRIVATE METHODS
+    // =========================================================================
+    velocityStep(dt) {
+        // Add sources
+        this.addSource(this.velocityX, this.velocityX0, dt);
+        this.addSource(this.velocityY, this.velocityY0, dt);
+        this.addSource(this.velocityZ, this.velocityZ0, dt);
+        // Diffuse
+        this.swap(this.velocityX0, this.velocityX);
+        this.swap(this.velocityY0, this.velocityY);
+        this.swap(this.velocityZ0, this.velocityZ);
+        this.diffuse(1, this.velocityX, this.velocityX0, this.viscosity, dt);
+        this.diffuse(2, this.velocityY, this.velocityY0, this.viscosity, dt);
+        this.diffuse(3, this.velocityZ, this.velocityZ0, this.viscosity, dt);
+        // Project to make divergence-free
+        this.project(this.velocityX, this.velocityY, this.velocityZ, this.velocityX0, this.velocityY0);
+        // Advect
+        this.swap(this.velocityX0, this.velocityX);
+        this.swap(this.velocityY0, this.velocityY);
+        this.swap(this.velocityZ0, this.velocityZ);
+        this.advect(1, this.velocityX, this.velocityX0, this.velocityX0, this.velocityY0, this.velocityZ0, dt);
+        this.advect(2, this.velocityY, this.velocityY0, this.velocityX0, this.velocityY0, this.velocityZ0, dt);
+        this.advect(3, this.velocityZ, this.velocityZ0, this.velocityX0, this.velocityY0, this.velocityZ0, dt);
+        // Project again
+        this.project(this.velocityX, this.velocityY, this.velocityZ, this.velocityX0, this.velocityY0);
+    }
+    densityStep(dt) {
+        // Add sources
+        this.addSource(this.density, this.density0, dt);
+        // Diffuse
+        this.swap(this.density0, this.density);
+        this.diffuse(0, this.density, this.density0, this.diffusion, dt);
+        // Advect
+        this.swap(this.density0, this.density);
+        this.advect(0, this.density, this.density0, this.velocityX, this.velocityY, this.velocityZ, dt);
+    }
+    addSource(target, source, dt) {
+        for (let i = 0; i < this.size; i++) {
+            target[i] += dt * source[i];
+        }
+        source.fill(0);
+    }
+    diffuse(b, x, x0, diff, dt) {
+        const a = dt * diff * this.width * this.height * this.depth;
+        this.linearSolve(b, x, x0, a, 1 + 6 * a);
+    }
+    advect(b, d, d0, u, v, w, dt) {
+        const dtx = dt * (this.width - 2);
+        const dty = dt * (this.height - 2);
+        const dtz = dt * (this.depth - 2);
+        for (let k = 1; k < this.depth - 1; k++) {
+            for (let j = 1; j < this.height - 1; j++) {
+                for (let i = 1; i < this.width - 1; i++) {
+                    const idx = this.indexFor(i, j, k);
+                    // Trace back
+                    let x = i - dtx * u[idx];
+                    let y = j - dty * v[idx];
+                    let z = k - dtz * w[idx];
+                    // Clamp to grid
+                    x = Math.max(0.5, Math.min(this.width - 1.5, x));
+                    y = Math.max(0.5, Math.min(this.height - 1.5, y));
+                    z = Math.max(0.5, Math.min(this.depth - 1.5, z));
+                    // Trilinear interpolation
+                    d[idx] = this.sampleField(d0, x, y, z);
+                }
+            }
+        }
+        this.setBoundary(b, d);
+    }
+    project(u, v, w, p, div) {
+        const h = 1.0 / Math.max(this.width, this.height, this.depth);
+        // Calculate divergence
+        for (let k = 1; k < this.depth - 1; k++) {
+            for (let j = 1; j < this.height - 1; j++) {
+                for (let i = 1; i < this.width - 1; i++) {
+                    const idx = this.indexFor(i, j, k);
+                    div[idx] =
+                        -0.5 *
+                            h *
+                            (u[this.indexFor(i + 1, j, k)] -
+                                u[this.indexFor(i - 1, j, k)] +
+                                v[this.indexFor(i, j + 1, k)] -
+                                v[this.indexFor(i, j - 1, k)] +
+                                w[this.indexFor(i, j, k + 1)] -
+                                w[this.indexFor(i, j, k - 1)]);
+                    p[idx] = 0;
+                }
+            }
+        }
+        this.setBoundary(0, div);
+        this.setBoundary(0, p);
+        // Solve for pressure
+        this.linearSolve(0, p, div, 1, 6);
+        // Subtract pressure gradient from velocity
+        for (let k = 1; k < this.depth - 1; k++) {
+            for (let j = 1; j < this.height - 1; j++) {
+                for (let i = 1; i < this.width - 1; i++) {
+                    const idx = this.indexFor(i, j, k);
+                    u[idx] -=
+                        (0.5 *
+                            (p[this.indexFor(i + 1, j, k)] - p[this.indexFor(i - 1, j, k)])) /
+                            h;
+                    v[idx] -=
+                        (0.5 *
+                            (p[this.indexFor(i, j + 1, k)] - p[this.indexFor(i, j - 1, k)])) /
+                            h;
+                    w[idx] -=
+                        (0.5 *
+                            (p[this.indexFor(i, j, k + 1)] - p[this.indexFor(i, j, k - 1)])) /
+                            h;
+                }
+            }
+        }
+        this.setBoundary(1, u);
+        this.setBoundary(2, v);
+        this.setBoundary(3, w);
+    }
+    linearSolve(b, x, x0, a, c) {
+        const cRecip = 1.0 / c;
+        for (let iter = 0; iter < this.iterations; iter++) {
+            for (let k = 1; k < this.depth - 1; k++) {
+                for (let j = 1; j < this.height - 1; j++) {
+                    for (let i = 1; i < this.width - 1; i++) {
+                        const idx = this.indexFor(i, j, k);
+                        x[idx] =
+                            (x0[idx] +
+                                a *
+                                    (x[this.indexFor(i + 1, j, k)] +
+                                        x[this.indexFor(i - 1, j, k)] +
+                                        x[this.indexFor(i, j + 1, k)] +
+                                        x[this.indexFor(i, j - 1, k)] +
+                                        x[this.indexFor(i, j, k + 1)] +
+                                        x[this.indexFor(i, j, k - 1)])) *
+                                cRecip;
+                    }
+                }
+            }
+            this.setBoundary(b, x);
+        }
+    }
+    setBoundary(b, x) {
+        // Set boundary conditions (reflective for velocity, continuous for density)
+        for (let k = 1; k < this.depth - 1; k++) {
+            for (let j = 1; j < this.height - 1; j++) {
+                x[this.indexFor(0, j, k)] =
+                    b === 1 ? -x[this.indexFor(1, j, k)] : x[this.indexFor(1, j, k)];
+                x[this.indexFor(this.width - 1, j, k)] =
+                    b === 1
+                        ? -x[this.indexFor(this.width - 2, j, k)]
+                        : x[this.indexFor(this.width - 2, j, k)];
+            }
+        }
+        for (let k = 1; k < this.depth - 1; k++) {
+            for (let i = 1; i < this.width - 1; i++) {
+                x[this.indexFor(i, 0, k)] =
+                    b === 2 ? -x[this.indexFor(i, 1, k)] : x[this.indexFor(i, 1, k)];
+                x[this.indexFor(i, this.height - 1, k)] =
+                    b === 2
+                        ? -x[this.indexFor(i, this.height - 2, k)]
+                        : x[this.indexFor(i, this.height - 2, k)];
+            }
+        }
+        for (let j = 1; j < this.height - 1; j++) {
+            for (let i = 1; i < this.width - 1; i++) {
+                x[this.indexFor(i, j, 0)] =
+                    b === 3 ? -x[this.indexFor(i, j, 1)] : x[this.indexFor(i, j, 1)];
+                x[this.indexFor(i, j, this.depth - 1)] =
+                    b === 3
+                        ? -x[this.indexFor(i, j, this.depth - 2)]
+                        : x[this.indexFor(i, j, this.depth - 2)];
+            }
+        }
+        // Corner cases - average of neighbors
+        x[this.indexFor(0, 0, 0)] =
+            0.33 *
+                (x[this.indexFor(1, 0, 0)] +
+                    x[this.indexFor(0, 1, 0)] +
+                    x[this.indexFor(0, 0, 1)]);
+        x[this.indexFor(0, this.height - 1, 0)] =
+            0.33 *
+                (x[this.indexFor(1, this.height - 1, 0)] +
+                    x[this.indexFor(0, this.height - 2, 0)] +
+                    x[this.indexFor(0, this.height - 1, 1)]);
+        x[this.indexFor(0, 0, this.depth - 1)] =
+            0.33 *
+                (x[this.indexFor(1, 0, this.depth - 1)] +
+                    x[this.indexFor(0, 1, this.depth - 1)] +
+                    x[this.indexFor(0, 0, this.depth - 2)]);
+        x[this.indexFor(0, this.height - 1, this.depth - 1)] =
+            0.33 *
+                (x[this.indexFor(1, this.height - 1, this.depth - 1)] +
+                    x[this.indexFor(0, this.height - 2, this.depth - 1)] +
+                    x[this.indexFor(0, this.height - 1, this.depth - 2)]);
+        x[this.indexFor(this.width - 1, 0, 0)] =
+            0.33 *
+                (x[this.indexFor(this.width - 2, 0, 0)] +
+                    x[this.indexFor(this.width - 1, 1, 0)] +
+                    x[this.indexFor(this.width - 1, 0, 1)]);
+        x[this.indexFor(this.width - 1, this.height - 1, 0)] =
+            0.33 *
+                (x[this.indexFor(this.width - 2, this.height - 1, 0)] +
+                    x[this.indexFor(this.width - 1, this.height - 2, 0)] +
+                    x[this.indexFor(this.width - 1, this.height - 1, 1)]);
+        x[this.indexFor(this.width - 1, 0, this.depth - 1)] =
+            0.33 *
+                (x[this.indexFor(this.width - 2, 0, this.depth - 1)] +
+                    x[this.indexFor(this.width - 1, 1, this.depth - 1)] +
+                    x[this.indexFor(this.width - 1, 0, this.depth - 2)]);
+        x[this.indexFor(this.width - 1, this.height - 1, this.depth - 1)] =
+            0.33 *
+                (x[this.indexFor(this.width - 2, this.height - 1, this.depth - 1)] +
+                    x[this.indexFor(this.width - 1, this.height - 2, this.depth - 1)] +
+                    x[this.indexFor(this.width - 1, this.height - 1, this.depth - 2)]);
+    }
+    sampleField(field, x, y, z) {
+        // Trilinear interpolation
+        const i0 = Math.floor(x);
+        const i1 = i0 + 1;
+        const j0 = Math.floor(y);
+        const j1 = j0 + 1;
+        const k0 = Math.floor(z);
+        const k1 = k0 + 1;
+        const sx = x - i0;
+        const sy = y - j0;
+        const sz = z - k0;
+        const c000 = field[this.indexForClamped(i0, j0, k0)];
+        const c001 = field[this.indexForClamped(i0, j0, k1)];
+        const c010 = field[this.indexForClamped(i0, j1, k0)];
+        const c011 = field[this.indexForClamped(i0, j1, k1)];
+        const c100 = field[this.indexForClamped(i1, j0, k0)];
+        const c101 = field[this.indexForClamped(i1, j0, k1)];
+        const c110 = field[this.indexForClamped(i1, j1, k0)];
+        const c111 = field[this.indexForClamped(i1, j1, k1)];
+        // Interpolate along x
+        const c00 = c000 * (1 - sx) + c100 * sx;
+        const c01 = c001 * (1 - sx) + c101 * sx;
+        const c10 = c010 * (1 - sx) + c110 * sx;
+        const c11 = c011 * (1 - sx) + c111 * sx;
+        // Interpolate along y
+        const c0 = c00 * (1 - sy) + c10 * sy;
+        const c1 = c01 * (1 - sy) + c11 * sy;
+        // Interpolate along z
+        return c0 * (1 - sz) + c1 * sz;
+    }
+    indexFor(x, y, z) {
+        return z * this.width * this.height + y * this.width + x;
+    }
+    indexForClamped(x, y, z) {
+        const ix = Math.min(this.width - 1, Math.max(0, x));
+        const iy = Math.min(this.height - 1, Math.max(0, y));
+        const iz = Math.min(this.depth - 1, Math.max(0, z));
+        return this.indexFor(ix, iy, iz);
+    }
+    swap(a, b) {
+        // Swap contents efficiently
+        const temp = new Float32Array(a);
+        a.set(b);
+        b.set(temp);
+    }
+}
+/**
+ * Pensieve-specific fluid simulator with aesthetic presets
+ */
+export class PensieveFluidSimulator {
+    constructor(size = 64) {
+        this.time = 0;
+        this.fluid = new StableFluids3D({
+            width: size,
+            height: size,
+            depth: size,
+            viscosity: 0.0001,
+            diffusion: 0.00001,
+            iterations: 4,
+        });
+    }
+    /**
+     * Add a "memory splash" - when a particle enters the pensieve
+     */
+    addMemorySplash(position, intensity) {
+        this.fluid.addDensity(position.x, position.y, position.z, intensity * 10, 5);
+        // Add a slight upward swirl
+        this.fluid.addForce(position, new Vector3(0, intensity * 2, 0), 3);
+    }
+    /**
+     * Add ambient swirling motion
+     */
+    addSwirl(dt) {
+        this.time += dt;
+        const dims = this.fluid.getDimensions();
+        const center = new Vector3(dims.width / 2, dims.height / 2, dims.depth / 2);
+        // Rotating force around Y axis
+        const angle = this.time * 0.5;
+        const radius = dims.width * 0.3;
+        const pos = new Vector3(center.x + Math.cos(angle) * radius, center.y, center.z + Math.sin(angle) * radius);
+        const tangent = new Vector3(-Math.sin(angle), 0, Math.cos(angle));
+        this.fluid.addForce(pos, tangent, radius * 0.5);
+    }
+    /**
+     * Step the simulation
+     */
+    step(dt) {
+        this.addSwirl(dt);
+        this.fluid.step(dt);
+    }
+    /**
+     * Get velocity at a point for particle advection
+     */
+    getVelocityAt(pos) {
+        return this.fluid.getVelocityAt(pos);
+    }
+    /**
+     * Get the underlying fluid for direct access
+     */
+    getFluid() {
+        return this.fluid;
+    }
+    /**
+     * Clear the simulation
+     */
+    clear() {
+        this.fluid.clear();
+        this.time = 0;
+    }
+}

package/dist/algorithms/FluidSimulation3DGPU.d.ts

@@ -0,0 +1,41 @@
+/**
+ * WebGPU Implementation of Fluid Simulation (Fallback)
+ */
+import { Vector3 } from '../math/Vector3';
+import type { FluidConfig3D } from './FluidSimulation3D';
+export declare class FluidSimulation3DGPU {
+    private width;
+    private height;
+    private depth;
+    private size;
+    private context;
+    private device;
+    private densityTextures;
+    private velocityTextures;
+    private pressureTextures;
+    private divergenceTexture;
+    private advectPipeline;
+    private diffusePipeline;
+    private divergencePipeline;
+    private subtractGradientPipeline;
+    private sampler;
+    private uniformBuffer;
+    private jacobiBuffer;
+    private viscosity;
+    private diffusion;
+    private iterations;
+    constructor(config: FluidConfig3D);
+    initialize(): Promise<boolean>;
+    step(dt: number): Promise<void>;
+    private dispatchAdvect;
+    private dispatchDiffuse;
+    private dispatchDivergence;
+    private dispatchPressure;
+    private dispatchSubtractGradient;
+    addDensity(x: number, y: number, z: number, amount: number, radius: number): void;
+    addForce(pos: Vector3, force: Vector3, radius: number): void;
+    getDensityAt(pos: Vector3): number;
+    getVelocityAt(pos: Vector3): Vector3;
+    clear(): void;
+}
+//# sourceMappingURL=FluidSimulation3DGPU.d.ts.map

package/dist/algorithms/FluidSimulation3DGPU.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FluidSimulation3DGPU.d.ts","sourceRoot":"","sources":["../../src/algorithms/FluidSimulation3DGPU.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIzD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,IAAI,CAAS;IAErB,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,MAAM,CAA0B;IAGxC,OAAO,CAAC,eAAe,CAAyC;IAChE,OAAO,CAAC,gBAAgB,CAAyC;IACjE,OAAO,CAAC,gBAAgB,CAAyC;IACjE,OAAO,CAAC,iBAAiB,CAA2B;IAGpD,OAAO,CAAC,cAAc,CAAmC;IACzD,OAAO,CAAC,eAAe,CAAmC;IAC1D,OAAO,CAAC,kBAAkB,CAAmC;IAC7D,OAAO,CAAC,wBAAwB,CAAmC;IAEnE,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,aAAa,CAA0B;IAC/C,OAAO,CAAC,YAAY,CAA0B;IAE9C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAS;gBAEf,MAAM,EAAE,aAAa;IAY3B,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAuE9B,IAAI,CAAC,EAAE,EAAE,MAAM;IAsCrB,OAAO,CAAC,cAAc;IA6BtB,OAAO,CAAC,eAAe;IAkDvB,OAAO,CAAC,kBAAkB;IAkB1B,OAAO,CAAC,gBAAgB;IAgExB,OAAO,CAAC,wBAAwB;IA2BhC,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAyB1E,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM;IAsBrD,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM;IAKlC,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO;IAIpC,KAAK;CAGN"}