@sythos/js_barcode_universal 1.5.8 → 1.5.9

package/src/ts/datamatrix/detector.ts

@@ -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/ts/datamatrix/encoder.ts

@@ -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);
+}

package/src/ts/datamatrix/index.ts

@@ -0,0 +1,42 @@
+/*!
+ * 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 entry points. @module datamatrix */
+
+export { encodeDataMatrix, encodeDataMatrixCodewords } from './encoder.js';
+export { decodeDataMatrix } from './decoder.js';
+export { detectDataMatrix, detectAndDecodeDataMatrix } from './detector.js';
+export {
+  DATAMATRIX_SYMBOLS,
+  SYMBOLS,
+  symbolForDataCodewords,
+  validateDataMatrixTables,
+  validateTables,
+} from './tables.js';

package/src/ts/datamatrix/tables.ts

@@ -0,0 +1,123 @@
+/*!
+ * 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 symbol parameters.
+ *
+ * Width and height include finder borders. `regionWidth` and `regionHeight`
+ * describe the usable modules inside one data region. The last three columns
+ * make the Reed-Solomon block split explicit instead of hiding the 144x144
+ * exception in encoder control flow.
+ *
+ * @module datamatrix/tables
+ */
+
+function symbol(width, height, dataRegionWidth, dataRegionHeight, dataCodewords, errorCodewords, dataBlockLengths) {
+  const blockCount = dataBlockLengths.length;
+  return Object.freeze({
+    width, height, rows: height, columns: width,
+    // Region dimensions include their one-module finder border on each side;
+    // dataRegion* expose the inner placement lattice explicitly.
+    regionWidth: dataRegionWidth + 2, regionHeight: dataRegionHeight + 2,
+    dataRegionWidth, dataRegionHeight,
+    dataRegionRows: dataRegionHeight, dataRegionColumns: dataRegionWidth,
+    dataCodewords, errorCodewords, blockCount,
+    eccPerBlock: errorCodewords / blockCount,
+    dataBlockLengths: Object.freeze(dataBlockLengths),
+  });
+}
+
+/** Classic ISO/IEC 16022 ECC 200 symbols; DMRE is deliberately excluded. */
+export const DATAMATRIX_SYMBOLS = Object.freeze([
+  symbol(10, 10, 8, 8, 3, 5, [3]),
+  symbol(12, 12, 10, 10, 5, 7, [5]),
+  symbol(14, 14, 12, 12, 8, 10, [8]),
+  symbol(16, 16, 14, 14, 12, 12, [12]),
+  symbol(18, 18, 16, 16, 18, 14, [18]),
+  symbol(20, 20, 18, 18, 22, 18, [22]),
+  symbol(22, 22, 20, 20, 30, 20, [30]),
+  symbol(24, 24, 22, 22, 36, 24, [36]),
+  symbol(26, 26, 24, 24, 44, 28, [44]),
+  symbol(32, 32, 14, 14, 62, 36, [62]),
+  symbol(36, 36, 16, 16, 86, 42, [86]),
+  symbol(40, 40, 18, 18, 114, 48, [114]),
+  symbol(44, 44, 20, 20, 144, 56, [144]),
+  symbol(48, 48, 22, 22, 174, 68, [174]),
+  symbol(52, 52, 24, 24, 204, 84, [102, 102]),
+  symbol(64, 64, 14, 14, 280, 112, [140, 140]),
+  symbol(72, 72, 16, 16, 368, 144, [92, 92, 92, 92]),
+  symbol(80, 80, 18, 18, 456, 192, [114, 114, 114, 114]),
+  symbol(88, 88, 20, 20, 576, 224, [144, 144, 144, 144]),
+  symbol(96, 96, 22, 22, 696, 272, [174, 174, 174, 174]),
+  symbol(104, 104, 24, 24, 816, 336, [136, 136, 136, 136, 136, 136]),
+  symbol(120, 120, 18, 18, 1050, 408, [175, 175, 175, 175, 175, 175]),
+  symbol(132, 132, 20, 20, 1304, 496, [163, 163, 163, 163, 163, 163, 163, 163]),
+  symbol(144, 144, 22, 22, 1558, 620, [156, 156, 156, 156, 156, 156, 156, 156, 155, 155]),
+  symbol(18, 8, 16, 6, 5, 7, [5]),
+  symbol(32, 8, 14, 6, 10, 11, [10]),
+  symbol(26, 12, 24, 10, 16, 14, [16]),
+  symbol(36, 12, 16, 10, 22, 18, [22]),
+  symbol(36, 16, 16, 14, 32, 24, [32]),
+  symbol(48, 16, 22, 14, 49, 28, [49]),
+]);
+
+/** Compatibility alias. */
+export const SYMBOLS = DATAMATRIX_SYMBOLS;
+
+/** Return the smallest permitted symbol that holds `count` data codewords. */
+export function symbolForDataCodewords(count, shape = 'any') {
+  for (const s of DATAMATRIX_SYMBOLS) {
+    const rectangular = s.width !== s.height;
+    if ((shape === 'square' && rectangular) || (shape === 'rectangular' && !rectangular)) continue;
+    if (count <= s.dataCodewords) return s;
+  }
+  throw new RangeError(`Data Matrix: ${count} data codewords do not fit an ECC 200 ${shape} symbol`);
+}
+
+/** Check redundant geometry and block identities in the static table. */
+export function validateDataMatrixTables() {
+  const issues = [];
+  for (const s of DATAMATRIX_SYMBOLS) {
+    const regionsX = s.width / s.regionWidth;
+    const regionsY = s.height / s.regionHeight;
+    if (!Number.isInteger(regionsX) || !Number.isInteger(regionsY)) issues.push(`${s.width}x${s.height}: non-integral regions`);
+    const modules = regionsX * regionsY * s.dataRegionWidth * s.dataRegionHeight;
+    // Annex F reserves four terminal modules on a few lattice dimensions.
+    // They are set to dark after codeword placement and do not carry data.
+    const unused = modules - (s.dataCodewords + s.errorCodewords) * 8;
+    if (unused !== 0 && unused !== 4) issues.push(`${s.width}x${s.height}: geometry/codeword mismatch`);
+    if (s.dataBlockLengths.reduce((a, b) => a + b, 0) !== s.dataCodewords) issues.push(`${s.width}x${s.height}: data block mismatch`);
+    if (s.eccPerBlock * s.blockCount !== s.errorCodewords) issues.push(`${s.width}x${s.height}: ecc block mismatch`);
+  }
+  return issues;
+}
+
+/** Compatibility alias. */
+export const validateTables = validateDataMatrixTables;