@sythos/js_barcode_universal 1.5.8 → 1.5.9

package/src/ts/micropdf417/compaction.ts

@@ -0,0 +1,116 @@
+/*!
+ * 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.
+ */
+
+/** MicroPDF417 high-level compaction adapter. @module micropdf417/compaction */
+
+import { EncodeError } from '../core/errors.js';
+import {
+  compactPdf417Bytes,
+  compactPdf417Numeric,
+  compactPdf417Text,
+} from '../pdf417/compaction.js';
+
+function byteLength(value) {
+  if (value instanceof Uint8Array) return value.byteLength;
+  if (ArrayBuffer.isView(value)) return value.byteLength;
+  return -1;
+}
+
+function assertNotEmpty(value) {
+  if ((typeof value === 'string' && value.length === 0) || byteLength(value) === 0) {
+    throw new EncodeError('MicroPDF417: value must not be empty');
+  }
+}
+
+function latin1Bytes(value) {
+  if (typeof value !== 'string') return value;
+  const bytes = [];
+  for (const character of value) {
+    const codePoint = character.codePointAt(0);
+    if (codePoint > 255) {
+      throw new EncodeError('MicroPDF417 ECI 3: string contains a character outside ISO-8859-1');
+    }
+    bytes.push(codePoint);
+  }
+  return Uint8Array.from(bytes);
+}
+
+function compactByte(value, eci) {
+  if (eci === undefined) return compactPdf417Bytes(value);
+  if (eci === 3) return compactPdf417Bytes(latin1Bytes(value));
+  if (eci === 26) {
+    if (typeof value !== 'string') {
+      throw new EncodeError('MicroPDF417 ECI 26: value must be a string so UTF-8 validity is known');
+    }
+    const encoded = compactPdf417Bytes(value);
+    return encoded[0] === 927 && encoded[1] === 26 ? encoded : [927, 26, ...encoded];
+  }
+  throw new EncodeError('MicroPDF417: supported ECI assignment numbers are 3 and 26');
+}
+
+/**
+ * Compact one MicroPDF417 value.
+ *
+ * Unlike PDF417, MicroPDF417 starts in Byte Compaction. Text therefore needs
+ * an explicit 900 latch. Byte compaction always emits 901 or 924 so its start
+ * state is unambiguous, including when an ECI designator precedes it.
+ */
+export function compactMicroPDF417(value, options = {}) {
+  assertNotEmpty(value);
+  const mode = options.compaction ?? 'auto';
+  const eci = options.eci;
+  if (eci !== undefined && eci !== 3 && eci !== 26) {
+    throw new EncodeError('MicroPDF417: supported ECI assignment numbers are 3 and 26');
+  }
+
+  if (mode === 'text') {
+    if (eci !== undefined) throw new EncodeError('MicroPDF417: explicit ECI is supported only with byte compaction');
+    return [900, ...compactPdf417Text(value)];
+  }
+  if (mode === 'numeric') {
+    if (eci !== undefined) throw new EncodeError('MicroPDF417: explicit ECI is supported only with byte compaction');
+    return compactPdf417Numeric(value);
+  }
+  if (mode === 'byte') return compactByte(value, eci);
+  if (mode !== 'auto') {
+    throw new EncodeError(`MicroPDF417: unsupported compaction mode ${JSON.stringify(mode)}`);
+  }
+
+  if (eci !== undefined) return compactByte(value, eci);
+  if (typeof value === 'string' && /^\d{13,}$/.test(value)) return compactPdf417Numeric(value);
+  if (typeof value === 'string') {
+    try {
+      return [900, ...compactPdf417Text(value)];
+    } catch (error) {
+      if (!(error instanceof EncodeError)) throw error;
+    }
+  }
+  return compactPdf417Bytes(value);
+}

package/src/ts/micropdf417/decoder.ts

