sprite-machine 0.1.0

package/src/carve.js

@@ -0,0 +1,198 @@
+// ---------------------------------------------------------------------------
+// Carve: reconcile grid dimensions from the ingested views, then compute the
+// visual hull = intersection of every provided view's extruded silhouette.
+//
+// Insight that keeps this simple: each view projects onto ONE of three planes
+//   FRONT/BACK -> X-Y,  LEFT/RIGHT -> Z-Y,  TOP/BOTTOM -> X-Z.
+// The two views of a pair produce the same silhouette (mirror images), so for
+// CARVING a single view per plane fully constrains that axis. Mirroring is only
+// needed for COLOR (see colorize.js). So carving is: UNION the views within
+// each plane (opposite silhouettes are identical in theory, so this is robust
+// to a 1-texel registration slip between hand-drawn opposite sprites — see
+// carve()), then AND across the planes. No camera math, no CSG.
+// ---------------------------------------------------------------------------
+
+import { placeView } from './ingest.js';
+import { VIEWS, VIEW_AXES, FACE_KEYS, FACE_NORMAL } from './views.js';
+
+export const voxIndex = (x, y, z, d) => x + d.nx * (y + d.ny * z);
+
+/** Inverse of voxIndex: linear grid index -> {x,y,z}. Kept next to voxIndex so
+ * the forward and inverse packing can't drift. */
+export const unvoxIndex = (idx, d) => {
+  const z = (idx / (d.nx * d.ny)) | 0;
+  const rem = idx - z * d.nx * d.ny;
+  const y = (rem / d.nx) | 0;
+  return { x: rem - y * d.nx, y, z };
+};
+
+/**
+ * Reconcile one integer resolution per axis from the (uncropped) tile sizes.
+ * For a well-formed sheet every view is the same size, so each axis has a single
+ * candidate and the grid is exactly the tile size. Unequal sizes (a malformed
+ * sheet, or non-square tiles whose depth differs between side-width and
+ * top-height) take the max and warn — the shorter view under-constrains the tail.
+ * @param {Record<string, {w:number,h:number}>} views  provided views by name
+ * @returns {{dims:{nx:number,ny:number,nz:number}, warnings:string[]}}
+ */
+export function reconcileDims(views) {
+  const cand = { nx: [], ny: [], nz: [] };
+  for (const [name, v] of Object.entries(views)) {
+    if (!v) continue;
+    const [wAxis, hAxis] = VIEW_AXES[name];
+    cand[wAxis].push(v.w);
+    cand[hAxis].push(v.h);
+  }
+  const warnings = [];
+  const pick = (axis, label) => {
+    const c = cand[axis];
+    if (c.length === 0) {
+      warnings.push(
+        `Axis ${label} is unconstrained (no view observes it); defaulting to 1. ` +
+          `Provide a view that sees ${label} for real depth.`
+      );
+      return 1;
+    }
+    const mn = Math.min(...c);
+    const mx = Math.max(...c);
+    if (mn !== mx) {
+      warnings.push(
+        `Views disagree on ${label} (${c.join(', ')}); strict registration ` +
+          `expects uniform, square tiles. Using ${mx}; a smaller view is placed ` +
+          `from the origin (not re-centered) and leaves the far end of ${label} ` +
+          `uncarved — check the atlas tile size.`
+      );
+    }
+    return mx;
+  };
+  const dims = { nx: pick('nx', 'X'), ny: pick('ny', 'Y'), nz: pick('nz', 'Z') };
+  return { dims, warnings };
+}
+
+/**
+ * Place each provided view into the reconciled (imgW,imgH) grid at NATIVE scale
+ * and IDENTITY position (offX=offY=0) — strict registration: a tile's texel
+ * (u,v) is a fixed lattice line, so it is NOT re-centered or bottom-anchored.
+ * For a well-formed (uniform-tile) sheet each view already equals the grid on
+ * the axes it constrains, so this is a 1:1 copy. There is no auto ground-rest:
+ * where the object sits in Y is wherever the artist painted it (paint at the
+ * tile's bottom rows to rest on y=0). A malformed sheet with unequal-size views
+ * lands each at the origin and warns (reconcileDims).
+ * @returns {Record<string,{occ:Uint8Array,rgb:Uint32Array,imgW:number,imgH:number}>}
+ */
+export function gridViews(views, dims) {
+  /** @type {Record<string, {occ:Uint8Array,rgb:Uint32Array,imgW:number,imgH:number}>} */
+  const out = {};
+  for (const [name, v] of Object.entries(views)) {
+    if (!v) continue;
+    const spec = VIEWS[name];
+    const imgW = spec.imgW(dims);
+    const imgH = spec.imgH(dims);
+    const { occ, rgb } = placeView(v, imgW, imgH, 0, 0);
+    out[name] = { occ, rgb, imgW, imgH };
+  }
+  return out;
+}
+
+/**
+ * Carve the visual hull.
+ * @param {Record<string,{occ:Uint8Array,imgW:number}>} gviews grid-sized views
+ * @param {{nx:number,ny:number,nz:number}} dims
+ * @returns {Uint8Array} solid occupancy, length nx*ny*nz
+ */
+export function carve(gviews, dims) {
+  const { nx, ny, nz } = dims;
+  const solid = new Uint8Array(nx * ny * nz).fill(1);
+  const active = Object.entries(gviews);
+  // Contract: with no views, nothing carves — the grid stays filled to its
+  // bounding box. reconcileDims defaults every unconstrained axis to 1, so a
+  // fully empty input yields a single solid voxel (pipeline.js warns about it).
+  if (active.length === 0) return solid;
+
+  // Group the provided views by the projection PLANE they constrain
+  // (front/back -> X-Y, left/right -> Z-Y, top/bottom -> X-Z). A real solid's
+  // two opposite silhouettes are identical, so WITHIN a plane we UNION the
+  // views — a voxel is covered if ANY view on that plane sees it. This is what
+  // the header means by "a single view per plane fully constrains that axis":
+  // the opposite view is redundant for carving, not an extra constraint.
+  // ANDing the pair instead lets a 1-texel registration slip between two
+  // hand-drawn opposite sprites erode thin protrusions — e.g. a car's side
+  // mirror that survives in the top sprite but sits one row over in the bottom
+  // sprite has an empty top∧bottom intersection, so its outer column vanishes.
+  // We then intersect ACROSS the (up to three) planes to get the visual hull.
+  const planes = new Map(); // planeKey -> [{spec, occ, imgW}, ...]
+  for (const [name, gv] of active) {
+    const key = VIEW_AXES[name].join(); // e.g. 'nx,ny' — one key per plane
+    const group = planes.get(key) || planes.set(key, []).get(key);
+    group.push({ spec: VIEWS[name], occ: gv.occ, imgW: gv.imgW });
+  }
+  const planeList = [...planes.values()];
+
+  // One reused scratch for the projection (projectInto mutates it) so the hot
+  // triple loop below allocates nothing per voxel × view.
+  const p = { u: 0, v: 0 };
+  for (let z = 0; z < nz; z++) {
+    for (let y = 0; y < ny; y++) {
+      for (let x = 0; x < nx; x++) {
+        const idx = voxIndex(x, y, z, dims);
+        for (const group of planeList) {
+          let covered = false;
+          for (const { spec, occ, imgW } of group) {
+            spec.projectInto(x, y, z, dims, p);
+            if (occ[p.v * imgW + p.u]) {
+              covered = true;
+              break;
+            }
+          }
+          if (!covered) {
+            solid[idx] = 0;
+            break;
+          }
+        }
+      }
+    }
+  }
+  return solid;
+}
+
+// 6 axis-neighbor offsets in FACE_KEYS order — the outward normals themselves.
+// Derived from FACE_NORMAL so they can't drift from the face convention.
+const NEIGHBORS = FACE_KEYS.map((k) => FACE_NORMAL[k]);
+
+/**
+ * Extract surface voxels: a solid voxel with >=1 empty/out-of-bounds neighbor.
+ * Also tallies the total solid count in the same pass (every voxel is visited and
+ * gated on solid here), so the pipeline needn't re-walk the grid a third time.
+ * @returns {{surfaceMask:Uint8Array, count:number, solidCount:number}}
+ *   surfaceMask[idx] holds a 6-bit exposure mask (bit i => FACE_KEYS[i] exposed);
+ *   count = surface voxels; solidCount = all solid voxels (surface + interior).
+ */
+export function extractSurface(solid, dims) {
+  const { nx, ny, nz } = dims;
+  const surfaceMask = new Uint8Array(nx * ny * nz);
+  let count = 0;
+  let solidCount = 0;
+  for (let z = 0; z < nz; z++) {
+    for (let y = 0; y < ny; y++) {
+      for (let x = 0; x < nx; x++) {
+        const idx = voxIndex(x, y, z, dims);
+        if (!solid[idx]) continue;
+        solidCount++;
+        let mask = 0;
+        for (let f = 0; f < 6; f++) {
+          const [dx, dy, dz] = NEIGHBORS[f];
+          const ax = x + dx,
+            ay = y + dy,
+            az = z + dz;
+          const outside = ax < 0 || ay < 0 || az < 0 || ax >= nx || ay >= ny || az >= nz;
+          if (outside || !solid[voxIndex(ax, ay, az, dims)]) mask |= 1 << f;
+        }
+        if (mask) {
+          surfaceMask[idx] = mask;
+          count++;
+        }
+      }
+    }
+  }
+  return { surfaceMask, count, solidCount };
+}

