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

package/lib/nativeSeed.js

@@ -0,0 +1,292 @@
+/**
+ * Native OpenCV alignment experiments.
+ *
+ * Two paths share the same bridge call:
+ *
+ *  - seedTransform() preserves the conservative prototype: OpenCV only gives
+ *    the JS pixel polish a starting point.
+ *  - alignFrame() is the deliberately aggressive prototype: OpenCV solves the
+ *    affine transform and returns the already-warped golden-sized grayscale
+ *    frame, allowing compareFrame to skip both summed-area tables, every JS
+ *    search/polish round, and the final JS global warp.
+ *
+ * Both paths are optional and return null on any native failure so the normal
+ * JS implementation remains the fallback.
+ */
+
+"use strict";
+
+const SEED_SCALE_MIN = 0.05;
+const SEED_SCALE_MAX = 100;
+const FAST_ALIGN_SCALE = 0.35;
+
+const ENGINE_PATH =
+	"@rosepetal/node-red-contrib-image-tools/node-red-contrib-image-tools/lib/cpp-bridge.js";
+
+let engine;
+function loadEngine() {
+	if (engine !== undefined) return engine;
+	try {
+		// eslint-disable-next-line global-require
+		engine = require(ENGINE_PATH);
+		if (typeof engine.imageAlign !== "function") engine = null;
+	} catch {
+		engine = null;
+	}
+	return engine;
+}
+
+function available() {
+	return loadEngine() !== null;
+}
+
+function _setEngine(fake) {
+	engine = fake;
+}
+
+function _resetEngine() {
+	engine = undefined;
+}
+
+function image(data, width, height, channels = 1) {
+	return {
+		data: Buffer.from(data.buffer, data.byteOffset, data.byteLength),
+		width,
+		height,
+		channels,
+		colorSpace: channels === 1 ? "GRAY" : channels === 4 ? "RGBA" : "RGB",
+		dtype: "uint8",
+	};
+}
+
+function rawResult(reply) {
+	const out = reply && reply.image;
+	if (!out || !out.data || !ArrayBuffer.isView(out.data)) return null;
+	const bytes = out.width * out.height * out.channels;
+	if (out.data.byteLength < bytes) return null;
+	return {
+		data: new Uint8Array(out.data.buffer, out.data.byteOffset, bytes),
+		width: out.width,
+		height: out.height,
+		channels: out.channels,
+		colorSpace: out.colorSpace,
+	};
+}
+
+/** Decode through OpenCV so the fast path does not pay sharp's serial PNG inflate. */
+async function decodeGray(input, raw) {
+	const cv = loadEngine();
+	if (cv === null || typeof cv.colorConvert !== "function") return null;
+	const source = raw
+		? image(input, raw.width, raw.height, raw.channels)
+		: Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+	try {
+		const out = rawResult(await cv.colorConvert(source, "GRAY", "raw"));
+		return out && out.channels === 1 ? out : null;
+	} catch {
+		return null;
+	}
+}
+
+async function resizeGray(raw, width, height) {
+	if (raw.width === width && raw.height === height) return raw.data;
+	const cv = loadEngine();
+	if (cv === null || typeof cv.resize !== "function") return null;
+	try {
+		const out = rawResult(
+			await cv.resize(
+				image(raw.data, raw.width, raw.height),
+				"num",
+				width,
+				"num",
+				height,
+				"raw",
+			),
+		);
+		return out && out.channels === 1 && out.width === width && out.height === height
+			? out.data
+			: null;
+	} catch {
+		return null;
+	}
+}
+
+function decodeTransform(reply, gW, gH, tW, tH) {
+	if (!reply || !reply.success || !reply.transformMatrix) return null;
+	const m = reply.transformMatrix.matrix2x3;
+	if (!Array.isArray(m) || m.length !== 6) return null;
+
+	// imageAlign first normalises the target to the reference dimensions.
+	// Its matrix maps reference coordinates into that normalised target, so
+	// scale each matrix row back into the target working canvas before
+	// decomposing it.
+	const fx = tW / gW;
+	const fy = tH / gH;
+	const a = m[0] * fx;
+	const b = m[1] * fx;
+	const ox = m[2] * fx;
+	const c = m[3] * fy;
+	const d = m[4] * fy;
+	const oy = m[5] * fy;
+	const mx = Math.hypot(a, c);
+	const my = Math.hypot(b, d);
+	const theta = Math.atan2(c, a);
+
+	if (![mx, my, theta, ox, oy].every(Number.isFinite)) return null;
+	if (mx < SEED_SCALE_MIN || mx > SEED_SCALE_MAX) return null;
+	if (my < SEED_SCALE_MIN || my > SEED_SCALE_MAX) return null;
+	return { mx, my, theta, ox, oy };
+}
+
+/**
+ * Keep the fast solve inside the geometry the inspection configuration says
+ * is physically possible. OpenCV affine is intentionally freer than the JS
+ * model; without this gate it can explain artwork differences as scale/shear.
+ */
+function validateAlignment(transform, pinnedScale, maxAngleDeg, scaleTolerance = 0.03) {
+	if (!transform) return "OpenCV returned no transform";
+	const angleDeg = Math.abs((transform.theta * 180) / Math.PI);
+	if (Number.isFinite(maxAngleDeg) && angleDeg > maxAngleDeg + 1e-9) {
+		return `OpenCV angle ${angleDeg.toFixed(2)}deg exceeds ${maxAngleDeg.toFixed(2)}deg`;
+	}
+	if (pinnedScale) {
+		const dx = Math.abs(transform.mx / pinnedScale.mx - 1);
+		const dy = Math.abs(transform.my / pinnedScale.my - 1);
+		if (dx > scaleTolerance || dy > scaleTolerance) {
+			return (
+				`OpenCV scale drift ${(dx * 100).toFixed(2)}% x / ` +
+				`${(dy * 100).toFixed(2)}% y exceeds ${(scaleTolerance * 100).toFixed(1)}%`
+			);
+		}
+	}
+	return null;
+}
+
+/**
+ * Run OpenCV affine alignment and return both its transform and its full-size
+ * aligned grayscale image. `scale` controls only the internal alignment copy;
+ * the returned image is always gW x gH.
+ */
+async function alignFrame(
+	goldenGray,
+	gW,
+	gH,
+	targetGray,
+	tW,
+	tH,
+	options = {},
+) {
+	const cv = loadEngine();
+	if (cv === null) return null;
+	const scale = Number.isFinite(options.scale)
+		? Math.max(0.05, Math.min(1, options.scale))
+		: FAST_ALIGN_SCALE;
+	const iterations = Number.isFinite(options.iterations)
+		? Math.max(1, Math.round(options.iterations))
+		: 30;
+	const epsilon = Number.isFinite(options.epsilon)
+		? Math.max(1e-6, options.epsilon)
+		: 1e-3;
+	const eccRefine = options.eccRefine === "always" ? "always" : "auto";
+
+	let reply;
+	try {
+		reply = await cv.imageAlign(
+			image(goldenGray, gW, gH),
+			image(targetGray, tW, tH),
+			scale,
+			iterations,
+			epsilon,
+			"raw",
+			90,
+			false,
+			true,
+			null,
+			"affine",
+			"features+ecc",
+			eccRefine,
+			"orb",
+		);
+	} catch {
+		return null;
+	}
+
+	const transform = decodeTransform(reply, gW, gH, tW, tH);
+	const out = reply && reply.image;
+	if (!transform || !out || !out.data) return null;
+	if (out.width !== gW || out.height !== gH || out.channels !== 1) return null;
+	const data = out.data;
+	if (!ArrayBuffer.isView(data) || data.byteLength < gW * gH) return null;
+	const gray = new Uint8Array(data.buffer, data.byteOffset, gW * gH);
+	return {
+		transform,
+		gray: blankOutsideSource(gray, gW, gH, transform, tW, tH),
+		timing: reply.timing || null,
+		scale,
+	};
+}
+
+/**
+ * OpenCV's warp fills everything that maps outside the frame with 0, and 0 is
+ * the darkest possible ink. Where the golden's canvas reaches past the edge of
+ * the photo - which it does on every frame whose label is not fully inside the
+ * shot - that fill lands in the background check as a solid, full-density bar
+ * of ink the part does not have, and fails it.
+ *
+ * lib/warp.js fills the same region with 255 for exactly this reason: blank
+ * substrate reads as "no ink here", which the *print* check flags as missing
+ * ink (true - the frame does not show it) instead of the background check
+ * flagging it as extra ink (false - the frame shows nothing at all there).
+ * The native path has no border-value parameter to pass, so restore the
+ * convention here rather than let the two alignment paths disagree about what
+ * an uncovered pixel means.
+ */
+function blankOutsideSource(gray, gW, gH, transform, tW, tH) {
+	const { mx, my, theta, ox, oy } = transform;
+	const cos = Math.cos(theta);
+	const sin = Math.sin(theta);
+	// target = (ox,oy) + R(theta) * diag(mx,my) * golden, the same mapping
+	// warpGray samples under.
+	const xFromGx = cos * mx;
+	const yFromGx = sin * mx;
+	const xFromGy = -sin * my;
+	const yFromGy = cos * my;
+
+	const out = new Uint8Array(gW * gH);
+	for (let y = 0; y < gH; y++) {
+		const baseX = ox + xFromGy * y;
+		const baseY = oy + yFromGy * y;
+		const row = y * gW;
+		for (let x = 0; x < gW; x++) {
+			const tx = baseX + xFromGx * x;
+			const ty = baseY + yFromGx * x;
+			out[row + x] =
+				tx >= 0 && tx < tW && ty >= 0 && ty < tH ? gray[row + x] : 255;
+		}
+	}
+	return out;
+}
+
+/** Conservative seed path retained for side-by-side benchmarking. */
+async function seedTransform(goldenGray, gW, gH, targetGray, tW, tH) {
+	const aligned = await alignFrame(goldenGray, gW, gH, targetGray, tW, tH, {
+		scale: 1,
+		iterations: 50,
+		epsilon: 1e-4,
+	});
+	return aligned ? aligned.transform : null;
+}
+
+module.exports = {
+	available,
+	decodeGray,
+	resizeGray,
+	alignFrame,
+	seedTransform,
+	validateAlignment,
+	SEED_SCALE_MIN,
+	SEED_SCALE_MAX,
+	FAST_ALIGN_SCALE,
+	_setEngine,
+	_resetEngine,
+};