@@ -0,0 +1,183 @@
+/*!
+ * 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.
+ */
+
+/**
+ * Direct-module MicroPDF417 decoder.
+ *
+ * This module reads an already sampled, axis-aligned `BitMatrix`. Image finding,
+ * perspective correction, and recognition from photographic pixels are deliberately
+ * outside this first decoder boundary. The RAP sequence is authoritative for format
+ * detection; matrix metadata is used only as an optional row-height hint.
+ *
+ * @module micropdf417/decoder
+ */
+
+import { FormatError } from '../core/errors.js';
+import { decodePdf417CompactionDetailed } from '../pdf417/compaction.js';
+import { pdf417CodewordForPattern } from '../pdf417/tables.js';
+import { microPdf417CorrectErrors } from './error-correction.js';
+import {
+  MICROPDF417_VARIANTS,
+  microPdf417RapSequence,
+  microPdf417RowAddress,
+  microPdf417VariantByNumber,
+} from './tables.js';
+
+function symbolWidth(columns) {
+  return 21 + columns * 17 + (columns > 2 ? 10 : 0);
+}
+
+function bits(matrix, y, x, width) {
+  let value = 0;
+  for (let i = 0; i < width; i++) value = (value << 1) | (matrix.get(x + i, y) ? 1 : 0);
+  return value;
+}
+
+function widthsToBits(widths) {
+  let dark = true;
+  let out = '';
+  for (const digit of widths) {
+    out += (dark ? '1' : '0').repeat(digit.charCodeAt(0) - 48);
+    dark = !dark;
+  }
+  return out;
+}
+
+function hasExpectedBits(matrix, y, x, sequence) {
+  const expected = widthsToBits(sequence);
+  for (let i = 0; i < expected.length; i++) {
+    if ((matrix.get(x + i, y) ? '1' : '0') !== expected[i]) return false;
+  }
+  return true;
+}
+
+function centralRapAfter(entry, column) {
+  return (entry.columns === 3 && column === 0) ||
+    (entry.columns === 4 && column === 1);
+}
+
+/** Return true when all address patterns for this format candidate agree. */
+function hasValidRowAddresses(matrix, entry, rowHeight) {
+  for (let row = 0; row < entry.rows; row++) {
+    const y = row * rowHeight;
+    const address = microPdf417RowAddress(entry, row);
+    let x = 0;
+    if (!hasExpectedBits(matrix, y, x, microPdf417RapSequence(address.left, 'side'))) return false;
+    x += 10;
+    for (let column = 0; column < entry.columns; column++) {
+      x += 17;
+      if (centralRapAfter(entry, column)) {
+        if (address.center === null ||
+            !hasExpectedBits(matrix, y, x, microPdf417RapSequence(address.center, 'center'))) return false;
+        x += 10;
+      }
+    }
+    if (!hasExpectedBits(matrix, y, x, microPdf417RapSequence(address.right, 'side'))) return false;
+    x += 10;
+    if (!matrix.get(x, y) || x + 1 !== matrix.width) return false;
+  }
+  return true;
+}
+
+function candidateFormats(matrix, options) {
+  const metadataHeight = matrix.micropdf417?.rowHeight;
+  const requestedHeight = options.rowHeight ?? metadataHeight;
+  if (requestedHeight !== undefined && (!Number.isInteger(requestedHeight) || requestedHeight < 1)) {
+    throw new FormatError('MicroPDF417: rowHeight must be a positive integer');
+  }
+  const requestedVariant = options.variant === undefined ? null : microPdf417VariantByNumber(options.variant);
+  const pool = requestedVariant ? [requestedVariant] : MICROPDF417_VARIANTS;
+  const candidates = [];
+  for (const entry of pool) {
+    if (matrix.width !== symbolWidth(entry.columns)) continue;
+    if (matrix.height % entry.rows) continue;
+    const rowHeight = matrix.height / entry.rows;
+    if (requestedHeight !== undefined && rowHeight !== requestedHeight) continue;
+    if (hasValidRowAddresses(matrix, entry, rowHeight)) candidates.push({ entry, rowHeight });
+  }
+  return candidates;
+}
+
+function resolveFormat(matrix, options) {
+  if (!matrix?.width || !matrix?.height || typeof matrix.get !== 'function') {
+    throw new FormatError('MicroPDF417: matrix with width, height and get() is required');
+  }
+  const candidates = candidateFormats(matrix, options);
+  if (!candidates.length) throw new FormatError('MicroPDF417: no variant matches matrix geometry and row-address patterns');
+  if (candidates.length > 1) throw new FormatError('MicroPDF417: row-address patterns do not identify a unique variant');
+  return candidates[0];
+}
+
+function readCodewords(matrix, entry, rowHeight) {
+  const codewords = [];
+  const erasures = [];
+  for (let row = 0; row < entry.rows; row++) {
+    const y = row * rowHeight;
+    const address = microPdf417RowAddress(entry, row);
+    let x = 10;
+    for (let column = 0; column < entry.columns; column++) {
+      const decoded = pdf417CodewordForPattern(bits(matrix, y, x, 17));
+      if (!decoded || decoded.cluster !== address.cluster) {
+        erasures.push(codewords.length);
+        codewords.push(0);
+      } else {
+        codewords.push(decoded.codeword);
+      }
+      x += 17;
+      if (centralRapAfter(entry, column)) x += 10;
+    }
+  }
+  return { codewords, erasures };
+}
+
+/**
+ * Decode a sampled MicroPDF417 matrix.
+ *
+ * The complete fixed data region is compacted after correction. Encoder padding
+ * is PDF417 Text latch 900, which contributes no characters at the end of the
+ * payload. This avoids relying on non-symbol metadata for payload length.
+ */
+export function decodeMicroPDF417(matrix, options = {}) {
+  const { entry, rowHeight } = resolveFormat(matrix, options);
+  const { codewords, erasures } = readCodewords(matrix, entry, rowHeight);
+  const corrections = microPdf417CorrectErrors(codewords, entry, erasures);
+  const data = codewords.slice(0, entry.dataCodewords);
+  const decoded = decodePdf417CompactionDetailed(data);
+  return {
+    ...decoded,
+    codewords,
+    rows: entry.rows,
+    columns: entry.columns,
+    variant: entry.id,
+    eccCodewords: entry.eccCodewords,
+    rowHeight,
+    corrections,
+  };
+}

