@sythos/js_barcode_universal 0.1.0 → 1.0.0

package/licenses/README.md

@@ -11,6 +11,7 @@ appendix carries the consolidated inventory these files expand on.
 | Format | File | `[TO VERIFY]` items |
 |---|---|---:|
 | QR Code | [`qr-code.license`](qr-code.license) | 5 |
+| Data Matrix ECC 200 | [`data-matrix.license`](data-matrix.license) | 9 |
 | EAN-13 | [`ean-13.license`](ean-13.license) | 5 |
 | EAN-8 | [`ean-8.license`](ean-8.license) | 5 |
 | UPC-A | [`upc-a.license`](upc-a.license) | 6 |

package/licenses/data-matrix.license

@@ -0,0 +1,82 @@
+Data Matrix ECC 200 — format provenance and usability
+==========================================================================
+
+This file records where the Data Matrix ECC 200 symbology comes from, what governs
+it, and the basis on which this project implements and redistributes it.
+
+It is an ENGINEERING INVENTORY, NOT LEGAL ADVICE. Items marked [TO VERIFY]
+have not been independently confirmed by the author.
+
+
+ORIGIN
+--------------------------------------------------------------------------
+
+Data Matrix emerged from industrial automatic-identification work
+associated with International Data Matrix and later RVSI/CI Matrix in the
+late 1980s and early 1990s. The exact corporate chronology and attribution
+have not been independently confirmed by the author. [TO VERIFY]
+
+
+SPECIFICATION
+--------------------------------------------------------------------------
+
+ISO/IEC 16022:2024 — Data Matrix bar code symbology specification.
+Published by ISO/IEC. The specification TEXT is copyrighted by its
+publisher and is paywalled; it is not reproduced here.
+GS1 General Specifications and the GS1 DataMatrix Guideline govern use
+of ECC 200 with a leading FNC1 and GS1 Application Identifiers.
+
+Specification TEXT is copyrighted by its publisher. The SYMBOLOGY it
+describes is not — an encoding scheme is a system, not a work of
+authorship. This project implements the symbology; it does not reproduce,
+redistribute or excerpt any specification document.
+
+
+PATENT STATUS
+--------------------------------------------------------------------------
+
+Patent rights associated with ECC 200 have been reported as released for
+public use by an earlier rights holder, but the original patents, chain of
+title and release terms have not been independently confirmed by the
+author. [TO VERIFY]
+
+
+TRADEMARK
+--------------------------------------------------------------------------
+
+The current registration status and ownership of the words "Data Matrix"
+have not been independently established. [TO VERIFY] "GS1" and "GS1
+DataMatrix" are GS1 designations; their use is descriptive here and does
+not imply endorsement. [TO VERIFY]
+
+A trademark does not restrict implementing a symbology. It restricts
+branding — how a product names and presents itself.
+
+
+IMPLEMENTATION BASIS IN THIS PROJECT
+--------------------------------------------------------------------------
+
+Data Matrix ECC 200 is implemented here from published descriptions of the format,
+which are systems and facts rather than works of authorship. No source
+code and no constant table from any other barcode implementation was used,
+consulted or copied, under any licence.
+
+
+CONCLUSION
+--------------------------------------------------------------------------
+
+This project's original implementation is distributed under the MIT
+License. The ISO/IEC and GS1 references establish the technical standards;
+this engineering inventory does not claim to have resolved the
+patent-release or trademark entries that remain marked [TO VERIFY].
+
+References relied upon:
+  - ISO/IEC 16022:2024, ISO/IEC
+  - GS1 General Specifications, GS1 AISBL
+  - GS1 DataMatrix Guideline, GS1 AISBL
+  - Reported ECC 200 patent-release position [TO VERIFY]
+  - Data Matrix trademark status and ownership [TO VERIFY]
+
+This is an engineering assessment, not legal advice. Items marked
+[TO VERIFY] have not been independently confirmed by the author. If your
+use is commercially sensitive, obtain your own legal review.

package/package.json

