@graciousstar/node-red-contrib-vision-tools 1.0.0

package/lib/shared.js

@@ -0,0 +1,87 @@
+/**
+ * Shared-memory allocation for the buffers the worker pool operates on.
+ *
+ * Worker threads can only touch a typed array without copying it if its
+ * backing store is a SharedArrayBuffer, and the per-frame buffers here
+ * run to tens of megabytes - copying them into and out of workers would
+ * cost more than the parallelism saves. So the large intermediates are
+ * allocated shared from the start; a typed array over a SharedArrayBuffer
+ * behaves identically to one over an ArrayBuffer for every operation in
+ * this codebase, so nothing else has to know.
+ *
+ * If SharedArrayBuffer is unavailable the allocators fall back to ordinary
+ * buffers and `isShared` reports false, which is the signal for callers to
+ * stay on the serial path rather than fail.
+ */
+
+const HAS_SAB = typeof SharedArrayBuffer !== "undefined";
+
+function allocU8(length) {
+	return HAS_SAB
+		? new Uint8Array(new SharedArrayBuffer(length))
+		: new Uint8Array(length);
+}
+
+function allocU32(length) {
+	return HAS_SAB
+		? new Uint32Array(new SharedArrayBuffer(length * 4))
+		: new Uint32Array(length);
+}
+
+function allocF32(length) {
+	return HAS_SAB
+		? new Float32Array(new SharedArrayBuffer(length * 4))
+		: new Float32Array(length);
+}
+
+function allocF64(length) {
+	return HAS_SAB
+		? new Float64Array(new SharedArrayBuffer(length * 8))
+		: new Float64Array(length);
+}
+
+/** Copy into shared memory only when it is not already there. */
+function toShared(array) {
+	if (!HAS_SAB) return array;
+	if (
+		array.buffer instanceof SharedArrayBuffer &&
+		array.byteOffset === 0 &&
+		array.byteLength === array.buffer.byteLength
+	) {
+		return array;
+	}
+	return copyToShared(array);
+}
+
+/**
+ * Copy `array`'s bytes into a fresh zero-offset SharedArrayBuffer-backed
+ * view with the same element type. Workers rebuild their side as
+ * `new Uint8Array(buffer)` from offset 0 (poolWorker.js), so a view that
+ * is a slice of a larger buffer (byteOffset > 0) must be copied or the
+ * workers would read the wrong bytes - silently.
+ */
+function copyToShared(array) {
+	const store = new SharedArrayBuffer(array.byteLength);
+	// Buffer's `new Buffer(SAB)` form is deprecated (DEP0005) and sharp's
+	// decodeGray hands us Buffers on every parallel frame; build those as
+	// a plain Uint8Array over the store instead. The element type only
+	// matters for the other typed arrays, which callers index as such.
+	const Ctor = array.constructor === Buffer ? Uint8Array : array.constructor;
+	const out = new Ctor(store);
+	out.set(array);
+	return out;
+}
+
+function isShared(array) {
+	return HAS_SAB && array != null && array.buffer instanceof SharedArrayBuffer;
+}
+
+module.exports = {
+	HAS_SAB,
+	allocU8,
+	allocU32,
+	allocF32,
+	allocF64,
+	toShared,
+	isShared,
+};

package/lib/threshold.js

