@feelgxxd/textel 0.0.0-stage → 0.3.0

package/dist/render.js

@@ -0,0 +1,309 @@
+import { computeSmoothNormals } from "./mesh.js";
+import { mergeStyles, resolveMaterial, resolveStyle } from "./style.js";
+const BG = -1;
+/**
+ * A small software rasterizer that draws into a character grid.
+ * The model is centered and scaled to a unit sphere; the camera sits on +z looking at the origin.
+ * Each cell is sampled `supersample`² times; the cell takes the mean brightness of the samples that hit.
+ */
+export function createRenderer(mesh, input = {}) {
+    const nV = mesh.positions.length / 3, nT = mesh.indices.length / 3;
+    if (!nT)
+        throw new Error('the model has no triangles');
+    const I = mesh.indices, TM = mesh.triMaterial;
+    // ---- normalize to a unit sphere around the bounding box center ----
+    const P = new Float32Array(nV * 3);
+    {
+        const src = mesh.positions;
+        const lo = [Infinity, Infinity, Infinity], hi = [-Infinity, -Infinity, -Infinity];
+        for (let v = 0; v < nV; v++)
+            for (let a = 0; a < 3; a++) {
+                const x = src[v * 3 + a];
+                if (x < lo[a])
+                    lo[a] = x;
+                if (x > hi[a])
+                    hi[a] = x;
+            }
+        const c = [0, 1, 2].map((a) => (lo[a] + hi[a]) / 2);
+        let r = 0;
+        for (let v = 0; v < nV; v++)
+            r = Math.max(r, Math.hypot(src[v * 3] - c[0], src[v * 3 + 1] - c[1], src[v * 3 + 2] - c[2]));
+        const k = 1 / (r || 1);
+        for (let v = 0; v < nV; v++)
+            for (let a = 0; a < 3; a++)
+                P[v * 3 + a] = (src[v * 3 + a] - c[a]) * k;
+    }
+    // extents used to fit the model in the grid while it spins around y
+    let rxz = 0, ry = 0;
+    for (let v = 0; v < nV; v++) {
+        rxz = Math.max(rxz, Math.hypot(P[v * 3], P[v * 3 + 2]));
+        ry = Math.max(ry, Math.abs(P[v * 3 + 1]));
+    }
+    let smoothN = null;
+    const VP = new Float32Array(nV * 3); // view space positions
+    const SX = new Float32Array(nV), SY = new Float32Array(nV), OZ = new Float32Array(nV);
+    let VN = null;
+    let styleInput = input;
+    let style = resolveStyle(styleInput);
+    let materials = [];
+    let sw = 0, sh = 0;
+    let sOoz = new Float32Array(0), sLum = new Float32Array(0), sMat = new Int16Array(0);
+    let cOoz = new Float32Array(0), cLum = new Float32Array(0), cMat = new Int16Array(0);
+    function configure() {
+        materials = mesh.materials.map((name) => resolveMaterial(name, style.materials[name]));
+        const ss = style.supersample;
+        if (sw !== style.width * ss || sh !== style.height * ss) {
+            sw = style.width * ss;
+            sh = style.height * ss;
+            sOoz = new Float32Array(sw * sh);
+            sLum = new Float32Array(sw * sh);
+            sMat = new Int16Array(sw * sh);
+        }
+        const n = style.width * style.height;
+        if (cOoz.length !== n) {
+            cOoz = new Float32Array(n);
+            cLum = new Float32Array(n);
+            cMat = new Int16Array(n);
+        }
+    }
+    configure();
+    function normals() {
+        if (style.shading === 'flat')
+            return null;
+        if (mesh.normals)
+            return mesh.normals;
+        if (style.shading === 'smooth')
+            return (smoothN ??= computeSmoothNormals(mesh));
+        return null;
+    }
+    /** focal length in samples: the model fits the grid at any yaw, at the resting pitch */
+    function focal() {
+        const D = style.distance;
+        // vertical half extent ry·cos p + rxz·sin p, at its largest over the pitches that must fit;
+        // it peaks at p = atan(rxz / ry), so check that point when it is inside the range
+        const lo = Math.abs(style.pitch), hi = Math.max(lo, style.fitPitch), peak = Math.atan2(rxz, ry);
+        const extent = (p) => ry * Math.cos(p) + rxz * Math.sin(p);
+        const hx = Math.max(rxz, 1e-3), hy = Math.max(peak > lo && peak < hi ? Math.hypot(ry, rxz) : Math.max(extent(lo), extent(hi)), 1e-3);
+        // largest x/z a circle of radius r at distance D reaches, with perspective
+        const tx = hx / Math.sqrt(D * D - Math.min(hx * hx, D * D * 0.99));
+        const ty = hy / Math.sqrt(D * D - 1);
+        return style.zoom * Math.min((sw / 2) / tx, ((sh / 2) * style.aspect) / ty) * 0.98;
+    }
+    function render(view = {}) {
+        const ss = style.supersample, W = style.width, H = style.height, D = style.distance, aspect = style.aspect;
+        const yaw = view.yaw ?? 0, pitch = view.pitch ?? style.pitch, roll = view.roll ?? 0;
+        // R = Rz(roll) * Rx(pitch) * Ry(yaw): spin on a turntable, then tilt toward the camera
+        const cy = Math.cos(yaw), sy = Math.sin(yaw), cp = Math.cos(pitch), sp = Math.sin(pitch), cr = Math.cos(roll), sr = Math.sin(roll);
+        // Rx*Ry
+        const a00 = cy, a01 = 0, a02 = sy;
+        const a10 = sp * sy, a11 = cp, a12 = -sp * cy;
+        const a20 = -cp * sy, a21 = sp, a22 = cp * cy;
+        const m00 = cr * a00 - sr * a10, m01 = cr * a01 - sr * a11, m02 = cr * a02 - sr * a12;
+        const m10 = sr * a00 + cr * a10, m11 = sr * a01 + cr * a11, m12 = sr * a02 + cr * a12;
+        const m20 = a20, m21 = a21, m22 = a22;
+        const f = focal(), fy = f / aspect, hw = sw / 2, hh = sh / 2;
+        for (let v = 0, o = 0; v < nV; v++, o += 3) {
+            const x = P[o], y = P[o + 1], z = P[o + 2];
+            const X = m00 * x + m01 * y + m02 * z, Y = m10 * x + m11 * y + m12 * z, Z = m20 * x + m21 * y + m22 * z;
+            VP[o] = X;
+            VP[o + 1] = Y;
+            VP[o + 2] = Z;
+            const ooz = 1 / (D - Z);
+            OZ[v] = ooz;
+            SX[v] = hw + f * X * ooz;
+            SY[v] = hh - fy * Y * ooz;
+        }
+        const N = normals();
+        if (N) {
+            if (!VN || VN.length !== N.length)
+                VN = new Float32Array(N.length);
+            for (let o = 0; o < N.length; o += 3) {
+                const x = N[o], y = N[o + 1], z = N[o + 2];
+                VN[o] = m00 * x + m01 * y + m02 * z;
+                VN[o + 1] = m10 * x + m11 * y + m12 * z;
+                VN[o + 2] = m20 * x + m21 * y + m22 * z;
+            }
+        }
+        sOoz.fill(0);
+        sMat.fill(BG);
+        const [lx, ly, lz] = style.light, amb = style.ambient, dif = 1 - amb;
+        for (let t = 0; t < nT; t++) {
+            const ia = I[t * 3], ib = I[t * 3 + 1], ic = I[t * 3 + 2];
+            const ax = SX[ia], ay = SY[ia], bx = SX[ib], by = SY[ib], cx = SX[ic], cyy = SY[ic];
+            const area = (bx - ax) * (cyy - ay) - (by - ay) * (cx - ax);
+            if (area === 0 || !Number.isFinite(area))
+                continue;
+            // sample centers sit at +0.5
+            const x0 = Math.max(0, Math.ceil(Math.min(ax, bx, cx) - 0.5)), x1 = Math.min(sw - 1, Math.floor(Math.max(ax, bx, cx) - 0.5));
+            const y0 = Math.max(0, Math.ceil(Math.min(ay, by, cyy) - 0.5)), y1 = Math.min(sh - 1, Math.floor(Math.max(ay, by, cyy) - 0.5));
+            if (x0 > x1 || y0 > y1)
+                continue;
+            // geometric normal in view space, oriented toward the camera
+            const pa = ia * 3, pb = ib * 3, pc = ic * 3;
+            const e1x = VP[pb] - VP[pa], e1y = VP[pb + 1] - VP[pa + 1], e1z = VP[pb + 2] - VP[pa + 2];
+            const e2x = VP[pc] - VP[pa], e2y = VP[pc + 1] - VP[pa + 1], e2z = VP[pc + 2] - VP[pa + 2];
+            let fnx = e1y * e2z - e1z * e2y, fny = e1z * e2x - e1x * e2z, fnz = e1x * e2y - e1y * e2x;
+            const gx = (VP[pa] + VP[pb] + VP[pc]) / 3, gy = (VP[pa + 1] + VP[pb + 1] + VP[pc + 1]) / 3, gz = (VP[pa + 2] + VP[pb + 2] + VP[pc + 2]) / 3;
+            const vx = -gx, vy = -gy, vz = D - gz;
+            let flip = 1, flatLum = 0;
+            if (VN) {
+                // trust the vertex normals for "outside"; flip them when we see the inside of a face
+                const nsx = VN[pa] + VN[pb] + VN[pc], nsy = VN[pa + 1] + VN[pb + 1] + VN[pc + 1], nsz = VN[pa + 2] + VN[pb + 2] + VN[pc + 2];
+                if (fnx * nsx + fny * nsy + fnz * nsz < 0) {
+                    fnx = -fnx;
+                    fny = -fny;
+                    fnz = -fnz;
+                }
+                if (fnx * vx + fny * vy + fnz * vz < 0)
+                    flip = -1;
+            }
+            else {
+                if (fnx * vx + fny * vy + fnz * vz < 0) {
+                    fnx = -fnx;
+                    fny = -fny;
+                    fnz = -fnz;
+                }
+                const l = Math.hypot(fnx, fny, fnz) || 1;
+                flatLum = amb + dif * Math.max(0, (fnx * lx + fny * ly + fnz * lz) / l);
+            }
+            const inv = 1 / area, mat = TM[t], oa = OZ[ia], ob = OZ[ib], oc = OZ[ic];
+            for (let y = y0; y <= y1; y++) {
+                const py = y + 0.5;
+                for (let x = x0; x <= x1; x++) {
+                    const px = x + 0.5;
+                    const w0 = ((bx - px) * (cyy - py) - (by - py) * (cx - px)) * inv;
+                    const w1 = ((cx - px) * (ay - py) - (cyy - py) * (ax - px)) * inv;
+                    const w2 = 1 - w0 - w1;
+                    if (w0 < -1e-7 || w1 < -1e-7 || w2 < -1e-7)
+                        continue;
+                    const ooz = w0 * oa + w1 * ob + w2 * oc, i = y * sw + x;
+                    if (ooz <= sOoz[i])
+                        continue;
+                    sOoz[i] = ooz;
+                    sMat[i] = mat;
+                    if (VN) {
+                        const nx = (w0 * VN[pa] + w1 * VN[pb] + w2 * VN[pc]) * flip;
+                        const ny = (w0 * VN[pa + 1] + w1 * VN[pb + 1] + w2 * VN[pc + 1]) * flip;
+                        const nz = (w0 * VN[pa + 2] + w1 * VN[pb + 2] + w2 * VN[pc + 2]) * flip;
+                        const l = Math.hypot(nx, ny, nz) || 1;
+                        sLum[i] = amb + dif * Math.max(0, (nx * lx + ny * ly + nz * lz) / l);
+                    }
+                    else {
+                        sLum[i] = flatLum;
+                    }
+                }
+            }
+        }
+        // ---- resolve samples into cells ----
+        const n = ss * ss, need = Math.max(1, Math.ceil(style.coverage * n - 1e-9));
+        const votes = new Int16Array(n);
+        for (let r = 0; r < H; r++)
+            for (let c = 0; c < W; c++) {
+                let hit = 0, lum = 0, ooz = 0;
+                for (let sy2 = 0; sy2 < ss; sy2++)
+                    for (let sx2 = 0; sx2 < ss; sx2++) {
+                        const i = (r * ss + sy2) * sw + c * ss + sx2;
+                        if (sMat[i] === BG)
+                            continue;
+                        votes[hit++] = sMat[i];
+                        lum += sLum[i];
+                        if (sOoz[i] > ooz)
+                            ooz = sOoz[i];
+                    }
+                const ci = r * W + c;
+                if (hit < need) {
+                    cMat[ci] = BG;
+                    cLum[ci] = 0;
+                    cOoz[ci] = 0;
+                    continue;
+                }
+                cMat[ci] = hit === 1 ? votes[0] : majority(votes, hit);
+                cLum[ci] = lum / hit;
+                cOoz[ci] = ooz;
+            }
+        // ---- glyphs ----
+        const chars = new Array(W * H);
+        for (let i = 0; i < W * H; i++) {
+            const m = cMat[i];
+            if (m === BG) {
+                chars[i] = ' ';
+                continue;
+            }
+            const ms = materials[m];
+            if (ms.carved) {
+                chars[i] = ' ';
+                continue;
+            }
+            const ramp = ms.chars ?? style.chars;
+            chars[i] = ramp[Math.min(ramp.length - 1, Math.floor(cLum[i] * ramp.length))];
+        }
+        if (style.edges)
+            drawEdges(chars, W, H);
+        return { width: W, height: H, chars, lum: cLum.slice(), mat: cMat.slice(), materials, style };
+    }
+    function drawEdges(chars, W, H) {
+        const depth = style.edges === 'depth', th = style.edgeThreshold, aspect = style.aspect;
+        const solid = (c, r) => c >= 0 && r >= 0 && c < W && r < H && cMat[r * W + c] !== BG;
+        const F = (c, r) => (solid(c, r) ? cOoz[r * W + c] : 0);
+        // the angles '/' and '\' actually sit at in a cell this tall
+        const diag = Math.atan(aspect), b1 = diag / 2, b2 = (diag + Math.PI / 2) / 2, b3 = Math.PI - b2, b4 = Math.PI - b1;
+        const [hz, rise, vert, fall] = style.edgeChars;
+        for (let r = 0; r < H; r++)
+            for (let c = 0; c < W; c++) {
+                const i = r * W + c;
+                if (cMat[i] === BG || materials[cMat[i]].carved)
+                    continue;
+                let edge = false;
+                for (const [dc, dr] of [[1, 0], [-1, 0], [0, 1], [0, -1]]) {
+                    if (!solid(c + dc, r + dr)) {
+                        edge = true;
+                        break;
+                    }
+                    // only the nearer side of a depth step gets the line
+                    if (depth && cOoz[i] - F(c + dc, r + dr) > th * cOoz[i]) {
+                        edge = true;
+                        break;
+                    }
+                }
+                if (!edge)
+                    continue;
+                // Sobel on inverse depth (background = 0); screen y points down
+                const gx = F(c + 1, r - 1) + 2 * F(c + 1, r) + F(c + 1, r + 1) - F(c - 1, r - 1) - 2 * F(c - 1, r) - F(c - 1, r + 1);
+                const gyDown = F(c - 1, r + 1) + 2 * F(c, r + 1) + F(c + 1, r + 1) - F(c - 1, r - 1) - 2 * F(c, r - 1) - F(c + 1, r - 1);
+                const gy = -gyDown / aspect;
+                if (gx === 0 && gy === 0)
+                    continue;
+                // the line runs perpendicular to the gradient
+                let a = Math.atan2(gx, -gy);
+                if (a < 0)
+                    a += Math.PI;
+                if (a >= Math.PI)
+                    a -= Math.PI;
+                chars[i] = a < b1 || a >= b4 ? hz : a < b2 ? rise : a < b3 ? vert : fall;
+            }
+    }
+    return {
+        mesh,
+        get style() { return style; },
+        setStyle(next) {
+            styleInput = mergeStyles(styleInput, next);
+            style = resolveStyle(styleInput);
+            configure();
+        },
+        render,
+    };
+}
+function majority(v, n) {
+    let best = v[0], bestN = 0;
+    for (let i = 0; i < n; i++) {
+        let k = 0;
+        for (let j = 0; j < n; j++)
+            if (v[j] === v[i])
+                k++;
+        if (k > bestN) {
+            bestN = k;
+            best = v[i];
+        }
+    }
+    return best;
+}

