@rig-c/parts 0.0.0-stage → 1.5.4

package/src/pyfmt.ts

@@ -0,0 +1,135 @@
+/**
+ * The handful of Python numeric and text semantics the proposer's outputs
+ * depend on, written once so no call site open-codes them.
+ *
+ * The reference proposer is Python, and three of its behaviours are not
+ * JavaScript's:
+ *
+ * - `round(x)` rounds half to EVEN (`round(2.5) == 2`), where `Math.round`
+ *   rounds half up. Every bone coordinate goes through it (`rnd`), and a part
+ *   box of even width puts its centre on a half pixel, so this decides real
+ *   coordinates, not an edge case.
+ * - `format(x, '.nf')` rounds the exact binary value correctly and breaks an
+ *   exact tie to even; `Number.prototype.toFixed` breaks it upward. The two
+ *   agree everywhere except an exact tie, which `pyFixed` detects.
+ * - `repr(str)` quotes with `'` unless the string holds a `'` and no `"`. The
+ *   LINT line prints a mesh name through it, and its format is kept verbatim.
+ *
+ * numpy's `mean`, `median` and `percentile` are here too, with numpy's own
+ * summation order and interpolation, so a summary line reads the same figure
+ * the reference printed.
+ */
+
+/** Python's `round(x)` on a float: nearest integer, ties to even. */
+export function pyRound(x: number): number {
+  const f = Math.floor(x);
+  const d = x - f;
+  if (d > 0.5) return f + 1;
+  if (d < 0.5) return f;
+  return f % 2 === 0 ? f : f + 1;
+}
+
+/** Python's `int(x)` on a float: truncation toward zero, with no negative zero. */
+export function pyInt(x: number): number {
+  const t = Math.trunc(x);
+  return t === 0 ? 0 : t;
+}
+
+/**
+ * Python's `format(x, '.<digits>f')`. `toFixed` is correctly rounded except on
+ * an exact decimal tie, which it breaks upward and Python breaks to even. A
+ * tie is recognised from `toFixed(digits + 20)`: a double near any value
+ * printed here is spaced far wider than 1e-20, so digits past the tie are
+ * either all zero (a true tie) or not a tie at all.
+ */
+export function pyFixed(x: number, digits: number): string {
+  if (!Number.isFinite(x)) return String(x);
+  const long = Math.abs(x).toFixed(digits + 20);
+  const tail = long.slice(long.length - 20);
+  if (tail !== `5${'0'.repeat(19)}`) return x.toFixed(digits);
+  // An exact tie: `head` is |x| truncated to `digits` places, and the tie goes to whichever neighbour is even.
+  const head = long.slice(0, long.length - 20).replace(/\.$/, '');
+  const last = Number(head.replace('.', '').slice(-1));
+  const scale = 10 ** digits;
+  const magnitude = last % 2 === 0 ? Number(head) : (Math.round(Number(head) * scale) + 1) / scale;
+  return `${x < 0 ? '-' : ''}${magnitude.toFixed(digits)}`;
+}
+
+/** Python's `repr(s)` for the strings the proposer prints: part and bone names. */
+export function pyRepr(s: string): string {
+  const quote = s.includes("'") && !s.includes('"') ? '"' : "'";
+  let out = '';
+  for (const ch of s) {
+    if (ch === '\\') out += '\\\\';
+    else if (ch === quote) out += `\\${quote}`;
+    else if (ch === '\n') out += '\\n';
+    else if (ch === '\t') out += '\\t';
+    else if (ch === '\r') out += '\\r';
+    else out += ch;
+  }
+  return `${quote}${out}${quote}`;
+}
+
+/** Python's `str(list_of_str)`: `['a', 'b']`. */
+export function pyStrList(items: readonly string[]): string {
+  return `[${items.map(pyRepr).join(', ')}]`;
+}
+
+/** Python's `str([int, int])`: `[335, 330]`. */
+export function pyIntList(items: readonly number[]): string {
+  return `[${items.map((n) => String(n)).join(', ')}]`;
+}
+
+/**
+ * numpy's float64 `sum`: its pairwise summation, which for fewer than 8
+ * values is a plain loop and up to 128 values is eight strided accumulators
+ * combined as `((r0+r1)+(r2+r3))+((r4+r5)+(r6+r7))`, then the remainder.
+ */
+export function npSum(a: readonly number[]): number {
+  const pairwise = (lo: number, n: number): number => {
+    if (n < 8) {
+      let s = 0;
+      for (let i = 0; i < n; i++) s += a[lo + i];
+      return s;
+    }
+    if (n <= 128) {
+      const r = [0, 1, 2, 3, 4, 5, 6, 7].map((k) => a[lo + k]);
+      let i = 8;
+      for (; i < n - (n % 8); i += 8) for (let k = 0; k < 8; k++) r[k] += a[lo + i + k];
+      let s = r[0] + r[1] + (r[2] + r[3]) + (r[4] + r[5] + (r[6] + r[7]));
+      for (; i < n; i++) s += a[lo + i];
+      return s;
+    }
+    let n2 = Math.floor(n / 2);
+    n2 -= n2 % 8;
+    return pairwise(lo, n2) + pairwise(lo + n2, n - n2);
+  };
+  return pairwise(0, a.length);
+}
+
+export function npMean(a: readonly number[]): number {
+  return npSum(a) / a.length;
+}
+
+export function npMedian(a: readonly number[]): number {
+  const s = [...a].sort((x, y) => x - y);
+  const n = s.length;
+  if (n % 2 === 1) return s[(n - 1) / 2];
+  // numpy takes the mean of the two middle values.
+  return npMean([s[n / 2 - 1], s[n / 2]]);
+}
+
+/** `np.percentile(a, q)` with the default linear method, numpy's index and lerp arithmetic included. */
+export function npPercentile(a: readonly number[], q: number): number {
+  const s = [...a].sort((x, y) => x - y);
+  const n = s.length;
+  const quantile = q / 100;
+  const virtual = n * quantile + (1 + quantile * (1 - 1 - 1)) - 1;
+  const clampIndex = (i: number): number => Math.min(Math.max(i, 0), n - 1);
+  const previous = Math.floor(virtual);
+  const gamma = virtual - previous;
+  const lo = s[clampIndex(previous)];
+  const hi = s[clampIndex(previous + 1)];
+  const diff = hi - lo;
+  return gamma >= 0.5 ? hi - diff * (1 - gamma) : lo + diff * gamma;
+}

