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

package/lib/components.js

@@ -0,0 +1,84 @@
+/**
+ * Connected-component labeling over a full-resolution binary mask.
+ *
+ * Unlike findRegions() in compare.js (which flood-fills a coarse block
+ * density grid for the heat map), this walks the raw pixel mask directly
+ * and tracks a running centroid per blob - needed to measure checkerboard
+ * square centroids precisely for lib/checkerboard.js.
+ */
+
+"use strict";
+
+/**
+ * 4-connected flood fill. Returns one entry per blob:
+ * { cx, cy, area, x0, y0, x1, y1 } - cx/cy are the centroid (mean x/y),
+ * x0/y0/x1/y1 is the half-open bounding box.
+ */
+function connectedComponents(mask, width, height, opts) {
+	const minArea = (opts && opts.minArea) || 0;
+	const maxArea = (opts && opts.maxArea) || Infinity;
+	const n = width * height;
+	const visited = new Uint8Array(n);
+	const stack = new Int32Array(n);
+	const blobs = [];
+
+	for (let start = 0; start < n; start++) {
+		if (!mask[start] || visited[start]) continue;
+		let stackLen = 0;
+		visited[start] = 1;
+		stack[stackLen++] = start;
+
+		let minX = width;
+		let minY = height;
+		let maxX = -1;
+		let maxY = -1;
+		let sumX = 0;
+		let sumY = 0;
+		let area = 0;
+
+		while (stackLen > 0) {
+			const idx = stack[--stackLen];
+			const x = idx % width;
+			const y = (idx / width) | 0;
+			if (x < minX) minX = x;
+			if (x > maxX) maxX = x;
+			if (y < minY) minY = y;
+			if (y > maxY) maxY = y;
+			sumX += x;
+			sumY += y;
+			area++;
+
+			if (x > 0 && mask[idx - 1] && !visited[idx - 1]) {
+				visited[idx - 1] = 1;
+				stack[stackLen++] = idx - 1;
+			}
+			if (x < width - 1 && mask[idx + 1] && !visited[idx + 1]) {
+				visited[idx + 1] = 1;
+				stack[stackLen++] = idx + 1;
+			}
+			if (y > 0 && mask[idx - width] && !visited[idx - width]) {
+				visited[idx - width] = 1;
+				stack[stackLen++] = idx - width;
+			}
+			if (y < height - 1 && mask[idx + width] && !visited[idx + width]) {
+				visited[idx + width] = 1;
+				stack[stackLen++] = idx + width;
+			}
+		}
+
+		if (area < minArea || area > maxArea) continue;
+		blobs.push({
+			cx: sumX / area,
+			cy: sumY / area,
+			area,
+			x0: minX,
+			y0: minY,
+			x1: maxX + 1,
+			y1: maxY + 1,
+		});
+	}
+
+	return blobs;
+}
+
+module.exports = { connectedComponents };

package/lib/dilate.js

@@ -0,0 +1,65 @@
+/**
+ * Separable morphological dilation with a square structuring element,
+ * via the sliding-window-maximum (monotonic deque) algorithm.
+ *
+ * Cost is O(width*height) regardless of the radius - a naive dilate that
+ * scans a (2r+1)x(2r+1) window per pixel would cost O(width*height*r^2),
+ * which gets slow fast as the tolerance radius grows. Two 1D passes (rows,
+ * then columns) give the same result as a single square-window 2D max
+ * filter because max is separable over a rectangular structuring element.
+ */
+
+"use strict";
+
+const { allocU8 } = require("./shared.js");
+
+// dst[j] = max(src[offset + max(0,j-r)*stride .. offset + min(n-1,j+r)*stride])
+// dq is caller-provided scratch (Int32Array, length >= n) to avoid
+// reallocating per row/column.
+function slidingMax1D(src, offset, stride, n, r, dst, dstOffset, dstStride, dq) {
+	let dqLen = 0;
+	let dqStart = 0;
+	let added = -1;
+	for (let j = 0; j < n; j++) {
+		const rightIdx = j + r < n - 1 ? j + r : n - 1;
+		while (added < rightIdx) {
+			added++;
+			const v = src[offset + added * stride];
+			while (dqLen > dqStart && src[offset + dq[dqLen - 1] * stride] <= v)
+				dqLen--;
+			dq[dqLen++] = added;
+		}
+		const leftIdx = j - r > 0 ? j - r : 0;
+		while (dq[dqStart] < leftIdx) dqStart++;
+		dst[dstOffset + j * dstStride] = src[offset + dq[dqStart] * stride];
+	}
+}
+
+/**
+ * Dilate a binary/grayscale Uint8Array (row-major, width x height) by
+ * `radius` px. Returns a new Uint8Array; a radius <= 0 returns a copy.
+ */
+function dilate(src, width, height, radius) {
+	// shared-backed so the worker pool can read it without a copy
+	const out = allocU8(width * height);
+	if (radius <= 0) {
+		out.set(src);
+		return out;
+	}
+	const scratchLen = width > height ? width : height;
+	const dq = new Int32Array(scratchLen);
+	const tmp = allocU8(width * height);
+
+	// horizontal pass: src -> tmp (contiguous rows, stride 1)
+	for (let y = 0; y < height; y++) {
+		const rowOffset = y * width;
+		slidingMax1D(src, rowOffset, 1, width, radius, tmp, rowOffset, 1, dq);
+	}
+	// vertical pass: tmp -> out (columns, stride = width)
+	for (let x = 0; x < width; x++) {
+		slidingMax1D(tmp, x, width, height, radius, out, x, width, dq);
+	}
+	return out;
+}
+
+module.exports = { dilate, slidingMax1D };

