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

package/lib/localAlign.js

@@ -0,0 +1,360 @@
+/**
+ * Local (per-tile) alignment refinement.
+ *
+ * The global transform gets the label into place; it cannot get all of it
+ * into place. Measured on this project's own good pair - artwork against
+ * a photograph of the print, after a correctly recovered 5-DOF transform
+ * - the leftover displacement has a median of 0.73px, a 90th percentile
+ * of 1.55px, and individual regions sitting 4-5px out that match their
+ * golden counterpart near-perfectly once shifted.
+ *
+ * That field is not smooth, so raising the global model does not reach
+ * it: fitting a homography (8 DOF) to it removed 18% of the residual, and
+ * a full quadratic (12 DOF) only 27%. A global warp cannot pull one
+ * corner 5px left while leaving the two-thirds of the label that is
+ * already sub-pixel untouched. The physical reason is that a label on a
+ * formed tray is not a plane - regions lift and bow independently - and
+ * no global parametrisation describes that.
+ *
+ * So each tile finds its own small offset. Two properties matter for
+ * correctness:
+ *
+ *  - The offsets are **capped** (maxOffset). Uncapped, a tile could slide
+ *    onto neighbouring ink and quietly align a genuine fault away. The
+ *    cap is what keeps this a registration refinement rather than a
+ *    licence to match anything.
+ *  - Tiles without enough contrast to localise are **not trusted**. A
+ *    blank tile matches equally well everywhere, so its "best" offset is
+ *    noise; it is filled from its neighbours instead.
+ *
+ * The field is median-filtered (a spurious match is a lone disagreeing
+ * tile, while real substrate movement is coherent across several) and
+ * then interpolated bilinearly between tile centres when resampling.
+ * Applying a piecewise-constant shift per tile would step at every tile
+ * boundary and manufacture a seam of false defects along each one.
+ */
+
+"use strict";
+
+const { allocU8, allocF32 } = require("./shared.js");
+
+/**
+ * Whole-pixel sample with edge clamping - deliberately NOT interpolated.
+ *
+ * Bilinear resampling here was tried and is actively harmful. Interpolating
+ * at a fractional offset is a low-pass filter, and the features this node
+ * has to see are one to two pixels wide: on the demo capture it blurred
+ * the pen mark until it no longer crossed the ink level, dropping the
+ * defect ratio by 82% and turning a failing part into a passing one. It
+ * quietly ate real ink everywhere else too, taking a clean part's
+ * background ratio from 0.00009 to exactly 0.
+ *
+ * So the displacement field is interpolated smoothly and then rounded,
+ * and pixels are moved rather than mixed. The cost is that correction is
+ * quantised to whole pixels - the measured median residual is ~0.75px, so
+ * roughly half of it survives - but the several-pixel outliers that
+ * actually manufacture false regions are removed, and no contrast is lost
+ * doing it. Sharpness is worth more than sub-pixel here.
+ */
+function sampleNearest(src, w, h, x, y) {
+	if (x < 0) x = 0;
+	else if (x > w - 1) x = w - 1;
+	if (y < 0) y = 0;
+	else if (y > h - 1) y = h - 1;
+	return src[y * w + x];
+}
+
+/**
+ * Mean squared difference between the golden tile and the frame shifted
+ * by (dx,dy). Subsampled by 2 in both axes - this is called (2r+1)^2
+ * times per tile and the extra precision buys nothing at this scale.
+ */
+// Subsample the tile when matching. This runs (2r+1)^2 times per tile
+// over several hundred tiles, so it is worth being stingy: going from
+// every 2nd pixel to every 3rd took local refinement from ~170ms to
+// ~120ms on a 1844x2656 golden with no measurable change to the field it
+// produces. The tile is 96px, so even at step 3 there are ~1000 samples
+// behind each offset.
+const SSD_STEP = 3;
+
+function tileSsd(golden, target, w, h, x0, y0, x1, y1, dx, dy) {
+	let sum = 0;
+	let count = 0;
+	for (let y = y0; y < y1; y += SSD_STEP) {
+		const sy = y + dy;
+		if (sy < 0 || sy >= h) continue;
+		const gRow = y * w;
+		const tRow = sy * w;
+		for (let x = x0; x < x1; x += SSD_STEP) {
+			const sx = x + dx;
+			if (sx < 0 || sx >= w) continue;
+			const d = golden[gRow + x] - target[tRow + sx];
+			sum += d * d;
+			count++;
+		}
+	}
+	return count ? sum / count : Infinity;
+}
+
+/** Standard deviation of a golden tile - its ability to localise at all. */
+function tileStdDev(golden, w, x0, y0, x1, y1) {
+	let sum = 0;
+	let sumSq = 0;
+	let n = 0;
+	for (let y = y0; y < y1; y += 2) {
+		const row = y * w;
+		for (let x = x0; x < x1; x += 2) {
+			const v = golden[row + x];
+			sum += v;
+			sumSq += v * v;
+			n++;
+		}
+	}
+	if (n === 0) return 0;
+	const mean = sum / n;
+	const variance = sumSq / n - mean * mean;
+	return variance > 0 ? Math.sqrt(variance) : 0;
+}
+
+/** Sub-pixel minimum from a parabola through three SSD samples. */
+function parabolic(before, at, after) {
+	const denom = before - 2 * at + after;
+	if (Math.abs(denom) < 1e-9) return 0;
+	const shift = (0.5 * (before - after)) / denom;
+	return shift > 1 || shift < -1 ? 0 : shift;
+}
+
+/**
+ * Per-tile displacement of the frame relative to the golden, in golden
+ * pixels: the golden's pixel (x,y) is found in the frame at
+ * (x + fx, y + fy).
+ */
+/**
+ * Fill tile rows [gyLo,gyHi) of an existing field. Tile rows are
+ * independent, so this is the unit the worker pool splits - and it calls
+ * this same function, so there is one implementation rather than a copy
+ * that could drift from it.
+ */
+function fieldRows(goldenGray, targetGray, width, height, opts, out, gyLo, gyHi) {
+	const tile = opts.tile;
+	const maxOffset = opts.maxOffset;
+	const minStdDev = opts.minStdDev;
+	const { fx, fy, valid, gridW } = out;
+
+	for (let gy = gyLo; gy < gyHi; gy++) {
+		const y0 = gy * tile;
+		const y1 = Math.min(height, y0 + tile);
+		for (let gx = 0; gx < gridW; gx++) {
+			const x0 = gx * tile;
+			const x1 = Math.min(width, x0 + tile);
+			const cell = gy * gridW + gx;
+			if (tileStdDev(goldenGray, width, x0, y0, x1, y1) < minStdDev) continue;
+
+			let bestDx = 0;
+			let bestDy = 0;
+			let bestVal = Infinity;
+			for (let dy = -maxOffset; dy <= maxOffset; dy++) {
+				for (let dx = -maxOffset; dx <= maxOffset; dx++) {
+					const v = tileSsd(goldenGray, targetGray, width, height, x0, y0, x1, y1, dx, dy);
+					if (v < bestVal) {
+						bestVal = v;
+						bestDx = dx;
+						bestDy = dy;
+					}
+				}
+			}
+			// a minimum sitting on the edge of the search box is not a
+			// minimum - the true one is outside the cap, and trusting it
+			// would be extrapolating past where we agreed to look
+			if (Math.abs(bestDx) === maxOffset || Math.abs(bestDy) === maxOffset) continue;
+
+			const sx = parabolic(
+				tileSsd(goldenGray, targetGray, width, height, x0, y0, x1, y1, bestDx - 1, bestDy),
+				bestVal,
+				tileSsd(goldenGray, targetGray, width, height, x0, y0, x1, y1, bestDx + 1, bestDy),
+			);
+			const sy = parabolic(
+				tileSsd(goldenGray, targetGray, width, height, x0, y0, x1, y1, bestDx, bestDy - 1),
+				bestVal,
+				tileSsd(goldenGray, targetGray, width, height, x0, y0, x1, y1, bestDx, bestDy + 1),
+			);
+			fx[cell] = bestDx + sx;
+			fy[cell] = bestDy + sy;
+			valid[cell] = 1;
+		}
+	}
+}
+
+function buildDisplacementField(goldenGray, targetGray, width, height, opts) {
+	const gridW = Math.max(1, Math.ceil(width / opts.tile));
+	const gridH = Math.max(1, Math.ceil(height / opts.tile));
+	const out = {
+		fx: allocF32(gridW * gridH),
+		fy: allocF32(gridW * gridH),
+		valid: allocU8(gridW * gridH),
+		gridW,
+		gridH,
+	};
+	fieldRows(goldenGray, targetGray, width, height, opts, out, 0, gridH);
+	return out;
+}
+
+/**
+ * 3x3 median over valid neighbours, which also fills the invalid tiles.
+ * A tile that matched something spurious disagrees with everything around
+ * it, while real substrate movement is coherent over several tiles - so
+ * the median keeps the second and discards the first. Filling blank tiles
+ * from their neighbours matters as much: leaving them at zero would put a
+ * step between a blank tile and a genuinely displaced one beside it, and
+ * the resampling would smear ink across that step.
+ */
+function smoothField(field) {
+	const { fx, fy, valid, gridW, gridH } = field;
+	const outX = allocF32(fx.length);
+	const outY = allocF32(fy.length);
+	const outValid = allocU8(valid.length);
+	const bufX = [];
+	const bufY = [];
+	const median = (arr) => {
+		arr.sort((a, b) => a - b);
+		const mid = arr.length >> 1;
+		return arr.length % 2 ? arr[mid] : (arr[mid - 1] + arr[mid]) / 2;
+	};
+
+	for (let gy = 0; gy < gridH; gy++) {
+		for (let gx = 0; gx < gridW; gx++) {
+			const cell = gy * gridW + gx;
+			bufX.length = 0;
+			bufY.length = 0;
+			for (let dy = -1; dy <= 1; dy++) {
+				const ny = gy + dy;
+				if (ny < 0 || ny >= gridH) continue;
+				for (let dx = -1; dx <= 1; dx++) {
+					const nx = gx + dx;
+					if (nx < 0 || nx >= gridW) continue;
+					const n = ny * gridW + nx;
+					if (!valid[n]) continue;
+					bufX.push(fx[n]);
+					bufY.push(fy[n]);
+				}
+			}
+			if (bufX.length === 0) continue;
+			outX[cell] = median(bufX);
+			outY[cell] = median(bufY);
+			outValid[cell] = 1;
+		}
+	}
+	return { fx: outX, fy: outY, valid: outValid, gridW, gridH };
+}
+
+/**
+ * Resample the frame under the displacement field: interpolated smoothly
+ * between tile centres, then rounded to whole pixels for the sample
+ * itself. See sampleNearest for why the image is never interpolated.
+ */
+/** Resample rows [yLo,yHi) under the field. Rows are independent. */
+function applyRows(out, targetGray, width, height, field, tile, yLo, yHi) {
+	const { fx, fy, gridW, gridH } = field;
+	for (let y = yLo; y < yHi; y++) {
+		// tile centres sit at (g + 0.5) * tile, so the field coordinate of
+		// an image row is y/tile - 0.5
+		let gyf = y / tile - 0.5;
+		if (gyf < 0) gyf = 0;
+		else if (gyf > gridH - 1) gyf = gridH - 1;
+		const gy0 = Math.floor(gyf);
+		const gy1 = gy0 + 1 < gridH ? gy0 + 1 : gy0;
+		const wy = gyf - gy0;
+		const row = y * width;
+		for (let x = 0; x < width; x++) {
+			let gxf = x / tile - 0.5;
+			if (gxf < 0) gxf = 0;
+			else if (gxf > gridW - 1) gxf = gridW - 1;
+			const gx0 = Math.floor(gxf);
+			const gx1 = gx0 + 1 < gridW ? gx0 + 1 : gx0;
+			const wx = gxf - gx0;
+
+			const i00 = gy0 * gridW + gx0;
+			const i01 = gy0 * gridW + gx1;
+			const i10 = gy1 * gridW + gx0;
+			const i11 = gy1 * gridW + gx1;
+			const top = fx[i00] + (fx[i01] - fx[i00]) * wx;
+			const bot = fx[i10] + (fx[i11] - fx[i10]) * wx;
+			const dx = top + (bot - top) * wy;
+			const topY = fy[i00] + (fy[i01] - fy[i00]) * wx;
+			const botY = fy[i10] + (fy[i11] - fy[i10]) * wx;
+			const dy = topY + (botY - topY) * wy;
+
+			out[row + x] = sampleNearest(
+				targetGray,
+				width,
+				height,
+				x + Math.round(dx),
+				y + Math.round(dy),
+			);
+		}
+	}
+}
+
+function applyField(targetGray, width, height, field, tile) {
+	const out = allocU8(width * height);
+	applyRows(out, targetGray, width, height, field, tile, 0, height);
+	return out;
+}
+
+/**
+ * Refine an already globally-aligned frame tile by tile. Returns the
+ * corrected grey plus what it had to move, so a caller can see whether
+ * the rig is drifting rather than only that it was compensated for.
+ */
+function refineLocally(goldenGray, alignedTargetGray, width, height, cfg) {
+	const tile = Math.max(8, cfg.localAlignTile | 0);
+	const maxOffset = Math.max(1, cfg.localAlignMax | 0);
+	const raw = buildDisplacementField(goldenGray, alignedTargetGray, width, height, {
+		tile,
+		maxOffset,
+		minStdDev: cfg.localAlignMinStdDev != null ? cfg.localAlignMinStdDev : 12,
+	});
+	const field = smoothField(raw);
+
+	return {
+		gray: applyField(alignedTargetGray, width, height, field, tile),
+		field,
+		tile,
+		stats: fieldStats(field),
+	};
+}
+
+/** How far the field had to move things - reported so a drifting rig is
+ * visible rather than merely compensated for. */
+function fieldStats(field) {
+	let localised = 0;
+	let sum = 0;
+	let max = 0;
+	const magnitudes = [];
+	for (let i = 0; i < field.valid.length; i++) {
+		if (!field.valid[i]) continue;
+		const m = Math.hypot(field.fx[i], field.fy[i]);
+		magnitudes.push(m);
+		localised++;
+		sum += m;
+		if (m > max) max = m;
+	}
+	magnitudes.sort((a, b) => a - b);
+	return {
+		tiles: field.valid.length,
+		localised,
+		meanPx: localised ? sum / localised : 0,
+		medianPx: magnitudes.length ? magnitudes[magnitudes.length >> 1] : 0,
+		maxPx: max,
+	};
+}
+
+module.exports = {
+	refineLocally,
+	buildDisplacementField,
+	fieldRows,
+	smoothField,
+	applyField,
+	applyRows,
+	fieldStats,
+};