package/src/raster/blur.ts

@@ -0,0 +1,80 @@
+import { type FloatImage, newFloatImage, RasterError } from './types.ts';
+
+/**
+ * The kernel size cv2 derives when it is asked for `ksize = (0, 0)`:
+ * `round(sigma * 4 * 2 + 1) | 1` for a floating-point image. (For an 8-bit
+ * image cv2 uses 3 sigma instead of 4; every call this port makes blurs a
+ * float image, so that is the only rule implemented, and it is named.)
+ */
+export function gaussianKernelSize(sigma: number): number {
+  return Math.round(sigma * 4 * 2 + 1) | 1;
+}
+
+/** `cv2.getGaussianKernel(ksize, sigma)`: `exp(-(i - (ksize-1)/2)^2 / (2 sigma^2))`, normalised to sum 1. */
+export function gaussianKernel(ksize: number, sigma: number): Float64Array {
+  if (!Number.isInteger(ksize) || ksize < 1 || ksize % 2 === 0) {
+    throw new RasterError(`gaussianKernel: ksize ${ksize}; a positive odd integer is required`);
+  }
+  if (!(sigma > 0) || !Number.isFinite(sigma)) {
+    throw new RasterError(`gaussianKernel: sigma ${sigma}; a positive finite number is required`);
+  }
+  const k = new Float64Array(ksize);
+  const c = (ksize - 1) / 2;
+  let sum = 0;
+  for (let i = 0; i < ksize; i++) {
+    const x = i - c;
+    k[i] = Math.exp(-(x * x) / (2 * sigma * sigma));
+    sum += k[i];
+  }
+  for (let i = 0; i < ksize; i++) k[i] /= sum;
+  return k;
+}
+
+/** cv2's `BORDER_REFLECT_101` (its default): `-1 -> 1`, `n -> n - 2`, no edge sample repeated. */
+function reflect101(i: number, n: number): number {
+  if (n === 1) return 0;
+  let p = i;
+  while (p < 0 || p >= n) {
+    if (p < 0) p = -p;
+    if (p >= n) p = 2 * (n - 1) - p;
+  }
+  return p;
+}
+
+/**
+ * `cv2.GaussianBlur(img, (0, 0), sigma)` on a float image, every channel
+ * independently: the separable kernel above, horizontal pass then vertical,
+ * border `REFLECT_101`.
+ *
+ * Computed in float64 and stored as float32; cv2 accumulates a float32 image
+ * in float32, so the two differ in the last bits of a sample. Measured against
+ * cv2 4.13 over 18,257 samples (1 and 4 channels, sigma 0.5 to 3): largest
+ * difference 3.1e-5.
+ */
+export function gaussianBlur(src: FloatImage, sigma: number): FloatImage {
+  const ksize = gaussianKernelSize(sigma);
+  const k = gaussianKernel(ksize, sigma);
+  const r = (ksize - 1) / 2;
+  const { width: w, height: h, channels: ch } = src;
+  const tmp = new Float64Array(w * h * ch);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      for (let c = 0; c < ch; c++) {
+        let s = 0;
+        for (let i = 0; i < ksize; i++) s += k[i] * src.data[(y * w + reflect101(x + i - r, w)) * ch + c];
+        tmp[(y * w + x) * ch + c] = s;
+      }
+    }
+  }
+  const out = newFloatImage(w, h, ch);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      for (let c = 0; c < ch; c++) {
+        let s = 0;
+        for (let i = 0; i < ksize; i++) s += k[i] * tmp[(reflect101(y + i - r, h) * w + x) * ch + c];
+        out.data[(y * w + x) * ch + c] = s;
+      }
+    }
+  }
+  return out;
+}

