@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/primitives/sdf-grid.ts

@@ -0,0 +1,131 @@
+// Samples a signed-distance field on a cubic grid for the meshers. The field is clipped to the
+// bounds box (max with the box's own distance), and the grid has a one-cell positive border, so
+// every surface comes out closed. Sparse: one coarse sample per 8³-cell block; a block whose
+// centre is farther from the surface than `lipschitz` × its half-diagonal cannot hold any of it,
+// so its points take that sign without evaluating the field (a head at 4 mm meshes in ~1 s).
+
+import type { Vec3 } from '../core/index.ts';
+import { invalid } from './check.ts';
+import type { Field } from './sdf-ops.ts';
+
+export interface Grid {
+  /** Points per axis. */
+  readonly nx: number;
+  readonly ny: number;
+  readonly nz: number;
+  /** Position of point (0, 0, 0) and the cell edge, metres. */
+  readonly origin: Vec3;
+  readonly h: number;
+  readonly values: Float32Array;
+  /** The clipped field the grid sampled (normals take its gradient). */
+  readonly field: Field;
+}
+
+/** Grid points above this are refused (≈ 80 MB of samples). */
+export const MAX_POINTS = 1 << 24;
+const BLOCK = 4;
+
+export function sampleGrid(
+  raw: Field,
+  bounds: readonly [Vec3, Vec3],
+  h: number,
+  lipschitz: number,
+  symmetricY = false,
+): Grid {
+  const [lo0, hi0] = bounds;
+  if (!Number.isFinite(h) || h <= 0)
+    invalid(
+      `sdf resolution is ${h}`,
+      'pass the cell edge in metres, e.g. ctx.pick([0.004, 0.012, 0.03])',
+    );
+  if (
+    ![0, 1, 2].every((k) => Number.isFinite(lo0[k] ?? Number.NaN) && (hi0[k] ?? 0) > (lo0[k] ?? 0))
+  )
+    invalid(
+      `sdf bounds [${lo0.join(', ')}] → [${hi0.join(', ')}] are empty or inverted`,
+      'give bounds as [min, max] corners with max > min on every axis, in metres',
+    );
+  // Mirror-symmetric shapes: bounds ±m cells in y, so y = 0 is a grid plane and every sample
+  // has its mirror twin at exactly (j − m − 1) · h — the mesh comes out symmetric.
+  const m = Math.ceil(Math.max(Math.abs(lo0[1]), Math.abs(hi0[1])) / h);
+  const lo: Vec3 = symmetricY ? [lo0[0], -m * h, lo0[2]] : lo0;
+  const hi: Vec3 = symmetricY ? [hi0[0], m * h, hi0[2]] : hi0;
+  const size = (k: number): number => Math.ceil(((hi[k] ?? 0) - (lo[k] ?? 0)) / h) + 3;
+  const [nx, ny, nz] = [size(0), symmetricY ? 2 * m + 3 : size(1), size(2)];
+  const yAt = (j: number): number => (symmetricY ? (j - m - 1) * h : lo[1] - h + j * h);
+  if (nx * ny * nz > MAX_POINTS) {
+    const vol = [0, 1, 2].reduce((v, k) => v * ((hi[k] ?? 0) - (lo[k] ?? 0)), 1);
+    invalid(
+      `sdf grid ${nx}×${ny}×${nz} exceeds ${MAX_POINTS} points at ${h} m cells`,
+      `use cells ≥ ${Math.cbrt(vol / MAX_POINTS).toPrecision(2)} m, or tighten the bounds`,
+    );
+  }
+  const cx = (lo[0] + hi[0]) / 2;
+  const cy = (lo[1] + hi[1]) / 2;
+  const cz = (lo[2] + hi[2]) / 2;
+  const [bx, by, bz] = [(hi[0] - lo[0]) / 2, (hi[1] - lo[1]) / 2, (hi[2] - lo[2]) / 2];
+  const field: Field = (p) => {
+    const qx = Math.abs(p[0] - cx) - bx;
+    const qy = Math.abs(p[1] - cy) - by;
+    const qz = Math.abs(p[2] - cz) - bz;
+    const box =
+      Math.hypot(Math.max(qx, 0), Math.max(qy, 0), Math.max(qz, 0)) +
+      Math.min(Math.max(qx, qy, qz), 0);
+    const f = raw(p);
+    if (Number.isNaN(f))
+      invalid(
+        `sdf field returned NaN at [${p.join(', ')}]`,
+        'make the field return a finite distance everywhere in bounds',
+      );
+    return Math.max(f, box);
+  };
+  const origin: Vec3 = [lo[0] - h, symmetricY ? -(m + 1) * h : lo[1] - h, lo[2] - h];
+  const values = new Float32Array(nx * ny * nz);
+  const exact = new Uint8Array(nx * ny * nz);
+  const [kx, ky, kz] = [
+    Math.ceil((nx - 1) / BLOCK),
+    Math.ceil((ny - 1) / BLOCK),
+    Math.ceil((nz - 1) / BLOCK),
+  ];
+  const coarse = new Float32Array(kx * ky * kz);
+  const p: [number, number, number] = [0, 0, 0];
+  const floor = h * 0.01;
+  const reach = lipschitz * BLOCK * h * Math.sqrt(3) * 0.5 + h;
+  for (let k = 0; k < kz; k++)
+    for (let j = 0; j < ky; j++)
+      for (let i = 0; i < kx; i++) {
+        p[0] = origin[0] + (i + 0.5) * BLOCK * h;
+        p[1] = origin[1] + (j + 0.5) * BLOCK * h;
+        p[2] = origin[2] + (k + 0.5) * BLOCK * h;
+        const v = field(p);
+        coarse[i + kx * (j + ky * k)] = v;
+        if (Math.abs(v) > reach) continue;
+        // Near the surface: every point of this block (faces included) is sampled exactly.
+        for (let z = k * BLOCK; z <= Math.min(nz - 1, (k + 1) * BLOCK); z++)
+          for (let y = j * BLOCK; y <= Math.min(ny - 1, (j + 1) * BLOCK); y++)
+            for (let x = i * BLOCK; x <= Math.min(nx - 1, (i + 1) * BLOCK); x++)
+              exact[x + nx * (y + ny * z)] = 1;
+      }
+  for (let z = 0; z < nz; z++)
+    for (let y = 0; y < ny; y++)
+      for (let x = 0; x < nx; x++) {
+        const id = x + nx * (y + ny * z);
+        if (exact[id]) {
+          p[0] = origin[0] + x * h;
+          p[1] = yAt(y);
+          p[2] = origin[2] + z * h;
+          const f = field(p);
+          // A sample (near) zero puts vertices of several cells on one grid point: marching cubes
+          // then emits slivers. Keep |value| ≥ 1% of a cell (moves the surface ≤ h / 100).
+          values[id] = Math.abs(f) >= floor ? f : f < 0 ? -floor : floor;
+        } else {
+          const b =
+            Math.min(kx - 1, Math.floor(x / BLOCK)) +
+            kx *
+              (Math.min(ky - 1, Math.floor(y / BLOCK)) +
+                ky * Math.min(kz - 1, Math.floor(z / BLOCK)));
+          values[id] = coarse[b] ?? 1;
+        }
+      }
+  return { nx, ny, nz, origin, h, values, field };
+}