package/src/colorize.js

@@ -0,0 +1,228 @@
+// ---------------------------------------------------------------------------
+// Colorize: assign a color to every EXPOSED face of every surface voxel.
+//
+// The corrected rule (the naive "stamp one sprite pixel down the whole depth
+// ray" smears color and was rejected):
+//   SURFACE-ONLY, PER-EXPOSED-FACE, DEPTH-AWARE (first-hit), CLOSEST-FACE-NORMAL,
+//   NEAREST-PALETTE.
+//
+// For each exposed face f with outward normal n:
+//   1. Facing view = the view whose normal == n. Sample it ONLY IF this voxel
+//      is the first solid hit marching from that view inward — i.e. nothing
+//      solid lies beyond the face along +n. This is what prevents a recessed
+//      step wall from being painted with the protruding front pixel's color.
+//   2. Else, if mirror-fill is enabled for this face's axis (on by default for
+//      all axes) and the OPPOSITE view exists, sample it mirrored (symmetry).
+//   3. Else relax: average already-assigned neighbor face colors.
+//   4. Else: the object's dominant body color.
+// Every sampled color is snapped to the sprite palette so AA fringe never
+// produces a muddy off-palette pixel.
+// ---------------------------------------------------------------------------
+
+import { unpackRGBA, packRGBA } from './ingest.js';
+import { voxIndex, unvoxIndex } from './carve.js';
+import {
+  VIEWS,
+  FACE_KEYS,
+  FACE_NORMAL,
+  FACE_TO_VIEW,
+  FACE_OPPOSITE,
+  FACE_AXIS,
+} from './views.js';
+import { DEFAULT_MIRROR } from './constants.js';
+
+/** Build the deduped palette (union of all solid sprite pixels). */
+export function buildPalette(gviews) {
+  const seen = new Set();
+  const palette = [];
+  for (const gv of Object.values(gviews)) {
+    const { occ, rgb } = gv;
+    for (let i = 0; i < occ.length; i++) {
+      if (!occ[i]) continue;
+      const c = rgb[i] >>> 0;
+      if (!seen.has(c)) {
+        seen.add(c);
+        palette.push(c);
+      }
+    }
+  }
+  return palette;
+}
+
+export function makeSnapper(palette) {
+  const cache = new Map();
+  // Unpack each palette entry once (keeping its packed value) instead of
+  // re-splitting bytes on every query iteration.
+  const pal = palette.map((c) => ({ c: c >>> 0, ...unpackRGBA(c) }));
+  return (color) => {
+    const key = color >>> 0;
+    const hit = cache.get(key);
+    if (hit !== undefined) return hit;
+    const { r, g, b } = unpackRGBA(key);
+    let best = key;
+    let bestD = Infinity;
+    for (const p of pal) {
+      const d = (r - p.r) ** 2 + (g - p.g) ** 2 + (b - p.b) ** 2;
+      if (d < bestD) {
+        bestD = d;
+        best = p.c;
+      }
+    }
+    cache.set(key, best);
+    return best;
+  };
+}
+
+/** Is `(x,y,z)`'s face `faceKey` the first solid hit from its facing view? */
+function firstHitFromFace(solid, dims, x, y, z, faceKey) {
+  const [nx, ny, nz] = FACE_NORMAL[faceKey];
+  let cx = x + nx,
+    cy = y + ny,
+    cz = z + nz;
+  while (cx >= 0 && cy >= 0 && cz >= 0 && cx < dims.nx && cy < dims.ny && cz < dims.nz) {
+    if (solid[voxIndex(cx, cy, cz, dims)]) return false; // occluded
+    cx += nx;
+    cy += ny;
+    cz += nz;
+  }
+  return true;
+}
+
+// One reused scratch — sampleView reads the projection immediately, so mutating a
+// shared object avoids a per-exposed-face allocation.
+const _sampleP = { u: 0, v: 0 };
+function sampleView(gv, name, x, y, z, dims) {
+  VIEWS[name].projectInto(x, y, z, dims, _sampleP);
+  const i = _sampleP.v * gv.imgW + _sampleP.u;
+  return gv.occ[i] ? gv.rgb[i] >>> 0 : null;
+}
+
+/**
+ * @param {Uint8Array} solid
+ * @param {Uint8Array} surfaceMask  6-bit exposure per voxel
+ * @param {Record<string,{occ,rgb,imgW,imgH}>} gviews
+ * @param {{nx,ny,nz}} dims
+ * @param {{mirror?:{x?:boolean,y?:boolean,z?:boolean}}} [opts]
+ * @returns {{faceColor: Map<number, number>, palette: number[]}}
+ *   faceColor key = idx*6 + faceIndex, value = packed RGBA; palette = solid colors.
+ */
+export function colorize(solid, surfaceMask, gviews, dims, opts = {}) {
+  const mirror = { ...DEFAULT_MIRROR, ...(opts.mirror || {}) };
+  const palette = buildPalette(gviews);
+  const snap = palette.length ? makeSnapper(palette) : (c) => c;
+  const faceColor = new Map();
+  const pending = []; // faces needing relaxation/fallback
+
+  for (let idx = 0; idx < surfaceMask.length; idx++) {
+    const mask = surfaceMask[idx];
+    if (!mask) continue;
+    const { x, y, z } = unvoxIndex(idx, dims);
+
+    for (let f = 0; f < 6; f++) {
+      if (!(mask & (1 << f))) continue;
+      const faceKey = FACE_KEYS[f];
+      const key = idx * 6 + f;
+
+      // firstHitFromFace is invariant for this face; memoize so the facing and
+      // mirror branches march the depth ray at most once between them.
+      let firstHit;
+      const isFirstHit = () =>
+        (firstHit ??= firstHitFromFace(solid, dims, x, y, z, faceKey));
+
+      // 1. Facing view, depth-gated.
+      const facing = FACE_TO_VIEW[faceKey];
+      let color = null;
+      if (gviews[facing] && isFirstHit()) {
+        color = sampleView(gviews[facing], facing, x, y, z, dims);
+      }
+      // 2. Mirrored opposite view.
+      if (color == null && mirror[FACE_AXIS[faceKey]]) {
+        const opp = FACE_TO_VIEW[FACE_OPPOSITE[faceKey]];
+        if (gviews[opp] && isFirstHit()) {
+          color = sampleView(gviews[opp], opp, x, y, z, dims);
+        }
+      }
+      if (color != null) faceColor.set(key, snap(color));
+      else pending.push({ key, idx, x, y, z, f });
+    }
+  }
+
+  // 3. Relaxation: average already-colored neighbors (few passes).
+  const TANGENTIAL = {
+    x: [
+      [0, 1, 0],
+      [0, -1, 0],
+      [0, 0, 1],
+      [0, 0, -1],
+    ],
+    y: [
+      [1, 0, 0],
+      [-1, 0, 0],
+      [0, 0, 1],
+      [0, 0, -1],
+    ],
+    z: [
+      [1, 0, 0],
+      [-1, 0, 0],
+      [0, 1, 0],
+      [0, -1, 0],
+    ],
+  };
+  for (let pass = 0; pass < 4 && pending.length; pass++) {
+    const still = [];
+    for (const item of pending) {
+      const faceKey = FACE_KEYS[item.f];
+      let r = 0,
+        g = 0,
+        b = 0,
+        n = 0;
+      // same voxel, other colored faces
+      for (let f2 = 0; f2 < 6; f2++) {
+        const c = faceColor.get(item.idx * 6 + f2);
+        if (c != null) {
+          const u = unpackRGBA(c);
+          r += u.r;
+          g += u.g;
+          b += u.b;
+          n++;
+        }
+      }
+      // same face on tangential neighbor voxels
+      for (const [dx, dy, dz] of TANGENTIAL[FACE_AXIS[faceKey]]) {
+        const ax = item.x + dx,
+          ay = item.y + dy,
+          az = item.z + dz;
+        if (ax < 0 || ay < 0 || az < 0) continue;
+        if (ax >= dims.nx || ay >= dims.ny || az >= dims.nz) continue;
+        const c = faceColor.get(voxIndex(ax, ay, az, dims) * 6 + item.f);
+        if (c != null) {
+          const u = unpackRGBA(c);
+          r += u.r;
+          g += u.g;
+          b += u.b;
+          n++;
+        }
+      }
+      if (n > 0) {
+        faceColor.set(
+          item.key,
+          snap(packRGBA(Math.round(r / n), Math.round(g / n), Math.round(b / n)))
+        );
+      } else still.push(item);
+    }
+    pending.length = 0;
+    pending.push(...still);
+  }
+
+  // 4. Dominant body color for anything left.
+  if (pending.length) {
+    const tally = new Map();
+    for (const c of faceColor.values()) tally.set(c, (tally.get(c) || 0) + 1);
+    let dom = palette[0] ?? packRGBA(200, 200, 200);
+    let domN = -1;
+    for (const [c, k] of tally) if (k > domN) (domN = k), (dom = c);
+    for (const item of pending) faceColor.set(item.key, dom);
+  }
+
+  return { faceColor, palette };
+}