package/src/raster/components.ts

@@ -0,0 +1,165 @@
+import { assertBinary, type Mask, RasterError } from './types.ts';
+
+/** One component's statistics, in the fields `cv2.connectedComponentsWithStats` returns. */
+export interface ComponentStats {
+  label: number;
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  area: number;
+  /** Mean x and y of the component's pixels — cv2's `centroids` row. */
+  cx: number;
+  cy: number;
+}
+
+export interface Components {
+  /** Labels including the background, which is label 0 — the `n` cv2 returns. */
+  count: number;
+  /** One label per pixel, row-major. */
+  labels: Int32Array;
+  /** `stats[0]` is the background (the zero pixels), as in cv2; components are 1..count-1. */
+  stats: ComponentStats[];
+}
+
+/**
+ * Label the connected components of a binary mask.
+ *
+ * Semantics of `cv2.connectedComponentsWithStats(mask, connectivity)` (the
+ * reference calls it with 8 for ghost clean-up and blob finding) and of
+ * `scipy.ndimage.label` with its default cross structure (connectivity 4, the
+ * reference's grid-cell islands): foreground is every non-zero pixel, label 0
+ * is the background, and components are numbered from 1 in the raster-scan
+ * order of their first pixel.
+ *
+ * Measured against cv2 4.13 and SciPy 1.17 on 40 random masks: component
+ * count, every label, every statistic and every centroid identical, for
+ * `connectedComponentsWithStats` at 4 and 8 and for `ndimage.label`.
+ *
+ * The numbering follows cv2 as well (see the block-order note in the body),
+ * but a caller that needs "the largest" or "the one touching a line" should
+ * still select by statistics: the numbering is an artefact of a scan order,
+ * and the statistics are the measurement.
+ */
+export function connectedComponents(mask: Mask, connectivity: 4 | 8): Components {
+  if (connectivity !== 4 && connectivity !== 8) {
+    throw new RasterError(`connectedComponents: connectivity ${String(connectivity)}; 4 or 8 is required`);
+  }
+  assertBinary('connectedComponents', mask);
+  const { width: w, height: h, data } = mask;
+  const provisional = new Int32Array(w * h);
+  const parent: number[] = [0];
+  const find = (x: number): number => {
+    let r = x;
+    while (parent[r] !== r) r = parent[r];
+    while (parent[x] !== r) {
+      const next = parent[x];
+      parent[x] = r;
+      x = next;
+    }
+    return r;
+  };
+  const union = (a: number, b: number): number => {
+    const ra = find(a);
+    const rb = find(b);
+    if (ra === rb) return ra;
+    // The smaller root wins, so a root is always the earliest provisional label
+    // of its component — which is what makes the final numbering a raster scan.
+    if (ra < rb) {
+      parent[rb] = ra;
+      return ra;
+    }
+    parent[ra] = rb;
+    return rb;
+  };
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const i = y * w + x;
+      if (data[i] === 0) continue;
+      let label = 0;
+      const take = (j: number): void => {
+        const l = provisional[j];
+        if (l === 0) return;
+        label = label === 0 ? find(l) : union(label, l);
+      };
+      if (x > 0) take(i - 1);
+      if (y > 0) {
+        take(i - w);
+        if (connectivity === 8) {
+          if (x > 0) take(i - w - 1);
+          if (x < w - 1) take(i - w + 1);
+        }
+      }
+      if (label === 0) {
+        label = parent.length;
+        parent.push(label);
+      }
+      provisional[i] = label;
+    }
+  }
+  // Final numbering. With 4-connectivity it is the raster order of each
+  // component's first pixel. With 8-connectivity it is the raster order of the
+  // first 2x2 BLOCK (rows 2k..2k+1, columns 2j..2j+1) holding one of its
+  // pixels — which is what cv2's block-based labeller produces, measured on 40
+  // random masks where a pixel-order numbering disagreed with cv2 on 31. One
+  // block can open at most one component under 8-connectivity, since its four
+  // pixels all touch, so the block order is total.
+  const final = new Int32Array(parent.length);
+  let count = 1;
+  const labels = new Int32Array(w * h);
+  const visit = (i: number): void => {
+    const p = provisional[i];
+    if (p === 0) return;
+    const root = find(p);
+    if (final[root] === 0) final[root] = count++;
+    labels[i] = final[root];
+  };
+  if (connectivity === 4) {
+    for (let i = 0; i < w * h; i++) visit(i);
+  } else {
+    for (let by = 0; by < h; by += 2) {
+      for (let bx = 0; bx < w; bx += 2) {
+        for (let dy = 0; dy < 2 && by + dy < h; dy++) {
+          for (let dx = 0; dx < 2 && bx + dx < w; dx++) visit((by + dy) * w + bx + dx);
+        }
+      }
+    }
+  }
+  const acc = Array.from({ length: count }, (_, label) => ({
+    label,
+    minX: Infinity,
+    minY: Infinity,
+    maxX: -Infinity,
+    maxY: -Infinity,
+    area: 0,
+    sx: 0,
+    sy: 0,
+  }));
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const a = acc[labels[y * w + x]];
+      a.area++;
+      a.sx += x;
+      a.sy += y;
+      if (x < a.minX) a.minX = x;
+      if (x > a.maxX) a.maxX = x;
+      if (y < a.minY) a.minY = y;
+      if (y > a.maxY) a.maxY = y;
+    }
+  }
+  const stats = acc.map((a) =>
+    a.area === 0
+      ? { label: a.label, left: 0, top: 0, width: 0, height: 0, area: 0, cx: Number.NaN, cy: Number.NaN }
+      : {
+          label: a.label,
+          left: a.minX,
+          top: a.minY,
+          width: a.maxX - a.minX + 1,
+          height: a.maxY - a.minY + 1,
+          area: a.area,
+          cx: a.sx / a.area,
+          cy: a.sy / a.area,
+        },
+  );
+  return { count, labels, stats };
+}