@@ -1,89 +1,92 @@
-{
-  "name": "@sythos/js_barcode_universal",
-  "version": "0.1.0",
-  "description": "Read and write barcodes in JavaScript. 100% original code, zero runtime dependencies. QR Code, EAN/UPC, ISBN, Code 128, Code 39, Code 93, ITF, Codabar, MSI, Code 11 and Pharmacode.",
-  "author": "Sythos",
-  "license": "MIT",
-  "type": "module",
-  "main": "./src/index.js",
-  "module": "./src/index.js",
-  "browser": "./bundle/sythos-barcode.js",
-  "unpkg": "./bundle/sythos-barcode.js",
-  "jsdelivr": "./bundle/sythos-barcode.js",
-  "sideEffects": false,
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "exports": {
-    ".": "./src/index.js",
-    "./core": "./src/core/index.js",
-    "./image": "./src/image/index.js",
-    "./oned": "./src/oned/index.js",
+{
+  "name": "@sythos/js_barcode_universal",
+  "version": "1.0.0",
+  "description": "Read and write barcodes in JavaScript. 100% original code, zero runtime dependencies. Data Matrix ECC 200, QR Code, EAN/UPC, ISBN, Code 128, Code 39, Code 93, ITF, Codabar, MSI, Code 11 and Pharmacode.",
+  "author": "Sythos",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "browser": "./bundle/sythos-barcode.js",
+  "unpkg": "./bundle/sythos-barcode.js",
+  "jsdelivr": "./bundle/sythos-barcode.js",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./core": "./src/core/index.js",
+    "./image": "./src/image/index.js",
+    "./oned": "./src/oned/index.js",
     "./qr": "./src/qr/index.js",
-    "./render": "./src/render/index.js",
-    "./render/svg": "./src/render/svg.js",
-    "./render/png": "./src/render/png.js",
-    "./render/image-data": "./src/render/image-data.js",
-    "./bundle": "./bundle/sythos-barcode.esm.js",
-    "./bundle/iife": "./bundle/sythos-barcode.js",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "src",
-    "bundle",
-    "examples",
-    "licenses",
-    "LICENSE",
-    "NOTICE.md",
-    "README.md"
-  ],
-  "keywords": [
+    "./datamatrix": "./src/datamatrix/index.js",
+    "./render": "./src/render/index.js",
+    "./render/svg": "./src/render/svg.js",
+    "./render/png": "./src/render/png.js",
+    "./render/image-data": "./src/render/image-data.js",
+    "./bundle": "./bundle/sythos-barcode.esm.js",
+    "./bundle/iife": "./bundle/sythos-barcode.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "bundle",
+    "examples",
+    "licenses",
+    "LICENSE",
+    "NOTICE.md",
+    "README.md"
+  ],
+  "keywords": [
     "barcode",
-    "barcode-generator",
-    "barcode-scanner",
-    "qrcode",
-    "qr",
-    "qr-code",
-    "ean",
-    "ean13",
-    "ean8",
-    "upc",
-    "upca",
-    "upce",
-    "isbn",
-    "code128",
-    "gs1-128",
-    "code39",
-    "code93",
-    "itf",
-    "itf14",
-    "codabar",
-    "msi",
-    "code11",
-    "pharmacode",
-    "scanner",
-    "decoder",
-    "encoder",
-    "generator",
-    "reader",
-    "writer",
-    "zero-dependencies",
-    "no-dependencies",
-    "browser",
-    "nodejs",
-    "esm"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Sythos/JS_Barcode_Universal.git"
-  },
-  "bugs": {
-    "url": "https://github.com/Sythos/JS_Barcode_Universal/issues"
-  },
-  "homepage": "https://github.com/Sythos/JS_Barcode_Universal#readme",
-  "dependencies": {},
-  "devDependencies": {}
-}
+    "datamatrix",
+    "ecc200",
+    "barcode-generator",
+    "barcode-scanner",
+    "qrcode",
+    "qr",
+    "qr-code",
+    "ean",
+    "ean13",
+    "ean8",
+    "upc",
+    "upca",
+    "upce",
+    "isbn",
+    "code128",
+    "gs1-128",
+    "code39",
+    "code93",
+    "itf",
+    "itf14",
+    "codabar",
+    "msi",
+    "code11",
+    "pharmacode",
+    "scanner",
+    "decoder",
+    "encoder",
+    "generator",
+    "reader",
+    "writer",
+    "zero-dependencies",
+    "no-dependencies",
+    "browser",
+    "nodejs",
+    "esm"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sythos/JS_Barcode_Universal.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Sythos/JS_Barcode_Universal/issues"
+  },
+  "homepage": "https://github.com/Sythos/JS_Barcode_Universal#readme",
+  "dependencies": {},
+  "devDependencies": {}
+}

package/src/core/reed-solomon.js

@@ -56,7 +56,7 @@ import { ChecksumError } from './errors.js';
  *
  *   g(x) = product over i of (x - a^(base + i)),  i = 0 .. eccLen-1
  *
- * `base` is 0 for QR, Data Matrix and Aztec; 1 for PDF417.
+ * `base` is 0 for QR and Aztec; 1 for Data Matrix and PDF417.
  *
  * @param {number} eccLen
  * @param {import('./galois-field.js').GaloisField} field

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 };