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

package/lib/pool.js

@@ -0,0 +1,250 @@
+/**
+ * A persistent worker-thread pool for the per-pixel stages.
+ *
+ * Everything after decode used to run on one core while the rest of the
+ * machine sat idle: on a 16-core host, ~630ms of an 850ms frame was
+ * single-threaded JavaScript. (`sharp` already decodes and resizes on all
+ * cores, which is why decode is not in here.)
+ *
+ * The pool is created once and reused. That is not an optimisation
+ * detail, it is the whole feasibility argument: spawning eight workers
+ * costs ~60ms, which would wipe out the ~40ms a frame's parallel stages
+ * save. Measured on the tile matcher, a warm pool takes 48ms of work down
+ * to 8ms with eight workers.
+ *
+ * Buffers are passed as SharedArrayBuffers, so a dispatch ships a handful
+ * of numbers and a memory handle rather than tens of megabytes.
+ *
+ * Callers must be able to do without it: `shouldParallelise` is false for
+ * small images, for a pool of one, and when SharedArrayBuffer is missing,
+ * and every kernel here has a serial twin that stays the reference
+ * implementation.
+ *
+ * Two invariants hold the concurrent case together, because Node-RED never
+ * awaits a node's input handler and two frames overlap freely inside
+ * compareFrame:
+ *
+ *  - **A dispatch is settled by id, never by "the next reply".** See
+ *    spawn(). Getting this wrong did not fail loudly; it returned a frame
+ *    aligned against a half-written buffer.
+ *  - **The pool is never torn down because a different size was asked
+ *    for.** See getPool(). It grows and stays grown.
+ */
+
+const os = require("node:os");
+const path = require("node:path");
+const { Worker } = require("node:worker_threads");
+const { HAS_SAB } = require("./shared.js");
+
+const WORKER_PATH = path.join(__dirname, "poolWorker.js");
+
+// Below this many pixels the dispatch costs more than the work saved.
+const MIN_PIXELS_TO_SPLIT = 400000;
+
+let pool = null;
+let nextDispatchId = 1;
+
+function defaultSize() {
+	const cpus = os.cpus().length;
+	// Leave a core for the event loop and for libvips finishing a decode.
+	//
+	// The cap used to be eight, on the grounds that the defect scan's curve
+	// is flat past it (5.76x at 8, 6.55x at 16). That is true of the scan
+	// and false of the alignment polish, which is the larger cost: the
+	// polish is ~15 *sequential* rounds of a small batch, so each round
+	// pays a fixed dispatch cost and finishes no sooner than its slowest
+	// worker. Measured on a 16-core host against a 4096x5500 frame, pinned,
+	// with bit-identical transforms and verdicts at every size:
+	//
+	//   workers   8 -> polish 342ms, align 798ms
+	//   workers  12 -> polish 220ms, align 680ms
+	//   workers  16 -> polish 215ms, align 678ms
+	//   workers  24 -> polish 216ms, align 680ms
+	//
+	// It plateaus around twelve, so the cap is sixteen rather than "one per
+	// core": past the plateau the extra threads only cost memory and
+	// contend with whatever else the instance is running. Boxes with nine
+	// cores or fewer are unaffected.
+	return Math.max(1, Math.min(16, cpus - 1));
+}
+
+/** The pool size a request resolves to. 0 (the default) means "one per
+ * core, capped at sixteen"; anything else is taken literally. */
+function wanted(size) {
+	return size && size > 0 ? size : defaultSize();
+}
+
+/**
+ * Spawn one worker and give it the *only* listeners it will ever have.
+ *
+ * The listeners are permanent, and each dispatch is tracked by id in
+ * `pending`, because the obvious alternative is broken: registering
+ * `once("message")` per dispatch means two concurrent dispatches to the
+ * same worker each add a listener, and the first reply fires *both* -
+ * EventEmitter delivers to every listener registered at emit time, and
+ * `once` only removes after delivery. The second caller then resolved on
+ * someone else's reply and read a half-written output buffer. Through the
+ * real pipeline that surfaced as two concurrent frames both reporting
+ * transform.score = 0, which is not an error value: it is a perfect match,
+ * it beats every candidate, and the part passes.
+ *
+ * Permanent listeners cost one thing that has to be paid back explicitly:
+ * an attached listener refs the worker's port, and the old per-dispatch
+ * attach/detach was doing that ref-counting by accident. Hence the
+ * ref()/unref() around `pending` going empty and non-empty - without it an
+ * idle pool holds the process open and `npm test` never exits.
+ */
+function spawn() {
+	const worker = new Worker(WORKER_PATH);
+	const pending = new Map();
+	worker.pending = pending;
+
+	const rejectAll = (err) => {
+		if (pending.size === 0) return;
+		const waiting = Array.from(pending.values());
+		pending.clear();
+		worker.unref();
+		for (const entry of waiting) entry.reject(err);
+	};
+
+	worker.on("message", (msg) => {
+		// null-safe, and an unknown id is ignored rather than thrown on: a
+		// reply can arrive for a dispatch already rejected by an earlier
+		// error or exit, and throwing here would be an uncaught exception
+		// inside the EventEmitter - it would take the process down, not the
+		// frame.
+		const entry = msg == null ? undefined : pending.get(msg.id);
+		if (!entry) return;
+		pending.delete(msg.id);
+		if (pending.size === 0) worker.unref();
+		if (msg.error) entry.reject(new Error(msg.error));
+		else entry.resolve();
+	});
+	worker.on("error", (err) => {
+		// only this worker leaves the pool. Tearing the whole pool down here
+		// would fail every other in-flight frame for one worker's fault; the
+		// next getPool() grows a replacement.
+		remove(worker);
+		rejectAll(err);
+		worker.terminate();
+	});
+	worker.on("exit", (code) => {
+		// a terminated or crashed worker can never answer its dispatches;
+		// without this they hung forever and the frame silently never
+		// settled (shutdown()/terminate() emit only 'exit')
+		remove(worker);
+		rejectAll(
+			new Error(`worker exited (code ${code}) before finishing its range`),
+		);
+	});
+	// idle: the listeners above would otherwise hold the loop open
+	worker.unref();
+	return worker;
+}
+
+function remove(worker) {
+	if (!pool) return;
+	const i = pool.workers.indexOf(worker);
+	if (i >= 0) pool.workers.splice(i, 1);
+}
+
+/**
+ * One pool, grown to the largest size anyone has asked for, never torn
+ * down because a different size was asked for next.
+ *
+ * The pool used to be rebuilt whenever the requested size changed, which
+ * two things reach: `msg.workers` is a per-message override, and two
+ * golden-compare nodes can be configured differently. That cost ~60ms of
+ * respawn per frame - the very cost this module's header argues is
+ * unaffordable - and, worse, the teardown terminated workers that another
+ * in-flight frame was still waiting on, failing that frame for no reason
+ * of its own.
+ *
+ * Growing instead keeps the thread count bounded by the same `workers`
+ * clamp as before (64), and a caller asking for fewer simply dispatches to
+ * a prefix of the pool.
+ */
+function getPool(size) {
+	const want = wanted(size);
+	if (!HAS_SAB || want <= 1) return null;
+	if (!pool) pool = { workers: [] };
+	while (pool.workers.length < want) pool.workers.push(spawn());
+	return pool;
+}
+
+function shouldParallelise(pixels, size) {
+	if (!HAS_SAB) return false;
+	if (size === 1) return false;
+	return pixels >= MIN_PIXELS_TO_SPLIT;
+}
+
+/**
+ * How many workers getPool(size) will actually run - for callers that
+ * must size per-worker scratch before dispatching (defectParallel's
+ * counter slots) and cannot wait until the pool exists. Keep in step
+ * with getPool's `want` computation.
+ */
+function poolSize(size) {
+	const want = wanted(size);
+	if (!HAS_SAB || want <= 1) return 0;
+	return want;
+}
+
+/** One dispatch to one worker, settled by id. */
+function dispatch(worker, message) {
+	return new Promise((resolve, reject) => {
+		const id = nextDispatchId++;
+		if (worker.pending.size === 0) worker.ref();
+		worker.pending.set(id, { resolve, reject });
+		try {
+			worker.postMessage({ ...message, id });
+		} catch (err) {
+			// a worker terminated between getPool() and here would otherwise
+			// leave this promise unsettled forever
+			worker.pending.delete(id);
+			if (worker.pending.size === 0) worker.unref();
+			reject(err);
+		}
+	});
+}
+
+/**
+ * Split [0,total) into one contiguous range per worker and run `kernel`
+ * over each. `ctx` must contain only SharedArrayBuffers and structured-
+ * cloneable scalars.
+ */
+function runRanges(kernel, ctx, total, size) {
+	const p = getPool(size);
+	if (!p) return null;
+	// A prefix of the pool, not all of it: the pool may hold more workers
+	// than this caller asked for, and `index` has to stay within 0..want-1
+	// to match the per-worker scratch the caller already sized from
+	// poolSize() - defectParallel's counter slots, in particular.
+	const want = wanted(size);
+	const workers = p.workers.slice(0, want);
+	const n = workers.length;
+	return Promise.all(
+		workers.map((worker, i) => {
+			const lo = Math.floor((i * total) / n);
+			const hi = Math.floor(((i + 1) * total) / n);
+			if (hi <= lo) return Promise.resolve();
+			return dispatch(worker, { kernel, ctx, lo, hi, index: i });
+		}),
+	);
+}
+
+function shutdown() {
+	if (!pool) return;
+	const workers = pool.workers;
+	pool = null;
+	for (const w of workers) w.terminate();
+}
+
+module.exports = {
+	getPool,
+	runRanges,
+	shouldParallelise,
+	shutdown,
+	defaultSize,
+	poolSize,
+};