package/src/raster/composite.ts

@@ -0,0 +1,81 @@
+import { newRaster, type Raster, RasterError } from './types.ts';
+
+/** `((a >> 8) + a) >> 8` — PIL's divide-by-255 for the alpha compositor. */
+function shiftForDiv255(a: number): number {
+  return ((a >>> 8) + a) >>> 8;
+}
+
+const PRECISION_BITS = 7;
+
+/**
+ * `PIL.Image.alpha_composite` / `Image.alpha_composite(im, dest=(x, y))`:
+ * straight-alpha "over" of `src` onto a copy of `dst` with `src`'s top-left
+ * at (x, y), in PIL's own integer arithmetic (7-bit precision colour weights,
+ * divide-by-255 by shift). Pixels of `src` that fall outside `dst` are clipped;
+ * `dst` itself is not modified. Measured bit-exact against Pillow 12.2.0 over
+ * 24,296 samples.
+ */
+export function alphaComposite(dst: Raster, src: Raster, x = 0, y = 0): Raster {
+  if (!Number.isInteger(x) || !Number.isInteger(y)) {
+    throw new RasterError(`alphaComposite: offset ${x},${y} is not integral`);
+  }
+  const out: Raster = { width: dst.width, height: dst.height, data: new Uint8ClampedArray(dst.data) };
+  for (let sy = 0; sy < src.height; sy++) {
+    const dy = sy + y;
+    if (dy < 0 || dy >= dst.height) continue;
+    for (let sx = 0; sx < src.width; sx++) {
+      const dx = sx + x;
+      if (dx < 0 || dx >= dst.width) continue;
+      const s = (sy * src.width + sx) * 4;
+      const d = (dy * dst.width + dx) * 4;
+      const sa = src.data[s + 3];
+      if (sa === 0) continue;
+      const da = out.data[d + 3];
+      const blend = da * (255 - sa);
+      const outa255 = sa * 255 + blend;
+      const coef1 = Math.floor((sa * 255 * 255 * (1 << PRECISION_BITS)) / outa255);
+      const coef2 = 255 * (1 << PRECISION_BITS) - coef1;
+      for (let c = 0; c < 3; c++) {
+        const t = src.data[s + c] * coef1 + out.data[d + c] * coef2;
+        out.data[d + c] = shiftForDiv255(t + (0x80 << PRECISION_BITS)) >>> PRECISION_BITS;
+      }
+      out.data[d + 3] = shiftForDiv255(outa255 + 0x80);
+    }
+  }
+  return out;
+}
+
+/** The `w`x`h` window of `src` at (x, y). A window reaching outside `src` is refused, not padded. */
+export function crop(src: Raster, x: number, y: number, w: number, h: number): Raster {
+  if (![x, y, w, h].every(Number.isInteger) || w < 0 || h < 0) {
+    throw new RasterError(`crop: window ${x},${y} ${w}x${h} is not four integers with a non-negative size`);
+  }
+  if (x < 0 || y < 0 || x + w > src.width || y + h > src.height) {
+    throw new RasterError(`crop: window ${x},${y} ${w}x${h} reaches outside the ${src.width}x${src.height} raster`);
+  }
+  const out = newRaster(w, h);
+  for (let r = 0; r < h; r++) {
+    out.data.set(src.data.subarray(((y + r) * src.width + x) * 4, ((y + r) * src.width + x + w) * 4), r * w * 4);
+  }
+  return out;
+}
+
+/** `src` with `left`/`top`/`right`/`bottom` pixels of `fill` added round it (`np.pad` with a constant). */
+export function pad(
+  src: Raster,
+  left: number,
+  top: number,
+  right: number,
+  bottom: number,
+  fill: readonly [number, number, number, number],
+): Raster {
+  if (![left, top, right, bottom].every((v) => Number.isInteger(v) && v >= 0)) {
+    throw new RasterError(`pad: margins ${left},${top},${right},${bottom} are not four non-negative integers`);
+  }
+  const out = newRaster(src.width + left + right, src.height + top + bottom);
+  for (let i = 0; i < out.width * out.height; i++) out.data.set(fill, i * 4);
+  for (let r = 0; r < src.height; r++) {
+    out.data.set(src.data.subarray(r * src.width * 4, (r + 1) * src.width * 4), ((r + top) * out.width + left) * 4);
+  }
+  return out;
+}