package/src/primitives/sdf-ops.ts

@@ -0,0 +1,145 @@
+// Signed-distance building blocks for `sdf`: exact shape distances (Quílez's formulas), boolean
+// and smooth combinators (noise for `displace`: value-noise.ts). Negative = inside, metres.
+// A field is called once per grid sample, so shapes do scalar maths only (no Vec3 allocation);
+// fields must not keep the `p` they are given (the mesher reuses it).
+
+import type { Vec3 } from '../core/index.ts';
+
+export type Field = (p: Vec3) => number;
+
+const clamp01 = (x: number): number => (x < 0 ? 0 : Math.min(x, 1));
+
+/** Shape distances in the shape's own frame (centre/base at the origin). */
+export const shapes = {
+  sphere: (x: number, y: number, z: number, r: number): number =>
+    Math.sqrt(x * x + y * y + z * z) - r,
+  ellipsoid(x: number, y: number, z: number, rx: number, ry: number, rz: number): number {
+    const k0 = Math.sqrt((x / rx) ** 2 + (y / ry) ** 2 + (z / rz) ** 2);
+    const k1 = Math.sqrt((x / (rx * rx)) ** 2 + (y / (ry * ry)) ** 2 + (z / (rz * rz)) ** 2);
+    return k1 === 0 ? -Math.min(rx, ry, rz) : (k0 * (k0 - 1)) / k1;
+  },
+  /** Box of half extents (hx, hy, hz) with edges rounded by `r`. */
+  roundBox(x: number, y: number, z: number, hx: number, hy: number, hz: number, r: number): number {
+    const qx = Math.abs(x) - hx + r;
+    const qy = Math.abs(y) - hy + r;
+    const qz = Math.abs(z) - hz + r;
+    const ox = Math.max(qx, 0);
+    const oy = Math.max(qy, 0);
+    const oz = Math.max(qz, 0);
+    return Math.sqrt(ox * ox + oy * oy + oz * oz) + Math.min(Math.max(qx, qy, qz), 0) - r;
+  },
+  /** Segment (0,0,0) → (0,0,len) with radius r. */
+  capsule(x: number, y: number, z: number, len: number, r: number): number {
+    const t = len > 0 ? Math.min(Math.max(z, 0), len) : 0;
+    return Math.sqrt(x * x + y * y + (z - t) * (z - t)) - r;
+  },
+  /** Capped cone standing on z = 0: base radius r1, top radius r2, height h. */
+  cone(x: number, y: number, z: number, r1: number, r2: number, h: number): number {
+    const hh = h / 2;
+    const qx = Math.sqrt(x * x + y * y);
+    const qy = z - hh;
+    const cax = qx - Math.min(qx, qy < 0 ? r1 : r2);
+    const cay = Math.abs(qy) - hh;
+    const k2x = r2 - r1;
+    const k2y = 2 * hh;
+    const t = clamp01(((r2 - qx) * k2x + (hh - qy) * k2y) / (k2x * k2x + k2y * k2y));
+    const cbx = qx - r2 + k2x * t;
+    const cby = qy - hh + k2y * t;
+    const s = cbx < 0 && cay < 0 ? -1 : 1;
+    return s * Math.sqrt(Math.min(cax * cax + cay * cay, cbx * cbx + cby * cby));
+  },
+  /** Ring in the XY plane: major radius R, tube radius r. */
+  torus(x: number, y: number, z: number, R: number, r: number): number {
+    const q = Math.sqrt(x * x + y * y) - R;
+    return Math.sqrt(q * q + z * z) - r;
+  },
+};
+
+/** Polynomial smooth-min weight: 1 → all `a`, 0 → all `b`; k = 0 is a hard min. */
+export const smoothWeight = (a: number, b: number, k: number): number =>
+  k > 0 ? clamp01(0.5 + (0.5 * (b - a)) / k) : a < b ? 1 : 0;
+
+/** Field constructors and combinators, world space. */
+export const sd = {
+  sphere:
+    (at: Vec3, r: number): Field =>
+    (p) =>
+      shapes.sphere(p[0] - at[0], p[1] - at[1], p[2] - at[2], r),
+  ellipsoid:
+    (at: Vec3, radii: Vec3): Field =>
+    (p) =>
+      shapes.ellipsoid(p[0] - at[0], p[1] - at[1], p[2] - at[2], radii[0], radii[1], radii[2]),
+  /** Axis-aligned box of full `size` centred on `at`, edges rounded by `round`. */
+  box:
+    (at: Vec3, size: Vec3, round = 0): Field =>
+    (p) =>
+      shapes.roundBox(
+        p[0] - at[0],
+        p[1] - at[1],
+        p[2] - at[2],
+        size[0] / 2,
+        size[1] / 2,
+        size[2] / 2,
+        round,
+      ),
+  capsule(a: Vec3, b: Vec3, r: number): Field {
+    const bx = b[0] - a[0];
+    const by = b[1] - a[1];
+    const bz = b[2] - a[2];
+    const bb = bx * bx + by * by + bz * bz;
+    return (p) => {
+      const px = p[0] - a[0];
+      const py = p[1] - a[1];
+      const pz = p[2] - a[2];
+      const h = bb > 0 ? clamp01((px * bx + py * by + pz * bz) / bb) : 0;
+      return Math.sqrt((px - bx * h) ** 2 + (py - by * h) ** 2 + (pz - bz * h) ** 2) - r;
+    };
+  },
+  cone:
+    (at: Vec3, r1: number, r2: number, h: number): Field =>
+    (p) =>
+      shapes.cone(p[0] - at[0], p[1] - at[1], p[2] - at[2], r1, r2, h),
+  torus:
+    (at: Vec3, R: number, r: number): Field =>
+    (p) =>
+      shapes.torus(p[0] - at[0], p[1] - at[1], p[2] - at[2], R, r),
+  union:
+    (...fs: readonly Field[]): Field =>
+    (p) => {
+      let d = Number.POSITIVE_INFINITY;
+      for (const f of fs) d = Math.min(d, f(p));
+      return d;
+    },
+  intersect:
+    (a: Field, b: Field): Field =>
+    (p) =>
+      Math.max(a(p), b(p)),
+  /** a minus b. */
+  subtract:
+    (a: Field, b: Field): Field =>
+    (p) =>
+      Math.max(a(p), -b(p)),
+  /** Union with a fillet of radius ~k metres between the two. */
+  smoothUnion:
+    (k: number, a: Field, b: Field): Field =>
+    (p) => {
+      const da = a(p);
+      const db = b(p);
+      const h = smoothWeight(da, db, k);
+      return db + (da - db) * h - k * h * (1 - h);
+    },
+  /** a minus b with a rounded crease of ~k metres. */
+  smoothSubtract:
+    (k: number, a: Field, b: Field): Field =>
+    (p) => {
+      const da = a(p);
+      const db = -b(p);
+      const h = smoothWeight(-da, -db, k);
+      return da + (db - da) * (1 - h) + k * h * (1 - h);
+    },
+  /** Push the surface out/in by `amount` metres × noise (∈ [−1, 1]). */
+  displace:
+    (f: Field, noise: Field, amount: number): Field =>
+    (p) =>
+      f(p) + amount * noise(p),
+};