package/lib/inspector.js

@@ -0,0 +1,188 @@
+/**
+ * Main-thread client for the inspection pipeline.
+ *
+ * Why this exists: `compareFrame` is ~600ms of CPU, and Node-RED has one
+ * thread. Before this, an unpinned frame blocked the runtime's event loop
+ * for 1499ms - measured - which stalls every other flow in the instance,
+ * the editor websocket, HTTP endpoints and MQTT keepalives along with it.
+ * Moving the pipeline into a worker takes the main thread's share of a
+ * frame to roughly 12ms.
+ *
+ * It does not make a frame faster. A 600ms frame is still 600ms; it stops
+ * being 600ms of frozen runtime.
+ *
+ * One inspector per process, spawned on first use and never torn down -
+ * the same decision lib/pool.js makes, for the same reason: a respawn
+ * costs a worker start plus a ~280ms re-prepare of the golden, which a
+ * redeploy would otherwise pay on its first frame. It is unref()'d, so an
+ * idle inspector never holds the process open.
+ *
+ * The nested worker pool lives inside the inspector, not here.
+ */
+
+"use strict";
+
+const path = require("node:path");
+const { HAS_SAB } = require("./shared.js");
+const core = require("./inspectorCore.js");
+
+const WORKER_PATH = path.join(__dirname, "inspectorWorker.js");
+
+let Worker = null;
+try {
+	({ Worker } = require("node:worker_threads"));
+} catch {
+	Worker = null;
+}
+
+/**
+ * Inline means calling the same core functions on this thread instead of
+ * in a worker. It is a fallback, not a second implementation - the
+ * verdict cannot differ, because it is the same code. What *does* differ
+ * is everything around the call: inline keeps real Buffers and the
+ * original Error objects, where the worker path gets structured clones of
+ * both. That is why the node-level tests run in both modes.
+ */
+const INLINE =
+	process.env.GOLDEN_COMPARE_INLINE === "1" || !HAS_SAB || Worker === null;
+
+let worker = null;
+let pending = null;
+let nextId = 1;
+
+function spawn() {
+	const w = new Worker(WORKER_PATH);
+	const waiting = new Map();
+
+	const rejectAll = (err) => {
+		if (waiting.size === 0) return;
+		const entries = Array.from(waiting.values());
+		waiting.clear();
+		w.unref();
+		for (const entry of entries) entry.reject(err);
+	};
+
+	w.on("message", (msg) => {
+		const entry = msg == null ? undefined : waiting.get(msg.id);
+		if (!entry) return; // a reply for a request already rejected
+		waiting.delete(msg.id);
+		if (waiting.size === 0) w.unref();
+		if (msg.error) {
+			const err = new Error(msg.error.message);
+			err.name = msg.error.name || "Error";
+			if (msg.error.stack) err.stack = msg.error.stack;
+			entry.reject(err);
+		} else {
+			entry.resolve(msg);
+		}
+	});
+	const drop = (err) => {
+		if (worker === w) {
+			worker = null;
+			pending = null;
+		}
+		rejectAll(err);
+	};
+	w.on("error", (err) => {
+		drop(err);
+		w.terminate();
+	});
+	w.on("exit", (code) =>
+		drop(new Error(`inspector exited (code ${code}) before answering`)),
+	);
+	// idle: the listeners above would otherwise ref the port and keep the
+	// process alive - the same trap lib/pool.js documents
+	w.unref();
+	worker = w;
+	pending = waiting;
+	return w;
+}
+
+function send(op, message) {
+	const w = worker || spawn();
+	const waiting = pending;
+	return new Promise((resolve, reject) => {
+		const id = nextId++;
+		if (waiting.size === 0) w.ref();
+		waiting.set(id, { resolve, reject });
+		try {
+			w.postMessage({ ...message, id, op });
+		} catch (err) {
+			waiting.delete(id);
+			if (waiting.size === 0) w.unref();
+			reject(err);
+		}
+	});
+}
+
+const call = (op, message) =>
+	INLINE ? core[op](message) : send(op, message);
+
+/**
+ * Structured clone turns a Buffer into a plain Uint8Array, and the
+ * difference is not academic: msg.printHeatmap is documented as a PNG
+ * Buffer and wired straight into an image viewer in the demo flow, and
+ *
+ *   Buffer.toString("base64")     -> "AQID+g=="
+ *   Uint8Array.toString("base64") -> "1,2,3,250"
+ *
+ * so the output would be silently wrong rather than an error. Re-wrapping
+ * shares the same memory; it does not copy.
+ *
+ * The null checks matter as much as the wrap: heatmaps are null unless
+ * asked for, and `stages` is null unless debugStages is on - which is the
+ * default, so an unguarded version would fail on the first frame of a
+ * default-configured flow.
+ */
+function asBuffer(value) {
+	if (value == null) return value;
+	if (Buffer.isBuffer(value)) return value;
+	return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+}
+
+function rewrapResult(result) {
+	if (!result) return result;
+	if (result.printBlemish) {
+		result.printBlemish.heatmap = asBuffer(result.printBlemish.heatmap);
+	}
+	if (result.backgroundBlemish) {
+		result.backgroundBlemish.heatmap = asBuffer(
+			result.backgroundBlemish.heatmap,
+		);
+	}
+	if (result.stages) {
+		for (const key of Object.keys(result.stages)) {
+			result.stages[key] = asBuffer(result.stages[key]);
+		}
+	}
+	return result;
+}
+
+/** Ensure a prepared golden exists for this key. Pass `golden` only after
+ * a first call has answered `needGolden` - the bytes are expensive to
+ * produce and the store usually already has them. */
+async function prepare({ cacheKey, cfg, golden }) {
+	return call("prepare", { cacheKey, cfg, golden });
+}
+
+async function inspect({ cacheKey, cfg, frame }) {
+	const reply = await call("inspect", { cacheKey, cfg, frame });
+	if (reply.needGolden) return reply;
+	return { ...reply, result: rewrapResult(reply.result) };
+}
+
+async function calibrate({ cfg, image }) {
+	return call("calibrate", { cfg, image });
+}
+
+/** Tests only. The inspector is process-wide and deliberately survives a
+ * redeploy. */
+function shutdown() {
+	const w = worker;
+	worker = null;
+	pending = null;
+	if (w) w.terminate();
+	core.clear();
+}
+
+module.exports = { prepare, inspect, calibrate, shutdown, INLINE };

