@sythos/js_barcode_universal 0.1.0 → 1.1.0

package/src/datamatrix/decoder.js

@@ -0,0 +1,262 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/**
+ * Data Matrix ECC 200 decoder for an already sampled symbol.
+ *
+ * The detector owns locating, perspective correction and orientation. This
+ * module starts with the complete, upright symbol including its finder borders.
+ * The table entry is deliberately read through a small normalizer so table data
+ * remains declarative: it needs total rows/columns, one data-region's rows and
+ * columns, data/ECC codeword counts, and either a block count or data block
+ * lengths. The standard 144x144 uneven data blocks are supported.
+ *
+ * @module datamatrix/decoder
+ */
+
+import { ChecksumError, FormatError } from '../core/errors.js';
+import { GF256_DM } from '../core/galois-field.js';
+import { rsDecode } from '../core/reed-solomon.js';
+import { SYMBOLS } from './tables.js';
+
+const CW_PAD = 129;
+const CW_BASE256 = 231;
+
+/** @param {object} entry @param {...string} names @returns {number | undefined} */
+function numberField(entry, ...names) {
+  for (const name of names) if (Number.isInteger(entry[name])) return entry[name];
+  return undefined;
+}
+
+/** Normalize the public table entry into the decoder's geometry contract. */
+function layoutFor(width, height) {
+  const entry = SYMBOLS.find((s) =>
+    numberField(s, 'columns', 'cols', 'matrixColumns', 'width') === width &&
+    numberField(s, 'rows', 'matrixRows', 'height') === height);
+  if (!entry) throw new FormatError(`Data Matrix: ${width}x${height} is not an ECC 200 symbol size`);
+
+  const regionRows = numberField(entry, 'dataRegionRows', 'regionRows') ??
+    (numberField(entry, 'regionHeight') ? numberField(entry, 'regionHeight') - 2 : undefined);
+  const regionCols = numberField(entry, 'dataRegionColumns', 'dataRegionCols', 'regionColumns') ??
+    (numberField(entry, 'regionWidth') ? numberField(entry, 'regionWidth') - 2 : undefined);
+  const dataCount = numberField(entry, 'dataCodewords', 'dataCapacity');
+  const eccCount = numberField(entry, 'errorCodewords', 'eccCodewords');
+  const blockCount = numberField(entry, 'interleavedBlocks', 'interleavedBlockCount', 'blockCount', 'rsBlocks') || 1;
+  if (!regionRows || !regionCols || dataCount === undefined || eccCount === undefined ||
+      height % (regionRows + 2) || width % (regionCols + 2) || eccCount % blockCount) {
+    throw new FormatError(`Data Matrix: invalid table layout for ${width}x${height}`);
+  }
+
+  const rows = height / (regionRows + 2);
+  const cols = width / (regionCols + 2);
+  const blockData = Array.isArray(entry.blockDataCodewords) ? entry.blockDataCodewords.slice() :
+    Array.isArray(entry.dataCodewordsPerBlock) ? entry.dataCodewordsPerBlock.slice() : null;
+  let dataLengths;
+  if (blockData) {
+    dataLengths = blockData;
+  } else {
+    // The sole uneven ECC 200 distribution is 144x144: its first eight of ten
+    // blocks contain one extra data codeword. This derives it instead of hiding
+    // a magic size check in the deinterleaver.
+    const short = Math.floor(dataCount / blockCount);
+    dataLengths = new Array(blockCount).fill(short);
+    for (let i = 0; i < dataCount % blockCount; i++) dataLengths[i]++;
+  }
+  if (dataLengths.length !== blockCount || dataLengths.reduce((a, b) => a + b, 0) !== dataCount) {
+    throw new FormatError(`Data Matrix: inconsistent block layout for ${width}x${height}`);
+  }
+  return { entry, regionRows, regionCols, regionRowCount: rows, regionColCount: cols,
+    dataRows: rows * regionRows, dataCols: cols * regionCols, dataCount, eccCount,
+    blockCount, eccPerBlock: eccCount / blockCount, dataLengths };
+}
+
+/** Remove the L/finders from every data region, retaining only placement modules. */
+function extractDataModules(matrix, layout) {
+  const data = new Uint8Array(layout.dataRows * layout.dataCols);
+  for (let regionY = 0; regionY < layout.regionRowCount; regionY++) {
+    for (let regionX = 0; regionX < layout.regionColCount; regionX++) {
+      const sourceX = regionX * (layout.regionCols + 2) + 1;
+      const sourceY = regionY * (layout.regionRows + 2) + 1;
+      for (let y = 0; y < layout.regionRows; y++) {
+        const targetY = regionY * layout.regionRows + y;
+        for (let x = 0; x < layout.regionCols; x++) {
+          data[targetY * layout.dataCols + regionX * layout.regionCols + x] =
+            matrix.get(sourceX + x, sourceY + y) ? 1 : 0;
+        }
+      }
+    }
+  }
+  return data;
+}
+
+/** Read placement codewords using the ECC 200 Utah sweep (the inverse writer path). */
+function readPlacement(modules, rows, cols, count) {
+  const seen = new Uint8Array(rows * cols);
+  const out = new Uint8Array(count);
+  const get = (row, col) => modules[row * cols + col] !== 0;
+  const module = (row, col) => {
+    if (row < 0) { row += rows; col += 4 - ((rows + 4) % 8); }
+    if (col < 0) { col += cols; row += 4 - ((cols + 4) % 8); }
+    if (row < 0 || row >= rows || col < 0 || col >= cols) {
+      throw new FormatError('Data Matrix: placement coordinate escaped data region');
+    }
+    seen[row * cols + col] = 1;
+    return get(row, col) ? 1 : 0;
+  };
+  const bits = (coords) => coords.reduce((value, p) => (value << 1) | module(p[0], p[1]), 0);
+  const utah = (row, col) => bits([[row - 2, col - 2], [row - 2, col - 1], [row - 1, col - 2], [row - 1, col - 1],
+    [row - 1, col], [row, col - 2], [row, col - 1], [row, col]]);
+  const corner1 = () => bits([[rows - 1, 0], [rows - 1, 1], [rows - 1, 2], [0, cols - 2], [0, cols - 1], [1, cols - 1], [2, cols - 1], [3, cols - 1]]);
+  const corner2 = () => bits([[rows - 3, 0], [rows - 2, 0], [rows - 1, 0], [0, cols - 4], [0, cols - 3], [0, cols - 2], [0, cols - 1], [1, cols - 1]]);
+  const corner3 = () => bits([[rows - 3, 0], [rows - 2, 0], [rows - 1, 0], [0, cols - 2], [0, cols - 1], [1, cols - 1], [2, cols - 1], [3, cols - 1]]);
+  const corner4 = () => bits([[rows - 1, 0], [rows - 1, cols - 1], [0, cols - 3], [0, cols - 2], [0, cols - 1], [1, cols - 3], [1, cols - 2], [1, cols - 1]]);
+
+  let row = 4, col = 0, n = 0;
+  const put = (value) => { if (n < count) out[n++] = value; };
+  do {
+    if (row === rows && col === 0) put(corner1());
+    if (row === rows - 2 && col === 0 && cols % 4 !== 0) put(corner2());
+    if (row === rows - 2 && col === 0 && cols % 8 === 4) put(corner3());
+    if (row === rows + 4 && col === 2 && cols % 8 === 0) put(corner4());
+    do { if (row < rows && col >= 0 && !seen[row * cols + col]) put(utah(row, col)); row -= 2; col += 2; } while (row >= 0 && col < cols);
+    row += 1; col += 3;
+    do { if (row >= 0 && col < cols && !seen[row * cols + col]) put(utah(row, col)); row += 2; col -= 2; } while (row < rows && col >= 0);
+    row += 3; col += 1;
+  } while (row < rows || col < cols);
+  if (n !== count) throw new FormatError(`Data Matrix: placement yielded ${n}, expected ${count} codewords`);
+  return out;
+}
+
+/** Restore RS blocks, correct them, then concatenate their data portions. */
+function deinterleaveAndCorrect(codewords, layout) {
+  if (codewords.length !== layout.dataCount + layout.eccCount) throw new FormatError('Data Matrix: codeword count mismatch');
+  const blocks = layout.dataLengths.map((len) => new Uint8Array(len + layout.eccPerBlock));
+  // Data codewords arrive in their original stream order. ECC 200 deals that
+  // stream round-robin across the RS blocks, so the inverse is determined by
+  // the wire index rather than by splitting it into consecutive block-sized
+  // chunks. For 144x144, indices 1550..1557 naturally land in the eight long
+  // blocks while the two short blocks remain at 155 data codewords.
+  for (let i = 0; i < layout.dataCount; i++) {
+    blocks[i % layout.blockCount][Math.floor(i / layout.blockCount)] = codewords[i];
+  }
+
+  // Parity normally begins with block zero. The uneven 144x144 layout rotates
+  // the parity wire order to begin with its first short block; derive the same
+  // mapping from the declarative lengths instead of keying it to dimensions.
+  const longest = Math.max(...layout.dataLengths);
+  const firstShort = layout.dataLengths.findIndex((length) => length < longest);
+  const rotation = firstShort < 0 ? 0 : firstShort;
+  let at = layout.dataCount;
+  for (let i = 0; i < layout.eccPerBlock; i++) {
+    for (let slot = 0; slot < layout.blockCount; slot++) {
+      const block = (slot + rotation) % layout.blockCount;
+      blocks[block][layout.dataLengths[block] + i] = codewords[at++];
+    }
+  }
+
+  let corrections = 0;
+  const data = new Uint8Array(layout.dataCount);
+  for (let b = 0; b < blocks.length; b++) {
+    corrections += rsDecode(blocks[b], layout.eccPerBlock, GF256_DM, 1);
+  }
+  // Rebuild the original high-level codeword stream after correction. Keeping
+  // this in wire-index order is essential: concatenating block data passes
+  // single-block round trips but scrambles every multi-block payload.
+  for (let i = 0; i < layout.dataCount; i++) {
+    data[i] = blocks[i % layout.blockCount][Math.floor(i / layout.blockCount)];
+  }
+  return { data, corrections };
+}
+
+function unrandomize(value, position) {
+  const pseudo = ((149 * position) % 255) + 1;
+  return value - pseudo >= 0 ? value - pseudo : value - pseudo + 256;
+}
+
+/** Decode ASCII plus Base 256, preserving semantic bytes alongside text. */
+function parseData(data) {
+  let text = '';
+  const bytes = [];
+  let upperShift = false;
+  let gs1 = false;
+  for (let i = 0; i < data.length;) {
+    const cw = data[i++];
+    if (cw === CW_PAD) break;
+    if (cw <= 128) {
+      const value = cw - 1 + (upperShift ? 128 : 0);
+      upperShift = false;
+      text += String.fromCharCode(value); bytes.push(value); continue;
+    }
+    if (cw <= 229) {
+      const pair = cw - 130;
+      const digits = String(pair).padStart(2, '0'); text += digits; bytes.push(digits.charCodeAt(0), digits.charCodeAt(1)); continue;
+    }
+    if (cw === 232) {
+      if (i === 1) gs1 = true;
+      else { text += '\x1d'; bytes.push(29); }
+      continue;
+    }
+    if (cw === 235) { upperShift = true; continue; }
+    if (cw === CW_BASE256) {
+      if (i >= data.length) throw new FormatError('Data Matrix: Base 256 length is missing');
+      let length = unrandomize(data[i], i + 1); i++;
+      if (length === 0) length = data.length - i;
+      else if (length >= 250) {
+        if (i >= data.length) throw new FormatError('Data Matrix: Base 256 extended length is missing');
+        length = 250 * (length - 249) + unrandomize(data[i], i + 1); i++;
+      }
+      if (i + length > data.length) throw new FormatError('Data Matrix: Base 256 segment exceeds data capacity');
+      const segment = new Uint8Array(length);
+      for (let n = 0; n < length; n++, i++) segment[n] = unrandomize(data[i], i + 1);
+      bytes.push(...segment);
+      for (let n = 0; n < segment.length; n++) text += String.fromCharCode(segment[n]);
+      continue;
+    }
+    throw new FormatError(`Data Matrix: unsupported encoding codeword ${cw}`);
+  }
+  return { text, bytes: Uint8Array.from(bytes), gs1 };
+}
+
+/**
+ * Decode an upright, sampled Data Matrix ECC 200 symbol.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} matrix Full symbol, no quiet zone.
+ * @returns {{text: string, bytes: Uint8Array, correctedErrors: number, symbol: object}}
+ */
+export function decodeDataMatrix(matrix) {
+  if (!matrix || !Number.isInteger(matrix.width) || !Number.isInteger(matrix.height)) throw new FormatError('Data Matrix: no matrix supplied');
+  const layout = layoutFor(matrix.width, matrix.height);
+  const placement = readPlacement(extractDataModules(matrix, layout), layout.dataRows, layout.dataCols, layout.dataCount + layout.eccCount);
+  const { data, corrections } = deinterleaveAndCorrect(placement, layout);
+  const result = parseData(data);
+  return { ...result, corrections, correctedErrors: corrections, symbol: layout.entry };
+}
+
+export { ChecksumError };