package/lib/poolWorker.js

@@ -0,0 +1,324 @@
+/**
+ * Worker side of the pool. Each kernel does the same arithmetic as its
+ * serial twin, over a contiguous range of rows or columns.
+ *
+ * The serial implementations stay the reference: they are what the tests
+ * assert against, and `test/parallel.test.js` asserts these produce
+ * byte-identical output. Keep them in step - a divergence here shows up
+ * as a defect that appears or vanishes depending on how many cores the
+ * machine has, which is close to the worst bug this project could have.
+ */
+
+"use strict";
+
+const { parentPort } = require("node:worker_threads");
+const { slidingMax1D } = require("./dilate.js");
+const { warpRows } = require("./warp.js");
+const { fieldRows, applyRows } = require("./localAlign.js");
+
+let scratch = null;
+function deque(n) {
+	if (scratch === null || scratch.length < n) scratch = new Int32Array(n);
+	return scratch;
+}
+
+const kernels = {
+	// horizontal pass of the separable dilation: rows are independent
+	dilateRows({ src, tmp, width, height, radius }, lo, hi) {
+		const s = new Uint8Array(src);
+		const t = new Uint8Array(tmp);
+		const dq = deque(width);
+		for (let y = lo; y < hi; y++) {
+			const off = y * width;
+			slidingMax1D(s, off, 1, width, radius, t, off, 1, dq);
+		}
+		void height;
+	},
+
+	// Summed-area table, pass 1: each row's own prefix sum, rows
+	// independent. The serial twin fuses this with the column
+	// accumulation below, which is cache-friendly but carries a
+	// dependency from one row to the next and so cannot be split.
+	integralRows({ src, out, width, stride }, lo, hi) {
+		const S = new Uint8Array(src);
+		const O = new Uint32Array(out);
+		for (let y = lo; y < hi; y++) {
+			const srcRow = y * width;
+			const intRow = (y + 1) * stride;
+			let rowSum = 0;
+			for (let x = 0; x < width; x++) {
+				rowSum += S[srcRow + x];
+				O[intRow + x + 1] = rowSum;
+			}
+		}
+	},
+
+	// Pass 2: accumulate each column downwards, columns independent.
+	// `lo`/`hi` are a column range, but the loops are row-major inside it
+	// so each worker walks a contiguous run of every row rather than
+	// striding down memory - row y only needs row y-1, which the previous
+	// iteration of this same loop already finished.
+	integralCols({ out, height, stride }, lo, hi) {
+		const O = new Uint32Array(out);
+		for (let y = 0; y < height; y++) {
+			const intRow = (y + 1) * stride;
+			const intPrevRow = y * stride;
+			for (let x = lo; x < hi; x++) {
+				O[intRow + x + 1] += O[intPrevRow + x + 1];
+			}
+		}
+	},
+
+	// The grey twin of the two passes above. Float64 addition is not
+	// associative in general, but every value here is an integer: greys
+	// are 0-255 and the largest sum this canvas can reach is far below
+	// 2^53, so each partial sum is exact and the split cannot change a
+	// single bit - the same reasoning that made this table Float64 rather
+	// than Uint32 in the first place.
+	integralRows64({ src, out, width, stride }, lo, hi) {
+		const S = new Uint8Array(src);
+		const O = new Float64Array(out);
+		for (let y = lo; y < hi; y++) {
+			const srcRow = y * width;
+			const intRow = (y + 1) * stride;
+			let rowSum = 0;
+			for (let x = 0; x < width; x++) {
+				rowSum += S[srcRow + x];
+				O[intRow + x + 1] = rowSum;
+			}
+		}
+	},
+
+	integralCols64({ out, height, stride }, lo, hi) {
+		const O = new Float64Array(out);
+		for (let y = 0; y < height; y++) {
+			const intRow = (y + 1) * stride;
+			const intPrevRow = y * stride;
+			for (let x = lo; x < hi; x++) {
+				O[intRow + x + 1] += O[intPrevRow + x + 1];
+			}
+		}
+	},
+
+	// vertical pass: columns are independent
+	dilateCols({ tmp, out, width, height, radius }, lo, hi) {
+		const t = new Uint8Array(tmp);
+		const o = new Uint8Array(out);
+		const dq = deque(height);
+		for (let x = lo; x < hi; x++) {
+			slidingMax1D(t, x, width, height, radius, o, x, width, dq);
+		}
+	},
+
+	// defect = a AND NOT b, then cleared where either image was ambiguous
+	defect({ a, b, ambiguousA, ambiguousB, out, counts, width }, lo, hi, index) {
+		const A = new Uint8Array(a);
+		const B = new Uint8Array(b);
+		const O = new Uint8Array(out);
+		const C = new Uint32Array(counts);
+		const ambA = ambiguousA ? new Uint8Array(ambiguousA) : null;
+		const ambB = ambiguousB ? new Uint8Array(ambiguousB) : null;
+		let count = 0;
+		for (let y = lo; y < hi; y++) {
+			const row = y * width;
+			for (let x = 0; x < width; x++) {
+				const i = row + x;
+				let d = A[i] & ~B[i] & 1;
+				if (d && ((ambA !== null && ambA[i]) || (ambB !== null && ambB[i]))) d = 0;
+				O[i] = d;
+				count += d;
+			}
+		}
+		// one slot per worker, summed by the caller - avoids an atomic in
+		// the inner loop for a number only needed once at the end
+		C[index] = count;
+	},
+
+	// resample the frame into golden's grid - rows are independent
+	warp(
+		{ src, out, srcW, srcH, mx, my, theta, ox, oy, outW, sat, satStride },
+		lo,
+		hi,
+	) {
+		// the grey summed-area table is Float64 (see buildGrayTable - a
+		// Uint32 table wraps on large frames); keep this in step with the
+		// serial path or the two stop being byte-identical
+		const table = sat
+			? {
+					integral: new Float64Array(sat),
+					stride: satStride,
+					width: srcW,
+					height: srcH,
+				}
+			: null;
+		warpRows(
+			new Uint8Array(out),
+			new Uint8Array(src),
+			srcW,
+			srcH,
+			mx,
+			my,
+			theta,
+			ox,
+			oy,
+			outW,
+			table,
+			lo,
+			hi,
+		);
+	},
+
+	// per-tile displacement - tile rows are independent
+	localField(
+		{
+			golden,
+			target,
+			fx,
+			fy,
+			valid,
+			width,
+			height,
+			gridW,
+			tile,
+			maxOffset,
+			minStdDev,
+		},
+		lo,
+		hi,
+	) {
+		fieldRows(
+			new Uint8Array(golden),
+			new Uint8Array(target),
+			width,
+			height,
+			{ tile, maxOffset, minStdDev },
+			{
+				fx: new Float32Array(fx),
+				fy: new Float32Array(fy),
+				valid: new Uint8Array(valid),
+				gridW,
+			},
+			lo,
+			hi,
+		);
+	},
+
+	// resample under the displacement field - rows are independent
+	localApply(
+		{ target, out, fx, fy, width, height, gridW, gridH, tile },
+		lo,
+		hi,
+	) {
+		applyRows(
+			new Uint8Array(out),
+			new Uint8Array(target),
+			width,
+			height,
+			{ fx: new Float32Array(fx), fy: new Float32Array(fy), gridW, gridH },
+			tile,
+			lo,
+			hi,
+		);
+	},
+
+	// Score a contiguous run of candidate transforms for the alignment
+	// polish - candidates are independent, so this splits by candidate
+	// rather than by rows.
+	//
+	// It has to reproduce warpGray + the serial scorer *exactly*, not
+	// closely: these numbers are compared against each other to choose a
+	// transform, so a last-bit difference that depended on how the batch
+	// was split would make the chosen alignment a function of the machine's
+	// core count. Hence the same fill of 255, the same mx/my > 1.001 test
+	// for the area-average path, and warpRows itself rather than a copy.
+	objective(
+		{
+			gray,
+			fgObj,
+			sat,
+			satStride,
+			srcW,
+			srcH,
+			outW,
+			outH,
+			level,
+			params,
+			scores,
+		},
+		lo,
+		hi,
+	) {
+		const src = new Uint8Array(gray);
+		const fg = new Uint8Array(fgObj);
+		const p = new Float64Array(params);
+		const outScores = new Float64Array(scores);
+		const table = {
+			integral: new Float64Array(sat),
+			stride: satStride,
+			width: srcW,
+			height: srcH,
+		};
+		// one scratch canvas for this worker's whole run of candidates
+		const out = new Uint8Array(outW * outH);
+		for (let c = lo; c < hi; c++) {
+			const mx = p[c * 5];
+			const my = p[c * 5 + 1];
+			const theta = p[c * 5 + 2];
+			const ox = p[c * 5 + 3];
+			const oy = p[c * 5 + 4];
+			// warpGray allocates a fresh canvas and fills it before warping;
+			// refilling the scratch is the same thing without the allocation
+			out.fill(255);
+			warpRows(
+				out,
+				src,
+				srcW,
+				srcH,
+				mx,
+				my,
+				theta,
+				ox,
+				oy,
+				outW,
+				mx > 1.001 || my > 1.001 ? table : null,
+				0,
+				outH,
+			);
+			let mismatch = 0;
+			for (let i = 0; i < out.length; i++) {
+				if ((out[i] < level ? 1 : 0) !== fg[i]) mismatch++;
+			}
+			outScores[c] = mismatch / out.length;
+		}
+	},
+
+	// grey -> ink mask against one global level, plus the ambiguity band
+	binarize({ gray, fg, ambiguous, level, margin, width }, lo, hi) {
+		const G = new Uint8Array(gray);
+		const F = new Uint8Array(fg);
+		const A = ambiguous ? new Uint8Array(ambiguous) : null;
+		const floor = level - margin;
+		const ceil = level + margin;
+		for (let y = lo; y < hi; y++) {
+			const row = y * width;
+			for (let x = 0; x < width; x++) {
+				const i = row + x;
+				const v = G[i];
+				F[i] = v < level ? 1 : 0;
+				if (A !== null) A[i] = v >= floor && v <= ceil ? 1 : 0;
+			}
+		}
+	},
+};
+
+// Every reply carries the id of the dispatch it answers. The pool used to
+// settle a dispatch on the next message from its worker, whichever dispatch
+// that message actually belonged to - see lib/pool.js.
+parentPort.on("message", ({ kernel, ctx, lo, hi, index, id }) => {
+	try {
+		kernels[kernel](ctx, lo, hi, index);
+		parentPort.postMessage({ id });
+	} catch (err) {
+		parentPort.postMessage({ id, error: `${kernel}: ${err.message}` });
+	}
+});