package/lib/inspectorCore.js

@@ -0,0 +1,128 @@
+/**
+ * The inspection pipeline behind one small request/response surface,
+ * plus the prepared-golden store it needs.
+ *
+ * This module is called two ways: directly, on the Node-RED thread, when
+ * worker threads or SharedArrayBuffer are unavailable; and from inside
+ * `lib/inspectorWorker.js`, which is where it runs in production. Both
+ * paths call these same functions, so a verdict cannot depend on which
+ * one ran - the same discipline `lib/parallel.js` uses for its kernels,
+ * and for the same reason.
+ *
+ * It deliberately does no file I/O. Structured clone drops an error's
+ * own properties - a cloned ENOENT arrives with `err.code === undefined`,
+ * and `golden-compare.js` branches on exactly that - so every path that
+ * needs to tell "missing" from "refused" stays on the calling thread.
+ */
+
+"use strict";
+
+const { prepareGolden, compareFrame } = require("./compare.js");
+const { measureCheckerboard } = require("./checkerboard.js");
+
+/**
+ * How many prepared goldens to keep.
+ *
+ * There has to be a bound. The store lives for the life of the process
+ * (like the worker pool, and for the same reason - re-preparing costs
+ * ~280ms), and it is keyed by everything baked into the golden, which
+ * includes settings a *message* can override: threshold, thresholdMode,
+ * sauvolaRadius, sauvolaK, inkMargin, backgroundTolerance, debugStages.
+ * A flow sweeping msg.threshold would otherwise add an entry per frame,
+ * each holding five masks - around 84MB at workingSize 4096.
+ *
+ * Four covers the cases that are actually concurrent: a couple of nodes
+ * with different goldens, plus a settings change being tuned.
+ */
+const MAX_GOLDENS = 4;
+
+// cacheKey -> { promise }, in insertion order, so the first key is the
+// least recently used.
+const goldens = new Map();
+
+function touch(cacheKey, entry) {
+	goldens.delete(cacheKey);
+	goldens.set(cacheKey, entry);
+	while (goldens.size > MAX_GOLDENS) {
+		goldens.delete(goldens.keys().next().value);
+	}
+}
+
+/** A SharedArrayBuffer handle back to a Buffer view over the same bytes.
+ * `Buffer.from(view)` would copy the whole frame again. */
+function view(handle) {
+	return handle == null ? null : Buffer.from(handle, 0, handle.byteLength);
+}
+
+/**
+ * Everything the calling thread still needs to know about a prepared
+ * golden: the two warnings it raises, the trained-transform record, and
+ * the threshold level. mmPerWorkingPx is not read on that side today -
+ * it is here so the reply is a complete description of the golden rather
+ * than a list of current callers, which is the thing that rots.
+ */
+function goldenMeta(golden) {
+	return {
+		nativeWidth: golden.nativeWidth,
+		nativeHeight: golden.nativeHeight,
+		width: golden.width,
+		height: golden.height,
+		thresholdLevel: golden.thresholdLevel,
+		mmPerWorkingPx: golden.mmPerWorkingPx,
+	};
+}
+
+/**
+ * Make sure the store holds a golden for `cacheKey`.
+ *
+ * Answers `{ needGolden: true }` rather than throwing when it does not
+ * have the key and was not given the bytes, so the caller can send them
+ * only when they are actually needed - a golden the store already holds
+ * must not be re-read from disk just to be discarded as a duplicate.
+ */
+async function prepare({ cacheKey, cfg, golden }) {
+	let entry = goldens.get(cacheKey);
+	if (!entry) {
+		if (!golden) return { needGolden: true };
+		entry = {};
+		entry.promise = prepareGolden(view(golden), cfg).catch((err) => {
+			// Drop the entry so the next message retries, instead of every
+			// later frame inheriting one transient failure for the life of
+			// the process. golden-compare.js does the same for its own
+			// cache; both are needed, since they are two caches.
+			if (goldens.get(cacheKey) === entry) goldens.delete(cacheKey);
+			throw err;
+		});
+		goldens.set(cacheKey, entry);
+	}
+	touch(cacheKey, entry);
+	return { goldenMeta: goldenMeta(await entry.promise) };
+}
+
+/**
+ * Compare one frame. `{ needGolden: true }` here means the golden was
+ * evicted between prepare and inspect; the caller re-prepares and retries
+ * exactly once.
+ */
+async function inspect({ cacheKey, cfg, frame }) {
+	const entry = goldens.get(cacheKey);
+	if (!entry) return { needGolden: true };
+	touch(cacheKey, entry);
+	const golden = await entry.promise;
+	const result = await compareFrame(view(frame), golden, cfg);
+	return { result, goldenMeta: goldenMeta(golden) };
+}
+
+/** checkerboard-calibrate's measurement, which is otherwise ~59ms of
+ * synchronous work on the event loop at full sensor resolution. */
+async function calibrate({ cfg, image }) {
+	return { result: await measureCheckerboard(view(image), cfg) };
+}
+
+/** Testing seam: the store is process-wide and deliberately survives a
+ * redeploy, so only tests should ever clear it. */
+function clear() {
+	goldens.clear();
+}
+
+module.exports = { prepare, inspect, calibrate, clear, MAX_GOLDENS };