package/src/primitives/sdf.ts

@@ -0,0 +1,83 @@
+// A signed-distance field meshed into a closed surface: rocks, boulders, terrain lumps, sculpted
+// heads (sculpt.ts builds the field). SMOOTH normals from the field gradient (central differences),
+// shared vertices. `resolution` is the cell edge in METRES, the LOD knob:
+// `ctx.pick([0.01, 0.03, 0.08])`. Default mesher is surface nets (see surface-nets.ts for why);
+// `mesher: 'cubes'` for marching cubes. UVs: planar along the normal's dominant axis, U at true
+// metres, V mirrored every band so it never leaves the strip.
+//   triangles = 2 × grid edges the surface crosses (nets) ≈ 2 · area / resolution² · 1.5
+
+import { type Mesh, MeshBuilder, type Vec3 } from '../core/index.ts';
+import { type StripId, stripRect } from '../material/index.ts';
+import { invalid } from './check.ts';
+import { sampleGrid } from './sdf-grid.ts';
+import { mirroredV, stripU, stripVMetres } from './strip-uv.ts';
+import { marchingCubes, surfaceNets } from './surface-nets.ts';
+
+/** One colour, or one per vertex from its position and unit normal (moss on top, dark in cracks). */
+export type SdfColor = Vec3 | ((p: Vec3, n: Vec3) => Vec3);
+
+export interface SdfOptions {
+  /** Signed distance in metres: negative inside. Must not keep the `p` it is given. */
+  readonly field: (p: Vec3) => number;
+  /** [min, max] corners; the surface is clipped to this box, so it is always closed. */
+  readonly bounds: readonly [Vec3, Vec3];
+  /** Cell edge in metres (the LOD knob). */
+  readonly resolution: number;
+  readonly color: SdfColor;
+  readonly strip?: StripId;
+  readonly mesher?: 'nets' | 'cubes';
+  /** Upper bound on |∇field| (1 for exact distances). Raise it for strongly displaced fields so
+   *  the sparse pass never skips a block that holds surface. Default 1.25. */
+  readonly lipschitz?: number;
+  /** 'y': the field is mirror-symmetric across y = 0 — snap the grid so the mesh is too. */
+  readonly symmetry?: 'y';
+}
+
+export function sdf(o: SdfOptions): Mesh {
+  const lip = o.lipschitz ?? 1.25;
+  if (!(lip >= 1)) invalid(`sdf lipschitz is ${lip}`, 'use ≥ 1 (1 = exact distance field)');
+  const g = sampleGrid(o.field, o.bounds, o.resolution, lip, o.symmetry === 'y');
+  const raw = o.mesher === 'cubes' ? marchingCubes(g) : surfaceNets(g);
+  if (raw.tris.length === 0)
+    invalid(
+      'sdf field has no surface inside its bounds (never crosses zero)',
+      'return negative distances inside the shape, positive outside, and make bounds contain it',
+    );
+  const strip = o.strip ?? 'plain';
+  const rect = stripRect(strip);
+  const vm = stripVMetres(strip);
+  const e = g.h * 0.5;
+  const q: [number, number, number] = [0, 0, 0];
+  const at = (x: number, y: number, z: number): number => {
+    q[0] = x;
+    q[1] = y;
+    q[2] = z;
+    return g.field(q);
+  };
+  const b = new MeshBuilder();
+  for (let i = 0; i < raw.pos.length; i += 3) {
+    const x = raw.pos[i] ?? 0;
+    const y = raw.pos[i + 1] ?? 0;
+    const z = raw.pos[i + 2] ?? 0;
+    const gx = at(x + e, y, z) - at(x - e, y, z);
+    const gy = at(x, y + e, z) - at(x, y - e, z);
+    const gz = at(x, y, z + e) - at(x, y, z - e);
+    const gl = Math.sqrt(gx * gx + gy * gy + gz * gz);
+    const n: Vec3 = gl > 0 ? [gx / gl, gy / gl, gz / gl] : [0, 0, 1];
+    const ax = Math.abs(n[0]);
+    const ay = Math.abs(n[1]);
+    const az = Math.abs(n[2]);
+    // Project onto the plane facing the normal's dominant axis; V runs with world up on walls.
+    const [s, t] = az >= ax && az >= ay ? [x, y] : ax >= ay ? [y, z] : [x, z];
+    const p: Vec3 = [x, y, z];
+    b.vertex({
+      p,
+      n,
+      uv: [stripU(rect, s), mirroredV(rect, t, vm)],
+      color: typeof o.color === 'function' ? o.color(p, n) : o.color,
+    });
+  }
+  for (let i = 0; i < raw.tris.length; i += 3)
+    b.tri(raw.tris[i] ?? 0, raw.tris[i + 1] ?? 0, raw.tris[i + 2] ?? 0);
+  return b.build();
+}

