@sythos/js_barcode_universal 0.1.0

package/src/qr/decoder.js

@@ -0,0 +1,575 @@
+/*!
+ * 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.
+ */
+
+/**
+ * QR Code decoder.
+ *
+ * Input is a square {@link BitMatrix} that is exactly the symbol — one bit per
+ * module, no quiet zone. Locating and resampling a symbol out of a photograph
+ * is the detector's job; this module assumes that has already happened, which
+ * keeps the two independently testable.
+ *
+ * Both BCH-protected fields — format information and version information — are
+ * recovered by nearest-neighbour lookup over the full set of legal codewords
+ * rather than by running a syndrome decoder. There are only 32 and 34 of them
+ * respectively, the minimum distance is known, and a Hamming search is both
+ * shorter and easier to be sure of than a second BCH implementation.
+ *
+ * @module qr/decoder
+ */
+
+import { BitReader } from '../core/bit-buffer.js';
+import { ChecksumError, FormatError } from '../core/errors.js';
+import { GF256_QR } from '../core/galois-field.js';
+import { rsDecode } from '../core/reed-solomon.js';
+import {
+  ECC_LEVELS,
+  MAX_VERSION,
+  MIN_VERSION,
+  MODE,
+  VERSION_INFO_MIN,
+  blockLayout,
+  countBits,
+  dataModuleOrder,
+  formatInfoPositions,
+  maskBit,
+  versionSize,
+} from './tables.js';
+import { ALPHANUMERIC_CHARS, formatInfoBits, versionInfoBits } from './encoder.js';
+
+/**
+ * Maximum bit errors tolerated when matching a BCH field.
+ *
+ * Both codes have minimum distance 7 in principle, but the format information
+ * is only guaranteed distance 7 across the whole set once masking is applied;
+ * accepting three errors is the conventional, safe limit, and a wrong match
+ * would be caught downstream by Reed-Solomon anyway.
+ */
+const BCH_MAX_DISTANCE = 3;
+
+/** Every legal masked format value, with what it means. */
+const FORMAT_CODES = (() => {
+  const codes = [];
+  for (let l = 0; l < ECC_LEVELS.length; l++) {
+    for (let mask = 0; mask < 8; mask++) {
+      codes.push({ bits: formatInfoBits(ECC_LEVELS[l], mask), ecc: ECC_LEVELS[l], mask });
+    }
+  }
+  return codes;
+})();
+
+/** Every legal version information value. */
+const VERSION_CODES = (() => {
+  const codes = [];
+  for (let v = VERSION_INFO_MIN; v <= MAX_VERSION; v++) {
+    codes.push({ bits: versionInfoBits(v), version: v });
+  }
+  return codes;
+})();
+
+/**
+ * @param {number} a @param {number} b
+ * @returns {number} Number of differing bits.
+ */
+function hammingDistance(a, b) {
+  let v = a ^ b;
+  let n = 0;
+  while (v !== 0) {
+    v &= v - 1;
+    n++;
+  }
+  return n;
+}
+
+/**
+ * Nearest legal codeword, or null when nothing is close enough.
+ *
+ * @template T
+ * @param {number} value
+ * @param {Array<T & {bits: number}>} codes
+ * @returns {(T & {distance: number}) | null}
+ */
+function nearestCode(value, codes) {
+  let best = null;
+  let bestDistance = BCH_MAX_DISTANCE + 1;
+  let ambiguous = false;
+
+  for (let i = 0; i < codes.length; i++) {
+    const d = hammingDistance(value, codes[i].bits);
+    if (d < bestDistance) {
+      bestDistance = d;
+      best = codes[i];
+      ambiguous = false;
+    } else if (d === bestDistance) {
+      ambiguous = true;
+    }
+  }
+
+  if (!best || bestDistance > BCH_MAX_DISTANCE || ambiguous) return null;
+  return Object.assign({ distance: bestDistance }, best);
+}
+
+/**
+ * Read a run of module positions as a little-endian bit value.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} m
+ * @param {Array<[number, number]>} positions Index i holds bit i.
+ * @returns {number}
+ */
+function readBits(m, positions) {
+  let value = 0;
+  for (let i = 0; i < positions.length; i++) {
+    if (m.get(positions[i][0], positions[i][1])) value |= 1 << i;
+  }
+  return value;
+}
+
+/**
+ * Recover the error correction level and mask.
+ *
+ * Both copies are tried and the cleaner one wins, so a symbol with one corner
+ * damaged still reads.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} m
+ * @param {number} size
+ * @returns {{ecc: string, mask: number}}
+ */
+function readFormatInfo(m, size) {
+  const [a, b] = formatInfoPositions(size);
+  const candidates = [nearestCode(readBits(m, a), FORMAT_CODES), nearestCode(readBits(m, b), FORMAT_CODES)];
+
+  let best = null;
+  for (let i = 0; i < candidates.length; i++) {
+    const c = candidates[i];
+    if (c && (!best || c.distance < best.distance)) best = c;
+  }
+  if (!best) {
+    throw new FormatError('QR: format information is unreadable in both copies');
+  }
+  return { ecc: best.ecc, mask: best.mask };
+}
+
+/**
+ * Cross-check the version information against the symbol's dimension.
+ *
+ * The dimension already determines the version, so this is redundancy rather
+ * than information — which is exactly why it is worth reading: a disagreement
+ * means the matrix handed to us is not the symbol we think it is.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} m
+ * @param {number} size @param {number} fromDimension
+ * @returns {number}
+ */
+function readVersionInfo(m, size, fromDimension) {
+  if (fromDimension < VERSION_INFO_MIN) return fromDimension;
+
+  /** @type {Array<[number, number]>} */
+  const bottomLeft = [];
+  /** @type {Array<[number, number]>} */
+  const topRight = [];
+  for (let i = 0; i < 18; i++) {
+    const major = Math.floor(i / 3);
+    const minor = i % 3;
+    bottomLeft.push([major, size - 11 + minor]);
+    topRight.push([size - 11 + minor, major]);
+  }
+
+  const candidates = [
+    nearestCode(readBits(m, bottomLeft), VERSION_CODES),
+    nearestCode(readBits(m, topRight), VERSION_CODES),
+  ];
+
+  let best = null;
+  for (let i = 0; i < candidates.length; i++) {
+    const c = candidates[i];
+    if (c && (!best || c.distance < best.distance)) best = c;
+  }
+
+  // Unreadable version information is survivable; contradictory version
+  // information is not.
+  if (!best) return fromDimension;
+  if (best.version !== fromDimension) {
+    throw new FormatError(
+      `QR: version information says ${best.version} but the symbol is ` +
+      `${size}x${size} modules (version ${fromDimension})`
+    );
+  }
+  return best.version;
+}
+
+/**
+ * Unmask and read the interleaved codewords out of the module grid.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} m
+ * @param {number} version @param {number} mask @param {number} totalCodewords
+ * @returns {Uint8Array}
+ */
+function readCodewords(m, version, mask, totalCodewords) {
+  const order = dataModuleOrder(version);
+  const out = new Uint8Array(totalCodewords);
+  const available = totalCodewords * 8;
+
+  for (let p = 0, bit = 0; p < order.length && bit < available; p += 2, bit++) {
+    const x = order[p];
+    const y = order[p + 1];
+    let dark = m.get(x, y);
+    if (maskBit(mask, x, y)) dark = !dark;
+    if (dark) out[bit >> 3] |= 0x80 >> (bit & 7);
+  }
+
+  return out;
+}
+
+/**
+ * Undo the block interleaving and repair each block.
+ *
+ * @param {Uint8Array} codewords
+ * @param {import('./tables.js').BlockLayout} layout
+ * @returns {{data: Uint8Array, corrections: number}}
+ */
+function deinterleaveAndCorrect(codewords, layout) {
+  const counts = new Array(layout.blockCount);
+  for (let b = 0; b < layout.blockCount; b++) {
+    counts[b] = b < layout.group1Blocks ? layout.group1DataCount : layout.group2DataCount;
+  }
+
+  const blocks = [];
+  for (let b = 0; b < layout.blockCount; b++) {
+    blocks.push(new Array(counts[b] + layout.eccPerBlock).fill(0));
+  }
+
+  let n = 0;
+  const maxData = layout.group2Blocks > 0 ? layout.group2DataCount : layout.group1DataCount;
+  for (let i = 0; i < maxData; i++) {
+    for (let b = 0; b < layout.blockCount; b++) {
+      if (i < counts[b]) blocks[b][i] = codewords[n++];
+    }
+  }
+  for (let i = 0; i < layout.eccPerBlock; i++) {
+    for (let b = 0; b < layout.blockCount; b++) {
+      blocks[b][counts[b] + i] = codewords[n++];
+    }
+  }
+
+  const data = new Uint8Array(layout.totalDataCodewords);
+  let offset = 0;
+  let corrections = 0;
+
+  for (let b = 0; b < layout.blockCount; b++) {
+    corrections += rsDecode(blocks[b], layout.eccPerBlock, GF256_QR, 0);
+    for (let i = 0; i < counts[b]; i++) data[offset + i] = blocks[b][i];
+    offset += counts[b];
+  }
+
+  return { data, corrections };
+}
+
+/* ------------------------------------------------------------------ *
+ * Bitstream interpretation
+ * ------------------------------------------------------------------ */
+
+/**
+ * Unpack a 13-bit kanji value back to Shift_JIS. Inverse of the encoder's
+ * `sjisToThirteenBits`; the round-trip is asserted by the test suite.
+ *
+ * @param {number} value
+ * @returns {number} 16-bit Shift_JIS value.
+ */
+function thirteenBitsToSjis(value) {
+  const combined = (Math.floor(value / 0xc0) << 8) | (value % 0xc0);
+  return combined + (combined + 0x8140 <= 0x9ffc ? 0x8140 : 0xc140);
+}
+
+/** ECI assignment numbers this decoder maps to a concrete codec label. */
+const ECI_LABELS = {
+  0: 'iso-8859-1',
+  1: 'iso-8859-1',
+  2: 'iso-8859-1',
+  3: 'iso-8859-1',
+  4: 'iso-8859-2',
+  5: 'iso-8859-3',
+  6: 'iso-8859-4',
+  7: 'iso-8859-5',
+  8: 'iso-8859-6',
+  9: 'iso-8859-7',
+  10: 'iso-8859-8',
+  11: 'iso-8859-9',
+  12: 'iso-8859-10',
+  13: 'iso-8859-11',
+  15: 'iso-8859-13',
+  16: 'iso-8859-14',
+  17: 'iso-8859-15',
+  18: 'iso-8859-16',
+  20: 'shift_jis',
+  21: 'windows-1250',
+  22: 'windows-1251',
+  23: 'windows-1252',
+  24: 'windows-1256',
+  25: 'utf-16be',
+  26: 'utf-8',
+  27: 'us-ascii',
+  28: 'big5',
+  29: 'gb18030',
+  30: 'euc-kr',
+  170: 'us-ascii',
+};
+
+/**
+ * Turn a byte segment into text.
+ *
+ * With no ECI in force the interpretation is genuinely ambiguous — the default
+ * is ISO-8859-1, but the overwhelming majority of real symbols carry UTF-8
+ * without announcing it. So: accept UTF-8 when the bytes are valid UTF-8, and
+ * fall back to ISO-8859-1 when they are not. Bytes that are valid under both
+ * readings cannot be told apart by anyone, encoder included.
+ *
+ * @param {Uint8Array} bytes @param {number | null} eci
+ * @returns {string}
+ */
+function decodeBytes(bytes, eci) {
+  if (eci !== null && eci !== undefined) {
+    const label = ECI_LABELS[eci];
+    if (label) {
+      try {
+        return new TextDecoder(label).decode(bytes);
+      } catch (e) {
+        /* Unsupported label on this platform; fall through. */
+      }
+    }
+  } else {
+    try {
+      return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    } catch (e) {
+      /* Not valid UTF-8; it is Latin-1. */
+    }
+  }
+  return latin1(bytes);
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+function latin1(bytes) {
+  let s = '';
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
+  return s;
+}
+
+/**
+ * @param {Uint8Array} bytes Shift_JIS double bytes.
+ * @returns {string}
+ */
+function decodeKanji(bytes) {
+  try {
+    const decoder = new TextDecoder('shift_jis');
+    const text = decoder.decode(bytes);
+    if (text.indexOf('�') === -1) return text;
+  } catch (e) {
+    /* No Shift_JIS codec on this platform. */
+  }
+  // Graceful degradation: the payload is structurally intact but we cannot
+  // name the characters, so mark them rather than failing the whole symbol.
+  let s = '';
+  for (let i = 0; i < bytes.length; i += 2) s += '�';
+  return s;
+}
+
+/**
+ * Read the ECI designator, which is 1, 2 or 3 bytes depending on its leading
+ * bits.
+ *
+ * @param {BitReader} reader
+ * @returns {number}
+ */
+function readEciDesignator(reader) {
+  const first = reader.read(8);
+  if ((first & 0x80) === 0) return first;
+  if ((first & 0xc0) === 0x80) return ((first & 0x3f) << 8) | reader.read(8);
+  if ((first & 0xe0) === 0xc0) return ((first & 0x1f) << 16) | reader.read(16);
+  throw new FormatError(`QR: malformed ECI designator (first byte 0x${first.toString(16)})`);
+}
+
+/**
+ * Walk the mode segments and rebuild the payload.
+ *
+ * @param {Uint8Array} data Corrected data codewords.
+ * @param {number} version
+ * @returns {{text: string, bytes: Uint8Array}}
+ */
+function parseSegments(data, version) {
+  const reader = new BitReader(data);
+  let text = '';
+  /** @type {number[]} */
+  const rawBytes = [];
+  /** @type {number | null} */
+  let eci = null;
+
+  // A symbol whose payload ends exactly on a codeword boundary has no room for
+  // a terminator, so running out of bits is a normal end, not an error.
+  while (reader.available() >= 4) {
+    const mode = reader.read(4);
+    if (mode === MODE.TERMINATOR) break;
+
+    if (mode === MODE.ECI) {
+      eci = readEciDesignator(reader);
+      continue;
+    }
+
+    if (mode === MODE.FNC1_FIRST) continue;
+    if (mode === MODE.FNC1_SECOND) {
+      reader.read(8); // application indicator
+      continue;
+    }
+    if (mode === MODE.STRUCTURED_APPEND) {
+      reader.read(16); // sequence position, total, parity
+      continue;
+    }
+
+    const width = countBits(mode, version);
+    if (width === 0) {
+      throw new FormatError(`QR: unsupported mode indicator 0x${mode.toString(16)}`);
+    }
+    const count = reader.read(width);
+
+    switch (mode) {
+      case MODE.NUMERIC: {
+        let i = 0;
+        while (i + 3 <= count) {
+          const triple = reader.read(10);
+          if (triple > 999) throw new FormatError(`QR: numeric triple ${triple} out of range`);
+          text += String(triple).padStart(3, '0');
+          i += 3;
+        }
+        if (count - i === 2) {
+          const pair = reader.read(7);
+          if (pair > 99) throw new FormatError(`QR: numeric pair ${pair} out of range`);
+          text += String(pair).padStart(2, '0');
+        } else if (count - i === 1) {
+          const single = reader.read(4);
+          if (single > 9) throw new FormatError(`QR: numeric digit ${single} out of range`);
+          text += String(single);
+        }
+        break;
+      }
+
+      case MODE.ALPHANUMERIC: {
+        let i = 0;
+        while (i + 2 <= count) {
+          const pair = reader.read(11);
+          if (pair >= 45 * 45) throw new FormatError(`QR: alphanumeric pair ${pair} out of range`);
+          text += ALPHANUMERIC_CHARS[Math.floor(pair / 45)] + ALPHANUMERIC_CHARS[pair % 45];
+          i += 2;
+        }
+        if (i < count) {
+          const single = reader.read(6);
+          if (single >= 45) throw new FormatError(`QR: alphanumeric value ${single} out of range`);
+          text += ALPHANUMERIC_CHARS[single];
+        }
+        break;
+      }
+
+      case MODE.BYTE: {
+        const bytes = new Uint8Array(count);
+        for (let i = 0; i < count; i++) {
+          bytes[i] = reader.read(8);
+          rawBytes.push(bytes[i]);
+        }
+        text += decodeBytes(bytes, eci);
+        break;
+      }
+
+      case MODE.KANJI: {
+        const bytes = new Uint8Array(count * 2);
+        for (let i = 0; i < count; i++) {
+          const sjis = thirteenBitsToSjis(reader.read(13));
+          bytes[i * 2] = sjis >> 8;
+          bytes[i * 2 + 1] = sjis & 0xff;
+        }
+        text += decodeKanji(bytes);
+        break;
+      }
+
+      default:
+        throw new FormatError(`QR: unsupported mode indicator 0x${mode.toString(16)}`);
+    }
+  }
+
+  return { text, bytes: Uint8Array.from(rawBytes) };
+}
+
+/**
+ * @typedef {object} DecodeResult
+ * @property {string} text Decoded payload.
+ * @property {Uint8Array} bytes Raw bytes of the byte-mode segments; empty when
+ *   the payload used no byte segments.
+ * @property {number} version 1-40.
+ * @property {string} ecc 'L' | 'M' | 'Q' | 'H'.
+ * @property {number} mask 0-7.
+ * @property {number} corrections Symbols repaired by Reed-Solomon.
+ */
+
+/**
+ * Decode a sampled QR Code symbol.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} matrix Square, exactly the
+ *   symbol, no quiet zone. Set bit = dark module.
+ * @returns {DecodeResult}
+ * @throws {FormatError} If the geometry or content is malformed.
+ * @throws {ChecksumError} If error correction cannot repair the symbol.
+ */
+export function decodeQR(matrix) {
+  if (!matrix || !matrix.width) throw new FormatError('QR: no matrix supplied');
+
+  const size = matrix.width;
+  if (matrix.height !== size) {
+    throw new FormatError(`QR: symbol must be square, got ${size}x${matrix.height}`);
+  }
+  if ((size - 17) % 4 !== 0) {
+    throw new FormatError(`QR: ${size} modules is not a valid symbol size`);
+  }
+
+  const dimensionVersion = (size - 17) / 4;
+  if (dimensionVersion < MIN_VERSION || dimensionVersion > MAX_VERSION) {
+    throw new FormatError(`QR: ${size} modules implies version ${dimensionVersion}`);
+  }
+
+  const { ecc, mask } = readFormatInfo(matrix, size);
+  const version = readVersionInfo(matrix, size, dimensionVersion);
+
+  const layout = blockLayout(version, ecc);
+  const codewords = readCodewords(matrix, version, mask, layout.totalCodewords);
+  const { data, corrections } = deinterleaveAndCorrect(codewords, layout);
+  const { text, bytes } = parseSegments(data, version);
+
+  return { text, bytes, version, ecc, mask, corrections };
+}
+
+export { ChecksumError };