package/dist/sdf.d.ts

@@ -0,0 +1,36 @@
+import { type Mesh } from './mesh.ts';
+import type { Vec3 } from './style.ts';
+export type Field = (x: number, y: number, z: number) => number;
+export declare const clamp: (v: number, a: number, b: number) => number;
+export declare const fract: (v: number) => number;
+export declare const sdSphere: (x: number, y: number, z: number, r: number) => number;
+/** axis-aligned box with half sizes hx hy hz, edges rounded by r */
+export declare const sdBox: (x: number, y: number, z: number, hx: number, hy: number, hz: number, r?: number) => number;
+/** capped cylinder along y: radius r, half height h */
+export declare const sdCyl: (x: number, y: number, z: number, r: number, h: number) => number;
+/** torus in the xz plane: ring radius R, tube radius r */
+export declare const sdTorus: (x: number, y: number, z: number, R: number, r: number) => number;
+/** 2D polygon in the xy plane */
+export declare const sdPoly: (v: number[][], px: number, py: number) => number;
+/** a 2D distance pushed out along z to half thickness h, edges rounded by r */
+export declare const extrude: (d2: number, z: number, h: number, r: number) => number;
+/** smooth union with blend radius k */
+export declare const smin: (a: number, b: number, k: number) => number;
+export interface SdfOptions {
+    /** bounds of the sampling grid */
+    min: Vec3;
+    max: Vec3;
+    /** grid spacing; the mesh has roughly one vertex per cell on the surface */
+    step: number;
+    /** material names, indexed by what `material` returns */
+    materials?: string[];
+    /** material index at a point on the surface */
+    material?: (x: number, y: number, z: number) => number;
+}
+/** Meshes a field with surface nets. Synchronous; see sdfToMeshSteps to spread the work out. */
+export declare function sdfToMesh(field: Field, opts: SdfOptions): Mesh;
+/**
+ * The same as sdfToMesh, as a generator that yields after every grid layer, so a browser can
+ * build a mesh in idle slices without blocking input.
+ */
+export declare function sdfToMeshSteps(field: Field, opts: SdfOptions): Generator<void, Mesh>;