@@ -0,0 +1,231 @@
+/**
+ * Foreground (ink) thresholding strategies.
+ *
+ * "Foreground" is always the dark side: ink/print/marks on a lighter
+ * substrate.
+ *
+ *  - "fixed"    - one hand-set grey level. Fastest and perfectly
+ *                 repeatable, but it silently drifts out of calibration
+ *                 with the lighting: a slightly darker exposure turns
+ *                 substrate into ink and floods the background check.
+ *  - "otsu"     - one level per image, chosen to maximally separate the
+ *                 two intensity modes. Absorbs uniform exposure changes,
+ *                 which is the common failure on a production line where
+ *                 lamps age and ambient light shifts.
+ *  - "sauvola"  - a per-pixel level from the local mean and standard
+ *                 deviation. Absorbs *gradients* (one edge of the part
+ *                 lit brighter than the other), which a single global
+ *                 level cannot. In blank regions the local deviation
+ *                 collapses, so the threshold sinks well below the local
+ *                 mean and the substrate is correctly left as background
+ *                 - that property is why this beats a plain local-mean
+ *                 threshold, which speckles blank areas with noise.
+ *
+ * Otsu and Sauvola both make golden and target independently
+ * self-normalizing, which is the point: they no longer have to have been
+ * shot under identical light to be comparable.
+ *
+ * Whichever mode is used, the decision is still a hard cut, and features
+ * that sit near the level land arbitrarily on one side of it. That is not
+ * hypothetical: comparing PDF artwork against a photograph of the print,
+ * a screened tint renders light in the PDF (above its level, so not ink)
+ * and prints heavier through dot gain (below its level, so ink). The
+ * design element is identical; only the quantization differs.
+ *
+ * Worse, the level itself is not stable. Otsu re-derives it from each
+ * image's histogram, and the histogram changes with resolution: on this
+ * project's artwork the level walks from 160 at workingSize 1024 down to
+ * 145 at 3072, which is enough to flip a solid grey "RX" panel sitting at
+ * 155 from ink to background and light up a whole region of false extra
+ * ink. Neither side is wrong; the panel is simply too close to the cut
+ * for the cut to mean anything.
+ *
+ * So each threshold also reports an `ambiguous` mask - pixels within
+ * `cfg.inkMargin` grey levels of the level they were judged against, on
+ * *either* side of it. Both blemish checks drop a pixel from the evidence
+ * when either image is ambiguous there. See computeExtraInkDefect in
+ * compare.js.
+ */
+
+"use strict";
+
+const { buildIntegral, blockSum } = require("./integral.js");
+const { allocU8 } = require("./shared.js");
+
+/** Standard histogram-based Otsu: the level maximizing between-class variance. */
+function otsuThreshold(gray) {
+	const hist = new Uint32Array(256);
+	for (let i = 0; i < gray.length; i++) hist[gray[i]]++;
+	const total = gray.length;
+
+	let sumAll = 0;
+	for (let t = 0; t < 256; t++) sumAll += t * hist[t];
+
+	let sumB = 0;
+	let weightB = 0;
+	let maxVariance = 0;
+	let threshold = 0;
+	for (let t = 0; t < 256; t++) {
+		weightB += hist[t];
+		if (weightB === 0) continue;
+		const weightF = total - weightB;
+		if (weightF === 0) break;
+		sumB += t * hist[t];
+		const meanB = sumB / weightB;
+		const meanF = (sumAll - sumB) / weightF;
+		const variance = weightB * weightF * (meanB - meanF) * (meanB - meanF);
+		if (variance > maxVariance) {
+			maxVariance = variance;
+			threshold = t;
+		}
+	}
+	return threshold;
+}
+
+/** foreground = dark pixels, against one global level. */
+function thresholdFgFixed(gray, level) {
+	const n = gray.length;
+	const out = allocU8(n);
+	for (let i = 0; i < n; i++) out[i] = gray[i] < level ? 1 : 0;
+	return out;
+}
+
+/**
+ * Pixels too close to a global level for the level to have decided
+ * anything: within `margin` grey levels either side. Null when the margin
+ * is disabled, so callers can skip the test entirely rather than walk an
+ * all-zero mask.
+ */
+function ambiguousFixed(gray, level, margin) {
+	if (!(margin > 0)) return null;
+	const n = gray.length;
+	const out = allocU8(n);
+	const lo = level - margin;
+	const hi = level + margin;
+	for (let i = 0; i < n; i++) {
+		const v = gray[i];
+		out[i] = v >= lo && v <= hi ? 1 : 0;
+	}
+	return out;
+}
+
+// Sum of squares needs more range than a Uint32 integral gives
+// (n*255^2 overflows past ~66k pixels), and Float32's 24-bit mantissa
+// loses the low bits that the corner-subtraction depends on - so the
+// squares table is Float64.
+function buildSquaredIntegral(gray, width, height) {
+	const stride = width + 1;
+	const integral = new Float64Array(stride * (height + 1));
+	for (let y = 0; y < height; y++) {
+		let rowSum = 0;
+		const srcRow = y * width;
+		const intRow = (y + 1) * stride;
+		const intPrevRow = y * stride;
+		for (let x = 0; x < width; x++) {
+			const v = gray[srcRow + x];
+			rowSum += v * v;
+			integral[intRow + x + 1] = integral[intPrevRow + x + 1] + rowSum;
+		}
+	}
+	return { integral, stride, width, height };
+}
+
+/**
+ * Sauvola: T(x,y) = m * (1 + k*(s/R - 1)), with m/s the local mean and
+ * standard deviation over a (2r+1)^2 window and R=128 the dynamic-range
+ * normalizer. Both windows come from integral images, so cost is
+ * O(width*height) independent of the radius.
+ */
+function thresholdFgSauvola(gray, width, height, radius, k, margin) {
+	const sum = buildIntegral(gray, width, height);
+	const sqSum = buildSquaredIntegral(gray, width, height);
+	const out = new Uint8Array(width * height);
+	// the level is per-pixel here, so "too close to call" has to be decided
+	// inside the loop - there is no single level to compare against after
+	const ambiguous = margin > 0 ? new Uint8Array(width * height) : null;
+	const R = 128;
+	for (let y = 0; y < height; y++) {
+		const y0 = y - radius;
+		const y1 = y + radius + 1;
+		for (let x = 0; x < width; x++) {
+			const x0 = x - radius;
+			const x1 = x + radius + 1;
+			const cx0 = x0 < 0 ? 0 : x0;
+			const cy0 = y0 < 0 ? 0 : y0;
+			const cx1 = x1 > width ? width : x1;
+			const cy1 = y1 > height ? height : y1;
+			const area = (cx1 - cx0) * (cy1 - cy0);
+			if (area <= 0) continue;
+			const mean = blockSum(sum, cx0, cy0, cx1, cy1) / area;
+			const meanSq = blockSum(sqSum, cx0, cy0, cx1, cy1) / area;
+			const variance = meanSq - mean * mean;
+			const std = variance > 0 ? Math.sqrt(variance) : 0;
+			const t = mean * (1 + k * (std / R - 1));
+			const i = y * width + x;
+			const v = gray[i];
+			out[i] = v < t ? 1 : 0;
+			if (ambiguous !== null) {
+				ambiguous[i] = v >= t - margin && v <= t + margin ? 1 : 0;
+			}
+		}
+	}
+	return { fg: out, ambiguous };
+}
+
+/**
+ * Threshold to a foreground mask under the configured mode. Returns
+ * { fg, level, ambiguous }:
+ *
+ *  - `level` is the global grey level actually used (null for sauvola,
+ *    which has no single level), reported for diagnostics so a drifting
+ *    exposure is visible rather than merely absorbed.
+ *  - `ambiguous` marks pixels within cfg.inkMargin grey levels of the
+ *    level they were judged against, either side of it - too close to the
+ *    cut for the cut to carry a defect claim. Null when inkMargin is 0,
+ *    which restores the plain hard-threshold behaviour exactly.
+ *
+ * `fg` itself is never narrowed by the margin: alignment scores against
+ * the full mask, where an ambiguous pixel is still perfectly good
+ * evidence of where the label is. The margin only withholds it from the
+ * *defect* decision.
+ */
+function thresholdForeground(gray, width, height, cfg) {
+	const margin = cfg.inkMargin > 0 ? cfg.inkMargin : 0;
+	switch (cfg.thresholdMode) {
+		case "otsu": {
+			const level = otsuThreshold(gray);
+			return {
+				fg: thresholdFgFixed(gray, level),
+				level,
+				ambiguous: ambiguousFixed(gray, level, margin),
+			};
+		}
+		case "sauvola": {
+			const { fg, ambiguous } = thresholdFgSauvola(
+				gray,
+				width,
+				height,
+				cfg.sauvolaRadius,
+				cfg.sauvolaK,
+				margin,
+			);
+			return { fg, level: null, ambiguous };
+		}
+		default: {
+			const level = cfg.threshold;
+			return {
+				fg: thresholdFgFixed(gray, level),
+				level,
+				ambiguous: ambiguousFixed(gray, level, margin),
+			};
+		}
+	}
+}
+
+module.exports = {
+	otsuThreshold,
+	thresholdFgFixed,
+	ambiguousFixed,
+	thresholdFgSauvola,
+	thresholdForeground,
+};