package/src/raster/index.ts

@@ -0,0 +1,9 @@
+export * from './types.ts';
+export * from './components.ts';
+export * from './morph.ts';
+export * from './blur.ts';
+export * from './resize.ts';
+export * from './warp.ts';
+export * from './poly.ts';
+export * from './composite.ts';
+export * from './png.ts';

package/src/raster/morph.ts

@@ -0,0 +1,116 @@
+import { assertBinary, type Mask, newMask, RasterError } from './types.ts';
+
+function assertKernel(op: string, kw: number, kh: number): void {
+  if (!Number.isInteger(kw) || !Number.isInteger(kh) || kw < 1 || kh < 1) {
+    throw new RasterError(`${op}: kernel ${kw}x${kh} is not a pair of positive integers`);
+  }
+}
+
+/**
+ * One separable pass of a rectangular max (dilate) or min (erode) filter.
+ *
+ * The window for output `x` is `[x - anchor, x - anchor + k)`, anchor
+ * `floor(k / 2)` — cv2's default anchor `(-1, -1)` for a rectangular kernel,
+ * which is not centred for an even `k`. Pixels outside the image are simply
+ * not in the window, which is cv2's default border for morphology
+ * (`morphologyDefaultBorderValue`): the image edge never dilates anything in
+ * and never erodes anything away.
+ *
+ * `dilate`, `erode`, `morphClose`, `morphGradient` and `fillHoles` were each
+ * measured bit-exact against cv2 4.13 / SciPy 1.17 on 30 random masks (24,478
+ * pixels, kernels 1 to 7 wide and 1 to 5 tall, even sizes included).
+ */
+function pass(src: Uint8Array, w: number, h: number, k: number, horizontal: boolean, max: boolean): Uint8Array {
+  const out = new Uint8Array(w * h);
+  const anchor = Math.floor(k / 2);
+  const len = horizontal ? w : h;
+  const lines = horizontal ? h : w;
+  for (let line = 0; line < lines; line++) {
+    for (let p = 0; p < len; p++) {
+      const lo = Math.max(0, p - anchor);
+      const hi = Math.min(len - 1, p - anchor + k - 1);
+      let v = max ? 0 : 1;
+      for (let q = lo; q <= hi; q++) {
+        const s = horizontal ? src[line * w + q] : src[q * w + line];
+        if (max ? s === 1 : s === 0) {
+          v = max ? 1 : 0;
+          break;
+        }
+      }
+      out[horizontal ? line * w + p : p * w + line] = v;
+    }
+  }
+  return out;
+}
+
+/** `cv2.dilate(mask, np.ones((kh, kw)))` on a binary mask. */
+export function dilate(m: Mask, kw: number, kh: number = kw): Mask {
+  assertKernel('dilate', kw, kh);
+  assertBinary('dilate', m);
+  const a = pass(m.data, m.width, m.height, kw, true, true);
+  return { width: m.width, height: m.height, data: pass(a, m.width, m.height, kh, false, true) };
+}
+
+/** `cv2.erode(mask, np.ones((kh, kw)))` on a binary mask. */
+export function erode(m: Mask, kw: number, kh: number = kw): Mask {
+  assertKernel('erode', kw, kh);
+  assertBinary('erode', m);
+  const a = pass(m.data, m.width, m.height, kw, true, false);
+  return { width: m.width, height: m.height, data: pass(a, m.width, m.height, kh, false, false) };
+}
+
+/** `cv2.morphologyEx(mask, cv2.MORPH_CLOSE, np.ones((kh, kw)))`: dilate, then erode, same kernel. */
+export function morphClose(m: Mask, kw: number, kh: number = kw): Mask {
+  return erode(dilate(m, kw, kh), kw, kh);
+}
+
+/** `cv2.morphologyEx(mask, cv2.MORPH_GRADIENT, np.ones((kh, kw)))`: dilate minus erode. */
+export function morphGradient(m: Mask, kw: number, kh: number = kw): Mask {
+  const d = dilate(m, kw, kh);
+  const e = erode(m, kw, kh);
+  const out = newMask(m.width, m.height);
+  for (let i = 0; i < out.data.length; i++) out.data[i] = d.data[i] === 1 && e.data[i] === 0 ? 1 : 0;
+  return out;
+}
+
+/**
+ * `scipy.ndimage.binary_fill_holes(mask)` with its default structure: every
+ * background pixel that cannot reach the image border through 4-connected
+ * background is foreground in the result.
+ *
+ * The 4-connectivity is scipy's default cross, and it matters: a background
+ * pocket that touches the outside only through a diagonal gap is a hole here.
+ */
+export function fillHoles(m: Mask): Mask {
+  assertBinary('fillHoles', m);
+  const { width: w, height: h } = m;
+  if (w === 0 || h === 0) return newMask(w, h);
+  const outside = new Uint8Array(w * h);
+  const stack: number[] = [];
+  const seed = (i: number): void => {
+    if (m.data[i] === 0 && outside[i] === 0) {
+      outside[i] = 1;
+      stack.push(i);
+    }
+  };
+  for (let x = 0; x < w; x++) {
+    seed(x);
+    seed((h - 1) * w + x);
+  }
+  for (let y = 0; y < h; y++) {
+    seed(y * w);
+    seed(y * w + w - 1);
+  }
+  while (stack.length > 0) {
+    const i = stack.pop() as number;
+    const x = i % w;
+    const y = (i - x) / w;
+    if (x > 0) seed(i - 1);
+    if (x < w - 1) seed(i + 1);
+    if (y > 0) seed(i - w);
+    if (y < h - 1) seed(i + w);
+  }
+  const out = newMask(w, h);
+  for (let i = 0; i < w * h; i++) out.data[i] = outside[i] === 1 ? 0 : 1;
+  return out;
+}