package/dist/sdf.js

@@ -0,0 +1,151 @@
+// Signed distance fields: build shapes in code and mesh them.
+// Convention: negative inside, positive outside, roughly the distance to the surface.
+import { MeshBuilder } from "./mesh.js";
+export const clamp = (v, a, b) => Math.max(a, Math.min(b, v));
+export const fract = (v) => v - Math.floor(v);
+export const sdSphere = (x, y, z, r) => Math.hypot(x, y, z) - r;
+/** axis-aligned box with half sizes hx hy hz, edges rounded by r */
+export const sdBox = (x, y, z, hx, hy, hz, r = 0) => {
+    const qx = Math.abs(x) - hx + r, qy = Math.abs(y) - hy + r, qz = Math.abs(z) - hz + r;
+    return Math.hypot(Math.max(qx, 0), Math.max(qy, 0), Math.max(qz, 0)) + Math.min(Math.max(qx, qy, qz), 0) - r;
+};
+/** capped cylinder along y: radius r, half height h */
+export const sdCyl = (x, y, z, r, h) => {
+    const dx = Math.hypot(x, z) - r, dy = Math.abs(y) - h;
+    return Math.min(Math.max(dx, dy), 0) + Math.hypot(Math.max(dx, 0), Math.max(dy, 0));
+};
+/** torus in the xz plane: ring radius R, tube radius r */
+export const sdTorus = (x, y, z, R, r) => Math.hypot(Math.hypot(x, z) - R, y) - r;
+/** 2D polygon in the xy plane */
+export const sdPoly = (v, px, py) => {
+    let d = (px - v[0][0]) ** 2 + (py - v[0][1]) ** 2, s = 1;
+    for (let i = 0, j = v.length - 1; i < v.length; j = i, i++) {
+        const ex = v[j][0] - v[i][0], ey = v[j][1] - v[i][1], wx = px - v[i][0], wy = py - v[i][1];
+        const t = clamp((wx * ex + wy * ey) / (ex * ex + ey * ey), 0, 1);
+        d = Math.min(d, (wx - ex * t) ** 2 + (wy - ey * t) ** 2);
+        const c1 = py >= v[i][1], c2 = py < v[j][1], c3 = ex * wy > ey * wx;
+        if ((c1 && c2 && c3) || (!c1 && !c2 && !c3))
+            s = -s;
+    }
+    return s * Math.sqrt(d);
+};
+/** a 2D distance pushed out along z to half thickness h, edges rounded by r */
+export const extrude = (d2, z, h, r) => {
+    const a = d2 + r, b = Math.abs(z) - h + r;
+    return Math.min(Math.max(a, b), 0) + Math.hypot(Math.max(a, 0), Math.max(b, 0)) - r;
+};
+/** smooth union with blend radius k */
+export const smin = (a, b, k) => {
+    const h = clamp(0.5 + (0.5 * (b - a)) / k, 0, 1);
+    return b + (a - b) * h - k * h * (1 - h);
+};
+/** Meshes a field with surface nets. Synchronous; see sdfToMeshSteps to spread the work out. */
+export function sdfToMesh(field, opts) {
+    const g = sdfToMeshSteps(field, opts);
+    let r = g.next();
+    while (!r.done)
+        r = g.next();
+    return r.value;
+}
+/**
+ * The same as sdfToMesh, as a generator that yields after every grid layer, so a browser can
+ * build a mesh in idle slices without blocking input.
+ */
+export function* sdfToMeshSteps(field, opts) {
+    const { step } = opts;
+    if (!(step > 0))
+        throw new Error('step must be > 0');
+    // one cell of padding so the surface is closed even if the bounds are tight
+    const min = opts.min.map((v) => v - step), max = opts.max.map((v) => v + step);
+    const NX = Math.ceil((max[0] - min[0]) / step) + 1, NY = Math.ceil((max[1] - min[1]) / step) + 1, NZ = Math.ceil((max[2] - min[2]) / step) + 1;
+    if (NX * NY * NZ > 64e6)
+        throw new Error('grid too fine: raise step or shrink the bounds');
+    const val = new Float32Array(NX * NY * NZ);
+    const at = (i, j, k) => (k * NY + j) * NX + i;
+    for (let k = 0; k < NZ; k++) {
+        const z = min[2] + k * step;
+        for (let j = 0; j < NY; j++) {
+            const y = min[1] + j * step;
+            for (let i = 0; i < NX; i++)
+                val[at(i, j, k)] = field(min[0] + i * step, y, z);
+        }
+        yield;
+    }
+    // the padding layer must be outside
+    for (let k = 0; k < NZ; k++)
+        for (let j = 0; j < NY; j++)
+            for (let i = 0; i < NX; i++)
+                if (i === 0 || j === 0 || k === 0 || i === NX - 1 || j === NY - 1 || k === NZ - 1)
+                    val[at(i, j, k)] = Math.max(val[at(i, j, k)], 1e-6);
+    const CX = NX - 1, CY = NY - 1;
+    const cell = new Int32Array(CX * CY * (NZ - 1)).fill(-1);
+    const cid = (i, j, k) => (k * CY + j) * CX + i;
+    const b = new MeshBuilder();
+    for (const name of opts.materials ?? ['default'])
+        b.material(name);
+    // the 12 cube edges as corner pairs; corner bits are x=1 y=2 z=4
+    const EDGES = [[0, 1], [2, 3], [4, 5], [6, 7], [0, 2], [1, 3], [4, 6], [5, 7], [0, 4], [1, 5], [2, 6], [3, 7]];
+    const cv = new Float64Array(8);
+    const h = step * 0.5;
+    for (let k = 0; k < NZ - 1; k++) {
+        for (let j = 0; j < CY; j++)
+            for (let i = 0; i < CX; i++) {
+                let mask = 0;
+                for (let c = 0; c < 8; c++) {
+                    cv[c] = val[at(i + (c & 1), j + ((c >> 1) & 1), k + ((c >> 2) & 1))];
+                    if (cv[c] < 0)
+                        mask |= 1 << c;
+                }
+                if (mask === 0 || mask === 255)
+                    continue;
+                // the vertex sits at the mean of the edge crossings
+                let sx = 0, sy = 0, sz = 0, n = 0;
+                for (const [a, bb] of EDGES) {
+                    if ((cv[a] < 0) === (cv[bb] < 0))
+                        continue;
+                    const t = cv[a] / (cv[a] - cv[bb]);
+                    sx += (a & 1) + t * ((bb & 1) - (a & 1));
+                    sy += ((a >> 1) & 1) + t * (((bb >> 1) & 1) - ((a >> 1) & 1));
+                    sz += ((a >> 2) & 1) + t * (((bb >> 2) & 1) - ((a >> 2) & 1));
+                    n++;
+                }
+                const x = min[0] + (i + sx / n) * step, y = min[1] + (j + sy / n) * step, z = min[2] + (k + sz / n) * step;
+                // outward normal = gradient of the field
+                const nx = field(x + h, y, z) - field(x - h, y, z), ny = field(x, y + h, z) - field(x, y - h, z), nz = field(x, y, z + h) - field(x, y, z - h);
+                const l = Math.hypot(nx, ny, nz) || 1;
+                cell[cid(i, j, k)] = b.vertex(x, y, z, nx / l, ny / l, nz / l);
+            }
+        yield;
+    }
+    const P = b.positions, mat = opts.material;
+    const quad = (q0, q1, q2, q3, inside) => {
+        const v = inside ? [q0, q1, q2, q3] : [q3, q2, q1, q0];
+        let m = 0;
+        if (mat) {
+            let x = 0, y = 0, z = 0;
+            for (const vi of v) {
+                x += P[vi * 3];
+                y += P[vi * 3 + 1];
+                z += P[vi * 3 + 2];
+            }
+            m = mat(x / 4, y / 4, z / 4) | 0;
+        }
+        b.triangle(v[0], v[1], v[2], m);
+        b.triangle(v[0], v[2], v[3], m);
+    };
+    for (let k = 0; k < NZ; k++) {
+        for (let j = 0; j < NY; j++)
+            for (let i = 0; i < NX; i++) {
+                const v0 = val[at(i, j, k)], in0 = v0 < 0;
+                // each grid edge that crosses the surface becomes a quad joining the 4 cells around it
+                if (i < NX - 1 && j > 0 && k > 0 && j < NY - 1 && k < NZ - 1 && in0 !== val[at(i + 1, j, k)] < 0)
+                    quad(cell[cid(i, j - 1, k - 1)], cell[cid(i, j, k - 1)], cell[cid(i, j, k)], cell[cid(i, j - 1, k)], in0);
+                if (j < NY - 1 && i > 0 && k > 0 && i < NX - 1 && k < NZ - 1 && in0 !== val[at(i, j + 1, k)] < 0)
+                    quad(cell[cid(i - 1, j, k - 1)], cell[cid(i - 1, j, k)], cell[cid(i, j, k)], cell[cid(i, j, k - 1)], in0);
+                if (k < NZ - 1 && i > 0 && j > 0 && i < NX - 1 && j < NY - 1 && in0 !== val[at(i, j, k + 1)] < 0)
+                    quad(cell[cid(i - 1, j - 1, k)], cell[cid(i, j - 1, k)], cell[cid(i, j, k)], cell[cid(i - 1, j, k)], in0);
+            }
+        yield;
+    }
+    return b.build();
+}