package/src/constants.js

@@ -0,0 +1,20 @@
+// ---------------------------------------------------------------------------
+// The engine's defaults. Centralized so the pipeline, the mesher and every
+// consumer can never drift on what "the defaults" are. Import and spread
+// (`{ ...DEFAULT_MIRROR }`) rather than mutating these objects in place.
+// (The editor's palettes, which shared this file before the engine became a
+// package, are the app's src/lib/palette.js.)
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-axis mirror-fill: a face with no view of its own is always filled from the
+ * mirrored opposite view. On for every axis — objects are treated as symmetric,
+ * so a half-drawn sheet (e.g. no LEFT/BACK/BOTTOM) still colors every face.
+ */
+export const DEFAULT_MIRROR = { x: true, y: true, z: true };
+
+/**
+ * World-space size the largest grid axis is scaled to fill — the app's stage
+ * units. A headless build (model.js) uses one unit per voxel instead.
+ */
+export const DEFAULT_WORLD_SIZE = 2.5;

package/src/diag.js

@@ -0,0 +1,68 @@
+// ---------------------------------------------------------------------------
+// Geometry self-check — a dev probe (the app reads it under ?diag=1; a
+// consumer can read it off any built mesh). Watertightness via
+// position-based edge parity + a per-face normal histogram: a closed surface
+// uses every undirected edge exactly twice; edges used an odd number of times
+// are boundaries — a genuine hole in a mesh that should be closed.
+//
+// MODE MATTERS: a nonzero boundary/odd count is only a "hole" for a mesh that
+// claims to be watertight. The low-poly (wedge) mesh is — its T-junctions are
+// repaired (t-junction.js) — but the greedy-voxel mesh (low-poly OFF) deliberately
+// leaves its step-riser T-junctions unrepaired, so it reports nonzero boundary/odd
+// edges as EXPECTED artifacts, not holes. main.js tags the ?diag=1 title with the
+// mode so the two conditions aren't conflated. This function just counts; it never
+// asserts watertightness on its own.
+// ---------------------------------------------------------------------------
+
+/** @param {import('three').BufferGeometry} geo */
+export function computeDiag(geo) {
+  const pos = geo.attributes.position.array;
+  const nrm = geo.attributes.normal.array;
+  const idx = geo.index ? geo.index.array : null;
+  const triCount = idx ? idx.length / 3 : pos.length / 9;
+  const key = (i) => {
+    const x = Math.round(pos[i * 3] * 1e4);
+    const y = Math.round(pos[i * 3 + 1] * 1e4);
+    const z = Math.round(pos[i * 3 + 2] * 1e4);
+    return x + ',' + y + ',' + z;
+  };
+  const edges = new Map();
+  const axis = (i) => {
+    const ax = Math.abs(nrm[i * 3]),
+      ay = Math.abs(nrm[i * 3 + 1]),
+      az = Math.abs(nrm[i * 3 + 2]);
+    if (ax >= ay && ax >= az) return nrm[i * 3] > 0 ? 'px' : 'nx';
+    if (ay >= az) return nrm[i * 3 + 1] > 0 ? 'py' : 'ny';
+    return nrm[i * 3 + 2] > 0 ? 'pz' : 'nz';
+  };
+  const hist = { px: 0, nx: 0, py: 0, ny: 0, pz: 0, nz: 0 };
+  for (let t = 0; t < triCount; t++) {
+    const a = idx ? idx[t * 3] : t * 3;
+    const b = idx ? idx[t * 3 + 1] : t * 3 + 1;
+    const c = idx ? idx[t * 3 + 2] : t * 3 + 2;
+    hist[axis(a)]++;
+    for (const [p, q] of [
+      [a, b],
+      [b, c],
+      [c, a],
+    ]) {
+      const ka = key(p),
+        kb = key(q);
+      const e = ka < kb ? ka + '|' + kb : kb + '|' + ka;
+      edges.set(e, (edges.get(e) || 0) + 1);
+    }
+  }
+  let boundary = 0,
+    odd = 0;
+  for (const n of edges.values()) {
+    if (n === 1) boundary++;
+    if (n % 2 === 1) odd++;
+  }
+  return {
+    triCount,
+    hist,
+    uniqueEdges: edges.size,
+    boundaryEdges: boundary,
+    oddEdges: odd,
+  };
+}