package/lib/scaleFile.js

@@ -0,0 +1,83 @@
+/**
+ * Shared calibration-baseline file helpers, used by both golden-compare
+ * (reads the calibrated mm/px scale) and checkerboard-calibrate (reads
+ * and writes it).
+ */
+
+"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;
+}
+
+// Physical sanity bound for mm/px. A vision lens maps a few mm onto many
+// pixels, so a value past 1000 mm/px is a corrupt file, not a real rig -
+// and so is 0, a negative, or an Infinity that JSON.parse happily accepts
+// from "1e999". Any of those flow downstream into NaN and a sharp.resize
+// that errors every frame (or a silent pass when the sizes happen to
+// match), so refuse with a reason instead of applying them.
+const MM_PER_PX_MAX = 1000;
+
+/**
+ * Read the calibration baseline, returning null when there is nothing
+ * configured or on disk. A file that exists but is unreadable, corrupt,
+ * or out of physical range comes back as { error } rather than null so
+ * the caller can say so instead of silently running uncalibrated.
+ *
+ * nativeWidth/nativeHeight (the calibration photo's own size, written by
+ * checkerboard-calibrate) are validated when present; files written
+ * before the geometry was recorded simply omit them and keep working
+ * with the golden-native fallback in prepareGolden.
+ */
+async function readScaleFile(scaleFilePath) {
+	if (!scaleFilePath || !(await pathExists(scaleFilePath))) return null;
+	let parsed;
+	try {
+		parsed = JSON.parse(await fsp.readFile(scaleFilePath, "utf8"));
+	} catch (err) {
+		return { error: `calibration file is not readable JSON: ${err.message}` };
+	}
+	if (
+		!isFinitePositive(parsed.mmPerPixelNative) ||
+		parsed.mmPerPixelNative > MM_PER_PX_MAX
+	) {
+		return {
+			error:
+				`calibration mmPerPixelNative must be a finite positive number <= ` +
+				`${MM_PER_PX_MAX} (got ${parsed.mmPerPixelNative}) - re-run ` +
+				`checkerboard-calibrate`,
+		};
+	}
+	const w = parsed.nativeWidth;
+	const h = parsed.nativeHeight;
+	if (w != null || h != null) {
+		if (!Number.isInteger(w) || !Number.isInteger(h) || w <= 0 || h <= 0) {
+			return {
+				error:
+					`calibration nativeWidth/nativeHeight must be positive integers ` +
+					`(got ${w}/${h}) - re-run checkerboard-calibrate`,
+			};
+		}
+	}
+	return parsed;
+}
+
+async function writeScaleFile(scaleFilePath, record) {
+	await fsp.mkdir(path.dirname(scaleFilePath), { recursive: true });
+	await fsp.writeFile(scaleFilePath, JSON.stringify(record, null, 2));
+}
+
+module.exports = { readScaleFile, writeScaleFile, pathExists };