@sythos/js_barcode_universal 1.5.13 → 1.5.15

package/src/ts/code16k/decoder.ts

@@ -0,0 +1,313 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ * Copyright (c) 2026 Sythos
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/** Code 16K decoder for sampled, axis-aligned module matrices. @module code16k/decoder */
+
+import { FormatError } from '../core/errors.js';
+import {
+  CODE16K_CODEWORD_WIDTH,
+  CODE16K_MAX_ROWS,
+  CODE16K_MIN_ROWS,
+  CODE16K_PAD,
+  CODE16K_SYMBOLS_PER_ROW,
+  code16kModeInfo,
+  code16kStartModules,
+  code16kStopModules,
+  type Code16KDecodeOptions,
+} from './tables.js';
+import {
+  code128ValueFromModules,
+} from '../stacked128/common.js';
+import type { Code16KMatrix } from './encoder.js';
+
+export type Code16KRow = {
+  row: number;
+  values: number[];
+};
+
+export type Code16KDecodeResult = {
+  format: 'code16k';
+  text: string;
+  rows: number;
+  columns: number;
+  rowHeight: number;
+  separatorHeight: number;
+  mode: number;
+  codewords: number[];
+  checksum: true;
+  symbologyIdentifier: string;
+  gs1?: boolean;
+  fnc1AtStart?: boolean;
+  fnc1Positions?: number[];
+};
+
+function equalAt(source: string, offset: number, expected: string): boolean {
+  return source.slice(offset, offset + expected.length) === expected;
+}
+
+/** Decode one complete 70-module Code 16K row. */
+export function decodeCode16KRow(modules: string, expectedRow: number | undefined = undefined): Code16KRow | null {
+  if (typeof modules !== 'string' || modules.length !== 70) return null;
+  const candidates = expectedRow === undefined
+    ? Array.from({ length: CODE16K_MAX_ROWS }, (_, index) => index)
+    : [expectedRow];
+  for (const row of candidates) {
+    if (!Number.isInteger(row) || row < 0 || row >= CODE16K_MAX_ROWS) continue;
+    if (!equalAt(modules, 0, code16kStartModules(row))) continue;
+    if (modules[7] !== '1') continue;
+    if (!equalAt(modules, 63, code16kStopModules(row))) continue;
+    const values: number[] = [];
+    let valid = true;
+    for (let column = 0; column < CODE16K_SYMBOLS_PER_ROW; column++) {
+      const value = code128ValueFromModules(modules, 8 + column * CODE16K_CODEWORD_WIDTH);
+      if (value === null) {
+        valid = false;
+        break;
+      }
+      values.push(value);
+    }
+    if (valid) return { row, values };
+  }
+  return null;
+}
+
+function separatorIsDark(matrix: Code16KMatrix, y: number): boolean {
+  if (y < 0 || y >= matrix.height) return false;
+  for (let x = 0; x < matrix.width; x++) if (!matrix.get(x, y)) return false;
+  return true;
+}
+
+function readRow(matrix: Code16KMatrix, y: number): Code16KRow | null {
+  if (y < 0 || y >= matrix.height) return null;
+  let modules = '';
+  for (let x = 0; x < matrix.width; x++) modules += matrix.get(x, y) ? '1' : '0';
+  return decodeCode16KRow(modules);
+}
+
+function rowIsConsistent(
+  matrix: Code16KMatrix,
+  y: number,
+  rowHeight: number,
+  expected: Code16KRow,
+): boolean {
+  for (let offset = 0; offset < rowHeight; offset++) {
+    const parsed = readRow(matrix, y + offset);
+    if (!parsed || parsed.row !== expected.row ||
+        parsed.values.some((value, index) => value !== expected.values[index])) return false;
+  }
+  return true;
+}
+
+function code128StartForMode(mode: number): number {
+  if (mode === 0) return 103;
+  if (mode === 1 || mode === 3) return 104;
+  if (mode === 2 || mode === 4) return 105;
+  return -1;
+}
+
+function checksumOne(values: readonly number[]): number {
+  let sum = 0;
+  for (let index = 0; index < values.length; index++) sum += (index + 2) * values[index];
+  return sum % 107;
+}
+
+function checksumTwo(valuesThroughC1: readonly number[]): number {
+  let sum = 0;
+  for (let index = 0; index < valuesThroughC1.length; index++) {
+    sum += (index + 1) * valuesThroughC1[index];
+  }
+  return sum % 107;
+}
+
+function decodeRows(rows: readonly Code16KRow[], rowHeight: number, separatorHeight: number): Code16KDecodeResult {
+  if (rows.length < CODE16K_MIN_ROWS || rows.length > CODE16K_MAX_ROWS) {
+    throw new FormatError('Code 16K: row count must be in 2..16');
+  }
+  const first = rows[0];
+  if (first.row !== 0 || first.values.length !== CODE16K_SYMBOLS_PER_ROW) {
+    throw new FormatError('Code 16K: first row is missing or malformed');
+  }
+  const symbol = first.values[0];
+  if (!Number.isInteger(symbol) || symbol < 0 || symbol > 104) {
+    throw new FormatError('Code 16K: invalid S symbol');
+  }
+  const rowCount = Math.floor(symbol / 7) + 2;
+  const mode = symbol % 7;
+  if (rowCount !== rows.length || rowCount < CODE16K_MIN_ROWS || rowCount > CODE16K_MAX_ROWS) {
+    throw new FormatError('Code 16K: S symbol does not agree with the row count');
+  }
+  if (mode === 5 || mode === 6) {
+    throw new FormatError('Code 16K: shift modes 5 and 6 are not supported by this decoder');
+  }
+  const expectedRows = Array.from({ length: rowCount }, (_, index) => index);
+  for (let index = 0; index < rowCount; index++) {
+    if (rows[index].row !== expectedRows[index] || rows[index].values.length !== CODE16K_SYMBOLS_PER_ROW) {
+      throw new FormatError('Code 16K: rows are missing or out of order');
+    }
+  }
+
+  const codewords = rows.flatMap((entry) => entry.values);
+  if (codewords.length !== rowCount * CODE16K_SYMBOLS_PER_ROW) {
+    throw new FormatError('Code 16K: invalid codeword count');
+  }
+  const c1 = codewords[codewords.length - 2];
+  const c2 = codewords[codewords.length - 1];
+  const beforeChecks = codewords.slice(0, -2);
+  if (checksumOne(beforeChecks) !== c1 || checksumTwo([...beforeChecks, c1]) !== c2) {
+    throw new FormatError('Code 16K: check character mismatch');
+  }
+
+  const data = codewords.slice(1, -2);
+  while (data.length && data[data.length - 1] === CODE16K_PAD) data.pop();
+  if (!data.length) throw new FormatError('Code 16K: data region is empty');
+  const expectedStart = code128StartForMode(mode);
+  if (expectedStart < 0) throw new FormatError('Code 16K: unsupported mode');
+  const info = code16kModeInfo(mode as 0 | 1 | 2 | 3 | 4, mode === 3 || mode === 4);
+  const firstIsFnc1 = data[0] === 102;
+  if (info.gs1 !== firstIsFnc1) {
+    throw new FormatError('Code 16K: mode and leading FNC1 do not agree');
+  }
+
+  // Keep Code 16K aligned with ordinary Code 128 A/B/C decoding while the row
+  // framing and checks remain format-specific.
+  const decoded = decodeCode128ValuesLocal(expectedStart, data);
+  if (!decoded) throw new FormatError('Code 16K: invalid Code 128 data stream');
+  return {
+    format: 'code16k',
+    text: decoded.text,
+    rows: rowCount,
+    columns: CODE16K_SYMBOLS_PER_ROW,
+    rowHeight,
+    separatorHeight,
+    mode,
+    codewords,
+    checksum: true,
+    symbologyIdentifier: info.gs1 ? ']K1' : ']K0',
+    ...(info.gs1 ? { gs1: true } : {}),
+    ...(decoded.fnc1AtStart ? { fnc1AtStart: true } : {}),
+    ...(decoded.fnc1Positions?.length ? { fnc1Positions: decoded.fnc1Positions } : {}),
+  };
+}
+
+/* Keep the decoder self-contained if this module is consumed without the full common declaration graph. */
+function decodeCode128ValuesLocal(
+  startCode: number,
+  dataValues: readonly number[],
+): { text: string; fnc1AtStart?: boolean; fnc1Positions?: number[] } | null {
+  if (![103, 104, 105].includes(startCode) || !dataValues.length) return null;
+  let mode: 'A' | 'B' | 'C' = startCode === 103 ? 'A' : startCode === 104 ? 'B' : 'C';
+  let shifted: 'A' | 'B' | null = null;
+  let text = '';
+  const fnc1AtStart = dataValues[0] === 102;
+  const fnc1Positions: number[] = [];
+  for (let index = 0; index < dataValues.length; index++) {
+    const value = dataValues[index];
+    const active = shifted ?? mode;
+    shifted = null;
+    if (value === 101 && mode !== 'A') { mode = 'A'; continue; }
+    if (value === 100 && mode !== 'B') { mode = 'B'; continue; }
+    if (value === 99) { mode = 'C'; continue; }
+    if (value === 98) { shifted = mode === 'A' ? 'B' : 'A'; continue; }
+    if (value === 102) {
+      if (index > 0) {
+        fnc1Positions.push(text.length);
+        text += '\x1d';
+      }
+      continue;
+    }
+    if (value >= 96 && value <= 102) continue;
+    if (active === 'C') {
+      if (value > 99) return null;
+      text += String(value).padStart(2, '0');
+    } else if (active === 'A') {
+      if (value > 95) return null;
+      text += value < 64 ? String.fromCharCode(value + 32) : String.fromCharCode(value - 64);
+    } else {
+      if (value > 95) return null;
+      text += String.fromCharCode(value + 32);
+    }
+    if (text.length > 100000) return null;
+  }
+  return text.length ? { text, ...(fnc1AtStart ? { fnc1AtStart: true } : {}), fnc1Positions } : null;
+}
+
+function candidateGeometry(matrix: Code16KMatrix, options: Code16KDecodeOptions): Array<{
+  rows: number;
+  rowHeight: number;
+  separatorHeight: number;
+  outer: boolean;
+}> {
+  const metadata = matrix.code16k;
+  const requestedRows = options.rows ?? metadata?.rows;
+  const requestedRowHeight = options.rowHeight ?? metadata?.rowHeight;
+  const requestedSeparatorHeight = options.separatorHeight ?? metadata?.separatorHeight;
+  const candidates: Array<{ rows: number; rowHeight: number; separatorHeight: number; outer: boolean }> = [];
+  for (const outer of [true, false]) {
+    const innerHeight = matrix.height - (outer ? 2 : 0);
+    for (let rows = CODE16K_MIN_ROWS; rows <= CODE16K_MAX_ROWS; rows++) {
+      if (requestedRows !== undefined && rows !== requestedRows) continue;
+      for (let separatorHeight = requestedSeparatorHeight ?? 1; separatorHeight <= (requestedSeparatorHeight ?? 16); separatorHeight++) {
+        if (!Number.isInteger(separatorHeight) || separatorHeight < 1 || separatorHeight > 16) continue;
+        const numerator = innerHeight - (rows - 1) * separatorHeight;
+        if (numerator < rows || numerator % rows !== 0) continue;
+        const rowHeight = numerator / rows;
+        if (rowHeight < 1 || rowHeight > 128) continue;
+        if (requestedRowHeight !== undefined && rowHeight !== requestedRowHeight) continue;
+        candidates.push({ rows, rowHeight, separatorHeight, outer });
+      }
+    }
+  }
+  return candidates;
+}
+
+/**
+ * Decode a complete, axis-aligned Code 16K module matrix.
+ *
+ * The decoder re-checks row geometry, row identifiers, both modulo-107 check
+ * characters and the Code 128 data stream. Metadata attached by the encoder
+ * is used only as a geometry hint and never substitutes for validation.
+ */
+export function decodeCode16K(
+  matrix: Code16KMatrix,
+  options: Code16KDecodeOptions = {},
+): Code16KDecodeResult {
+  if (!matrix?.width || !matrix?.height || typeof matrix.get !== 'function') {
+    throw new FormatError('Code 16K: matrix with width, height and get() is required');
+  }
+  if (matrix.width !== 70) throw new FormatError('Code 16K: matrix width must be 70 modules');
+  for (const geometry of candidateGeometry(matrix, options)) {
+    const first = readRow(matrix, geometry.outer ? 1 : 0);
+    if (!first || first.row !== 0) continue;
+    const encodedRows = Math.floor(first.values[0] / 7) + 2;
+    if (encodedRows !== geometry.rows) continue;
+    const rows: Code16KRow[] = [];
+    let valid = true;
+    for (let row = 0; row < geometry.rows; row++) {
+      const y = (geometry.outer ? 1 : 0) + row * (geometry.rowHeight + geometry.separatorHeight);
+      const parsed = readRow(matrix, y);
+      if (!parsed || parsed.row !== row) { valid = false; break; }
+      if (!rowIsConsistent(matrix, y, geometry.rowHeight, parsed)) { valid = false; break; }
+      rows.push(parsed);
+      if (row < geometry.rows - 1 && !separatorIsDark(matrix, y + geometry.rowHeight)) {
+        valid = false;
+        break;
+      }
+    }
+    if (!valid) continue;
+    if (geometry.outer && (!separatorIsDark(matrix, 0) ||
+        !separatorIsDark(matrix, matrix.height - 1))) continue;
+    try {
+      return decodeRows(rows, geometry.rowHeight, geometry.separatorHeight);
+    } catch {
+      // Try another legal geometry before rejecting the matrix.
+    }
+  }
+  throw new FormatError('Code 16K: no valid row geometry or checksum found');
+}