package/src/datamatrix/detector.js

@@ -0,0 +1,225 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/**
+ * Data Matrix ECC 200 detection in a binarized image.
+ *
+ * An ECC 200 symbol is distinguished by two neighbouring solid finder borders
+ * (the L) and two alternating clock borders.  The detector first finds dark
+ * connected components, then scores every legal ECC 200 size and every
+ * quarter-turn of the component's bounding quadrilateral against those four
+ * borders.  This deliberately verifies the complete border rather than merely
+ * looking for an L: ordinary text and table rules produce L shapes often.
+ *
+ * The resulting quadrilateral is sampled back into the canonical orientation:
+ * solid borders at left and bottom.  It is intentionally independent of the
+ * payload decoder, so geometry can be used by callers that need the matrix.
+ *
+ * @module datamatrix/detector
+ */
+
+import { NotFoundError } from '../core/errors.js';
+import { sampleGrid, sampleQuad } from '../image/grid-sampler.js';
+import { PerspectiveTransform } from '../image/perspective.js';
+import { decodeDataMatrix } from './decoder.js';
+
+// ECC 200 dimensions.  DMRE is deliberately not included: it uses a separate
+// size table and is not part of the original ECC 200 family implemented here.
+const SIZES = [
+  [10, 10], [12, 12], [14, 14], [16, 16], [18, 18], [20, 20], [22, 22], [24, 24], [26, 26],
+  [32, 32], [36, 36], [40, 40], [44, 44], [48, 48], [52, 52], [64, 64], [72, 72], [80, 80],
+  [88, 88], [96, 96], [104, 104], [120, 120], [132, 132], [144, 144],
+  [18, 8], [32, 8], [26, 12], [36, 12], [36, 16], [48, 16],
+];
+
+/** @typedef {{x:number, y:number}} Point */
+/** @typedef {{corners: Point[], dimension: number, width: number, height: number, moduleSize: number, matrix: import('../core/bit-matrix.js').BitMatrix}} Detection */
+
+function dark(image, x, y) {
+  return image.get(Math.max(0, Math.min(image.width - 1, Math.round(x))),
+    Math.max(0, Math.min(image.height - 1, Math.round(y))));
+}
+
+/** Return components which are large enough to plausibly contain a symbol. */
+function components(image) {
+  const seen = new Uint8Array(image.width * image.height);
+  const out = [];
+  const push = (x, y, xs, ys) => { xs.push(x); ys.push(y); };
+  for (let y = 0; y < image.height; y++) for (let x = 0; x < image.width; x++) {
+    const start = y * image.width + x;
+    if (seen[start] || !image.get(x, y)) continue;
+    const xs = [x], ys = [y]; seen[start] = 1;
+    let head = 0, minX = x, maxX = x, minY = y, maxY = y;
+    while (head < xs.length) {
+      const px = xs[head], py = ys[head++];
+      if (px < minX) minX = px; if (px > maxX) maxX = px;
+      if (py < minY) minY = py; if (py > maxY) maxY = py;
+      for (const [nx, ny] of [[px - 1, py], [px + 1, py], [px, py - 1], [px, py + 1]]) {
+        if (nx < 0 || ny < 0 || nx >= image.width || ny >= image.height) continue;
+        const at = ny * image.width + nx;
+        if (!seen[at] && image.get(nx, ny)) { seen[at] = 1; push(nx, ny, xs, ys); }
+      }
+    }
+    if (maxX - minX >= 7 && maxY - minY >= 7) out.push({ minX, minY, maxX, maxY, pixels: xs.length });
+  }
+  return out.sort((a, b) => b.pixels - a.pixels).slice(0, 40);
+}
+
+/** Sample a physical edge at module centres. */
+function edge(image, a, b, count) {
+  const values = [];
+  for (let i = 0; i < count; i++) {
+    const t = (i + 0.5) / count;
+    values.push(dark(image, a.x + (b.x - a.x) * t, a.y + (b.y - a.y) * t));
+  }
+  return values;
+}
+
+function solidScore(values) {
+  let n = 0; for (const value of values) if (value) n++;
+  return n / values.length;
+}
+
+function clockScore(values, startsDark) {
+  let n = 0;
+  for (let i = 0; i < values.length; i++) if (values[i] === ((i & 1) === 0 ? startsDark : !startsDark)) n++;
+  return n / values.length;
+}
+
+/** Count light/dark changes along a physical edge at approximately one-pixel intervals. */
+function edgeTransitions(image, a, b) {
+  const steps = Math.max(1, Math.ceil(Math.hypot(b.x - a.x, b.y - a.y)));
+  let previous = dark(image, a.x, a.y);
+  let changes = 0;
+  for (let i = 1; i <= steps; i++) {
+    const t = i / steps;
+    const value = dark(image, a.x + (b.x - a.x) * t, a.y + (b.y - a.y) * t);
+    if (value !== previous) changes++;
+    previous = value;
+  }
+  return changes;
+}
+
+/** Reject a smaller harmonic whose module-centre samples happen to alternate. */
+function transitionCountFits(observed, modules) {
+  const expected = modules - 1;
+  const tolerance = Math.max(2, Math.floor(expected * 0.08));
+  return Math.abs(observed - expected) <= tolerance;
+}
+
+function sample(image, width, height, corners, voting) {
+  if (width === height) return sampleQuad(image, width, corners, voting);
+  const [tl, tr, br, bl] = corners;
+  const transform = PerspectiveTransform.quadToQuad(0, 0, width, 0, width, height, 0, height,
+    tl.x, tl.y, tr.x, tr.y, br.x, br.y, bl.x, bl.y);
+  return sampleGrid(image, width, height, transform);
+}
+
+/**
+ * Find Data Matrix symbols in a binarized image.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} binaryImage Set bit = dark.
+ * @returns {Detection | null} The strongest candidate, or null when absent.
+ */
+export function detectDataMatrix(binaryImage) {
+  if (!binaryImage || !binaryImage.width || !binaryImage.height) {
+    throw new NotFoundError('detectDataMatrix: no image supplied');
+  }
+  const detections = [];
+  const used = new Set();
+  for (const box of components(binaryImage)) {
+    const base = [
+      { x: box.minX, y: box.minY }, { x: box.maxX + 1, y: box.minY },
+      { x: box.maxX + 1, y: box.maxY + 1 }, { x: box.minX, y: box.maxY + 1 },
+    ];
+    // Profile the actual ink, rather than the outer sampling quadrilateral:
+    // its far x/y boundary lies one pixel beyond the last dark pixel.
+    const ink = [
+      { x: box.minX, y: box.minY }, { x: box.maxX, y: box.minY },
+      { x: box.maxX, y: box.maxY }, { x: box.minX, y: box.maxY },
+    ];
+    for (const [w, h] of SIZES) for (let turn = 0; turn < 4; turn++) {
+      // A 90 degree turn swaps physical width and height.
+      const physicalW = (turn & 1) ? h : w, physicalH = (turn & 1) ? w : h;
+      const pitchX = (box.maxX - box.minX + 1) / physicalW;
+      const pitchY = (box.maxY - box.minY + 1) / physicalH;
+      if (Math.min(pitchX, pitchY) < 1 || Math.abs(pitchX - pitchY) > Math.max(pitchX, pitchY) * 0.22) continue;
+      const corners = base.slice(turn).concat(base.slice(0, turn));
+      const profile = ink.slice(turn).concat(ink.slice(0, turn));
+      // Canonical edge order: top clock, right clock, bottom solid, left solid.
+      const top = edge(binaryImage, profile[0], profile[1], w);
+      const right = edge(binaryImage, profile[1], profile[2], h);
+      const bottom = edge(binaryImage, profile[2], profile[3], w);
+      const left = edge(binaryImage, profile[3], profile[0], h);
+      // Sampling only the proposed module centres aliases exact harmonics: an
+      // 80-module clock border, for example, can look like a perfect 16-module
+      // border.  Count transitions at image-pixel resolution as an independent
+      // dimension measurement before accepting the candidate.
+      if (!transitionCountFits(edgeTransitions(binaryImage, profile[0], profile[1]), w) ||
+          !transitionCountFits(edgeTransitions(binaryImage, profile[1], profile[2]), h)) continue;
+      // The top clock starts dark at the solid left border.  The right clock is
+      // anchored dark at the solid bottom border instead, so its top phase
+      // depends on the symbol height (all ECC 200 heights are even and
+      // therefore start light).
+      const score = (clockScore(top, true) + clockScore(right, (h & 1) === 1) +
+        solidScore(bottom) + solidScore(left)) / 4;
+      if (score < 0.88) continue;
+      const key = `${box.minX},${box.minY},${box.maxX},${box.maxY}`;
+      if (used.has(key)) continue;
+      let matrix;
+      try { matrix = sample(binaryImage, w, h, corners, false); } catch (e) { continue; }
+      used.add(key);
+      detections.push({ corners, dimension: w === h ? w : 0, width: w, height: h,
+        moduleSize: (pitchX + pitchY) / 2, matrix, score });
+    }
+  }
+  detections.sort((a, b) => b.score - a.score || b.moduleSize - a.moduleSize);
+  return detections[0] ?? null;
+}
+
+/**
+ * Detect and decode Data Matrix symbols.  Detection failure is normal for an
+ * image without a symbol, so candidates that cannot decode are skipped.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} binaryImage
+ * @returns {(import('./decoder.js').DecodeResult & {corners: Point[]}) | null}
+ */
+export function detectAndDecodeDataMatrix(binaryImage) {
+  let detection;
+  try { detection = detectDataMatrix(binaryImage); } catch (e) { return null; }
+  if (!detection) return null;
+  for (const voting of [false, true]) {
+    let matrix = detection.matrix;
+    try { if (voting) matrix = sample(binaryImage, detection.width, detection.height, detection.corners, true); } catch (e) { continue; }
+    try { return Object.assign({ corners: detection.corners }, decodeDataMatrix(matrix)); }
+    catch (e) { /* A geometric candidate is not necessarily a symbol. */ }
+  }
+  return null;
+}