package/lib/transformFile.js

@@ -0,0 +1,169 @@
+/**
+ * Trained-transform file helpers.
+ *
+ * The alignment transform splits cleanly into two halves by what
+ * physically varies between frames:
+ *
+ *   - magnification (mx) and stretch (my/mx) come from the camera's
+ *     standoff and the press's pull on the media. Neither changes from
+ *     one part to the next, so both are measured once and reused - the
+ *     same reasoning as the mm/px calibration next door.
+ *   - translation and rotation are where the part happens to be sitting
+ *     this time, and have to be solved every frame.
+ *
+ * Reusing the first half is not primarily a speed optimization. A search
+ * that is free to re-solve magnification per frame can pick wrong, and it
+ * is likeliest to pick wrong on a badly printed label - the case the
+ * inspection exists for - because a poor print gives the search poor
+ * evidence to fit. Pinning removes that whole class of failure.
+ *
+ * A trained record is tied to the golden it was measured against and to
+ * the working size it was measured at, because the numbers are meaningless
+ * against a different golden or at a different resolution. Both are
+ * checked on load and a mismatch is rejected rather than silently applied.
+ *
+ * "The golden it was measured against" has to mean the *image*, not the
+ * way the image arrived. `goldenKey` is the caller's cheap fingerprint,
+ * and its form follows the delivery: `buf:<sha1>` for a golden sent on the
+ * message, `path:<file>:<mtime>:<size>` for one read from disk, `key:<n>`
+ * for one the flow named. Training through msg.golden and then producing
+ * frames from the configured goldenPath - the documented "train from any
+ * two images" flow - therefore compared `buf:...` against `path:...` and
+ * refused a perfectly good record on every frame, silently falling back
+ * to the full search. So a record also carries `goldenContentKey`, a hash
+ * of the golden's bytes, and the cheap keys disagreeing only means
+ * "resolve it against the content" rather than "refuse". Computing that
+ * hash means reading the golden, which is the one thing the cheap keys
+ * exist to avoid, so the caller passes a resolver that is consulted only
+ * on a cheap-key mismatch and never on the hot path.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const fsp = fs.promises;
+const path = require("path");
+
+async function pathExists(p) {
+	try {
+		await fsp.access(p);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function isFinitePositive(v) {
+	return typeof v === "number" && Number.isFinite(v) && v > 0;
+}
+
+// The physical range a trained magnification can plausibly take. A
+// standoff a few cm further out changes a scale by a few percent; nothing
+// in this rig produces a 1000x or 1e-4x relationship between the golden's
+// working pixels and the frame's. The bound is not about being right at
+// the edges - a huge but finite scaleX like 1e308 flows through the
+// pinned search into centerX = (tW - mx*gW)/2 = -Infinity and an infinite
+// halfRange, which makes the sweep loop forever and freezes the Node-RED
+// process. Refuse the record instead, the same way a golden/workingSize
+// mismatch is refused, and let the caller fall back to searching.
+const SCALE_MIN = 0.05;
+const SCALE_MAX = 100;
+
+/**
+ * Read a trained transform, returning null when there is nothing usable.
+ * `expect` is { goldenKey, workingSize, goldenContentKey }, where
+ * goldenContentKey is a hash of the golden's bytes or a function
+ * returning one; a record trained against a different golden or working
+ * size is refused with a reason rather than applied, since applying it
+ * would misalign every frame in a way that looks like a print fault.
+ */
+async function readTransformFile(filePath, expect) {
+	if (!filePath || !(await pathExists(filePath))) return null;
+	let parsed;
+	try {
+		parsed = JSON.parse(await fsp.readFile(filePath, "utf8"));
+	} catch (err) {
+		return { error: `trained transform is not readable JSON: ${err.message}` };
+	}
+	if (!isFinitePositive(parsed.scaleX) || !isFinitePositive(parsed.scaleY)) {
+		return { error: "trained transform has no usable scaleX/scaleY" };
+	}
+	if (
+		parsed.scaleX < SCALE_MIN ||
+		parsed.scaleX > SCALE_MAX ||
+		parsed.scaleY < SCALE_MIN ||
+		parsed.scaleY > SCALE_MAX
+	) {
+		return {
+			error:
+				`trained transform scaleX/scaleY must be within ${SCALE_MIN}..${SCALE_MAX} ` +
+				`(got ${parsed.scaleX}/${parsed.scaleY}) - retrain it`,
+		};
+	}
+	if (expect) {
+		if (
+			expect.goldenKey &&
+			parsed.goldenKey &&
+			parsed.goldenKey !== expect.goldenKey
+		) {
+			// The cheap keys record how the golden was delivered, so they
+			// disagree both when the golden really changed and when the same
+			// image simply arrived a different way. Only the content can tell
+			// those apart; resolving it costs a read, so it happens here and
+			// nowhere else.
+			const mine = await resolveContentKey(expect);
+			if (!parsed.goldenContentKey || !mine) {
+				return {
+					error:
+						`trained transform was measured against a different golden ` +
+						`(${parsed.goldenKey} vs ${expect.goldenKey}) - retrain it` +
+						(parsed.goldenContentKey
+							? ""
+							: ` (this record predates content-keyed training, so the same ` +
+								`golden delivered a different way cannot be recognised)`),
+				};
+			}
+			if (parsed.goldenContentKey !== mine) {
+				return {
+					error:
+						`trained transform was measured against different golden content ` +
+						`(${parsed.goldenContentKey} vs ${mine}) - retrain it`,
+				};
+			}
+		}
+		if (
+			expect.workingSize &&
+			parsed.workingSize &&
+			parsed.workingSize !== expect.workingSize
+		) {
+			return {
+				error:
+					`trained transform was measured at workingSize ${parsed.workingSize}, ` +
+					`now running at ${expect.workingSize} - retrain it`,
+			};
+		}
+	}
+	return { scaleX: parsed.scaleX, scaleY: parsed.scaleY, record: parsed };
+}
+
+// expect.goldenContentKey may be a string or a function returning one
+// (sync or async); a resolver that throws - an unreadable golden, say -
+// leaves the mismatch unresolved, which refuses the record and falls back
+// to searching, the same as before it existed.
+async function resolveContentKey(expect) {
+	const c = expect.goldenContentKey;
+	if (typeof c === "string") return c || null;
+	if (typeof c !== "function") return null;
+	try {
+		return (await c()) || null;
+	} catch {
+		return null;
+	}
+}
+
+async function writeTransformFile(filePath, record) {
+	await fsp.mkdir(path.dirname(filePath), { recursive: true });
+	await fsp.writeFile(filePath, JSON.stringify(record, null, 2));
+}
+
+module.exports = { readTransformFile, writeTransformFile };