package/dist/style.d.ts

@@ -0,0 +1,138 @@
+export type Vec3 = [number, number, number];
+export type RGB = [number, number, number];
+/**
+ * Character ramps, darkest first. A ramp that starts with a space lets shadows go empty
+ * (crisp on flat faces); one that does not keeps the whole silhouette visible.
+ */
+export declare const CHARSETS: Record<string, string>;
+/**
+ * How a material is drawn.
+ * - `solid`: the normal ramp
+ * - `carved`: blank, but still hides what is behind it (holes, eye sockets, engravings)
+ * - `dim`: the normal ramp at lower intensity
+ */
+export type MaterialInput = 'solid' | 'carved' | 'dim' | {
+    chars?: string;
+    charset?: string;
+    color?: string;
+    opacity?: number;
+    carved?: boolean;
+};
+export interface ResolvedMaterial {
+    name: string;
+    /** own ramp, or null for the style's */
+    chars: string[] | null;
+    color: RGB | null;
+    opacity: number;
+    carved: boolean;
+}
+/** `'none'`, a single `'#hex'` (mono), a list of hex stops (gradient by brightness) or the full object. */
+export type ColorInput = string | string[] | {
+    mode?: 'none' | 'mono' | 'gradient';
+    fg?: string;
+    stops?: string[];
+    bg?: string;
+};
+export interface ResolvedColor {
+    mode: 'none' | 'mono' | 'gradient';
+    fg: RGB;
+    stops: RGB[];
+    bg: RGB | null;
+}
+export type EdgeMode = false | 'outline' | 'depth';
+/** Everything about the look. Every field is optional; see DEFAULTS. This is what a preset file holds. */
+export interface StyleInput {
+    /** grid size in characters */
+    width?: number;
+    height?: number;
+    /** character cell height / width. ~2 in most terminals. */
+    aspect?: number;
+    /** a name from CHARSETS */
+    charset?: string;
+    /** a custom ramp, darkest first; overrides `charset` */
+    chars?: string;
+    /** resting tilt toward the viewer, radians. Positive shows the top. */
+    pitch?: number;
+    /**
+     * the model is fitted so it stays inside the grid for any pitch up to this (radians, either way);
+     * default: just the resting pitch. Viewers that let people tilt the model set it higher.
+     */
+    fitPitch?: number;
+    /** auto-rotation speed around the vertical axis, radians per second (players use it, the renderer does not) */
+    spin?: number;
+    /** camera distance in model radii; smaller is more perspective */
+    distance?: number;
+    /** 1 fills the grid */
+    zoom?: number;
+    /** direction toward the light in view space: x right, y up, z toward the viewer */
+    light?: Vec3;
+    /** brightness floor, 0..1 */
+    ambient?: number;
+    /** auto: smooth if the model has normals, flat otherwise */
+    shading?: 'auto' | 'flat' | 'smooth';
+    /** samples per cell along each axis (2 = 4 samples). Higher is steadier and slower. */
+    supersample?: number;
+    /** share of a cell's samples that must hit the model for the cell to be drawn */
+    coverage?: number;
+    /** draw outlines with directional glyphs */
+    edges?: EdgeMode | boolean;
+    /** four glyphs: horizontal, rising, vertical, falling */
+    edgeChars?: string;
+    /** depth jump (relative) that counts as an edge in `depth` mode */
+    edgeThreshold?: number;
+    color?: ColorInput;
+    /**
+     * how many distinct colors a gradient uses. Default: one per glyph of the ramp, so a color
+     * changes only where the glyph does (far fewer color changes to draw). 0 = smooth.
+     */
+    colorSteps?: number;
+    /** per material name */
+    materials?: Record<string, MaterialInput>;
+}
+export interface Style {
+    width: number;
+    height: number;
+    aspect: number;
+    chars: string[];
+    pitch: number;
+    fitPitch: number;
+    spin: number;
+    distance: number;
+    zoom: number;
+    light: Vec3;
+    ambient: number;
+    shading: 'auto' | 'flat' | 'smooth';
+    supersample: number;
+    coverage: number;
+    edges: EdgeMode;
+    edgeChars: string[];
+    edgeThreshold: number;
+    color: ResolvedColor;
+    /** 0 = smooth; otherwise the number of gradient colors (default: the ramp length) */
+    colorSteps: number;
+    materials: Record<string, MaterialInput>;
+}
+export declare const DEFAULTS: {
+    width: number;
+    height: number;
+    aspect: number;
+    charset: string;
+    pitch: number;
+    spin: number;
+    distance: number;
+    zoom: number;
+    light: Vec3;
+    ambient: number;
+    shading: "auto";
+    supersample: number;
+    coverage: number;
+    edgeChars: string;
+    edgeThreshold: number;
+};
+/** Later inputs win; materials are merged by name. */
+export declare function mergeStyles(...inputs: (StyleInput | undefined)[]): StyleInput;
+export declare function resolveRamp(chars: string | undefined, charset: string | undefined): string[];
+export declare function resolveStyle(input?: StyleInput): Style;
+export declare function parseHex(hex: string): RGB;
+export declare function resolveColor(c: ColorInput | undefined): ResolvedColor;
+export declare function resolveMaterial(name: string, input: MaterialInput | undefined): ResolvedMaterial;