package/src/datamatrix/encoder.js

@@ -0,0 +1,191 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/** Data Matrix ECC 200 encoder: ASCII/Base256, RS interleaving and Annex F placement. */
+import { BitMatrix } from '../core/bit-matrix.js';
+import { EncodeError } from '../core/errors.js';
+import { GF256_DM } from '../core/galois-field.js';
+import { rsEncode } from '../core/reed-solomon.js';
+import { symbolForDataCodewords } from './tables.js';
+
+function asciiCodewords(text) {
+  const out = [];
+  for (let i = 0; i < text.length;) {
+    const a = text.charCodeAt(i);
+    if (a > 255) throw new EncodeError('Data Matrix ASCII: characters must fit ISO-8859-1; use Base256 for UTF-8');
+    if (i + 1 < text.length) {
+      const b = text.charCodeAt(i + 1);
+      if (a >= 48 && a <= 57 && b >= 48 && b <= 57) { out.push(130 + (a - 48) * 10 + b - 48); i += 2; continue; }
+    }
+    if (a <= 127) out.push(a + 1);
+    else out.push(235, a - 127);
+    i++;
+  }
+  return out;
+}
+
+function bytesFor(value) {
+  if (value instanceof Uint8Array) return value;
+  if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  if (typeof value !== 'string') throw new EncodeError('Data Matrix: value must be a string or byte array');
+  return new TextEncoder().encode(value);
+}
+
+function randomize255(value, position) {
+  const pseudo = (149 * position) % 255 + 1;
+  return value + pseudo <= 255 ? value + pseudo : value + pseudo - 256;
+}
+
+function base256Codewords(value, prefixLength = 0) {
+  const bytes = bytesFor(value);
+  if (bytes.length > 1555) throw new EncodeError('Data Matrix Base256: payload exceeds ECC 200 capacity');
+  const out = [231];
+  if (bytes.length <= 249) out.push(bytes.length);
+  else out.push(Math.floor(bytes.length / 250) + 249, bytes.length % 250);
+  // Base256 randomization uses the absolute 1-based codeword position in the
+  // symbol. A leading GS1 FNC1 therefore shifts every randomized codeword.
+  for (let i = 1; i < out.length; i++) out[i] = randomize255(out[i], prefixLength + i + 1);
+  for (const b of bytes) out.push(randomize255(b, prefixLength + out.length + 1));
+  return out;
+}
+
+function pad(data, capacity) {
+  const out = data.slice();
+  if (out.length < capacity) out.push(129);
+  while (out.length < capacity) {
+    const position = out.length + 1;
+    const pseudo = (149 * position) % 253 + 1;
+    const v = 129 + pseudo;
+    out.push(v <= 254 ? v : v - 254);
+  }
+  return out;
+}
+
+function interleave(data, symbol) {
+  const blocks = symbol.dataBlockLengths.map((length) => ({ data: new Array(length), ecc: null }));
+  let at = 0;
+  const longest = Math.max(...symbol.dataBlockLengths);
+  // Data codewords are dealt across the RS blocks by column. Splitting the
+  // stream into consecutive chunks and then interleaving those chunks looks
+  // self-consistent to a decoder doing the same inverse operation, but it is
+  // not ECC 200's wire order once a symbol has multiple blocks.
+  for (let i = 0; i < longest; i++) {
+    for (const block of blocks) if (i < block.data.length) block.data[i] = data[at++];
+  }
+  for (const block of blocks) {
+    // ECC 200 starts its generator roots at alpha^1 (generator base 1).
+    block.ecc = rsEncode(block.data, symbol.eccPerBlock, GF256_DM, 1);
+  }
+
+  const out = [];
+  for (let i = 0; i < longest; i++) for (const b of blocks) if (i < b.data.length) out.push(b.data[i]);
+  // The 144x144 symbol has eight long and two short data blocks. Its parity
+  // interleave begins with the first short block; deriving the rotation from
+  // the declarative lengths keeps that exception out of a size-specific test.
+  const eccOffset = blocks.findIndex((block) => block.data.length < longest);
+  const rotation = eccOffset < 0 ? 0 : eccOffset;
+  for (let i = 0; i < symbol.eccPerBlock; i++) {
+    for (let b = 0; b < blocks.length; b++) out.push(blocks[(b + rotation) % blocks.length].ecc[i]);
+  }
+  return out;
+}
+
+function place(codewords, rows, cols) {
+  const cells = new Int8Array(rows * cols).fill(-1);
+  const bit = (row, col, pos, n) => {
+    if (row < 0) { row += rows; col += 4 - ((rows + 4) % 8); }
+    if (col < 0) { col += cols; row += 4 - ((cols + 4) % 8); }
+    cells[row * cols + col] = (codewords[pos] >>> (8 - n)) & 1;
+  };
+  const utah = (r, c, p) => { bit(r - 2, c - 2, p, 1); bit(r - 2, c - 1, p, 2); bit(r - 1, c - 2, p, 3); bit(r - 1, c - 1, p, 4); bit(r - 1, c, p, 5); bit(r, c - 2, p, 6); bit(r, c - 1, p, 7); bit(r, c, p, 8); };
+  const corner1 = (p) => { bit(rows - 1, 0, p, 1); bit(rows - 1, 1, p, 2); bit(rows - 1, 2, p, 3); bit(0, cols - 2, p, 4); bit(0, cols - 1, p, 5); bit(1, cols - 1, p, 6); bit(2, cols - 1, p, 7); bit(3, cols - 1, p, 8); };
+  const corner2 = (p) => { bit(rows - 3, 0, p, 1); bit(rows - 2, 0, p, 2); bit(rows - 1, 0, p, 3); bit(0, cols - 4, p, 4); bit(0, cols - 3, p, 5); bit(0, cols - 2, p, 6); bit(0, cols - 1, p, 7); bit(1, cols - 1, p, 8); };
+  const corner3 = (p) => { bit(rows - 3, 0, p, 1); bit(rows - 2, 0, p, 2); bit(rows - 1, 0, p, 3); bit(0, cols - 2, p, 4); bit(0, cols - 1, p, 5); bit(1, cols - 1, p, 6); bit(2, cols - 1, p, 7); bit(3, cols - 1, p, 8); };
+  const corner4 = (p) => { bit(rows - 1, 0, p, 1); bit(rows - 1, cols - 1, p, 2); bit(0, cols - 3, p, 3); bit(0, cols - 2, p, 4); bit(0, cols - 1, p, 5); bit(1, cols - 3, p, 6); bit(1, cols - 2, p, 7); bit(1, cols - 1, p, 8); };
+  let row = 4, col = 0, pos = 0;
+  do {
+    if (row === rows && col === 0) corner1(pos++);
+    if (row === rows - 2 && col === 0 && cols % 4 !== 0) corner2(pos++);
+    if (row === rows - 2 && col === 0 && cols % 8 === 4) corner3(pos++);
+    if (row === rows + 4 && col === 2 && cols % 8 === 0) corner4(pos++);
+    do { if (row < rows && col >= 0 && cells[row * cols + col] < 0) utah(row, col, pos++); row -= 2; col += 2; } while (row >= 0 && col < cols);
+    row += 1; col += 3;
+    do { if (row >= 0 && col < cols && cells[row * cols + col] < 0) utah(row, col, pos++); row += 2; col -= 2; } while (row < rows && col >= 0);
+    row += 3; col += 1;
+  } while (row < rows || col < cols);
+  if (cells[cells.length - 1] < 0) { cells[cells.length - 1] = 1; cells[cells.length - cols - 2] = 1; }
+  if (pos !== codewords.length) throw new EncodeError(`Data Matrix: placement consumed ${pos} of ${codewords.length} codewords`);
+  return cells;
+}
+
+function buildMatrix(codewords, symbol) {
+  const regionCols = symbol.width / symbol.regionWidth;
+  const regionRows = symbol.height / symbol.regionHeight;
+  const dataWidth = symbol.dataRegionColumns;
+  const dataHeight = symbol.dataRegionRows;
+  const data = place(codewords, regionRows * dataHeight, regionCols * dataWidth);
+  const matrix = new BitMatrix(symbol.width, symbol.height);
+  for (let ry = 0; ry < regionRows; ry++) for (let rx = 0; rx < regionCols; rx++) {
+    const x0 = rx * symbol.regionWidth, y0 = ry * symbol.regionHeight;
+    for (let x = 0; x < symbol.regionWidth; x++) { if ((x & 1) === 0) matrix.set(x0 + x, y0); matrix.set(x0 + x, y0 + dataHeight + 1); }
+    // The top and right timing borders are complementary: top-left is dark,
+    // top-right is light, and the solid bottom-right corner remains dark.
+    for (let y = 0; y < symbol.regionHeight; y++) { matrix.set(x0, y0 + y); if ((y & 1) === 1) matrix.set(x0 + dataWidth + 1, y0 + y); }
+    for (let y = 0; y < dataHeight; y++) for (let x = 0; x < dataWidth; x++) if (data[(ry * dataHeight + y) * (regionCols * dataWidth) + rx * dataWidth + x]) matrix.set(x0 + 1 + x, y0 + 1 + y);
+  }
+  return matrix;
+}
+
+/** Encode a string (ASCII mode) or byte payload (Base256) into Data Matrix ECC 200. */
+export function encodeDataMatrix(value, options = {}) {
+  const encoding = options.encoding ?? (value instanceof Uint8Array ? 'base256' : 'ascii');
+  let raw;
+  if (encoding === 'ascii') {
+    if (typeof value !== 'string') throw new EncodeError('Data Matrix ASCII: value must be a string');
+    raw = asciiCodewords(value);
+  } else if (encoding === 'base256') raw = base256Codewords(value, options.gs1 === true ? 1 : 0);
+  else throw new EncodeError(`Data Matrix: unsupported encoding "${encoding}"`);
+  // GS1 DataMatrix is ECC 200 with FNC1 in the first codeword position.
+  if (options.gs1 === true) raw.unshift(232);
+  const shape = options.shape ?? 'any';
+  if (shape !== 'any' && shape !== 'square' && shape !== 'rectangular') throw new EncodeError(`Data Matrix: invalid shape "${shape}"`);
+  const symbol = symbolForDataCodewords(raw.length, shape);
+  if (!symbol) throw new EncodeError(`Data Matrix: ${raw.length} data codewords do not fit an ECC 200 ${shape} symbol`);
+  return buildMatrix(interleave(pad(raw, symbol.dataCodewords), symbol), symbol);
+}
+
+/** Encode already compacted ASCII/Base256 codewords, primarily for conformance tests. */
+export function encodeDataMatrixCodewords(codewords, options = {}) {
+  if (!Array.isArray(codewords) && !(codewords instanceof Uint8Array)) throw new EncodeError('Data Matrix: codewords must be an array');
+  for (const c of codewords) if (!Number.isInteger(c) || c < 0 || c > 255) throw new EncodeError('Data Matrix: codewords must be bytes');
+  const symbol = symbolForDataCodewords(codewords.length, options.shape ?? 'any');
+  if (!symbol) throw new EncodeError('Data Matrix: codewords do not fit ECC 200');
+  return buildMatrix(interleave(pad(Array.from(codewords), symbol.dataCodewords), symbol), symbol);
+}