package/lib/warp.js

@@ -0,0 +1,216 @@
+/**
+ * Resampling the matched region of a camera frame into the golden's own
+ * frame, given the transform recovered by lib/align.js.
+ *
+ * The old code could get away with a plain windowed byte copy because the
+ * only transform it supported was an integer translation. Once
+ * magnification is in play the sampling method starts to matter a great
+ * deal, and in the wrong direction for the naive choice: when the frame
+ * resolves the part more finely than the golden does (m > 1, the usual
+ * case for a 23MP capture against a downscaled template), point-sampling
+ * one frame pixel per golden pixel throws away all but 1/m^2 of the data.
+ * On the fine text that this node exists to inspect, that aliases strokes
+ * in and out of existence and manufactures defects no printer produced.
+ *
+ * So sampling adapts to the magnification, per axis - mx and my differ
+ * whenever the press stretched the print along one axis:
+ *
+ *   m > 1  - area-average the mx by my frame footprint of each golden
+ *            pixel, read in O(1) from a summed-area table. This is a true
+ *            box downsample, the same thing an image resizer would do,
+ *            and it costs the same per output pixel regardless of m.
+ *   m <= 1 - bilinear interpolation. There is no footprint to average
+ *            (the frame carries less detail than the golden), so the
+ *            useful thing is smooth sub-pixel placement.
+ *
+ * Under rotation the footprint is treated as its axis-aligned bounding
+ * box rather than a rotated rectangle. Across the small angles this
+ * handles, the difference is a slight extra blur at the corners of each
+ * footprint, which costs far less than the aliasing it avoids.
+ */
+
+"use strict";
+
+const { allocU8 } = require("./shared.js");
+
+const { buildIntegral64 } = require("./integral.js");
+
+// The area-average path needs a summed-area table over the source. Built
+// separately so a caller evaluating many candidate transforms against the
+// same frame (the refinement loop in lib/align.js) pays for it once
+// instead of once per candidate - rebuilding it per call would make the
+// table, not the sampling, the dominant cost.
+//
+// This is the *grey* table (0-255 per pixel), so it uses the Float64
+// accumulator: a Uint32 table wraps once the frame's canvas passes
+// ~16.8M bright pixels, and the bottom rows of the wrap read as garbage
+// to the area-average warp. Float64 holds every sum here exactly.
+function buildGrayTable(src, srcW, srcH) {
+	return buildIntegral64(src, srcW, srcH);
+}
+
+// Value of a cumulative table at a fractional corner. The table is a
+// lattice over [0,width] x [0,height] (entry (x,y) is the sum of the
+// pixels strictly above and left of (x,y)); bilinear interpolation
+// between the four surrounding lattice points is what makes a box with
+// fractional corners summable in O(1) - the standard interpolated
+// summed-area table.
+function satAt(table, x, y) {
+	const { integral, stride, width, height } = table;
+	if (x <= 0 || y <= 0) return 0;
+	if (x >= width) x = width;
+	if (y >= height) y = height;
+	const ix = x | 0;
+	const iy = y | 0;
+	const fx = x - ix;
+	const fy = y - iy;
+	const x1 = ix + 1 > width ? width : ix + 1;
+	const y1 = iy + 1 > height ? height : iy + 1;
+	const p00 = integral[iy * stride + ix];
+	const p10 = integral[iy * stride + x1];
+	const p01 = integral[y1 * stride + ix];
+	const p11 = integral[y1 * stride + x1];
+	return (
+		p00 + (p10 - p00) * fx + (p01 - p00) * fy + (p00 - p10 - p01 + p11) * fx * fy
+	);
+}
+
+/**
+ * Sample `src` (srcW x srcH, 8-bit) into an outW x outH canvas under
+ * target = (ox,oy) + R(theta) * diag(mx,my) * golden.
+ *
+ * Pixels mapping outside the source are filled with `fill` (default 255,
+ * i.e. blank substrate - so a template hanging off the frame edge reads
+ * as "no ink there", which the print check will flag, rather than as a
+ * black bar, which would flood the background check with a defect the
+ * part does not have).
+ *
+ * `table` is an optional prebuilt summed-area table from buildGrayTable,
+ * for callers warping the same frame many times.
+ */
+/**
+ * Resample rows [yLo,yHi) only. Rows are independent, so this is what the
+ * worker pool splits - and it calls this very function, so there is one
+ * implementation of the sampling rather than a copy that could drift.
+ * `sat` non-null selects the area-average path.
+ */
+function warpRows(
+	out,
+	src,
+	srcW,
+	srcH,
+	mx,
+	my,
+	theta,
+	ox,
+	oy,
+	outW,
+	sat,
+	yLo,
+	yHi,
+) {
+	const cos = Math.cos(theta);
+	const sin = Math.sin(theta);
+	const xFromGx = cos * mx;
+	const yFromGx = sin * mx;
+	const xFromGy = -sin * my;
+	const yFromGy = cos * my;
+
+	if (sat !== null) {
+		// downsampling: area-average each golden pixel's footprint
+		const halfX = mx / 2;
+		const halfY = my / 2;
+		for (let y = yLo; y < yHi; y++) {
+			const baseX = ox + xFromGy * y;
+			const baseY = oy + yFromGy * y;
+			const outRow = y * outW;
+			for (let x = 0; x < outW; x++) {
+				const tx = baseX + xFromGx * x;
+				const ty = baseY + yFromGx * x;
+				// Pixel index j spans continuous [j, j+1), so the footprint
+				// centered on index tx spans [tx+0.5-half, tx+0.5+half).
+				// Dropping that half-pixel biases every footprint half a
+				// pixel up-left, which is invisible on a single image and
+				// fatal when two independently-resampled grids are compared:
+				// the best alignment stops being the true one.
+				let x0 = tx + 0.5 - halfX;
+				let y0 = ty + 0.5 - halfY;
+				let x1 = tx + 0.5 + halfX;
+				let y1 = ty + 0.5 + halfY;
+				if (x1 <= 0 || y1 <= 0 || x0 >= srcW || y0 >= srcH) continue;
+				if (x0 < 0) x0 = 0;
+				if (y0 < 0) y0 = 0;
+				if (x1 > srcW) x1 = srcW;
+				if (y1 > srcH) y1 = srcH;
+				// The corners stay fractional. Rounding them to integers was
+				// exact for an odd integer magnification, but any fractional
+				// m shifts the box half a pixel and degenerates toward point
+				// sampling (at m = 1.5, every other box rounds to a 1-px
+				// footprint) - exactly the aliasing this path exists to
+				// avoid. With the corners interpolated in the cumulative
+				// table, every box - integer or fractional m - is a true
+				// area average.
+				const area = (x1 - x0) * (y1 - y0);
+				if (area <= 0) continue;
+				const sum =
+					satAt(sat, x1, y1) -
+					satAt(sat, x0, y1) -
+					satAt(sat, x1, y0) +
+					satAt(sat, x0, y0);
+				out[outRow + x] = Math.round(sum / area);
+			}
+		}
+		return;
+	}
+
+	// upsampling / same scale: bilinear
+	for (let y = yLo; y < yHi; y++) {
+		const baseX = ox + xFromGy * y;
+		const baseY = oy + yFromGy * y;
+		const outRow = y * outW;
+		for (let x = 0; x < outW; x++) {
+			const tx = baseX + xFromGx * x;
+			const ty = baseY + yFromGx * x;
+			if (tx < -1 || ty < -1 || tx > srcW || ty > srcH) continue;
+			const fx = Math.floor(tx);
+			const fy = Math.floor(ty);
+			const dx = tx - fx;
+			const dy = ty - fy;
+			const x0 = fx < 0 ? 0 : fx >= srcW ? srcW - 1 : fx;
+			const y0 = fy < 0 ? 0 : fy >= srcH ? srcH - 1 : fy;
+			const x1 = x0 + 1 >= srcW ? srcW - 1 : x0 + 1;
+			const y1 = y0 + 1 >= srcH ? srcH - 1 : y0 + 1;
+			const p00 = src[y0 * srcW + x0];
+			const p10 = src[y0 * srcW + x1];
+			const p01 = src[y1 * srcW + x0];
+			const p11 = src[y1 * srcW + x1];
+			const top = p00 + (p10 - p00) * dx;
+			const bottom = p01 + (p11 - p01) * dx;
+			out[outRow + x] = Math.round(top + (bottom - top) * dy);
+		}
+	}
+}
+
+function warpGray(
+	src,
+	srcW,
+	srcH,
+	mx,
+	my,
+	theta,
+	ox,
+	oy,
+	outW,
+	outH,
+	fill,
+	table,
+) {
+	const out = allocU8(outW * outH);
+	out.fill(fill == null ? 255 : fill);
+	const sat =
+		mx > 1.001 || my > 1.001 ? table || buildIntegral64(src, srcW, srcH) : null;
+	warpRows(out, src, srcW, srcH, mx, my, theta, ox, oy, outW, sat, 0, outH);
+	return out;
+}
+
+module.exports = { warpGray, warpRows, buildGrayTable };