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

package/checkerboard-calibrate.js

@@ -0,0 +1,282 @@
+/**
+ * checkerboard-calibrate Node-RED node.
+ *
+ * A calibration step for a fixed camera rig:
+ * photograph a printed checkerboard of known physical pitch, measure the
+ * detected pixel pitch, and compare the resulting mm/px scale against a
+ * previously-saved baseline. Detection/measurement lives in
+ * lib/checkerboard.js so it can be exercised outside Node-RED.
+ *
+ * Run this once at commissioning and again after camera/mechanical
+ * maintenance - not per production frame.
+ *
+ * Input (msg.payload): Buffer / Uint8Array / ArrayBuffer with image bytes,
+ * a file path string, or an object { data | buffer | path } - a photo of
+ * the printed checkerboard.
+ * msg.save (bool): persist the freshly detected scale as the new
+ * baseline (their "Match New Scale" + "Save").
+ */
+
+const fs = require("fs");
+const fsp = fs.promises;
+const inspector = require("./lib/inspector.js");
+const { toShared } = require("./lib/shared.js");
+const { readScaleFile, writeScaleFile } = require("./lib/scaleFile.js");
+
+module.exports = (RED) => {
+	function clampInt(value, fallback, min, max) {
+		const n = parseInt(value, 10);
+		if (isNaN(n)) return fallback;
+		return Math.min(max, Math.max(min, n));
+	}
+
+	function clampFloat(value, fallback, min, max) {
+		const n = parseFloat(value);
+		if (isNaN(n)) return fallback;
+		return Math.min(max, Math.max(min, n));
+	}
+
+	// Same input caps as golden-compare.js: an unbounded buffer would be
+	// copied on every message for no measurement value, and an unbounded
+	// path read would hang or OOM on a special file like /dev/zero.
+	const MAX_IMAGE_BYTES = 512 * 1024 * 1024;
+
+	/**
+	 * Read an image file through one handle: open -> fstat -> guards ->
+	 * read. The guards are the point - see golden-compare.js's twin. A
+	 * pathExists() then readFile() pair is a race, and an unguarded path
+	 * read lets a flow point msg.payload at /dev/zero and hang the node.
+	 * Returns null when the path does not exist, so callers can keep
+	 * distinguishing "missing" from "refused".
+	 */
+	async function readRegularFile(p, label) {
+		let fd;
+		try {
+			fd = await fsp.open(p, fs.constants.O_RDONLY);
+		} catch (err) {
+			if (err && (err.code === "ENOENT" || err.code === "ENOTDIR")) return null;
+			throw err;
+		}
+		try {
+			const stat = await fd.stat();
+			if ((stat.mode & fs.constants.S_IFMT) !== fs.constants.S_IFREG) {
+				throw new Error(
+					`${label} is not a regular file: "${p}" - refusing to read it`,
+				);
+			}
+			if (stat.size > MAX_IMAGE_BYTES) {
+				throw new Error(
+					`${label} is ${stat.size} bytes, above the ${MAX_IMAGE_BYTES}-byte cap: "${p}"`,
+				);
+			}
+			return await fd.readFile();
+		} finally {
+			await fd.close();
+		}
+	}
+
+	// same resolveImage contract as golden-compare.js
+	async function resolveImage(source, label) {
+		if (source == null || source === "") {
+			throw new Error(`${label} is empty`);
+		}
+		if (
+			Buffer.isBuffer(source) ||
+			source instanceof Uint8Array ||
+			source instanceof ArrayBuffer
+		) {
+			if (source.byteLength > MAX_IMAGE_BYTES) {
+				throw new Error(
+					`${label} is ${source.byteLength} bytes, above the ${MAX_IMAGE_BYTES}-byte cap`,
+				);
+			}
+			return Buffer.from(source);
+		}
+		if (typeof source === "string") {
+			const file = await readRegularFile(source, label);
+			if (!file) throw new Error(`${label} does not exist on disk: "${source}"`);
+			return file;
+		}
+		if (typeof source === "object") {
+			const data = source.data || source.buffer;
+			if (
+				Buffer.isBuffer(data) ||
+				data instanceof Uint8Array ||
+				data instanceof ArrayBuffer
+			) {
+				if (data.byteLength > MAX_IMAGE_BYTES) {
+					throw new Error(
+						`${label} is ${data.byteLength} bytes, above the ${MAX_IMAGE_BYTES}-byte cap`,
+					);
+				}
+				return Buffer.from(data);
+			}
+			if (typeof source.path === "string") {
+				const file = await readRegularFile(source.path, label);
+				if (file) return file;
+			}
+			throw new Error(
+				`${label} object must contain "data"/"buffer" or an existing "path"`,
+			);
+		}
+		throw new Error(`unsupported ${label} type: ${typeof source}`);
+	}
+
+	function fmtMs(ms) {
+		return ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(2)}s`;
+	}
+
+	function CheckerboardCalibrateNode(config) {
+		RED.nodes.createNode(this, config);
+		const node = this;
+
+		node.targetPitchMm = clampFloat(config.targetPitchMm, 10, 0.01, 10000);
+		node.checkerboardCols = clampInt(config.checkerboardCols, 4, 2, 100);
+		node.checkerboardRows = clampInt(config.checkerboardRows, 6, 3, 100);
+		node.allowedErrorPercent = clampFloat(config.allowedErrorPercent, 2, 0, 100);
+		node.scaleFilePath = String(config.scaleFilePath || "").trim();
+
+		node.on("input", async (msg, send, done) => {
+			send =
+				send ||
+				function () {
+					node.send.apply(node, arguments);
+				};
+			const totalStart = performance.now();
+			try {
+				if (!node.scaleFilePath) {
+					throw new Error(
+						"no scale file path configured - set where the calibration baseline should be saved/read",
+					);
+				}
+				const cfg = {
+					targetPitchMm: clampFloat(
+						msg.targetPitchMm,
+						node.targetPitchMm,
+						0.01,
+						10000,
+					),
+					checkerboardCols: clampInt(
+						msg.checkerboardCols,
+						node.checkerboardCols,
+						2,
+						100,
+					),
+					checkerboardRows: clampInt(
+						msg.checkerboardRows,
+						node.checkerboardRows,
+						3,
+						100,
+					),
+					allowedErrorPercent: clampFloat(
+						msg.allowedErrorPercent,
+						node.allowedErrorPercent,
+						0,
+						100,
+					),
+				};
+
+				const buffer = await resolveImage(msg.payload, "msg.payload");
+
+				node.status({
+					fill: "blue",
+					shape: "dot",
+					text: "detecting checkerboard…",
+				});
+				// Off the event loop, like golden-compare: this runs at full
+				// sensor resolution with no downscale, which measured ~59ms of
+				// synchronous work on a 5520x4140 capture and more when a board
+				// is actually found.
+				const measured = (
+					await inspector.calibrate({ cfg, image: toShared(buffer).buffer })
+				).result;
+
+				if (!measured.detected) {
+					msg.payload = false;
+					msg.result = {
+						checkerboardDetected: false,
+						reason: measured.reason,
+						pass: false,
+					};
+					msg.timings = { totalMs: Math.round(performance.now() - totalStart) };
+					send(msg);
+					node.status({ fill: "red", shape: "ring", text: "not detected" });
+					node.warn(`checkerboard-calibrate: not detected - ${measured.reason}`);
+					done();
+					return;
+				}
+
+				const baseline = await readScaleFile(node.scaleFilePath);
+				const detectedScale = measured.mmPerPixel;
+				const currentScale = baseline ? baseline.mmPerPixelNative : null;
+				const bootstrap = currentScale == null;
+				if (bootstrap && !msg.save) {
+					// Bootstrap mode is informational only - nothing is persisted
+					// unless the message says so. The status line reads like
+					// success, so say plainly that the scale was not saved, or an
+					// operator walks away thinking the rig is calibrated.
+					node.warn(
+						`checkerboard-calibrate: detected ${detectedScale.toFixed(5)}mm/px but nothing was saved - ` +
+							`send msg.save:true to persist this as the baseline`,
+					);
+				}
+				const deviationPercent = bootstrap
+					? null
+					: (Math.abs(detectedScale - currentScale) / currentScale) * 100;
+				const pass = bootstrap || deviationPercent <= cfg.allowedErrorPercent;
+
+				let saved = false;
+				if (msg.save) {
+					await writeScaleFile(node.scaleFilePath, {
+						mmPerPixelNative: detectedScale,
+						nativeWidth: measured.width,
+						nativeHeight: measured.height,
+						calibratedAt: new Date().toISOString(),
+					});
+					saved = true;
+				}
+
+				msg.payload = pass;
+				msg.result = {
+					checkerboardDetected: true,
+					currentScale: saved ? detectedScale : currentScale,
+					detectedScale,
+					deviationPercent,
+					bootstrap,
+					pass,
+					saved,
+					pitchXPx: measured.pitchXPx,
+					pitchYPx: measured.pitchYPx,
+					nativeWidth: measured.width,
+					nativeHeight: measured.height,
+				};
+				msg.timings = { totalMs: Math.round(performance.now() - totalStart) };
+				send(msg);
+
+				const statusText = bootstrap
+					? `no baseline · ${detectedScale.toFixed(5)}mm/px${saved ? " · saved" : ""}`
+					: `${pass ? "pass" : "fail"} · dev ${deviationPercent.toFixed(2)}%${saved ? " · saved" : ""}`;
+				node.status({
+					fill: bootstrap ? "blue" : pass ? "green" : "red",
+					shape: bootstrap ? "dot" : pass ? "dot" : "ring",
+					text: statusText,
+				});
+				node.log(
+					`checkerboard-calibrate: detected=${detectedScale.toFixed(6)}mm/px ` +
+						`current=${currentScale == null ? "none" : currentScale.toFixed(6)} ` +
+						`deviation=${deviationPercent == null ? "n/a" : deviationPercent.toFixed(2) + "%"} ` +
+						`pass=${pass} saved=${saved} total ${fmtMs(msg.timings.totalMs)}`,
+				);
+				done();
+			} catch (err) {
+				node.status({ fill: "red", shape: "ring", text: "error" });
+				// done(err) routes the failure through node.error exactly
+				// once; an explicit node.error here reported every failure
+				// twice (double log lines, Catch nodes firing twice)
+				done(err);
+			}
+		});
+	}
+
+	RED.nodes.registerType("checkerboard-calibrate", CheckerboardCalibrateNode);
+};

package/examples/label-crop-with-line-finder.json

@@ -0,0 +1,239 @@
+[
+    {
+        "id": "lfx-note-a",
+        "type": "comment",
+        "z": "lfx-tab",
+        "name": "1 · TUNE ONE EDGE  ─  line-finder is the setup tool, not the cropper",
+        "info": "`line-finder` never crops anything. It measures ONE straight edge inside\nONE region you draw, so you can get that edge solid before handing the\nnumbers to `label-crop` (section 2), which runs four of them itself.\n\nOpen the `line finder` node, load a sample frame into its canvas and\ndrag across the edge you want - the drag *direction* sets the scan\ndirection. Then hit Inject and read the preview drawn on the canvas:\n\n  blue parallelogram = the search region\n  green ticks        = calipers that agreed and were used in the fit\n  red ticks          = calipers dropped as outliers\n  yellow line        = the fitted line\n\nTune until it is found on every frame you try, with few red ticks:\n\n  * found nothing        -> lower `contrastThreshold`; if only some\n                            calipers find it, lower\n                            `minCaliperFraction` too\n  * found the WRONG edge -> tighten the region, do NOT raise contrast\n  * soft, multi-step     -> `Edge select` = `first` or `last` instead\n    transition              of `best`. `best` picks the strongest step,\n                            which flips between two similar ones from\n                            frame to frame; `first`/`last` are\n                            positional, so they stay on the same step.\n                            This is what makes a boundary repeatable.\n  * a few red ticks      -> widen the region so the edge stays inside it\n                            on every frame, or raise\n                            `outlierTolerancePx` a little\n\nThe region loaded here is this rig's *top* edge - the hardest one, a\n4-grey-level step that is never found at the default contrast of 2.\nRepeat for the other three, then move to section 2.",
+        "x": 300,
+        "y": 60,
+        "wires": []
+    },
+    {
+        "id": "lfx-inject-a",
+        "type": "inject",
+        "z": "lfx-tab",
+        "name": "one frame",
+        "props": [
+            {
+                "p": "payload"
+            }
+        ],
+        "repeat": "",
+        "crontab": "",
+        "once": false,
+        "onceDelay": 0.1,
+        "topic": "",
+        "payload": "",
+        "payloadType": "date",
+        "x": 140,
+        "y": 120,
+        "wires": [
+            [
+                "lfx-read-a"
+            ]
+        ]
+    },
+    {
+        "id": "lfx-read-a",
+        "type": "file in",
+        "z": "lfx-tab",
+        "name": "sample frame",
+        "filename": "/data/Inspection/sample_images/good/image_20260907_093135-748Z.jpg",
+        "filenameType": "str",
+        "format": "",
+        "chunk": false,
+        "sendError": true,
+        "encoding": "none",
+        "allProps": false,
+        "x": 320,
+        "y": 120,
+        "wires": [
+            [
+                "lfx-finder"
+            ]
+        ]
+    },
+    {
+        "id": "lfx-finder",
+        "type": "line-finder",
+        "z": "lfx-tab",
+        "name": "top edge",
+        "regionX": 300,
+        "regionY": 8,
+        "regionWidth": 2400,
+        "regionHeight": 90,
+        "regionAngleDeg": 0,
+        "scanDirection": "down",
+        "polarity": "either",
+        "edgeSelect": "first",
+        "ignoreCount": 0,
+        "calipers": 16,
+        "contrastThreshold": 0.35,
+        "filterHalfWidth": 2,
+        "outlierTolerancePx": 2.5,
+        "minCaliperFraction": 0.25,
+        "angleToleranceDeg": 10,
+        "minScore": 0,
+        "previewEnabled": true,
+        "previewWidth": 260,
+        "x": 530,
+        "y": 120,
+        "wires": [
+            [
+                "lfx-debug-a"
+            ]
+        ]
+    },
+    {
+        "id": "lfx-debug-a",
+        "type": "debug",
+        "z": "lfx-tab",
+        "name": "msg.lineFinder",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": false,
+        "complete": "lineFinder",
+        "targetType": "msg",
+        "statusVal": "",
+        "statusType": "auto",
+        "x": 740,
+        "y": 120,
+        "wires": []
+    },
+    {
+        "id": "lfx-note-b",
+        "type": "comment",
+        "z": "lfx-tab",
+        "name": "2 · CROP  ─  label-crop in calipers mode runs four line finders itself",
+        "info": "`label-crop` with **Boundary = calipers** runs no blob search at all. It\ngreys the frame once, runs one line finder per side over the regions in\nthe `edgeRegions` JSON, intersects the four fitted lines into a\nrectangle, then deskews and crops to it - the same rotate/crop tail the\nblob mode uses.\n\nThe scan direction per side is implied (left scans rightwards, top\nscans downwards, ...), so each side needs only its box plus whichever\nline-finder options you tuned in section 1. Every option in\n`lib/lineFinder.js` is accepted per side.\n\nCoordinates are FULL-RESOLUTION frame pixels. Calipers mode ignores\n`maxEdge` and measures at full res on purpose - a caliper looks for a\nposition, not a shape, so a 640px detection copy would coarsen every\nreading 6x.\n\nIf one edge is not found the frame is NOT cropped:\n`msg.labelCrop.reason` names the side (e.g.\n`calipers:missing-edge:top`) and `msg.labelCrop.edges` carries per-side\ndiagnostics (found / reason / score / calipers / residualPx) so you can\nsee which region to re-aim. Guessing a missing edge would silently\nmis-crop, so it refuses instead.\n\nMeasured with the regions below over this rig's 148 good frames:\n\n  found on           148/148\n  label width spread 1.8 px\n  height spread      5.2 px\n  deskew angle spread 0.14 deg\n\nand of the 14 bad frames it refuses 6 outright - the blanks, which have\nno label boundary to find.\n\nNote the lowered `minCaliperFraction`. Left, right and top are found\nby all 16 calipers on every one of the 148 frames, but the bottom edge\nis picked up by only a third of them - 5 of 16 at worst - so at the 0.5\ndefault it is reported missing on 76 of them. Lowering the fraction is\nthe right fix there, not raising contrast.",
+        "x": 300,
+        "y": 240,
+        "wires": []
+    },
+    {
+        "id": "lfx-inject-b",
+        "type": "inject",
+        "z": "lfx-tab",
+        "name": "one frame",
+        "props": [
+            {
+                "p": "payload"
+            }
+        ],
+        "repeat": "",
+        "crontab": "",
+        "once": false,
+        "onceDelay": 0.1,
+        "topic": "",
+        "payload": "",
+        "payloadType": "date",
+        "x": 140,
+        "y": 300,
+        "wires": [
+            [
+                "lfx-read-b"
+            ]
+        ]
+    },
+    {
+        "id": "lfx-read-b",
+        "type": "file in",
+        "z": "lfx-tab",
+        "name": "sample frame",
+        "filename": "/data/Inspection/sample_images/good/image_20260907_093135-748Z.jpg",
+        "filenameType": "str",
+        "format": "",
+        "chunk": false,
+        "sendError": true,
+        "encoding": "none",
+        "allProps": false,
+        "x": 320,
+        "y": 300,
+        "wires": [
+            [
+                "lfx-crop"
+            ]
+        ]
+    },
+    {
+        "id": "lfx-crop",
+        "type": "label-crop",
+        "z": "lfx-tab",
+        "name": "crop by calipers",
+        "boundaryMode": "calipers",
+        "edgeRegions": "{\n  \"left\":   { \"x\": 40,   \"y\": 400,  \"width\": 90,   \"height\": 2800, \"contrastThreshold\": 1.0,  \"edgeSelect\": \"last\",  \"minCaliperFraction\": 0.25 },\n  \"right\":  { \"x\": 2900, \"y\": 400,  \"width\": 90,   \"height\": 2800, \"contrastThreshold\": 0.6,  \"edgeSelect\": \"last\",  \"minCaliperFraction\": 0.25 },\n  \"top\":    { \"x\": 300,  \"y\": 8,    \"width\": 2400, \"height\": 90,   \"contrastThreshold\": 0.35, \"edgeSelect\": \"first\", \"minCaliperFraction\": 0.25 },\n  \"bottom\": { \"x\": 300,  \"y\": 3580, \"width\": 2400, \"height\": 90,   \"contrastThreshold\": 2.5,  \"edgeSelect\": \"best\",  \"minCaliperFraction\": 0.2 }\n}",
+        "maxEdge": 640,
+        "polarity": "auto",
+        "minAreaFraction": 0.05,
+        "maxAreaFraction": 0.9,
+        "minRectangularity": 0.4,
+        "maxBorderContact": 0.5,
+        "minDominance": 1.5,
+        "minConfidence": 0.4,
+        "aspectRatio": "",
+        "aspectTolerance": 0.15,
+        "expectedSizeFraction": "",
+        "sizeTolerance": 0.2,
+        "cropMargin": 0,
+        "minRotateAngleDeg": 0.5,
+        "previewEnabled": true,
+        "previewWidth": 220,
+        "outputFormat": "jpg",
+        "outputQuality": 92,
+        "pngOptimize": false,
+        "x": 540,
+        "y": 300,
+        "wires": [
+            [
+                "lfx-debug-b",
+                "lfx-write"
+            ]
+        ]
+    },
+    {
+        "id": "lfx-debug-b",
+        "type": "debug",
+        "z": "lfx-tab",
+        "name": "msg.labelCrop",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": false,
+        "complete": "labelCrop",
+        "targetType": "msg",
+        "statusVal": "",
+        "statusType": "auto",
+        "x": 760,
+        "y": 260,
+        "wires": []
+    },
+    {
+        "id": "lfx-write",
+        "type": "file",
+        "z": "lfx-tab",
+        "name": "/data/label-crop.jpg",
+        "filename": "/data/label-crop.jpg",
+        "filenameType": "str",
+        "appendNewline": false,
+        "createDir": true,
+        "overwriteFile": "true",
+        "encoding": "none",
+        "x": 790,
+        "y": 320,
+        "wires": [
+            []
+        ]
+    },
+    {
+        "id": "lfx-note-c",
+        "type": "comment",
+        "z": "lfx-tab",
+        "name": "3 · WHAT NOT TO EXPECT from cropping (measured on this rig)",
+        "info": "The crop above is geometrically excellent and still does not improve\nthe inspection on this label. Measured over 148 good / 14 bad frames\nagainst a Demo_Good_60 golden:\n\n  no crop           148/148 good pass\n  blob crop          72/148\n  fixed rect         55/148\n  calipers crop      28/148\n\nThe cause is not the crop quality. The recurring background-defect\nregions sit on logotype strokes and barcode bar fields - real fine\nartwork in the label's left margin. Cropping shifts\nwhich pixels land in which comparison block, which moves that artwork\nrelative to the golden and makes the mismatch worse.\n\nSo use this flow when you want a deskewed, consistently framed label\nimage - archiving, OCR, a downstream tool that wants the label alone -\nnot as a way to raise the inspection score. See ARCHITECTURE.md,\n\"What it does not solve\".",
+        "x": 280,
+        "y": 400,
+        "wires": []
+    }
+]