@sythos/js_barcode_universal 0.1.0

package/src/image/grid-sampler.js

@@ -0,0 +1,164 @@
+/*!
+ * 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.
+ */
+
+/**
+ * Resample a distorted symbol in the image into an upright module grid.
+ *
+ * Given a transform that maps grid coordinates to image coordinates, this
+ * samples the centre of every module. Sampling centres rather than averaging
+ * whole cells is deliberate: module edges are where blur and bleed live, and
+ * including them turns a marginal symbol into an unreadable one.
+ *
+ * @module image/grid-sampler
+ */
+
+import { BitMatrix } from '../core/bit-matrix.js';
+import { NotFoundError } from '../core/errors.js';
+import { PerspectiveTransform } from './perspective.js';
+
+/**
+ * Sample a `dimension` x `dimension` grid (or `width` x `height`).
+ *
+ * @param {BitMatrix} image Binarized source image.
+ * @param {number} width Modules across.
+ * @param {number} height Modules down.
+ * @param {PerspectiveTransform} transform Grid space -> image space.
+ * @returns {BitMatrix}
+ * @throws {NotFoundError} If the grid falls outside the image.
+ */
+export function sampleGrid(image, width, height, transform) {
+  const out = new BitMatrix(width, height);
+  const points = new Float32Array(width * 2);
+
+  for (let y = 0; y < height; y++) {
+    // Module centres: offset by half a module in both axes.
+    const gridY = y + 0.5;
+    for (let x = 0; x < width; x++) {
+      points[x * 2] = x + 0.5;
+      points[x * 2 + 1] = gridY;
+    }
+    transform.transform(points);
+
+    for (let x = 0; x < width; x++) {
+      const px = points[x * 2] | 0;
+      const py = points[x * 2 + 1] | 0;
+      if (px < 0 || py < 0 || px >= image.width || py >= image.height) {
+        throw new NotFoundError(
+          `Sampling grid escapes the image at module (${x}, ${y})`
+        );
+      }
+      if (image.get(px, py)) out.set(x, y);
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Sample with a 3x3 majority vote per module.
+ *
+ * Slower, and worth it when a single-point sample lands on a speck of noise or
+ * a JPEG artefact. Readers fall back to this after a clean sample fails to
+ * decode, rather than paying for it on every attempt.
+ *
+ * @param {BitMatrix} image
+ * @param {number} width
+ * @param {number} height
+ * @param {PerspectiveTransform} transform
+ * @returns {BitMatrix}
+ */
+export function sampleGridVoting(image, width, height, transform) {
+  const out = new BitMatrix(width, height);
+
+  // Spacing between module centres, measured in image pixels, so the vote
+  // spreads across the module rather than a fixed pixel radius that would be
+  // meaningless at a different scale.
+  const p0 = transform.transformPoint(0.5, 0.5);
+  const p1 = transform.transformPoint(1.5, 0.5);
+  const p2 = transform.transformPoint(0.5, 1.5);
+  const stepX = Math.hypot(p1.x - p0.x, p1.y - p0.y);
+  const stepY = Math.hypot(p2.x - p0.x, p2.y - p0.y);
+  const rx = Math.max(1, Math.round(stepX / 4));
+  const ry = Math.max(1, Math.round(stepY / 4));
+
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const c = transform.transformPoint(x + 0.5, y + 0.5);
+      const cx = c.x | 0;
+      const cy = c.y | 0;
+      if (cx < 0 || cy < 0 || cx >= image.width || cy >= image.height) {
+        throw new NotFoundError(
+          `Sampling grid escapes the image at module (${x}, ${y})`
+        );
+      }
+
+      let dark = 0;
+      let total = 0;
+      for (let dy = -1; dy <= 1; dy++) {
+        for (let dx = -1; dx <= 1; dx++) {
+          const sx = cx + dx * rx;
+          const sy = cy + dy * ry;
+          if (sx < 0 || sy < 0 || sx >= image.width || sy >= image.height) continue;
+          total++;
+          if (image.get(sx, sy)) dark++;
+        }
+      }
+      if (total > 0 && dark * 2 > total) out.set(x, y);
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Build the transform for a symbol whose four corners are known, and sample it.
+ *
+ * Corners are in reading order: top-left, top-right, bottom-right, bottom-left.
+ *
+ * @param {BitMatrix} image
+ * @param {number} dimension Modules per side.
+ * @param {Array<{x: number, y: number}>} corners
+ * @param {boolean} [voting]
+ * @returns {BitMatrix}
+ */
+export function sampleQuad(image, dimension, corners, voting = false) {
+  if (corners.length !== 4) throw new NotFoundError('sampleQuad needs exactly 4 corners');
+  const [tl, tr, br, bl] = corners;
+  const d = dimension;
+
+  const transform = PerspectiveTransform.quadToQuad(
+    0, 0, d, 0, d, d, 0, d,
+    tl.x, tl.y, tr.x, tr.y, br.x, br.y, bl.x, bl.y
+  );
+
+  return voting
+    ? sampleGridVoting(image, d, d, transform)
+    : sampleGrid(image, d, d, transform);
+}

package/src/image/index.js

@@ -0,0 +1,40 @@
+/*!
+ * 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.
+ */
+
+/**
+ * Image pipeline, re-exported.
+ *
+ * @module image
+ */
+
+export { LuminanceSource } from './luminance.js';
+export { binarize, binarizeGlobal, binarizeHybrid } from './binarizer.js';
+export { PerspectiveTransform } from './perspective.js';
+export { sampleGrid, sampleGridVoting, sampleQuad } from './grid-sampler.js';

package/src/image/luminance.js

@@ -0,0 +1,196 @@
+/*!
+ * 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.
+ */
+
+/**
+ * Greyscale conversion — the boundary between "an image" and "our problem".
+ *
+ * The whole library accepts exactly one image shape: `{ data, width, height }`
+ * with `data` in RGBA order. That is what `ImageData` is, so a `<canvas>`, an
+ * `OffscreenCanvas`, `createImageBitmap`, sharp, jimp and node-canvas all
+ * satisfy it without an adapter. Nothing below this file knows about the DOM,
+ * the filesystem, or any image codec.
+ *
+ * @module image/luminance
+ */
+
+import { NotFoundError } from '../core/errors.js';
+
+/**
+ * @typedef {object} ImageLike
+ * @property {Uint8ClampedArray | Uint8Array | number[]} data RGBA, 4 bytes per pixel.
+ * @property {number} width
+ * @property {number} height
+ */
+
+export class LuminanceSource {
+  /**
+   * @param {Uint8Array} grey One byte per pixel.
+   * @param {number} width
+   * @param {number} height
+   */
+  constructor(grey, width, height) {
+    this.grey = grey;
+    this.width = width;
+    this.height = height;
+  }
+
+  /**
+   * Build from any ImageData-shaped object.
+   *
+   * Transparent pixels are composited over white rather than read as black:
+   * a PNG barcode with a transparent background is common, and treating alpha
+   * as ink turns the entire quiet zone into a solid dark field.
+   *
+   * @param {ImageLike} image
+   * @returns {LuminanceSource}
+   */
+  static fromImageData(image) {
+    const { data, width, height } = image;
+    if (!data || !width || !height) {
+      throw new NotFoundError('Image must be { data, width, height } with RGBA data');
+    }
+    if (data.length < width * height * 4) {
+      throw new NotFoundError(
+        `Image data too short: ${data.length} bytes for ${width}x${height} RGBA ` +
+        `(expected ${width * height * 4})`
+      );
+    }
+
+    const grey = new Uint8Array(width * height);
+    for (let i = 0, p = 0; i < grey.length; i++, p += 4) {
+      const a = data[p + 3];
+      let r = data[p], g = data[p + 1], b = data[p + 2];
+      if (a !== 255) {
+        // Composite over white.
+        const inv = 255 - a;
+        r = (r * a + 255 * inv) / 255;
+        g = (g * a + 255 * inv) / 255;
+        b = (b * a + 255 * inv) / 255;
+      }
+      // Integer luma approximation of Rec. 601: 0.299/0.587/0.114 scaled by 256.
+      grey[i] = (r * 77 + g * 150 + b * 29) >> 8;
+    }
+    return new LuminanceSource(grey, width, height);
+  }
+
+  /**
+   * Build directly from single-channel data, skipping conversion.
+   *
+   * @param {Uint8Array} grey
+   * @param {number} width
+   * @param {number} height
+   * @returns {LuminanceSource}
+   */
+  static fromGrey(grey, width, height) {
+    if (grey.length < width * height) {
+      throw new NotFoundError('Greyscale buffer shorter than width * height');
+    }
+    return new LuminanceSource(grey, width, height);
+  }
+
+  /**
+   * @param {number} x @param {number} y
+   * @returns {number} 0-255.
+   */
+  get(x, y) {
+    return this.grey[y * this.width + x];
+  }
+
+  /**
+   * @param {number} y
+   * @param {Uint8Array} [out]
+   * @returns {Uint8Array}
+   */
+  getRow(y, out) {
+    const row = out && out.length >= this.width ? out : new Uint8Array(this.width);
+    row.set(this.grey.subarray(y * this.width, (y + 1) * this.width));
+    return row;
+  }
+
+  /**
+   * Rotate 90 degrees clockwise.
+   *
+   * The 1D readers scan horizontally, so this is how they find vertically
+   * oriented barcodes: scan, rotate, scan again.
+   *
+   * @returns {LuminanceSource}
+   */
+  rotate90() {
+    const { width: w, height: h, grey } = this;
+    const out = new Uint8Array(grey.length);
+    for (let y = 0; y < h; y++) {
+      for (let x = 0; x < w; x++) {
+        out[x * h + (h - 1 - y)] = grey[y * w + x];
+      }
+    }
+    return new LuminanceSource(out, h, w);
+  }
+
+  /**
+   * Downscale by an integer factor with box averaging.
+   *
+   * Large camera frames are slow to scan and no more informative than a
+   * half-size copy; detectors use this to find candidates cheaply.
+   *
+   * @param {number} factor
+   * @returns {LuminanceSource}
+   */
+  downscale(factor) {
+    const f = Math.max(1, Math.floor(factor));
+    if (f === 1) return this;
+    const w = Math.floor(this.width / f);
+    const h = Math.floor(this.height / f);
+    const out = new Uint8Array(w * h);
+    const area = f * f;
+    for (let y = 0; y < h; y++) {
+      for (let x = 0; x < w; x++) {
+        let sum = 0;
+        for (let dy = 0; dy < f; dy++) {
+          const base = (y * f + dy) * this.width + x * f;
+          for (let dx = 0; dx < f; dx++) sum += this.grey[base + dx];
+        }
+        out[y * w + x] = (sum / area) | 0;
+      }
+    }
+    return new LuminanceSource(out, w, h);
+  }
+
+  /**
+   * Invert. Some symbols are printed light-on-dark, and readers retry inverted
+   * when a first pass finds nothing.
+   *
+   * @returns {LuminanceSource}
+   */
+  invert() {
+    const out = new Uint8Array(this.grey.length);
+    for (let i = 0; i < out.length; i++) out[i] = 255 - this.grey[i];
+    return new LuminanceSource(out, this.width, this.height);
+  }
+}

package/src/image/perspective.js

@@ -0,0 +1,195 @@
+/*!
+ * 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.
+ */
+
+/**
+ * Projective (perspective) transforms.
+ *
+ * A 2D symbol photographed off-axis is not a rotated square — it is a
+ * quadrilateral with converging edges. Correcting that needs a full projective
+ * map, not an affine one; an affine approximation reads the near edge of a
+ * tilted symbol correctly and drifts a module or more by the far edge.
+ *
+ * The map is a 3x3 homogeneous matrix. Points are transformed as
+ * (x, y, 1) * M, then divided through by the resulting w.
+ *
+ * @module image/perspective
+ */
+
+export class PerspectiveTransform {
+  /* eslint-disable-next-line max-params */
+  constructor(a11, a21, a31, a12, a22, a32, a13, a23, a33) {
+    this.a11 = a11; this.a21 = a21; this.a31 = a31;
+    this.a12 = a12; this.a22 = a22; this.a32 = a32;
+    this.a13 = a13; this.a23 = a23; this.a33 = a33;
+  }
+
+  /**
+   * Transform points in place.
+   *
+   * @param {Float32Array | number[]} points Interleaved [x0, y0, x1, y1, ...].
+   * @returns {Float32Array | number[]} The same array.
+   */
+  transform(points) {
+    const { a11, a21, a31, a12, a22, a32, a13, a23, a33 } = this;
+    for (let i = 0; i < points.length; i += 2) {
+      const x = points[i];
+      const y = points[i + 1];
+      const w = a13 * x + a23 * y + a33;
+      points[i] = (a11 * x + a21 * y + a31) / w;
+      points[i + 1] = (a12 * x + a22 * y + a32) / w;
+    }
+    return points;
+  }
+
+  /**
+   * Transform a single point.
+   *
+   * @param {number} x @param {number} y
+   * @returns {{x: number, y: number}}
+   */
+  transformPoint(x, y) {
+    const w = this.a13 * x + this.a23 * y + this.a33;
+    return {
+      x: (this.a11 * x + this.a21 * y + this.a31) / w,
+      y: (this.a12 * x + this.a22 * y + this.a32) / w,
+    };
+  }
+
+  /**
+   * Map the unit square — (0,0), (1,0), (1,1), (0,1) — onto an arbitrary quad.
+   *
+   * Corners are given in that same order, i.e. going around the quad, not
+   * as opposite pairs.
+   *
+   * @returns {PerspectiveTransform}
+   */
+  /* eslint-disable-next-line max-params */
+  static squareToQuad(x0, y0, x1, y1, x2, y2, x3, y3) {
+    const dx3 = x0 - x1 + x2 - x3;
+    const dy3 = y0 - y1 + y2 - y3;
+
+    if (dx3 === 0 && dy3 === 0) {
+      // The quad is a parallelogram, so the map is affine and the projective
+      // terms vanish. Worth special-casing: it is the common case for flat
+      // scans, and the general solution divides by zero here.
+      return new PerspectiveTransform(
+        x1 - x0, x2 - x1, x0,
+        y1 - y0, y2 - y1, y0,
+        0, 0, 1
+      );
+    }
+
+    const dx1 = x1 - x2;
+    const dx2 = x3 - x2;
+    const dy1 = y1 - y2;
+    const dy2 = y3 - y2;
+    const denominator = dx1 * dy2 - dx2 * dy1;
+    const a13 = (dx3 * dy2 - dx2 * dy3) / denominator;
+    const a23 = (dx1 * dy3 - dx3 * dy1) / denominator;
+
+    return new PerspectiveTransform(
+      x1 - x0 + a13 * x1, x3 - x0 + a23 * x3, x0,
+      y1 - y0 + a13 * y1, y3 - y0 + a23 * y3, y0,
+      a13, a23, 1
+    );
+  }
+
+  /**
+   * Map an arbitrary quad onto the unit square — the inverse of
+   * {@link squareToQuad}, via the adjugate.
+   *
+   * @returns {PerspectiveTransform}
+   */
+  /* eslint-disable-next-line max-params */
+  static quadToSquare(x0, y0, x1, y1, x2, y2, x3, y3) {
+    return PerspectiveTransform.squareToQuad(x0, y0, x1, y1, x2, y2, x3, y3).inverse();
+  }
+
+  /**
+   * Map one quad onto another, corner for corner.
+   *
+   * This is what turns four detected finder corners into a sampling grid:
+   * compose "detected quad -> unit square" with "unit square -> ideal grid".
+   *
+   * @returns {PerspectiveTransform}
+   */
+  /* eslint-disable-next-line max-params */
+  static quadToQuad(
+    sx0, sy0, sx1, sy1, sx2, sy2, sx3, sy3,
+    dx0, dy0, dx1, dy1, dx2, dy2, dx3, dy3
+  ) {
+    const toSquare = PerspectiveTransform.quadToSquare(sx0, sy0, sx1, sy1, sx2, sy2, sx3, sy3);
+    const toQuad = PerspectiveTransform.squareToQuad(dx0, dy0, dx1, dy1, dx2, dy2, dx3, dy3);
+    return toSquare.times(toQuad);
+  }
+
+  /**
+   * Adjugate — the inverse up to a scale factor, which is irrelevant in
+   * homogeneous coordinates because the division by w cancels it.
+   *
+   * @returns {PerspectiveTransform}
+   */
+  inverse() {
+    const { a11, a21, a31, a12, a22, a32, a13, a23, a33 } = this;
+    return new PerspectiveTransform(
+      a22 * a33 - a23 * a32,
+      a23 * a31 - a21 * a33,
+      a21 * a32 - a22 * a31,
+      a13 * a32 - a12 * a33,
+      a11 * a33 - a13 * a31,
+      a12 * a31 - a11 * a32,
+      a12 * a23 - a13 * a22,
+      a13 * a21 - a11 * a23,
+      a11 * a22 - a12 * a21
+    );
+  }
+
+  /**
+   * Matrix product: apply `this` first, then `other`.
+   *
+   * @param {PerspectiveTransform} other
+   * @returns {PerspectiveTransform}
+   */
+  times(other) {
+    const { a11, a21, a31, a12, a22, a32, a13, a23, a33 } = this;
+    const o = other;
+    return new PerspectiveTransform(
+      o.a11 * a11 + o.a21 * a12 + o.a31 * a13,
+      o.a11 * a21 + o.a21 * a22 + o.a31 * a23,
+      o.a11 * a31 + o.a21 * a32 + o.a31 * a33,
+      o.a12 * a11 + o.a22 * a12 + o.a32 * a13,
+      o.a12 * a21 + o.a22 * a22 + o.a32 * a23,
+      o.a12 * a31 + o.a22 * a32 + o.a32 * a33,
+      o.a13 * a11 + o.a23 * a12 + o.a33 * a13,
+      o.a13 * a21 + o.a23 * a22 + o.a33 * a23,
+      o.a13 * a31 + o.a23 * a32 + o.a33 * a33
+    );
+  }
+}