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

package/barcode-locate.html

@@ -0,0 +1,256 @@
+<script type="text/html" data-template-name="barcode-locate">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" placeholder="Name" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-mode"><i class="fa fa-search"></i> Mode</label>
+    <select id="node-input-mode" style="width:70%;">
+      <option value="regionsThenAuto">Regions, then full image if nothing found</option>
+      <option value="regionsOnly">Regions only (no full-image fallback)</option>
+      <option value="autoOnly">Full image only (ignore regions)</option>
+    </select>
+  </div>
+
+  <div class="form-row node-input-region-container-row">
+    <label><i class="fa fa-crop"></i> Regions</label>
+    <span class="node-input-hint" style="color:#999;">
+      pixel coordinates on the full-resolution image - find them with any
+      image viewer (see Help). Scanned in order, fastest first; skipped
+      entirely in "Full image only" mode.
+    </span>
+    <ol id="node-input-region-container" style="margin-top:8px;"></ol>
+  </div>
+
+  <div class="form-row">
+    <label><i class="fa fa-list"></i> Formats</label>
+  </div>
+  <div class="form-row" style="margin-left:110px;">
+    <input type="checkbox" id="node-input-Code128" style="width:auto;vertical-align:middle;" />
+    <label for="node-input-Code128" style="width:auto;">Code128</label>
+    <input type="checkbox" id="node-input-DataMatrix" style="width:auto;vertical-align:middle;margin-left:12px;" />
+    <label for="node-input-DataMatrix" style="width:auto;">DataMatrix</label>
+    <input type="checkbox" id="node-input-QRCode" style="width:auto;vertical-align:middle;margin-left:12px;" />
+    <label for="node-input-QRCode" style="width:auto;">QRCode</label>
+  </div>
+  <div class="form-row" style="margin-left:110px;">
+    <input type="checkbox" id="node-input-EAN13" style="width:auto;vertical-align:middle;" />
+    <label for="node-input-EAN13" style="width:auto;">EAN13</label>
+    <input type="checkbox" id="node-input-Code39" style="width:auto;vertical-align:middle;margin-left:12px;" />
+    <label for="node-input-Code39" style="width:auto;">Code39</label>
+    <input type="checkbox" id="node-input-ITF" style="width:auto;vertical-align:middle;margin-left:12px;" />
+    <label for="node-input-ITF" style="width:auto;">ITF</label>
+    <input type="checkbox" id="node-input-PDF417" style="width:auto;vertical-align:middle;margin-left:12px;" />
+    <label for="node-input-PDF417" style="width:auto;">PDF417</label>
+  </div>
+  <div class="form-row" style="margin-left:110px;">
+    <input type="checkbox" id="node-input-EAN8" style="width:auto;vertical-align:middle;" />
+    <label for="node-input-EAN8" style="width:auto;">EAN8</label>
+    <span class="node-input-hint" style="margin-left:10px; color:#999;"
+      >off by default - short enough to have a real chance of misreading noise as a confident wrong result, see Help</span
+    >
+  </div>
+
+  <div class="form-row">
+    <label><i class="fa fa-cogs"></i> Reader</label>
+  </div>
+  <div class="form-row" style="margin-left:110px;">
+    <input type="checkbox" id="node-input-tryHarder" style="width:auto;vertical-align:middle;" />
+    <label for="node-input-tryHarder" style="width:auto;">try harder</label>
+    <input type="checkbox" id="node-input-tryRotate" style="width:auto;vertical-align:middle;margin-left:12px;" />
+    <label for="node-input-tryRotate" style="width:auto;">try rotate</label>
+    <span class="node-input-hint" style="margin-left:10px; color:#999;"
+      >both needed for full recall - see Help</span
+    >
+  </div>
+</script>
+
+<script type="text/html" data-help-name="barcode-locate">
+  <p>
+    Finds and decodes barcodes (1D and 2D) in an image using
+    <a href="https://github.com/Sec-ant/zxing-wasm" target="_blank">zxing-wasm</a>
+    - a WebAssembly build of the real <code>zxing-cpp</code> engine, not the
+    much weaker pure-JS <code>@zxing/library</code> port
+    <code>node-red-contrib-image-tools</code>'s Barcode Decoder uses. Genuine
+    multi-symbol detection, rotation tolerance, and native DataMatrix
+    support - no separate localization step needed to get a result out of
+    it on a big photo.
+  </p>
+
+  <h3>Why regions</h3>
+  <p>
+    Scanning a whole multi-megapixel photo takes on the order of a second,
+    mostly the detector's own search over the full frame. On a fixed camera
+    rig - the same assumption <code>golden-compare</code> and
+    <code>checkerboard-calibrate</code> already make - barcodes land in
+    roughly the same place shot to shot, so telling this node where to look
+    turns that into a handful of single-digit-millisecond crops instead
+    (measured ~2-15ms per region vs ~1.4s for the same image scanned whole
+    on a 4096x5500 test photo - roughly two orders of magnitude). Mode
+    <i>"Regions, then full image if nothing found"</i> keeps the slower
+    whole-image scan available as a safety net (label repositioned, a
+    region mis-measured) without paying its cost on every normal run.
+  </p>
+  <p>
+    Regions are plain pixel coordinates on the image at its native
+    resolution - <code>x</code>/<code>y</code> is the top-left corner,
+    <code>width</code>/<code>height</code> its size. Find them by opening a
+    sample photo in any image viewer that shows a pixel-coordinate readout
+    (or crop candidates and check the crop looks right) and reading off a
+    box comfortably around the barcode, including its quiet-zone margin -
+    tight crops with no margin can make the reader fail even though the
+    barcode itself is perfectly legible. Re-measure regions if the camera,
+    lens, or mounting changes.
+  </p>
+
+  <h3>Input</h3>
+  <p>
+    <code>msg.payload</code> - the image: Buffer / Uint8Array, a file path
+    string, or an object with <code>data</code>/<code>buffer</code>/<code>path</code>.
+  </p>
+  <p>
+    Optional per-message overrides: <code>msg.regions</code> (array of
+    <code>{ label, x, y, width, height }</code>, replaces the configured
+    list for this message) and <code>msg.mode</code>.
+  </p>
+
+  <h3>Output</h3>
+  <p>One message per barcode found, in scan order (regions first, then the full-image fallback if it ran):</p>
+  <ul>
+    <li><code>msg.text</code> - the decoded content</li>
+    <li><code>msg.format</code> - e.g. <code>"Code128"</code>, <code>"DataMatrix"</code></li>
+    <li><code>msg.roi</code> - <code>{ x, y, width, height }</code> of the region scanned (full-image coordinates)</li>
+    <li><code>msg.regionLabel</code> - the region's configured label, or <code>null</code> for a full-image find</li>
+    <li><code>msg.source</code> - <code>"region"</code> or <code>"fullImage"</code></li>
+    <li><code>msg.decodeMs</code> - time for that specific region/scan (not the whole node's runtime)</li>
+    <li><code>msg.timings</code> - <code>{ regionsMs, fullImageMs }</code>, whichever ran</li>
+    <li><code>msg.payload</code> - a cropped preview image of that result's region</li>
+  </ul>
+  <p>
+    If nothing is found anywhere, one message is sent with
+    <code>msg.text = null</code>, <code>msg.barcodeCount = 0</code>.
+  </p>
+
+  <h3>Notes</h3>
+  <p>
+    <b>EAN8 is off by default.</b> It's short enough that ZXing
+    implementations (both the JS port and, in testing against this
+    project's own sample label, zxing-wasm itself) have a real chance of
+    matching noise in a region/crop that has no barcode in it at all - a
+    confident wrong answer, worse than "not found". Turn it on only if a
+    real EAN-8 code is expected.
+  </p>
+  <p>
+    <b>Try harder / try rotate</b> are both on by default and both matter:
+    against this project's sample label, <code>tryHarder=false</code>
+    missed most of the real barcodes, and <code>tryRotate=false</code>
+    missed ones printed upside-down or rotated 90 degrees. Turning either
+    off trades recall for speed.
+  </p>
+  <p>
+    The first decode after Node-RED starts (or this flow redeploys) pays a
+    one-time warmup cost for zxing-wasm's WASM module - handled internally
+    so it doesn't land on whichever message happens to arrive first.
+  </p>
+</script>
+
+<script type="text/javascript">
+  RED.nodes.registerType("barcode-locate", {
+    category: "vision",
+    color: "#FFAAAA",
+    defaults: {
+      name: { value: "" },
+      mode: { value: "regionsThenAuto" },
+      regions: { value: [] },
+      Code128: { value: true },
+      DataMatrix: { value: true },
+      QRCode: { value: true },
+      EAN13: { value: true },
+      Code39: { value: true },
+      ITF: { value: true },
+      PDF417: { value: true },
+      EAN8: { value: false },
+      tryHarder: { value: true },
+      tryRotate: { value: true },
+    },
+    inputs: 1,
+    outputs: 1,
+    icon: "font-awesome/fa-barcode",
+    label: function () {
+      return this.name || "barcode locate";
+    },
+    paletteLabel: function () {
+      return "barcode locate";
+    },
+    oneditprepare: function () {
+      const list = $("#node-input-region-container")
+        .css("min-height", "150px")
+        .css("min-width", "450px")
+        .editableList({
+          addItem: function (container, index, region) {
+            region.label = region.label || "";
+            region.x = region.x || 0;
+            region.y = region.y || 0;
+            region.width = region.width || 0;
+            region.height = region.height || 0;
+
+            container.css({ overflow: "hidden", whiteSpace: "nowrap" });
+
+            const row1 = $("<div/>", { style: "margin-bottom:4px;" }).appendTo(container);
+            const labelInput = $("<input/>", {
+              type: "text",
+              style: "width:100%;",
+              placeholder: "label (optional, e.g. \"main UDI barcode\")",
+            })
+              .appendTo(row1)
+              .val(region.label);
+
+            const row2 = $("<div/>").appendTo(container);
+            function numField(placeholder, value) {
+              return $("<input/>", {
+                type: "number",
+                style: "width:70px;margin-right:6px;",
+                placeholder: placeholder,
+              })
+                .appendTo(row2)
+                .val(value);
+            }
+            $("<span/>", { text: "x:", style: "margin-right:3px;" }).appendTo(row2);
+            const xInput = numField("x", region.x);
+            $("<span/>", { text: "y:", style: "margin-right:3px;" }).appendTo(row2);
+            const yInput = numField("y", region.y);
+            $("<span/>", { text: "w:", style: "margin-right:3px;" }).appendTo(row2);
+            const wInput = numField("width", region.width);
+            $("<span/>", { text: "h:", style: "margin-right:3px;" }).appendTo(row2);
+            const hInput = numField("height", region.height);
+
+            container.data("read", function () {
+              return {
+                label: labelInput.val(),
+                x: parseInt(xInput.val(), 10) || 0,
+                y: parseInt(yInput.val(), 10) || 0,
+                width: parseInt(wInput.val(), 10) || 0,
+                height: parseInt(hInput.val(), 10) || 0,
+              };
+            });
+          },
+          removable: true,
+          sortable: true,
+        });
+
+      const regions = this.regions || [];
+      for (let i = 0; i < regions.length; i++) {
+        list.editableList("addItem", regions[i]);
+      }
+    },
+    oneditsave: function () {
+      const items = $("#node-input-region-container").editableList("items");
+      const regions = [];
+      items.each(function () {
+        const read = $(this).data("read");
+        if (read) regions.push(read());
+      });
+      this.regions = regions;
+    },
+  });
+</script>

package/barcode-locate.js

@@ -0,0 +1,156 @@
+/**
+ * barcode-locate Node-RED node.
+ *
+ * Finds and decodes barcodes (1D and 2D) in an image using zxing-wasm, a
+ * WebAssembly build of the zxing-cpp engine. Detection and decode logic
+ * lives in lib/locate.js so it can be exercised outside Node-RED.
+ *
+ * The point of this node over just calling zxing-wasm directly on the full
+ * image every time: on a fixed camera rig (same assumption
+ * golden-compare/checkerboard-calibrate already make - see their docs),
+ * barcodes land in roughly the same place shot to shot, so pre-defining
+ * where to look and scanning only those regions is 1-2 orders of magnitude
+ * faster than scanning the whole frame. "Regions, then full image if
+ * nothing found" keeps the whole-image scan available as a safety net
+ * (label repositioned, region mis-measured, etc.) without paying its cost
+ * on every normal run.
+ *
+ * Input (msg.payload): Buffer / Uint8Array / ArrayBuffer with image bytes,
+ * a file path string, or an object { data | buffer | path }.
+ * Optional per-message overrides: msg.regions (array), msg.mode.
+ *
+ * Output: one message per barcode found, in the order regions were scanned
+ * (then, if used, the full-image fallback) - msg.text, msg.format,
+ * msg.roi, msg.regionLabel, msg.source ("region"|"fullImage"),
+ * msg.decodeMs, msg.timings, msg.payload (a preview crop of that barcode's
+ * region). If nothing is found at all, sends one message with
+ * msg.text = null.
+ */
+
+const fs = require("fs");
+const fsp = fs.promises;
+const { locateBarcodes, DEFAULT_FORMATS } = require("./lib/locate.js");
+
+module.exports = (RED) => {
+	// same resolveImage contract as golden-compare.js / checkerboard-calibrate.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) {
+			return Buffer.from(source);
+		}
+		if (typeof source === "string") {
+			if (fs.existsSync(source)) return fsp.readFile(source);
+			throw new Error(`${label} does not exist on disk: "${source}"`);
+		}
+		if (typeof source === "object") {
+			const data = source.data || source.buffer;
+			if (Buffer.isBuffer(data) || data instanceof Uint8Array) {
+				return Buffer.from(data);
+			}
+			if (typeof source.path === "string" && fs.existsSync(source.path)) {
+				return fsp.readFile(source.path);
+			}
+			throw new Error(`${label} object must contain "data"/"buffer" or an existing "path"`);
+		}
+		throw new Error(`unsupported ${label} type: ${typeof source}`);
+	}
+
+	function normalizeRegions(regions) {
+		if (!Array.isArray(regions)) return [];
+		return regions
+			.map((r) => ({
+				label: String(r.label || "").trim(),
+				x: parseInt(r.x, 10) || 0,
+				y: parseInt(r.y, 10) || 0,
+				width: parseInt(r.width, 10) || 0,
+				height: parseInt(r.height, 10) || 0,
+			}))
+			.filter((r) => r.width > 0 && r.height > 0);
+	}
+
+	function totalMs(timings) {
+		return (timings.regionsMs || 0) + (timings.fullImageMs || 0);
+	}
+
+	function BarcodeLocateNode(config) {
+		RED.nodes.createNode(this, config);
+		const node = this;
+
+		node.mode = config.mode === "regionsOnly" || config.mode === "autoOnly" ? config.mode : "regionsThenAuto";
+		node.regions = normalizeRegions(config.regions);
+
+		const enabledFormats = DEFAULT_FORMATS.concat(["EAN8"]).filter((f) => config[f]);
+		node.readerOptions = {
+			tryHarder: config.tryHarder !== false,
+			tryRotate: config.tryRotate !== false,
+			maxNumberOfSymbols: 20,
+			formats: enabledFormats.length ? enabledFormats : DEFAULT_FORMATS,
+		};
+
+		node.on("input", async (msg, send, done) => {
+			send = send || function () { node.send.apply(node, arguments); };
+			try {
+				const buffer = await resolveImage(msg.payload, "msg.payload");
+				const regions = msg.regions !== undefined ? normalizeRegions(msg.regions) : node.regions;
+				const mode = msg.mode || node.mode;
+
+				node.status({ fill: "blue", shape: "dot", text: `scanning ${regions.length} region${regions.length === 1 ? "" : "s"}…` });
+
+				const { results, timings, usedFullImage } = await locateBarcodes(buffer, {
+					regions,
+					mode,
+					readerOptions: node.readerOptions,
+				});
+
+				if (results.length === 0) {
+					const noneMsg = Object.assign({}, msg, {
+						barcodeIndex: 0,
+						barcodeCount: 0,
+						text: null,
+						format: null,
+						roi: null,
+						regionLabel: null,
+						source: usedFullImage ? "fullImage" : "region",
+						timings,
+					});
+					send(noneMsg);
+					node.status({ fill: "yellow", shape: "ring", text: `none found (${totalMs(timings)}ms)` });
+					done();
+					return;
+				}
+
+				for (let i = 0; i < results.length; i++) {
+					const r = results[i];
+					const outMsg = Object.assign({}, msg, {
+						barcodeIndex: i,
+						barcodeCount: results.length,
+						text: r.text,
+						format: r.format,
+						roi: r.roi,
+						regionLabel: r.regionLabel,
+						source: r.source,
+						decodeMs: r.decodeMs,
+						timings,
+						payload: r.previewBuffer,
+					});
+					send(outMsg);
+				}
+
+				node.status({
+					fill: "green",
+					shape: "dot",
+					text: `${results.length} found (${usedFullImage ? "full image" : "regions"}, ${totalMs(timings)}ms)`,
+				});
+				done();
+			} catch (err) {
+				node.status({ fill: "red", shape: "ring", text: "error" });
+				node.error(`barcode-locate: ${err && err.message ? err.message : err}`, msg);
+				done(err);
+			}
+		});
+	}
+
+	RED.nodes.registerType("barcode-locate", BarcodeLocateNode);
+};