package/lib/locate.js

@@ -0,0 +1,302 @@
+/**
+ * Barcode location + decode, kept independent of Node-RED (plain functions
+ * over Buffers/plain objects) so it can be exercised from a standalone
+ * script without booting the runtime - same convention as
+ * node-red-contrib-golden-compare/lib.
+ *
+ * Uses zxing-wasm (the real zxing-cpp C++ engine as WebAssembly) rather than
+ * @zxing/library (the pure-JS port node-red-contrib-image-tools' Barcode
+ * Decoder uses) - genuine multi-symbol detection, rotation tolerance, and
+ * native DataMatrix support, all needed to reliably read a real multi-code
+ * label. Full-image scanning with it is already far more capable than the
+ * JS port, but on a large photo (megapixels) it still costs on the order of
+ * a second per scan (mostly the detector's own search over the full frame).
+ * If the barcode locations are known in advance - a fixed camera rig with
+ * labels landing in roughly the same place shot to shot, same assumption
+ * golden-compare's "one-time/per-maintenance calibration" already makes for
+ * this project - decoding small, pre-defined regions instead is much
+ * faster: on the 4096x5500 test photo (6 regions, warmed up), the whole
+ * regions pass measured ~190-235ms against ~1.4-1.8s for the same image
+ * scanned whole - a ~7x wall-clock win, and the gap widens with fewer/
+ * smaller regions since most of that 190-235ms is one fixed decode (next
+ * paragraph), not per-region cost (each region's own search measured
+ * 1-50ms).
+ *
+ * When regions are in play, the raw decode itself is restricted to the
+ * union bounding box of all regions (via sharp's extract-on-load, driven
+ * by a near-free sharp().metadata() header read to get image dimensions
+ * first) rather than decoding the full frame - on the 4096x5500 test
+ * photo this cut the dominant decode cost from ~180ms to ~139ms (a bbox of
+ * 1666x3677 out of the full frame), and it means the full-resolution raw
+ * buffer is never materialized at all on the common path where regions
+ * succeed. The full-frame decode only happens lazily, inside
+ * decodeFullImage, when the automatic fallback actually fires. Every
+ * region crop (for both the search itself and the preview image attached
+ * to each result) is sliced from that bbox-restricted raw buffer via
+ * sharp's raw-input mode, and all regions are searched concurrently via
+ * Promise.all (verified both faster - ~30ms vs ~35-65ms sequential for 6
+ * regions - and correctness-identical to sequential, i.e. concurrent
+ * zxing-wasm readBarcodes() calls don't corrupt each other's results, at
+ * least as tested against this project's real sample photo).
+ *
+ * Three implementation traps worth knowing about if touching this file,
+ * all found by benchmarking against this project's real 4096x5500 sample
+ * photo rather than trusting any approach to "obviously" be fast:
+ *  - A first version re-ran `sharp(pngBuffer).extract(box)` per region
+ *    instead - a fresh full PNG decode every time. Across 6 regions that
+ *    alone cost ~1.1s (region timings summed to ~125ms, the wrapping loop
+ *    took ~1220ms) - decode-once-slice-many fixed it.
+ *  - A second version sliced each region via one `sharp(raw.data,
+ *    {raw:...}).extract(box)` pipeline, forked into two outputs (raw +
+ *    PNG preview) with `.clone()` run concurrently through `Promise.all`.
+ *    Measured 400-600ms *per region* against the 90MB raw buffer - worse
+ *    than the original bug. Two independent, *sequential* pipelines (see
+ *    sliceRawImage) measured 2-40ms for the same crops instead. The cause
+ *    wasn't fully pinned down (suspected libvips contention over shared
+ *    large raw input across concurrent clones) - if tempted to
+ *    "simplify" this back to clone()+Promise.all, re-benchmark against a
+ *    real multi-megapixel raw buffer first, not a small test image.
+ *  - The region-level parallelism added later (Promise.all across
+ *    *different* regions, each with its own independent sliceRawImage
+ *    call) is a different thing from the clone()+Promise.all trap above -
+ *    it's independent pipelines from the start, never sharing one via
+ *    .clone(), and was benchmarked as a genuine win. Don't conflate the
+ *    two when reasoning about future changes here.
+ */
+
+"use strict";
+
+const sharp = require("sharp");
+const { readBarcodes } = require("zxing-wasm/reader");
+
+// Formats enabled by default. EAN8 is deliberately left out: it's short
+// enough that ZXing's implementations (both the JS port and, in one test
+// against this project's own sample label, zxing-wasm) have a real chance
+// of matching noise in a region that has no barcode in it at all - a
+// confident wrong answer, worse than "not found". Turn it on explicitly
+// per-call if a real EAN-8 code is expected.
+const DEFAULT_FORMATS = ["Code128", "DataMatrix", "QRCode", "EAN13", "Code39", "ITF", "PDF417"];
+
+const WARMUP_WIDTH = 4500;
+const WARMUP_HEIGHT = 6000;
+
+// zxing-wasm's first-ever readBarcodes() call in this process pays a
+// one-time cost (WASM instantiation, plus linear-memory growth to fit a
+// large image) of roughly 1.5-2s that has nothing to do with the image
+// content - verified by timing repeated calls, where call 1 was
+// consistently ~1.8x slower than every call after it. A same-size blank
+// canvas warms it up exactly as well as a real photo does. Module-level so
+// it runs (and is paid for) only once per Node-RED process, however many
+// barcode-locate node instances exist across however many flows.
+let warmupPromise = null;
+function warmUp(readerOptions) {
+	if (!warmupPromise) {
+		warmupPromise = (async () => {
+			const blank = await sharp({
+				create: {
+					width: WARMUP_WIDTH,
+					height: WARMUP_HEIGHT,
+					channels: 3,
+					background: { r: 255, g: 255, b: 255 },
+				},
+			})
+				.png()
+				.toBuffer();
+			try {
+				await readBarcodes(blank, readerOptions);
+			} catch (err) {
+				// a blank canvas decodes to nothing - expected; only the warmup
+				// side effect (WASM init + heap growth) matters here
+			}
+		})();
+	}
+	return warmupPromise;
+}
+
+// Decodes the source image to raw RGBA pixels. With no extractBox, decodes
+// the full frame (used for the automatic fallback, and for full-frame-only
+// mode). With extractBox, decodes only that region via sharp's
+// extract-on-load - cheaper than decoding the full frame and slicing after,
+// see the region-bbox note in the module docstring. Every crop after this
+// point (for search input or preview output) slices whichever buffer this
+// returns via sharp's raw-input mode, which is pure memory work - no
+// re-parsing of the original PNG/JPEG per region.
+async function decodeToRawImage(buffer, extractBox) {
+	let pipeline = sharp(buffer).ensureAlpha();
+	if (extractBox) pipeline = pipeline.extract(extractBox);
+	const { data, info } = await pipeline.raw().toBuffer({ resolveWithObject: true });
+	return { data, width: info.width, height: info.height, channels: info.channels };
+}
+
+function boundingBoxFromPosition(position) {
+	const xs = [position.topLeft.x, position.topRight.x, position.bottomRight.x, position.bottomLeft.x];
+	const ys = [position.topLeft.y, position.topRight.y, position.bottomRight.y, position.bottomLeft.y];
+	return {
+		minX: Math.min(...xs),
+		maxX: Math.max(...xs),
+		minY: Math.min(...ys),
+		maxY: Math.max(...ys),
+	};
+}
+
+// clamps a user-defined region to the image bounds - regions are measured
+// by eye against a specific photo/rig and can drift slightly out of bounds
+// (a region near an edge, or a photo that came in smaller than expected)
+function clampBox(box, imageWidth, imageHeight) {
+	const left = Math.max(0, Math.min(Math.round(box.x), imageWidth - 1));
+	const top = Math.max(0, Math.min(Math.round(box.y), imageHeight - 1));
+	const width = Math.max(1, Math.min(Math.round(box.width), imageWidth - left));
+	const height = Math.max(1, Math.min(Math.round(box.height), imageHeight - top));
+	return { left, top, width, height };
+}
+
+// union bounding box of a set of already-clamped boxes, in the same
+// {left,top,width,height} shape - used to restrict the raw decode to just
+// the area regions actually cover instead of the whole frame
+function unionBox(boxes) {
+	const left = Math.min(...boxes.map((b) => b.left));
+	const top = Math.min(...boxes.map((b) => b.top));
+	const right = Math.max(...boxes.map((b) => b.left + b.width));
+	const bottom = Math.max(...boxes.map((b) => b.top + b.height));
+	return { left, top, width: right - left, height: bottom - top };
+}
+
+// Slices a box out of the raw image, returning both an ImageData-shaped
+// object (fed straight to readBarcodes - no PNG encode/decode round trip
+// needed just to search it) and a PNG buffer (for the result's preview
+// crop). Two independent, *sequential* pipelines from raw.data, not one
+// pipeline forked with .clone() and run concurrently via Promise.all -
+// that combination measured 400-600ms per crop against this raw buffer
+// (90MB, 4096x5500 RGBA) vs. 2-40ms doing the same two crops sequentially
+// as separate pipelines. Cause not fully pinned down (likely libvips
+// contention over the same large raw source when two pipelines derived
+// from it via clone() process concurrently) - the fix is empirical, not
+// fully understood, so don't "simplify" this back to clone()+Promise.all
+// without re-benchmarking against a large raw buffer specifically.
+async function sliceRawImage(raw, box) {
+	const rawCrop = await sharp(raw.data, { raw: { width: raw.width, height: raw.height, channels: raw.channels } })
+		.extract(box)
+		.raw()
+		.toBuffer({ resolveWithObject: true });
+	const previewPng = await sharp(raw.data, { raw: { width: raw.width, height: raw.height, channels: raw.channels } })
+		.extract(box)
+		.png()
+		.toBuffer();
+	const imageData = {
+		data: new Uint8ClampedArray(rawCrop.data.buffer, rawCrop.data.byteOffset, rawCrop.data.byteLength),
+		width: rawCrop.info.width,
+		height: rawCrop.info.height,
+	};
+	return { imageData, previewPng };
+}
+
+// `raw` may be decoded from an extract-on-load restricted to a bbox rather
+// than the full frame (see locateBarcodes) - `origin` carries that bbox's
+// offset plus the true full-image dimensions, so region boxes can be
+// clamped/reported in real image coordinates (roi) while the actual slice
+// happens in raw's own, possibly-offset, coordinate space (localBox).
+async function decodeRegion(raw, origin, region, readerOptions) {
+	const fullBox = clampBox(region, origin.imageWidth, origin.imageHeight);
+	const localBox = { left: fullBox.left - origin.left, top: fullBox.top - origin.top, width: fullBox.width, height: fullBox.height };
+	const { imageData, previewPng } = await sliceRawImage(raw, localBox);
+
+	const start = Date.now();
+	const found = await readBarcodes(imageData, readerOptions);
+	const decodeMs = Date.now() - start;
+
+	return found.map((r) => ({
+		text: r.text,
+		format: r.format,
+		decodeMs,
+		source: "region",
+		regionLabel: region.label || null,
+		roi: { x: fullBox.left, y: fullBox.top, width: fullBox.width, height: fullBox.height },
+		previewBuffer: previewPng,
+	}));
+}
+
+async function decodeFullImage(raw, readerOptions) {
+	const imageData = { data: new Uint8ClampedArray(raw.data.buffer, raw.data.byteOffset, raw.data.byteLength), width: raw.width, height: raw.height };
+
+	const start = Date.now();
+	const found = await readBarcodes(imageData, readerOptions);
+	const decodeMs = Date.now() - start;
+
+	const results = [];
+	for (const r of found) {
+		const bbox = boundingBoxFromPosition(r.position);
+		const box = clampBox(
+			{ x: bbox.minX, y: bbox.minY, width: bbox.maxX - bbox.minX, height: bbox.maxY - bbox.minY },
+			raw.width,
+			raw.height,
+		);
+		const { previewPng } = await sliceRawImage(raw, box);
+		results.push({
+			text: r.text,
+			format: r.format,
+			decodeMs,
+			source: "fullImage",
+			regionLabel: null,
+			roi: { x: box.left, y: box.top, width: box.width, height: box.height },
+			previewBuffer: previewPng,
+		});
+	}
+	return results;
+}
+
+/**
+ * @param {Buffer} buffer - full image bytes
+ * @param {object} options
+ * @param {Array<{label?:string,x:number,y:number,width:number,height:number}>} [options.regions]
+ * @param {"regionsThenAuto"|"regionsOnly"|"autoOnly"} [options.mode]
+ * @param {object} [options.readerOptions] - passed straight through to zxing-wasm's readBarcodes
+ * @returns {Promise<{results: object[], timings: object, usedFullImage: boolean, imageWidth: number, imageHeight: number}>}
+ */
+async function locateBarcodes(buffer, options = {}) {
+	const mode = options.mode || "regionsThenAuto";
+	const regions = Array.isArray(options.regions) ? options.regions : [];
+	const readerOptions = options.readerOptions || { formats: DEFAULT_FORMATS, tryHarder: true, tryRotate: true, maxNumberOfSymbols: 20 };
+
+	await warmUp(readerOptions);
+
+	// header-only read (~1-3ms, no pixel decode) - just enough to clamp
+	// regions and compute their union bbox before touching pixel data
+	const metadata = await sharp(buffer).metadata();
+	const imageWidth = metadata.width;
+	const imageHeight = metadata.height;
+
+	const timings = {};
+	let results = [];
+
+	const tryRegions = mode !== "autoOnly" && regions.length > 0;
+	if (tryRegions) {
+		const start = Date.now();
+		const clampedBoxes = regions.map((r) => clampBox(r, imageWidth, imageHeight));
+		const bbox = unionBox(clampedBoxes);
+		const bboxRaw = await decodeToRawImage(buffer, bbox);
+		const origin = { left: bbox.left, top: bbox.top, imageWidth, imageHeight };
+		const regionResults = await Promise.all(regions.map((region) => decodeRegion(bboxRaw, origin, region, readerOptions)));
+		results = results.concat(...regionResults);
+		timings.regionsMs = Date.now() - start;
+	}
+
+	const shouldFallback = mode === "autoOnly" || (mode === "regionsThenAuto" && results.length === 0);
+	let usedFullImage = false;
+	if (shouldFallback) {
+		usedFullImage = true;
+		const start = Date.now();
+		const raw = await decodeToRawImage(buffer);
+		results = results.concat(await decodeFullImage(raw, readerOptions));
+		timings.fullImageMs = Date.now() - start;
+	}
+
+	return {
+		results,
+		timings,
+		usedFullImage,
+		imageWidth,
+		imageHeight,
+	};
+}
+
+module.exports = { locateBarcodes, DEFAULT_FORMATS };