package/lib/inspectorWorker.js

@@ -0,0 +1,40 @@
+/**
+ * Worker side of the inspector: a thin messaging wrapper around
+ * lib/inspectorCore.js.
+ *
+ * Nothing but plumbing belongs here. The core is what runs on the
+ * Node-RED thread when worker threads are unavailable, so any logic that
+ * crept in here would be logic the inline path does not have.
+ *
+ * Replies carry the id of the request they answer, for the reason
+ * lib/pool.js documents at length: settling on "the next reply" lets two
+ * concurrent requests take each other's answers.
+ */
+
+"use strict";
+
+const { parentPort } = require("node:worker_threads");
+const core = require("./inspectorCore.js");
+
+parentPort.on("message", async (msg) => {
+	const { id, op } = msg;
+	try {
+		const handler = core[op];
+		if (typeof handler !== "function") {
+			throw new Error(`unknown inspector op: ${op}`);
+		}
+		parentPort.postMessage({ id, ...(await handler(msg)) });
+	} catch (err) {
+		// name and stack are carried explicitly: structured clone keeps
+		// neither an Error's own properties nor its class, so anything the
+		// caller wants to see has to be named here.
+		parentPort.postMessage({
+			id,
+			error: {
+				message: err && err.message ? err.message : String(err),
+				name: err && err.name ? err.name : "Error",
+				stack: err && err.stack ? err.stack : undefined,
+			},
+		});
+	}
+});