package/lib/parallel.js

@@ -0,0 +1,428 @@
+/**
+ * Parallel forms of the per-pixel stages, each falling back to its serial
+ * twin whenever the pool is unavailable, the image is small enough that
+ * dispatch would cost more than it saves, or the caller asked for one
+ * worker.
+ *
+ * The fallbacks are not a nicety. The serial implementations remain the
+ * reference — the tests assert these agree with them byte for byte —
+ * because a divergence would surface as a defect that appears or
+ * disappears depending on the core count of the machine.
+ */
+
+"use strict";
+
+const { dilate } = require("./dilate.js");
+const { buildIntegral, buildIntegral64 } = require("./integral.js");
+const { warpGray } = require("./warp.js");
+const { smoothField, fieldStats } = require("./localAlign.js");
+const { runRanges, shouldParallelise, poolSize } = require("./pool.js");
+const {
+	allocU8,
+	allocU32,
+	allocF32,
+	allocF64,
+	toShared,
+	HAS_SAB,
+} = require("./shared.js");
+
+/**
+ * Summed-area table over a binary mask: row prefix sums in parallel, then
+ * the column accumulation in parallel.
+ *
+ * The serial `buildIntegral` fuses both into one pass, which is the right
+ * shape for one thread and the wrong shape for several: the fused loop
+ * reads the row above as it writes, so no two rows can run at once.
+ * Split into two passes each dimension is independent, and the arithmetic
+ * is unchanged - Uint32 addition is exact and associative modulo 2^32, so
+ * the table is byte-identical to the serial one either way.
+ *
+ * Worth doing because this is per-frame work on the full frame canvas:
+ * ~99ms of a 918ms align on a 4096x5500 frame, run on the main path while
+ * the pool sits idle.
+ */
+async function buildIntegralParallel(src, width, height, workers) {
+	if (!shouldParallelise(width * height, workers)) {
+		return buildIntegral(src, width, height);
+	}
+	const stride = width + 1;
+	const s = toShared(src);
+	const integral = allocU32(stride * (height + 1));
+	const rows = runRanges(
+		"integralRows",
+		{ src: s.buffer, out: integral.buffer, width, stride },
+		height,
+		workers,
+	);
+	if (rows === null) return buildIntegral(src, width, height);
+	await rows;
+	// the column pass reads what every row-pass worker wrote, so this
+	// await is a real barrier, exactly as in dilateParallel
+	await runRanges(
+		"integralCols",
+		{ out: integral.buffer, height, stride },
+		width,
+		workers,
+	);
+	return { integral, stride, width, height };
+}
+
+/**
+ * The grey (Float64) summed-area table, split the same way. This is the
+ * second per-frame table: `buildIntegralParallel` covers the binary mask
+ * the transform search reads, this one covers the greys that every
+ * candidate warp in the polish and the final full-resolution warp read.
+ * ~110ms per frame on a 4096x5500 canvas, also built while the pool idles.
+ */
+async function buildGrayTableParallel(src, width, height, workers) {
+	if (!shouldParallelise(width * height, workers)) {
+		return buildIntegral64(src, width, height);
+	}
+	const stride = width + 1;
+	const s = toShared(src);
+	const integral = allocF64(stride * (height + 1));
+	const rows = runRanges(
+		"integralRows64",
+		{ src: s.buffer, out: integral.buffer, width, stride },
+		height,
+		workers,
+	);
+	if (rows === null) return buildIntegral64(src, width, height);
+	await rows;
+	await runRanges(
+		"integralCols64",
+		{ out: integral.buffer, height, stride },
+		width,
+		workers,
+	);
+	return { integral, stride, width, height };
+}
+
+/** Separable dilation: rows in parallel, then columns in parallel. */
+async function dilateParallel(src, width, height, radius, workers) {
+	if (radius <= 0 || !shouldParallelise(width * height, workers)) {
+		return dilate(src, width, height, radius);
+	}
+	const s = toShared(src);
+	const tmp = allocU8(width * height);
+	const out = allocU8(width * height);
+	const rows = runRanges(
+		"dilateRows",
+		{ src: s.buffer, tmp: tmp.buffer, width, height, radius },
+		height,
+		workers,
+	);
+	if (rows === null) return dilate(src, width, height, radius);
+	await rows;
+	// the column pass reads what every row-pass worker wrote, so the two
+	// dispatches cannot be merged - this await is a real barrier
+	await runRanges(
+		"dilateCols",
+		{ tmp: tmp.buffer, out: out.buffer, width, height, radius },
+		width,
+		workers,
+	);
+	return out;
+}
+
+/**
+ * defect = a AND NOT b, cleared wherever either image was too close to
+ * its own ink level to have decided anything. Either ambiguity mask may
+ * be null.
+ */
+async function defectParallel(
+	a,
+	b,
+	ambiguousA,
+	ambiguousB,
+	width,
+	height,
+	workers,
+) {
+	const n = width * height;
+	if (!shouldParallelise(n, workers)) return null;
+
+	const sa = toShared(a);
+	const sb = toShared(b);
+	const sAmbA = ambiguousA ? toShared(ambiguousA) : null;
+	const sAmbB = ambiguousB ? toShared(ambiguousB) : null;
+	const out = allocU8(n);
+	// one counter slot per worker rather than an atomic in the inner loop.
+	// Sized from the pool, not a fixed 64: a worker index past the end of
+	// a typed array is a silently ignored write (no RangeError), so with a
+	// pool larger than the slot count the defect count came up short with
+	// no error anywhere.
+	const slots = allocU32(Math.max(1, poolSize(workers)));
+	const p = runRanges(
+		"defect",
+		{
+			a: sa.buffer,
+			b: sb.buffer,
+			ambiguousA: sAmbA ? sAmbA.buffer : null,
+			ambiguousB: sAmbB ? sAmbB.buffer : null,
+			out: out.buffer,
+			counts: slots.buffer,
+			width,
+		},
+		height,
+		workers,
+	);
+	if (p === null) return null;
+	await p;
+	let count = 0;
+	for (let i = 0; i < slots.length; i++) count += slots[i];
+	return { defect: out, count };
+}
+
+/** Grey -> ink mask against one global level, plus the ambiguity band. */
+async function binarizeParallel(gray, width, height, level, margin, workers) {
+	const n = width * height;
+	if (!shouldParallelise(n, workers)) return null;
+	const g = toShared(gray);
+	const fg = allocU8(n);
+	const ambiguous = margin > 0 ? allocU8(n) : null;
+	const p = runRanges(
+		"binarize",
+		{
+			gray: g.buffer,
+			fg: fg.buffer,
+			ambiguous: ambiguous ? ambiguous.buffer : null,
+			level,
+			margin,
+			width,
+		},
+		height,
+		workers,
+	);
+	if (p === null) return null;
+	await p;
+	return { fg, ambiguous };
+}
+
+module.exports = {
+	buildIntegralParallel,
+	buildGrayTableParallel,
+	dilateParallel,
+	defectParallel,
+	binarizeParallel,
+	warpParallel,
+	refineLocallyParallel,
+	objectiveBatchParallel,
+};
+
+// The polish objective splits by *candidate*, not by rows, so the row-split
+// threshold is the wrong economics: one candidate is a whole warp of the
+// objective canvas, on the order of a millisecond, where one row is
+// microseconds. Using MIN_PIXELS_TO_SPLIT here sent the entire polish
+// serial for any golden past roughly 2.5:1 - a legitimate label shape - at
+// the pattern search's full serial cost. 100k total pixels is ~10k per
+// candidate on a 10-wide pinned batch, around half a millisecond each,
+// which comfortably clears a dispatch.
+const MIN_OBJECTIVE_PIXELS = 100000;
+
+/**
+ * Score a whole neighbourhood of candidate transforms at once, one
+ * contiguous run of candidates per worker.
+ *
+ * Returns null - meaning "score these yourself" - rather than throwing,
+ * because the serial scorer in lib/compare.js stays the reference
+ * implementation and every caller already has it to hand.
+ *
+ * `frame` is { gray, width, height, table, outW, outH, level, fgObj }, all
+ * already expressed on the objective's own decimated grid: this function
+ * does no coordinate conversion, so what it scores is exactly what the
+ * serial scorer scores.
+ */
+async function objectiveBatchParallel(cands, frame, workers) {
+	const n = cands.length;
+	// A single candidate is the polish's opening evaluation. Splitting one
+	// warp across eight workers costs a dispatch to save nothing.
+	if (n < 2) return null;
+	if (!frame || !frame.table) return null;
+	if (!HAS_SAB || workers === 1) return null;
+	if (n * frame.outW * frame.outH < MIN_OBJECTIVE_PIXELS) return null;
+
+	const gray = toShared(frame.gray);
+	const fgObj = toShared(frame.fgObj);
+	const integral = toShared(frame.table.integral);
+
+	// five parameters per candidate, flat, so the dispatch carries numbers
+	// rather than a structured clone of an array of objects
+	const params = allocF64(n * 5);
+	for (let i = 0; i < n; i++) {
+		const c = cands[i];
+		params[i * 5] = c.mx;
+		params[i * 5 + 1] = c.my;
+		params[i * 5 + 2] = c.theta;
+		params[i * 5 + 3] = c.ox;
+		params[i * 5 + 4] = c.oy;
+	}
+
+	// NaN, not zero. A score of 0 is "a perfect match" - it beats every
+	// other candidate and passes the part - so a dispatch that silently
+	// failed to write would steer the alignment rather than fail. Any
+	// surviving NaN below is that bug, made loud.
+	const scores = allocF64(n);
+	scores.fill(NaN);
+
+	const p = runRanges(
+		"objective",
+		{
+			gray: gray.buffer,
+			fgObj: fgObj.buffer,
+			sat: integral.buffer,
+			satStride: frame.table.stride,
+			srcW: frame.width,
+			srcH: frame.height,
+			outW: frame.outW,
+			outH: frame.outH,
+			level: frame.level,
+			params: params.buffer,
+			scores: scores.buffer,
+		},
+		n,
+		workers,
+	);
+	// getPool returns null on a host that resolves to one worker even though
+	// the pixel gate passed - a 2-core machine, where defaultSize() is 1.
+	// Without this the zero-filled scores would come back as a perfect match
+	// for every candidate.
+	if (p === null) return null;
+	await p;
+
+	const out = new Array(n);
+	for (let i = 0; i < n; i++) {
+		if (Number.isNaN(scores[i])) {
+			throw new Error(
+				`objective batch left candidate ${i} of ${n} unscored - a dispatch did not write its range`,
+			);
+		}
+		out[i] = scores[i];
+	}
+	return out;
+}
+
+/** Resample the frame into golden's grid, rows split across the pool. */
+async function warpParallel(
+	src,
+	srcW,
+	srcH,
+	mx,
+	my,
+	theta,
+	ox,
+	oy,
+	outW,
+	outH,
+	fill,
+	table,
+	workers,
+) {
+	const serial = () =>
+		warpGray(src, srcW, srcH, mx, my, theta, ox, oy, outW, outH, fill, table);
+	if (!shouldParallelise(outW * outH, workers)) return serial();
+	// only the area-average path has a table to share; the bilinear path
+	// reads the source directly and is rare here anyway
+	if (!(mx > 1.001 || my > 1.001) || !table) return serial();
+
+	const s = toShared(src);
+	const integral = toShared(table.integral);
+	const out = allocU8(outW * outH);
+	out.fill(fill == null ? 255 : fill);
+	const p = runRanges(
+		"warp",
+		{
+			src: s.buffer,
+			out: out.buffer,
+			srcW,
+			srcH,
+			mx,
+			my,
+			theta,
+			ox,
+			oy,
+			outW,
+			sat: integral.buffer,
+			satStride: table.stride,
+		},
+		outH,
+		workers,
+	);
+	if (p === null) return serial();
+	await p;
+	return out;
+}
+
+/**
+ * Per-tile refinement with both halves split: the field build over tile
+ * rows, then - after a barrier, since the median filter reads the whole
+ * field - the resampling over image rows.
+ */
+async function refineLocallyParallel(
+	goldenGray,
+	alignedTargetGray,
+	width,
+	height,
+	cfg,
+) {
+	const tile = Math.max(8, cfg.localAlignTile | 0);
+	const maxOffset = Math.max(1, cfg.localAlignMax | 0);
+	const minStdDev =
+		cfg.localAlignMinStdDev != null ? cfg.localAlignMinStdDev : 12;
+	const opts = { tile, maxOffset, minStdDev };
+	if (!shouldParallelise(width * height, cfg.workers)) return null;
+
+	const g = toShared(goldenGray);
+	const t = toShared(alignedTargetGray);
+	const gridW = Math.max(1, Math.ceil(width / tile));
+	const gridH = Math.max(1, Math.ceil(height / tile));
+	const raw = {
+		fx: allocF32(gridW * gridH),
+		fy: allocF32(gridW * gridH),
+		valid: allocU8(gridW * gridH),
+		gridW,
+		gridH,
+	};
+	const build = runRanges(
+		"localField",
+		{
+			golden: g.buffer,
+			target: t.buffer,
+			fx: raw.fx.buffer,
+			fy: raw.fy.buffer,
+			valid: raw.valid.buffer,
+			width,
+			height,
+			gridW,
+			tile,
+			maxOffset,
+			minStdDev,
+		},
+		gridH,
+		cfg.workers,
+	);
+	if (build === null) return null;
+	await build;
+
+	// small enough that splitting it would cost more than it saves
+	const field = smoothField(raw);
+
+	const out = allocU8(width * height);
+	await runRanges(
+		"localApply",
+		{
+			target: t.buffer,
+			out: out.buffer,
+			fx: field.fx.buffer,
+			fy: field.fy.buffer,
+			width,
+			height,
+			gridW,
+			gridH,
+			tile,
+		},
+		height,
+		cfg.workers,
+	);
+	return { gray: out, field, tile, stats: fieldStats(field) };
+}