package/src/primitives/strip-uv.ts

@@ -0,0 +1,26 @@
+// True-scale UV mapping onto the trim sheet. U tiles across a strip through the REPEAT sampler
+// (metres / rect.metres); V cannot wrap (the next strip sits there), so V maps one strip band of
+// `vMetres` world metres onto the rect, half a texel inside its edges against bleeding.
+
+import { DEFAULT_SHEET, type StripId, TRIM_SHEET_SIZE, type UvRect } from '../material/index.ts';
+
+/** Half a texel at the house sheet size: keeps bilinear samples inside the region. */
+export const HALF_TEXEL = 0.5 / TRIM_SHEET_SIZE;
+
+/** World metres one strip band covers along V on the house sheet (`scaleMetres`). */
+export const stripVMetres = (id: StripId): number => DEFAULT_SHEET.strips[id]?.scaleMetres ?? 1;
+
+/** U for a run of `metres` along the strip. */
+export const stripU = (rect: UvRect, metres: number): number =>
+  rect.u0 + (metres / rect.metres) * (rect.u1 - rect.u0);
+
+/** V for a fraction 0..1 of one band. */
+export const stripV = (rect: UvRect, frac: number): number =>
+  rect.v0 + HALF_TEXEL + frac * (rect.v1 - rect.v0 - 2 * HALF_TEXEL);
+
+/** V for any metre value, mirrored every band: continuous, never leaves the strip (organic). */
+export function mirroredV(rect: UvRect, metres: number, vMetres: number): number {
+  const t = metres / vMetres;
+  const m = t - 2 * Math.floor(t / 2);
+  return stripV(rect, m <= 1 ? m : 2 - m);
+}