package/src/faces.js

@@ -0,0 +1,69 @@
+// ---------------------------------------------------------------------------
+// The face vocabulary's GEOMETRY: for each face key, the axes its plane spans
+// (A, B — the tangent frame every 2D read of a face uses: the regions, the
+// skin's charts and the UV read) and the axis it faces along (N), plus the two
+// lattice reads built on them — a tangent coordinate's voxel index (idxFor)
+// and its 3D point (pointOf). Pure, no THREE, Node-testable.
+//
+// A face's plane sits at slice s along N: at s for a negative face (the
+// voxel's near side), at s + 1 for a positive one. Tangent (a, b) is the
+// voxel's own A/B coordinate, so the unit square [a, a+1] × [b, b+1] on the
+// plane IS that voxel's face, and a texel per face is a texel per unit
+// square — the skin's orientation rule, stated once (skin.js).
+//
+// Until Sep 7 2026 this module also merged faces into greedy rectangles
+// (culledQuads / greedyQuads); the mesher traces coplanar REGIONS now
+// (regions.js) — a rectangle being the region with four corners — so the quad
+// builders went with their last consumer.
+// ---------------------------------------------------------------------------
+
+import { voxIndex } from './carve.js';
+import { FACE_NORMAL, AXIS_INDEX } from './views.js';
+
+// Per-face tangent axes and the normal axis. The outward normal is read from
+// the shared FACE_NORMAL (views.js), not restated here.
+export const FACE_GEO = {
+  px: { N: 'x', A: 'y', B: 'z' },
+  nx: { N: 'x', A: 'y', B: 'z' },
+  py: { N: 'y', A: 'x', B: 'z' },
+  ny: { N: 'y', A: 'x', B: 'z' },
+  pz: { N: 'z', A: 'x', B: 'y' },
+  nz: { N: 'z', A: 'x', B: 'y' },
+};
+
+/**
+ * The voxel index behind tangent coords (a, b) on slice s of `face` — the
+ * lattice cell whose face that is. One home: the regions, the skin's baker
+ * and every test compose it here.
+ * @param {string} face  a FACE_KEYS key
+ * @param {number} a  along FACE_GEO[face].A
+ * @param {number} b  along FACE_GEO[face].B
+ * @param {number} s  the slice along FACE_GEO[face].N
+ * @param {{nx:number, ny:number, nz:number}} dims
+ */
+export function idxFor(face, a, b, s, dims) {
+  const g = FACE_GEO[face];
+  const c = { x: 0, y: 0, z: 0 };
+  c[g.N] = s;
+  c[g.A] = a;
+  c[g.B] = b;
+  return voxIndex(c.x, c.y, c.z, dims);
+}
+
+/**
+ * The 3D lattice point at tangent (a, b) on the plane of `face` at slice s —
+ * the plane at s + 1 for a positive face, at s for a negative one.
+ * @param {string} face
+ * @param {number} a
+ * @param {number} b
+ * @param {number} s
+ * @returns {number[]}
+ */
+export function pointOf(face, a, b, s) {
+  const g = FACE_GEO[face];
+  const c = { x: 0, y: 0, z: 0 };
+  c[g.N] = s + (FACE_NORMAL[face][AXIS_INDEX[g.N]] > 0 ? 1 : 0);
+  c[g.A] = a;
+  c[g.B] = b;
+  return [c.x, c.y, c.z];
+}