package/src/ts/micropdf417/detector.ts

@@ -0,0 +1,149 @@
+/*!
+ * 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.
+ */
+
+/**
+ * Axis-aligned MicroPDF417 raster detection.
+ *
+ * A MicroPDF417 symbol has a fixed module width for each column count and a
+ * dark leading and trailing module in every row.  Consequently the bounding
+ * rectangle of dark pixels identifies the complete symbol even when a light
+ * quiet zone surrounds it.  Its width determines the integer raster scale;
+ * the existing direct-module decoder then verifies every row-address pattern
+ * and selects the exact variant.  This is intentionally narrower than the
+ * PDF417 photo detector: it handles clean binarized rasters only, not skew or
+ * projective camera images.
+ *
+ * @module micropdf417/detector
+ */
+
+import { BitMatrix } from '../core/bit-matrix.js';
+import { decodeMicroPDF417 } from './decoder.js';
+
+/** @typedef {{x:number, y:number}} Point */
+
+// Each row has two 10-module side RAPs, a final separator, and 17 modules for
+// each data column. Three and four columns also contain one central RAP.
+function symbolWidth(columns) { return 21 + columns * 17 + (columns > 2 ? 10 : 0); }
+const WIDTHS = [1, 2, 3, 4].map(symbolWidth);
+
+function rotateClockwise(source) {
+  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 integerScale(width, modules) {
+  if (width % modules) return 0;
+  const scale = width / modules;
+  return Number.isInteger(scale) && scale > 0 ? scale : 0;
+}
+
+/** Collapse exact integer scale blocks using a majority vote. */
+function sampleRaster(image, bounds, modulesWide, scale) {
+  const modulesHigh = bounds.height / scale;
+  if (!Number.isInteger(modulesHigh) || modulesHigh < 1) return null;
+  const matrix = new BitMatrix(modulesWide, modulesHigh);
+  for (let y = 0; y < modulesHigh; y++) for (let x = 0; x < modulesWide; x++) {
+    let dark = 0;
+    for (let py = 0; py < scale; py++) for (let px = 0; px < scale; px++) {
+      if (image.get(bounds.x + x * scale + px, bounds.y + y * scale + py)) dark++;
+    }
+    if (dark * 2 >= scale * scale) matrix.set(x, y);
+  }
+  return matrix;
+}
+
+function rectangle(bounds) {
+  return [
+    { x: bounds.x, y: bounds.y },
+    { x: bounds.x + bounds.width, y: bounds.y },
+    { x: bounds.x + bounds.width, y: bounds.y + bounds.height },
+    { x: bounds.x, y: bounds.y + bounds.height },
+  ];
+}
+
+function detectAxisAligned(image, options) {
+  const bounds = image.getBounds();
+  if (!bounds) return null;
+  for (const width of WIDTHS) {
+    const scale = integerScale(bounds.width, width);
+    if (!scale || bounds.height % scale) continue;
+    const matrix = sampleRaster(image, bounds, width, scale);
+    if (!matrix) continue;
+    try {
+      const decoded = decodeMicroPDF417(matrix, options);
+      return { matrix, corners: rectangle(bounds), moduleSize: scale, ...decoded };
+    } catch { /* The RAP sequence is not a MicroPDF417 symbol of this width. */ }
+  }
+  return null;
+}
+
+/**
+ * Detect and decode one clean, binarized MicroPDF417 raster.
+ *
+ * Integer upscaling and quiet zones are accepted. The image is retried at all
+ * quarter-turns, but arbitrary angles and perspective require caller-side
+ * rectification before this function is used. `rotation` reports the clockwise
+ * orientation of the supplied input relative to a normally oriented symbol;
+ * it is not the inverse correction applied internally while searching.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} binaryImage Set bit = dark.
+ * @param {object} [options] Passed to {@link decodeMicroPDF417}.
+ * @returns {(ReturnType<typeof decodeMicroPDF417> & {matrix: BitMatrix, corners: Point[], moduleSize: number, rotation: number}) | null}
+ */
+export function detectMicroPDF417(binaryImage, options = {}) {
+  if (!binaryImage?.width || !binaryImage?.height || typeof binaryImage.get !== 'function') return null;
+  let oriented = binaryImage;
+  let toOriginal = (point) => ({ x: point.x, y: point.y });
+  for (let turns = 0; turns < 4; turns++) {
+    const found = detectAxisAligned(oriented, options);
+    // Search rotates clockwise to normalize the input. Public rotation has the
+    // opposite meaning: it describes how the input itself was rotated.
+    if (found) return {
+      ...found,
+      rotation: (360 - turns * 90) % 360,
+      corners: found.corners.map(toOriginal),
+    };
+    const previous = oriented;
+    const previousToOriginal = toOriginal;
+    oriented = rotateClockwise(previous);
+    // Boundary coordinates (rather than just pixel centres) are transformed
+    // here, so callers can draw the returned rectangle directly on the input.
+    toOriginal = (point) => previousToOriginal({ x: point.y, y: previous.height - point.x });
+  }
+  return null;
+}
+
+/** Alias kept symmetric with the other 2D readers. */
+export function detectAndDecodeMicroPDF417(binaryImage, options = {}) {
+  return detectMicroPDF417(binaryImage, options);
+}

package/src/ts/micropdf417/encoder.ts

@@ -0,0 +1,209 @@
+/*!
+ * 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.
+ */
+
+/** MicroPDF417 encoder. @module micropdf417/encoder */
+
+import { BitMatrix } from '../core/bit-matrix.js';
+import { EncodeError } from '../core/errors.js';
+import { pdf417PatternForCodeword } from '../pdf417/tables.js';
+import { compactMicroPDF417 } from './compaction.js';
+import { microPdf417ErrorCorrection } from './error-correction.js';
+import {
+  MICROPDF417_VARIANTS,
+  microPdf417RapSequence,
+  microPdf417RowAddress,
+  microPdf417VariantByNumber,
+  microPdf417VariantForCapacity,
+} from './tables.js';
+
+function appendWidths(matrix, y, x, sequence, height) {
+  let dark = true;
+  for (const digit of sequence) {
+    const width = digit.charCodeAt(0) - 48;
+    if (!Number.isInteger(width) || width < 1 || width > 6) {
+      throw new EncodeError('MicroPDF417: invalid module-width sequence');
+    }
+    if (dark) matrix.setRegion(x, y, width, height);
+    x += width;
+    dark = !dark;
+  }
+  return x;
+}
+
+function codewordSequence(codeword, cluster) {
+  return pdf417PatternForCodeword(codeword, cluster)
+    .toString(2)
+    .padStart(17, '0')
+    .replace(/0+|1+/g, (run) => String(run.length));
+}
+
+function symbolWidth(columns) {
+  return 21 + columns * 17 + (columns > 2 ? 10 : 0);
+}
+
+function validateOptions(options) {
+  const rowHeight = options.rowHeight ?? 2;
+  if (!Number.isInteger(rowHeight) || rowHeight < 2) {
+    throw new EncodeError('MicroPDF417: rowHeight must be an integer of at least 2');
+  }
+  if (options.columns !== undefined &&
+      (!Number.isInteger(options.columns) || options.columns < 1 || options.columns > 4)) {
+    throw new EncodeError('MicroPDF417: columns must be an integer in 1..4');
+  }
+  if (options.variant !== undefined &&
+      (!Number.isInteger(options.variant) || options.variant < 1 || options.variant > 34)) {
+    throw new EncodeError('MicroPDF417: variant must be an integer in 1..34');
+  }
+  if (options.aspectRatio !== undefined &&
+      (!Number.isFinite(options.aspectRatio) || options.aspectRatio <= 0)) {
+    throw new EncodeError('MicroPDF417: aspectRatio must be positive');
+  }
+  if (options.rows !== undefined) {
+    throw new EncodeError('MicroPDF417: rows are fixed by the selected variant');
+  }
+  if (options.eccLevel !== undefined) {
+    throw new EncodeError('MicroPDF417: error correction is fixed by the selected variant');
+  }
+  for (const feature of [
+    'structuredAppend', 'macro', 'macroPdf417', 'macroControlBlock',
+    'readerInit', 'gs1', 'hibc', 'linkage',
+  ]) {
+    if (options[feature] !== undefined) {
+      throw new EncodeError(`MicroPDF417: ${feature} is not implemented`);
+    }
+  }
+  return rowHeight;
+}
+
+function chooseVariant(codewordCount, rowHeight, options) {
+  if (options.variant !== undefined) {
+    const variant = microPdf417VariantByNumber(options.variant);
+    if (!variant) throw new EncodeError(`MicroPDF417: unknown variant ${options.variant}`);
+    if (options.columns !== undefined && variant.columns !== options.columns) {
+      throw new EncodeError(`MicroPDF417: variant ${variant.id} has ${variant.columns} columns`);
+    }
+    if (codewordCount > variant.dataCodewords) {
+      throw new EncodeError(
+        `MicroPDF417: payload requires ${codewordCount} data codewords, variant ${variant.id} holds ${variant.dataCodewords}`
+      );
+    }
+    return variant;
+  }
+
+  if (options.columns === undefined && options.aspectRatio === undefined) {
+    try {
+      return microPdf417VariantForCapacity(codewordCount);
+    } catch (error) {
+      if (!(error instanceof RangeError)) throw error;
+      throw new EncodeError(`MicroPDF417: payload requires ${codewordCount} data codewords and exceeds every variant`);
+    }
+  }
+
+  const candidates = MICROPDF417_VARIANTS.filter((variant) =>
+    variant.dataCodewords >= codewordCount &&
+    (options.columns === undefined || variant.columns === options.columns)
+  );
+  if (!candidates.length) {
+    const columnText = options.columns === undefined ? '' : ` with ${options.columns} columns`;
+    throw new EncodeError(`MicroPDF417: payload does not fit any supported variant${columnText}`);
+  }
+  if (options.aspectRatio === undefined) {
+    return candidates.reduce((best, variant) =>
+      variant.dataCodewords < best.dataCodewords ||
+      (variant.dataCodewords === best.dataCodewords && variant.totalCodewords < best.totalCodewords)
+        ? variant : best
+    );
+  }
+
+  const target = options.aspectRatio;
+  return candidates.reduce((best, variant) => {
+    const ratio = symbolWidth(variant.columns) / (variant.rows * rowHeight);
+    const score = Math.abs(Math.log(ratio / target)) +
+      (variant.dataCodewords - codewordCount) / 10000;
+    return !best || score < best.score ? { variant, score } : best;
+  }, null).variant;
+}
+
+/** Encode a value as one of the 34 fixed MicroPDF417 variants. */
+export function encodeMicroPDF417(value, options = {}) {
+  const rowHeight = validateOptions(options);
+  const payload = compactMicroPDF417(value, options);
+  const variant = chooseVariant(payload.length, rowHeight, options);
+  const data = payload.slice();
+  while (data.length < variant.dataCodewords) data.push(900);
+  const ecc = microPdf417ErrorCorrection(data, variant);
+  if (ecc.length !== variant.eccCodewords) {
+    throw new EncodeError('MicroPDF417: error-correction length does not match the selected variant');
+  }
+  const codewords = data.concat(ecc);
+  if (codewords.length !== variant.totalCodewords || codewords.length !== variant.rows * variant.columns) {
+    throw new EncodeError('MicroPDF417: selected variant has inconsistent codeword dimensions');
+  }
+
+  const matrix = new BitMatrix(symbolWidth(variant.columns), variant.rows * rowHeight);
+  for (let row = 0; row < variant.rows; row++) {
+    const y = row * rowHeight;
+    const address = microPdf417RowAddress(variant, row);
+    let x = appendWidths(matrix, y, 0, microPdf417RapSequence(address.left, 'side'), rowHeight);
+    for (let column = 0; column < variant.columns; column++) {
+      x = appendWidths(
+        matrix,
+        y,
+        x,
+        codewordSequence(codewords[row * variant.columns + column], address.cluster),
+        rowHeight
+      );
+      const hasCentralRap = (variant.columns === 3 && column === 0) ||
+        (variant.columns === 4 && column === 1);
+      if (hasCentralRap) {
+        if (address.center === null) {
+          throw new EncodeError('MicroPDF417: selected variant is missing its centre row address');
+        }
+        x = appendWidths(matrix, y, x, microPdf417RapSequence(address.center, 'center'), rowHeight);
+      }
+    }
+    x = appendWidths(matrix, y, x, microPdf417RapSequence(address.right, 'side'), rowHeight);
+    matrix.setRegion(x, y, 1, rowHeight);
+    x++;
+    if (x !== matrix.width) throw new EncodeError('MicroPDF417: row width does not match the selected variant');
+  }
+
+  matrix.micropdf417 = {
+    variant: variant.id,
+    rows: variant.rows,
+    columns: variant.columns,
+    eccCodewords: variant.eccCodewords,
+    rowHeight,
+    payloadCodewords: payload.length,
+    dataCodewords: data,
+    codewords,
+  };
+  return matrix;
+}