package/src/ts/code16k/detector.d.ts

@@ -0,0 +1,21 @@
+/*! SPDX-FileCopyrightText: 2026 Sythos (https://www.sythos.net) */
+/*! SPDX-License-Identifier: MIT */
+import type { BitMatrix } from '../core/bit-matrix.js';
+import type { Code16KDecodeResult } from './decoder.js';
+export type Code16KDetectOptions = {
+    rowHeight?: number;
+    separatorHeight?: number;
+    moduleSize?: number;
+};
+export type Code16KPoint = {
+    x: number;
+    y: number;
+};
+export type Code16KDetectedResult = Code16KDecodeResult & {
+    matrix: BitMatrix;
+    corners: Code16KPoint[];
+    rotation: 0 | 90 | 180 | 270;
+    moduleSize: number;
+};
+export declare function detectCode16K(binaryImage: BitMatrix, options?: Code16KDetectOptions): Code16KDetectedResult | null;
+export declare function detectAndDecodeCode16K(binaryImage: BitMatrix, options?: Code16KDetectOptions): Code16KDetectedResult | null;

package/src/ts/code16k/detector.ts

@@ -0,0 +1,203 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ * Copyright (c) 2026 Sythos
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/** Conservative integer-module Code 16K detector. @module code16k/detector */
+
+import { BitMatrix } from '../core/bit-matrix.js';
+import {
+  code128PatternModules,
+  renderStackedRows,
+  sampleModules,
+  scanStackedRows,
+} from '../stacked128/common.js';
+import { code16kStartModules, code16kStopModules } from './tables.js';
+import { decodeCode16K, decodeCode16KRow } from './decoder.js';
+import type { Code16KDecodeResult } from './decoder.js';
+
+export type Code16KDetectOptions = {
+  rowHeight?: number;
+  separatorHeight?: number;
+  moduleSize?: number;
+};
+
+export type Code16KPoint = { x: number; y: number };
+
+export type Code16KDetectedResult = Code16KDecodeResult & {
+  matrix: BitMatrix;
+  corners: Code16KPoint[];
+  rotation: 0 | 90 | 180 | 270;
+  moduleSize: number;
+};
+
+function rowModules(row: number, values: readonly number[]): string {
+  return code16kStartModules(row) + '1' + values.map((value) => code128PatternModules(value)).join('') +
+    code16kStopModules(row);
+}
+
+function rotateClockwise(source: BitMatrix): BitMatrix {
+  const rotated = new BitMatrix(source.height, source.width);
+  for (let y = 0; y < source.height; y++) {
+    for (let x = 0; x < source.width; x++) {
+      if (source.get(x, y)) rotated.set(source.height - 1 - y, x);
+    }
+  }
+  return rotated;
+}
+
+function cornersFor(x: number, y: number, width: number, height: number) {
+  return [
+    { x, y }, { x: x + width, y },
+    { x: x + width, y: y + height }, { x, y: y + height },
+  ];
+}
+
+function rowHasDarkPixels(image: BitMatrix, y: number, x: number, width: number): boolean {
+  if (y < 0 || y >= image.height) return false;
+  for (let offset = 0; offset < width; offset++) if (!image.get(x + offset, y)) return false;
+  return true;
+}
+
+function contiguousSpan(values: readonly number[]): number {
+  if (!values.length) return 0;
+  const sorted = [...new Set(values)].sort((a, b) => a - b);
+  let best = 1;
+  let current = 1;
+  for (let index = 1; index < sorted.length; index++) {
+    if (sorted[index] === sorted[index - 1] + 1) current++;
+    else { best = Math.max(best, current); current = 1; }
+  }
+  return Math.max(best, current);
+}
+
+function parseSample(row: Uint8Array, start: number, moduleSize: number) {
+  const modules = sampleModules(row, start, moduleSize, 70);
+  if (!modules) return null;
+  const parsed = decodeCode16KRow(modules);
+  return parsed ? { ...parsed, modules } : null;
+}
+
+function detectOriented(image: BitMatrix, options: Code16KDetectOptions) {
+  const requestedScale = options.moduleSize;
+  if (requestedScale !== undefined &&
+      (!Number.isInteger(requestedScale) || requestedScale < 1 || requestedScale > 32)) return null;
+  const maxModules = 70 * (requestedScale ?? 32);
+  const found = scanStackedRows(image, 70, parseSample, maxModules)
+    .filter((candidate) => requestedScale === undefined || candidate.moduleSize === requestedScale);
+  const groups = new Map<string, {
+    x: number;
+    moduleSize: number;
+    rows: Map<number, Array<{ y: number; parsed: { row: number; values: number[]; modules: string } }>>;
+  }>();
+  for (const candidate of found) {
+    const key = `${candidate.x}:${candidate.moduleSize}`;
+    let group = groups.get(key);
+    if (!group) {
+      group = { x: candidate.x, moduleSize: candidate.moduleSize, rows: new Map() };
+      groups.set(key, group);
+    }
+    let values = group.rows.get(candidate.parsed.row);
+    if (!values) { values = []; group.rows.set(candidate.parsed.row, values); }
+    values.push({ y: candidate.y, parsed: candidate.parsed });
+  }
+
+  for (const group of groups.values()) {
+    const firstCandidates = group.rows.get(0);
+    if (!firstCandidates?.length) continue;
+    for (const first of firstCandidates) {
+      const encodedRows = Math.floor(first.parsed.values[0] / 7) + 2;
+      if (encodedRows < 2 || encodedRows > 16 || group.rows.size !== encodedRows) continue;
+      const chosen: Array<{ y: number; parsed: { row: number; values: number[]; modules: string } }> = [];
+      let complete = true;
+      for (let row = 0; row < encodedRows; row++) {
+        const entries = group.rows.get(row);
+        if (!entries?.length) { complete = false; break; }
+        const sorted = entries.slice().sort((a, b) => a.y - b.y);
+        chosen.push({ y: sorted[0].y, parsed: sorted[0].parsed });
+      }
+      if (!complete) continue;
+      const scale = group.moduleSize;
+      const spans = chosen.map((entry) => {
+        const entries = group.rows.get(entry.parsed.row) ?? [];
+        return contiguousSpan(entries.map((candidate) => candidate.y));
+      });
+      if (!spans.every((span) => span === spans[0]) || spans[0] < scale || spans[0] % scale !== 0) continue;
+      const rowHeight = spans[0] / scale;
+      const firstY = chosen[0].y;
+      const steps = chosen.slice(1).map((entry, index) => entry.y - chosen[index].y);
+      if (!steps.length || !steps.every((step) => step === steps[0]) || steps[0] % scale !== 0) continue;
+      const separatorHeight = steps[0] / scale - rowHeight;
+      if (separatorHeight < 1 || separatorHeight > 16) continue;
+      if (options.rowHeight !== undefined && rowHeight !== options.rowHeight) continue;
+      if (options.separatorHeight !== undefined && separatorHeight !== options.separatorHeight) continue;
+      const modules = chosen.map((entry) => rowModules(entry.parsed.row, entry.parsed.values));
+      let matrix;
+      try {
+        matrix = renderStackedRows(modules, rowHeight, separatorHeight);
+        const result = decodeCode16K(matrix, { rowHeight, separatorHeight, rows: encodedRows });
+        const topSeparator = rowHasDarkPixels(image, firstY - scale, group.x, 70 * scale) ? scale : 0;
+        const last = chosen[chosen.length - 1];
+        const bottomY = last.y + spans[spans.length - 1];
+        const bottomSeparator = rowHasDarkPixels(image, bottomY, group.x, 70 * scale) ? scale : 0;
+        const boundsY = firstY - topSeparator;
+        const boundsHeight = (bottomY + bottomSeparator) - boundsY;
+        return {
+          ...result,
+          matrix,
+          corners: cornersFor(group.x, boundsY, 70 * scale, boundsHeight),
+          rotation: 0,
+          moduleSize: scale,
+        };
+      } catch {
+        // A candidate is accepted only after all rows and checks decode.
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Detect and decode one Code 16K symbol from a binarized image.
+ *
+ * The detector is intentionally conservative and enumerates integer module
+ * scales and the four orthogonal orientations. Non-integer perspective and
+ * photographic threshold recovery remain the responsibility of the generic
+ * image pipeline.
+ */
+export function detectCode16K(
+  binaryImage: BitMatrix,
+  options: Code16KDetectOptions = {},
+): Code16KDetectedResult | null {
+  if (!binaryImage?.width || !binaryImage?.height || typeof binaryImage.get !== 'function') return null;
+  let oriented = binaryImage;
+  let toOriginal = (point: { x: number; y: number }) => ({ x: point.x, y: point.y });
+  for (let rotation = 0; rotation < 4; rotation++) {
+    const found = detectOriented(oriented, options);
+    if (found) {
+      return {
+        ...found,
+        corners: found.corners.map(toOriginal),
+        rotation: rotation * 90 as 0 | 90 | 180 | 270,
+      };
+    }
+    const previous = oriented;
+    const previousToOriginal = toOriginal;
+    oriented = rotateClockwise(previous);
+    toOriginal = (point) => previousToOriginal({ x: point.y, y: previous.height - point.x });
+  }
+  return null;
+}
+
+/** Alias matching the detector naming used by the other format modules. */
+export function detectAndDecodeCode16K(
+  binaryImage: BitMatrix,
+  options: Code16KDetectOptions = {},
+): Code16KDetectedResult | null {
+  return detectCode16K(binaryImage, options);
+}

package/src/ts/code16k/encoder.d.ts

@@ -0,0 +1,26 @@
+/*! SPDX-FileCopyrightText: 2026 Sythos (https://www.sythos.net) */
+/*! SPDX-License-Identifier: MIT */
+import { BitMatrix } from '../core/bit-matrix.js';
+import type { Code16KEncodeOptions } from './tables.js';
+export type Code16KMetadata = {
+    format: 'code16k';
+    rows: number;
+    columns: number;
+    rowHeight: number;
+    separatorHeight: number;
+    mode: number;
+    codewords: number[];
+    checksum: true;
+};
+export type Code16KMatrix = BitMatrix & {
+    code16k?: Code16KMetadata;
+};
+export declare function encodeCode16K(value: string | Uint8Array | readonly number[], options?: Code16KEncodeOptions): Code16KMatrix;
+export declare function code16kDimensions(value: string | Uint8Array | readonly number[], options?: Code16KEncodeOptions): {
+    rows: number;
+    columns: number;
+    width: number;
+    height: number;
+    rowHeight: number;
+    separatorHeight: number;
+};