package/src/primitives/surface-nets.ts

@@ -0,0 +1,161 @@
+// Meshers over a sampled grid (inside = value < 0). Both return positions + triangle indices
+// wound CCW seen from outside; sdf.ts adds normals, UVs and colour.
+//   nets:  naive surface nets — one vertex per surface cell (mean of its edge crossings), one quad
+//          per sign-changing grid edge: triangles = 2 × crossing edges. Even, well-shaped
+//          triangles, ~half of marching cubes' count, smooth by construction: the organic default.
+//   cubes: marching cubes (Lorensen & Cline) — vertices on the grid edges, the classic table.
+
+import { TRI } from './mc-table.ts';
+import type { Grid } from './sdf-grid.ts';
+
+export interface RawSurface {
+  readonly pos: number[];
+  readonly tris: number[];
+}
+
+// Cube corners (Bourke numbering) and the 12 edges as corner pairs.
+const CORNER = [0, 0, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 0, 0, 1, 1, 0, 1, 1, 1, 1, 0, 1, 1];
+const EDGE = [0, 1, 1, 2, 2, 3, 3, 0, 4, 5, 5, 6, 6, 7, 7, 4, 0, 4, 1, 5, 2, 6, 3, 7];
+
+export function surfaceNets(g: Grid): RawSurface {
+  const { nx, ny, nz, values: v, h, origin: o } = g;
+  const cells = new Int32Array((nx - 1) * (ny - 1) * (nz - 1)).fill(-1);
+  const pos: number[] = [];
+  const c = new Float64Array(8);
+  for (let z = 0; z < nz - 1; z++)
+    for (let y = 0; y < ny - 1; y++)
+      for (let x = 0; x < nx - 1; x++) {
+        let mask = 0;
+        for (let k = 0; k < 8; k++) {
+          const val =
+            v[
+              x +
+                (CORNER[k * 3] ?? 0) +
+                nx * (y + (CORNER[k * 3 + 1] ?? 0) + ny * (z + (CORNER[k * 3 + 2] ?? 0)))
+            ] ?? 1;
+          c[k] = val;
+          if (val < 0) mask |= 1 << k;
+        }
+        if (mask === 0 || mask === 255) continue;
+        let sx = 0;
+        let sy = 0;
+        let sz = 0;
+        let n = 0;
+        for (let e = 0; e < 12; e++) {
+          const a = EDGE[e * 2] ?? 0;
+          const b = EDGE[e * 2 + 1] ?? 0;
+          const va = c[a] ?? 0;
+          const vb = c[b] ?? 0;
+          if (va < 0 === vb < 0) continue;
+          const t = va / (va - vb);
+          sx += (CORNER[a * 3] ?? 0) + t * ((CORNER[b * 3] ?? 0) - (CORNER[a * 3] ?? 0));
+          sy +=
+            (CORNER[a * 3 + 1] ?? 0) + t * ((CORNER[b * 3 + 1] ?? 0) - (CORNER[a * 3 + 1] ?? 0));
+          sz +=
+            (CORNER[a * 3 + 2] ?? 0) + t * ((CORNER[b * 3 + 2] ?? 0) - (CORNER[a * 3 + 2] ?? 0));
+          n++;
+        }
+        cells[x + (nx - 1) * (y + (ny - 1) * z)] = pos.length / 3;
+        pos.push(o[0] + (x + sx / n) * h, o[1] + (y + sy / n) * h, o[2] + (z + sz / n) * h);
+      }
+  const tris: number[] = [];
+  const cell = (x: number, y: number, z: number): number =>
+    cells[x + (nx - 1) * (y + (ny - 1) * z)] ?? 0;
+  const P = (i: number, k: number): number => pos[i * 3 + k] ?? 0;
+  /** Unit normal of triangle (a, b, c) written into n. */
+  const n1 = new Float64Array(3);
+  const n2 = new Float64Array(3);
+  const normal = (a: number, b: number, c: number, n: Float64Array): void => {
+    const ex = P(b, 0) - P(a, 0);
+    const ey = P(b, 1) - P(a, 1);
+    const ez = P(b, 2) - P(a, 2);
+    const fx = P(c, 0) - P(a, 0);
+    const fy = P(c, 1) - P(a, 1);
+    const fz = P(c, 2) - P(a, 2);
+    const x = ey * fz - ez * fy;
+    const y = ez * fx - ex * fz;
+    const z = ex * fy - ey * fx;
+    const l = Math.sqrt(x * x + y * y + z * z) || 1;
+    n[0] = x / l;
+    n[1] = y / l;
+    n[2] = z / l;
+  };
+  const flatness = (): number =>
+    (n1[0] ?? 0) * (n2[0] ?? 0) + (n1[1] ?? 0) * (n2[1] ?? 0) + (n1[2] ?? 0) * (n2[2] ?? 0);
+  const quad = (a: number, b: number, cc: number, d: number, out: boolean): void => {
+    const [q0, q1, q2, q3] = out ? [a, b, cc, d] : [a, d, cc, b];
+    // Split along the diagonal whose two triangles fold least (no creases on thin features).
+    normal(q0, q1, q2, n1);
+    normal(q0, q2, q3, n2);
+    const along02 = flatness();
+    normal(q0, q1, q3, n1);
+    normal(q1, q2, q3, n2);
+    if (along02 >= flatness()) tris.push(q0, q1, q2, q0, q2, q3);
+    else tris.push(q0, q1, q3, q1, q2, q3);
+  };
+  for (let z = 1; z < nz - 1; z++)
+    for (let y = 1; y < ny - 1; y++)
+      for (let x = 1; x < nx - 1; x++) {
+        const inside = (v[x + nx * (y + ny * z)] ?? 1) < 0;
+        // Edge +X: cells around it in the (y, z) plane, CCW seen from +X.
+        if (x < nx - 1 && inside !== (v[x + 1 + nx * (y + ny * z)] ?? 1) < 0)
+          quad(cell(x, y - 1, z - 1), cell(x, y, z - 1), cell(x, y, z), cell(x, y - 1, z), inside);
+        if (y < ny - 1 && inside !== (v[x + nx * (y + 1 + ny * z)] ?? 1) < 0)
+          quad(cell(x - 1, y, z - 1), cell(x - 1, y, z), cell(x, y, z), cell(x, y, z - 1), inside);
+        if (z < nz - 1 && inside !== (v[x + nx * (y + ny * (z + 1))] ?? 1) < 0)
+          quad(cell(x - 1, y - 1, z), cell(x, y - 1, z), cell(x, y, z), cell(x - 1, y, z), inside);
+      }
+  return { pos, tris };
+}
+
+export function marchingCubes(g: Grid): RawSurface {
+  const { nx, ny, nz, values: v, h, origin: o } = g;
+  const shared = new Map<number, number>();
+  const pos: number[] = [];
+  const tris: number[] = [];
+  for (let z = 0; z < nz - 1; z++)
+    for (let y = 0; y < ny - 1; y++)
+      for (let x = 0; x < nx - 1; x++) {
+        let mask = 0;
+        for (let k = 0; k < 8; k++)
+          if (
+            (v[
+              x +
+                (CORNER[k * 3] ?? 0) +
+                nx * (y + (CORNER[k * 3 + 1] ?? 0) + ny * (z + (CORNER[k * 3 + 2] ?? 0)))
+            ] ?? 1) < 0
+          )
+            mask |= 1 << k;
+        const list = TRI[mask] ?? [];
+        for (let t = 0; t < list.length; t += 3)
+          for (const j of [0, 2, 1]) {
+            const e = list[t + j] ?? 0;
+            const a = EDGE[e * 2] ?? 0;
+            const b = EDGE[e * 2 + 1] ?? 0;
+            const ax = x + (CORNER[a * 3] ?? 0);
+            const ay = y + (CORNER[a * 3 + 1] ?? 0);
+            const az = z + (CORNER[a * 3 + 2] ?? 0);
+            const bx = x + (CORNER[b * 3] ?? 0);
+            const by = y + (CORNER[b * 3 + 1] ?? 0);
+            const bz = z + (CORNER[b * 3 + 2] ?? 0);
+            const ia = ax + nx * (ay + ny * az);
+            const ib = bx + nx * (by + ny * bz);
+            const lowId = Math.min(ia, ib);
+            const key = lowId * 3 + (ax !== bx ? 0 : ay !== by ? 1 : 2);
+            let id = shared.get(key);
+            if (id === undefined) {
+              const va = v[ia] ?? 0;
+              const s = va / (va - (v[ib] ?? 0));
+              id = pos.length / 3;
+              pos.push(
+                o[0] + (ax + s * (bx - ax)) * h,
+                o[1] + (ay + s * (by - ay)) * h,
+                o[2] + (az + s * (bz - az)) * h,
+              );
+              shared.set(key, id);
+            }
+            tris.push(id);
+          }
+      }
+  return { pos, tris };
+}