package/src/raster/png.ts

@@ -0,0 +1,82 @@
+/**
+ * PNG in and out, through rig-c's own codec.
+ *
+ * ⚖️ **Why no PNG dependency.** `rig-c` ships a complete PNG codec inside
+ * its published allowlist: `tools/plate.ts` exports `decodePng` (every colour
+ * type the PNG spec defines — greyscale, RGB, indexed with `PLTE`/`tRNS`,
+ * grey+alpha, RGBA — at every legal bit depth, all five scanline filters,
+ * expanded to straight RGBA) and `encodePng` (8-bit RGBA, filter 0, zlib level
+ * 9, deterministic), and `src/png.ts` exports `assertPng`, which names what a
+ * file is when it is not a PNG. `npm pack --dry-run` of rig-c 1.2.3 lists
+ * both files. The one gap is interlaced (Adam7) files, which `decodePng`
+ * refuses by name rather than misreading. So adding `pngjs` would have been a
+ * second codec for the same bytes, and two codecs are two answers.
+ *
+ * 🔌 **The deep path is the interface.** rig-c's `exports` map carries
+ * `./*.ts`, so `rig-c/tools/plate.ts` is how a consumer reaches the codec
+ * and it is what the installed package resolves. If a rigc release narrows the
+ * map to omit these paths, this import is what breaks, by name, and
+ * `bun run smoke` is where that is seen first.
+ */
+import { assertPng } from 'rig-c/src/png.ts';
+import { decodePng, encodePng } from 'rig-c/tools/plate.ts';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { type FloatImage, newFloatImage, newRaster, type Raster, RasterError } from './types.ts';
+
+/** Decode PNG bytes to a straight-alpha RGBA raster. `label` names the bytes in any refusal. */
+export function decodePngBytes(bytes: Uint8Array, label: string): Raster {
+  assertPng(bytes, label);
+  let plate;
+  try {
+    plate = decodePng(bytes);
+  } catch (err) {
+    throw new RasterError(`cannot decode PNG ${label}: ${(err as Error).message}`);
+  }
+  return { width: plate.width, height: plate.height, data: new Uint8ClampedArray(plate.data) };
+}
+
+export function readPng(path: string): Raster {
+  return decodePngBytes(new Uint8Array(readFileSync(path)), path);
+}
+
+export function encodePngBytes(r: Raster): Uint8Array {
+  return encodePng(r.width, r.height, new Uint8Array(r.data.buffer, r.data.byteOffset, r.data.byteLength));
+}
+
+export function writePng(path: string, r: Raster): void {
+  writeFileSync(path, encodePngBytes(r));
+}
+
+/**
+ * A raster as four float channels, optionally premultiplied (`c * a / 255`,
+ * unrounded) — the form the reference warps in.
+ */
+export function toFloat(r: Raster, premultiply: boolean): FloatImage {
+  const f = newFloatImage(r.width, r.height, 4);
+  for (let i = 0; i < r.width * r.height; i++) {
+    const a = r.data[i * 4 + 3];
+    for (let c = 0; c < 3; c++) f.data[i * 4 + c] = premultiply ? (r.data[i * 4 + c] * a) / 255 : r.data[i * 4 + c];
+    f.data[i * 4 + 3] = a;
+  }
+  return f;
+}
+
+/**
+ * Four float channels back to a raster: clipped to 0..255, optionally
+ * un-premultiplied, then TRUNCATED to integers — `np.clip(...).astype(np.uint8)`,
+ * which is what the reference does, and which is not rounding.
+ */
+export function fromFloat(f: FloatImage, premultiplied: boolean): Raster {
+  if (f.channels !== 4) throw new RasterError(`fromFloat: ${f.channels} channel(s); 4 are required`);
+  const r = newRaster(f.width, f.height);
+  const clip = (v: number): number => (v < 0 ? 0 : v > 255 ? 255 : v);
+  for (let i = 0; i < f.width * f.height; i++) {
+    const a = clip(f.data[i * 4 + 3]);
+    for (let c = 0; c < 3; c++) {
+      const v = clip(f.data[i * 4 + c]);
+      r.data[i * 4 + c] = Math.trunc(premultiplied ? (a > 0 ? clip((v * 255) / Math.max(a, 1e-3)) : 0) : v);
+    }
+    r.data[i * 4 + 3] = Math.trunc(a);
+  }
+  return r;
+}