package/lib/integral.js

@@ -0,0 +1,76 @@
+/**
+ * Summed-area table (integral image) over a binary/grayscale Uint8Array,
+ * so a rectangular block sum is an O(1) lookup instead of an O(block area)
+ * scan - used to turn the per-pixel defect mask into a heat-map grid
+ * without re-walking every pixel per block.
+ */
+
+"use strict";
+
+const { allocU32, allocF64 } = require("./shared.js");
+
+function buildIntegral(src, width, height) {
+	const stride = width + 1;
+	// shared-backed: the warp kernel reads this from worker threads
+	const integral = allocU32(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++) {
+			rowSum += src[srcRow + x];
+			integral[intRow + x + 1] = integral[intPrevRow + x + 1] + rowSum;
+		}
+	}
+	return { integral, stride, width, height };
+}
+
+/**
+ * Wider-accumulator twin of buildIntegral, for summing *grey* values
+ * (0-255) rather than binary 0/1 masks.
+ *
+ * A Uint32 table wraps at 2^32 / 255 ~= 16.8M pixels. The frame's working
+ * canvas is capped at 2.5x workingSize on the long edge, which at
+ * workingSize 3072 is roughly 7680x5720 - the bottom rows of a Uint32
+ * table there wrap silently and the area-average warp reads garbage
+ * (phantom or missed defects). Float64 holds every integer sum in this
+ * codebase exactly (well past 2^53), so a grey table built this way is
+ * exact regardless of canvas size. The binary-mask tables must stay
+ * Uint32: they are what scoreCandidate/blockSum read inline, and the
+ * Float64 form would cost 2x the memory for no benefit.
+ */
+function buildIntegral64(src, width, height) {
+	const stride = width + 1;
+	// shared-backed: the warp kernel reads this from worker threads
+	const integral = allocF64(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++) {
+			rowSum += src[srcRow + x];
+			integral[intRow + x + 1] = integral[intPrevRow + x + 1] + rowSum;
+		}
+	}
+	return { integral, stride, width, height };
+}
+
+// Sum over the half-open rectangle [x0,x1) x [y0,y1), clamped to bounds.
+function blockSum(table, x0, y0, x1, y1) {
+	const { integral, stride, width, height } = table;
+	const cx0 = x0 < 0 ? 0 : x0 > width ? width : x0;
+	const cy0 = y0 < 0 ? 0 : y0 > height ? height : y0;
+	const cx1 = x1 < 0 ? 0 : x1 > width ? width : x1;
+	const cy1 = y1 < 0 ? 0 : y1 > height ? height : y1;
+	if (cx1 <= cx0 || cy1 <= cy0) return 0;
+	return (
+		integral[cy1 * stride + cx1] -
+		integral[cy0 * stride + cx1] -
+		integral[cy1 * stride + cx0] +
+		integral[cy0 * stride + cx0]
+	);
+}
+
+module.exports = { buildIntegral, buildIntegral64, blockSum };