package/checkerboard-calibrate.html

@@ -0,0 +1,167 @@
+<script type="text/html" data-template-name="checkerboard-calibrate">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" placeholder="Name" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-targetPitchMm"
+      ><i class="fa fa-arrows-h"></i> Target pitch [mm]</label
+    >
+    <input
+      type="number"
+      id="node-input-targetPitchMm"
+      min="0.01"
+      step="0.01"
+      style="width:90px;"
+    />
+    <span class="node-input-hint" style="margin-left:10px; color:#999;"
+      >physical distance between adjacent same-colour squares on the
+      printed checkerboard</span
+    >
+  </div>
+  <div class="form-row">
+    <label for="node-input-checkerboardCols"
+      ><i class="fa fa-th"></i> Grid size</label
+    >
+    <input
+      type="number"
+      id="node-input-checkerboardCols"
+      min="2"
+      style="width:70px;"
+      placeholder="cols"
+    />
+    <span style="margin:0 6px;">x</span>
+    <input
+      type="number"
+      id="node-input-checkerboardRows"
+      min="3"
+      style="width:70px;"
+      placeholder="rows"
+    />
+    <span class="node-input-hint" style="margin-left:10px; color:#999;"
+      >expected dark-square grid (cols = longest row x rows) - see help</span
+    >
+  </div>
+  <div class="form-row">
+    <label for="node-input-allowedErrorPercent"
+      ><i class="fa fa-exclamation-triangle"></i> Allowed error</label
+    >
+    <input
+      type="number"
+      id="node-input-allowedErrorPercent"
+      min="0"
+      max="100"
+      step="0.1"
+      style="width:80px;"
+    />
+    <span class="node-input-hint" style="margin-left:10px; color:#999;">%</span>
+  </div>
+  <div class="form-row">
+    <label for="node-input-scaleFilePath"
+      ><i class="fa fa-save"></i> Scale file path</label
+    >
+    <input
+      type="text"
+      id="node-input-scaleFilePath"
+      placeholder="/data/golden/calibration.json (container path)"
+    />
+  </div>
+</script>
+
+<script type="text/html" data-help-name="checkerboard-calibrate">
+  <p>
+    Measure how many millimetres a pixel covers, and check that it has not
+    drifted: 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. Run this once at commissioning and
+    again after camera or mechanical maintenance - not per production frame.
+  </p>
+  <p>
+    Detection is centroid/pitch-based (no sub-pixel corner refinement, no
+    lens-distortion or perspective correction) - it answers "has the
+    scale/geometry drifted since the last calibration," consistent with
+    <code>golden-compare</code>'s translation-only, fixed-rig scope.
+  </p>
+
+  <h3>Checkerboard requirements</h3>
+  <p>
+    <i>Grid size</i> counts <b>dark squares</b>, not total squares or inner
+    corners: cols = dark squares in the <b>longest</b> row, rows = number of
+    rows. Needs at least 3 rows (a 2-row step is used to measure vertical
+    pitch consistently with the horizontal same-colour spacing - see
+    <code>lib/checkerboard.js</code>).
+  </p>
+  <p>
+    A board with an <b>even</b> number of square columns holds the same
+    number of dark squares in every row: 16 columns means cols = 8. An
+    <b>odd</b> number cannot, so its rows alternate - 17 columns gives 9
+    dark squares in the rows that start dark and 8 in the rows that start
+    light, and cols = 9. Both shapes are accepted; count the longest row
+    either way, and the corner colour does not matter.
+  </p>
+
+  <h3>Input</h3>
+  <p>
+    <code>msg.payload</code> — a photo of the printed checkerboard: Buffer /
+    Uint8Array, a file path string, or an object with
+    <code>data</code>/<code>buffer</code>/<code>path</code>.
+  </p>
+  <p>
+    <code>msg.save</code> (bool) — persist the freshly detected scale as the
+    new baseline (their "Match New Scale" + "Save"). Optional per-message
+    overrides: <code>msg.targetPitchMm</code>,
+    <code>msg.checkerboardCols</code>, <code>msg.checkerboardRows</code>,
+    <code>msg.allowedErrorPercent</code>.
+  </p>
+
+  <h3>Output</h3>
+  <ul>
+    <li><code>msg.payload</code> — <code>true</code>/<code>false</code> pass</li>
+    <li>
+      <code>msg.result</code> —
+      <code
+        >{ checkerboardDetected, currentScale, detectedScale,
+        deviationPercent, bootstrap, pass, saved, pitchXPx, pitchYPx,
+        nativeWidth, nativeHeight }</code
+      >
+      (scales in mm/px; <code>bootstrap</code> is true when there's no saved
+      baseline yet to compare against - always passes, since there's
+      nothing to deviate from)
+    </li>
+    <li><code>msg.timings</code> — <code>{ totalMs }</code></li>
+  </ul>
+
+  <h3>Notes</h3>
+  <p>
+    <i>Scale file path</i> is a path <b>inside the container</b> - use
+    <code>/data</code> so the calibration baseline survives a rebuild. The
+    saved scale is <code>mmPerPixelNative</code> - measured at this
+    calibration photo's own native resolution, not any particular
+    <code>golden-compare</code> working resolution - so it stays valid
+    however <code>golden-compare</code>'s <i>Working size</i> is configured.
+  </p>
+</script>
+
+<script type="text/javascript">
+  RED.nodes.registerType("checkerboard-calibrate", {
+    category: "vision",
+    color: "#5DADE2",
+    defaults: {
+      name: { value: "" },
+      targetPitchMm: { value: 10, validate: RED.validators.number(true) },
+      checkerboardCols: { value: 4, validate: RED.validators.number(true) },
+      checkerboardRows: { value: 6, validate: RED.validators.number(true) },
+      allowedErrorPercent: { value: 2, validate: RED.validators.number(true) },
+      scaleFilePath: { value: "" },
+    },
+    inputs: 1,
+    outputs: 1,
+    icon: "checkerboard-calibrate.svg",
+    label: function () {
+      return this.name || "checkerboard calibrate";
+    },
+    paletteLabel: function () {
+      return "checkerboard calibrate";
+    },
+  });
+</script>