qr_reader 0.0.1

data/lib/qr_reader/decoder.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require_relative "decoder/galois_field"
+require_relative "decoder/reed_solomon"
+require_relative "decoder/function_patterns"
+require_relative "decoder/data_mask"
+require_relative "decoder/codewords"
+require_relative "decoder/format_reader"
+require_relative "decoder/character_set"
+require_relative "decoder/bitstream_parser"
+
+module QrReader
+  # Decodes a sampled QR code module grid (ISO/IEC 18004:2015, Model 2).
+  #
+  #   result = QrReader::Decoder.decode(bit_matrix)   # => Result or nil
+  #   QrReader::Decoder.diagnose(bit_matrix)          # => { status: :reed_solomon, ... }
+  #
+  # The pipeline is ordered so that garbage fails as early and cheaply as
+  # possible (the detector may try many candidate grids): dimension, format
+  # information (at most two candidates per orientation when the copies
+  # disagree), version information, then the RS blocks one at a time, and
+  # only then the bit stream.
+  module Decoder
+    # Diagnostic statuses in pipeline order (later = got further).
+    STATUSES = %i[dimension format_info version_info reed_solomon bitstream ok].freeze
+
+    # Array#pack formats "C<count>" that take the first +count+ codewords of
+    # an RS block (at most 123 data codewords per block).
+    DATA_FORMATS = Array.new(124) { |count| "C#{count}".freeze }.freeze
+    # Strength order of the EC levels.
+    EC_STRENGTH = { L: 0, M: 1, Q: 2, H: 3 }.freeze
+    private_constant :DATA_FORMATS, :EC_STRENGTH
+
+    class << self
+      # Decodes +bit_matrix+ (N x N, N = 21..177, 1 = dark, no quiet zone).
+      # Returns a Result (with points: nil) or nil when the grid is not a
+      # decodable symbol. With +try_mirrored+, the grid is also read
+      # transposed (first, if its format information reads better that way);
+      # a Result read so is marked mirrored.
+      #
+      # Never raises for any grid content; raises TypeError if +bit_matrix+
+      # is not a QrReader::BitMatrix.
+      def decode(bit_matrix, try_mirrored: true)
+        bits = module_bits(bit_matrix)
+        bits && run(bits, bit_matrix.width, try_mirrored, nil)
+      end
+
+      # Runs the decoder with bookkeeping and returns a Hash describing how far
+      # it got: :status (one of STATUSES), :mirrored, :dimension, :format_bits,
+      # :ec_level (:l, :m, :q, :h), :mask, :format_distance, :version, :version_bits,
+      # :version_info (decoded version numbers of both copies), :blocks,
+      # :block_errors (corrected codewords per RS block, nil = uncorrectable),
+      # :errors_corrected, :error (bit stream message) and :result.
+      #
+      # Makes exactly the attempts #decode makes, so :status is :ok exactly
+      # when #decode returns a Result (then :result is that Result);
+      # otherwise the attempt that got furthest is reported.
+      def diagnose(bit_matrix, try_mirrored: true)
+        bits = module_bits(bit_matrix)
+        return { status: :dimension, mirrored: false, dimension: [bit_matrix.width, bit_matrix.height] } unless bits
+
+        diags = []
+        result = run(bits, bit_matrix.width, try_mirrored, diags)
+        return diags.find { |diag| diag[:result].equal?(result) } if result
+
+        diags.max_by.with_index { |diag, i| [STATUSES.index(diag[:status]), -i] }
+      end
+
+      private
+
+      # Tries the format information candidates of the readings in turn and
+      # returns the first Result, or nil. With +diags+ (an Array), a Hash per
+      # attempt is appended (an attempt without format information too).
+      #
+      # A code word of a stronger EC level is also one of a weaker level with
+      # the same block layout (its generator has the weaker one's roots and
+      # more), so when damaged format information names both levels with the
+      # same mask, the weaker reading would succeed - with the wrong level and,
+      # for a symbol filled to capacity, parity bytes parsed as data. The
+      # same-mask runner-up is therefore tried as well and the stronger
+      # successful reading wins.
+      def run(bits, n, try_mirrored, diags)
+        readings(bits, n, try_mirrored).each do |mirrored, words, candidates|
+          candidates = [nil] if candidates.empty? && diags
+          candidates.each_with_index do |format, k|
+            result = attempt(bits, n, mirrored, words, format, diags && (diags << { mirrored: mirrored }).last)
+            next unless result
+
+            sibling = candidates[k + 1]
+            if sibling && stronger_reading?(sibling[0], format[0])
+              stronger = attempt(bits, n, mirrored, words, sibling, diags && (diags << { mirrored: mirrored }).last)
+              return stronger if stronger
+            end
+            return result
+          end
+        end
+        nil
+      end
+
+      # True if +other+ (FormatInformation) has the mask of +info+ and a
+      # stronger EC level.
+      def stronger_reading?(other, info)
+        other.mask == info.mask && EC_STRENGTH[other.ec_level] > EC_STRENGTH[info.ec_level]
+      end
+
+      # The module String with only 0/1 bytes, or nil if the matrix cannot be
+      # a symbol (not square, wrong dimension, inconsistent storage).
+      def module_bits(matrix)
+        raise TypeError, "expected a QrReader::BitMatrix, got #{matrix.class}" unless matrix.is_a?(BitMatrix)
+
+        n = matrix.width
+        bits = matrix.bits
+        return nil unless n.is_a?(Integer) && bits.is_a?(String) && matrix.height == n &&
+                          SymbolVersion.for_dimension(n) && bits.bytesize == n * n
+
+        # Byte-wise operations below need a binary String (the BitMatrix
+        # constructor ensures one, but the String is mutable).
+        bits = bits.b unless bits.encoding == Encoding::BINARY
+        # Any byte other than 1 counts as light (like BitMatrix#dark?).
+        bits.count("\x00\x01") == bits.bytesize ? bits : bits.tr("^\x01", "\x00")
+      end
+
+      # The orientations worth trying, the one whose format information reads
+      # better first: Array of [mirrored, format_words, format_candidates].
+      #
+      # A symbol read the wrong way round yields format words at distance 2
+      # or more from every (masked) code word, so when both copies of one
+      # orientation read the same exact code word and the other orientation
+      # is at least 2 away, only the first is tried. (Copies written without
+      # the 0x5412 mask can read exactly both ways round; then both
+      # orientations are tried.)
+      def readings(bits, n, try_mirrored)
+        normal = reading(bits, n, false)
+        return [normal] unless try_mirrored
+
+        mirrored = reading(bits, n, true)
+        first, second = best_distance(mirrored) < best_distance(normal) ? [mirrored, normal] : [normal, mirrored]
+        words = first[1]
+        exact = words[0] == words[1] && best_distance(first).zero?
+        exact && best_distance(second) >= 2 ? [first] : [first, second]
+      end
+
+      def reading(bits, n, mirrored)
+        words = FormatReader.format_bits(bits, n, mirrored: mirrored)
+        [mirrored, words, FormatReader.format_candidates(*words)]
+      end
+
+      # Smallest format distance of a reading (4 when nothing is within 3).
+      def best_distance(reading)
+        best = 4
+        reading[2].each { |_, distance| best = distance if distance < best }
+        best
+      end
+
+      # One decoding pass in one orientation, given the format information
+      # words read for it and the format information to assume
+      # ([FormatInformation, distance] or nil). Returns a Result or nil;
+      # fills +diag+ if given.
+      def attempt(bits, n, mirrored, format_words, format, diag)
+        version = SymbolVersion.for_dimension(n)
+        diag&.merge!(dimension: n, version: version.number, format_bits: format_words)
+        return failure(diag, :format_info) unless format
+
+        info, distance = format
+        level = info.ec_level
+        mask = info.mask
+        diag&.merge!(ec_level: level.downcase, mask: mask, format_distance: distance)
+        return failure(diag, :version_info) unless version_info_consistent?(bits, n, version, mirrored, diag)
+
+        data, corrected = correct_blocks(bits, version, level, mask, mirrored, diag)
+        return failure(diag, :reed_solomon) unless data
+
+        content = begin
+          BitstreamParser.parse(data, version.number)
+        rescue FormatError => e
+          diag[:error] = e.message if diag
+          return failure(diag, :bitstream)
+        end
+
+        result = Result.new(text: content.text, raw_bytes: content.raw_bytes, version: version.number,
+                            ec_level: level.downcase, mask: mask, mirrored: mirrored, errors_corrected: corrected,
+                            eci: content.eci, fnc1: content.fnc1, structured_append: content.structured_append,
+                            symbology_identifier: content.symbology_identifier, segments: content.segments)
+        diag&.merge!(status: :ok, result: result)
+        result
+      end
+
+      def failure(diag, status)
+        diag[:status] = status if diag
+        nil
+      end
+
+      # Versions 7+ carry their version number twice. The dimension decides:
+      # the grid is rejected only when both copies name the same other
+      # version (it was most likely sampled at the wrong size - a hint for
+      # the detector). Unreadable copies, or a single copy damaged into
+      # another version's code word, fall back to the dimension; Reed-Solomon
+      # has the final word.
+      def version_info_consistent?(bits, n, version, mirrored, diag)
+        return true if version.number < 7
+
+        copies = FormatReader.version_bits(bits, n, mirrored: mirrored)
+        diag[:version_bits] = copies if diag
+        return true if copies.include?(version.version_info_bits) && !diag
+
+        first = FormatReader.decode_version(copies[0])
+        second = FormatReader.decode_version(copies[1])
+        diag[:version_info] = [first, second] if diag
+        first.nil? || first != second || first == version.number
+      end
+
+      # Reads, error-corrects and concatenates the data codewords of all RS
+      # blocks. Returns [data String, corrected count] or nil at the first
+      # uncorrectable block (with +diag+, all blocks are checked).
+      def correct_blocks(bits, version, level, mask, mirrored, diag)
+        layout = Codewords.layout(version.number)
+        order = mirrored ? layout.mirrored_order : layout.order
+        mask_codewords = layout.mask_codewords(mask)
+        ec_count = version.ec_blocks(level).ec_codewords_per_block
+        blocks = layout.blocks(level)
+        data = "".b
+        corrected = 0
+        block_errors = diag ? [] : nil
+        blocks.each do |data_count, indices|
+          codewords = Codewords.read_block(bits, order, mask_codewords, indices)
+          fixed = ReedSolomon.decode(codewords, ec_count)
+          block_errors << fixed if diag
+          if fixed
+            corrected += fixed
+            data << codewords.pack(DATA_FORMATS[data_count])
+          elsif !diag
+            return nil
+          end
+        end
+        failed = diag && block_errors.include?(nil)
+        diag&.merge!(blocks: blocks.size, block_errors: block_errors, errors_corrected: failed ? nil : corrected)
+        failed ? nil : [data, corrected]
+      end
+    end
+  end
+end

data/lib/qr_reader/detector/alignment_grid.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module QrReader
+  class Detector
+    # Piecewise sampling support for versions 7+ (zxing-cpp's approach):
+    # locates every alignment pattern, predicting each one from its already
+    # located neighbours, and returns one local transform per cell of the
+    # alignment pattern grid. This follows bent, curved or unevenly
+    # stretched symbols far better than a single homography.
+    class AlignmentGrid
+      # +finder_corners+ - callable taking the last grid index n and
+      # returning measured positions of the grid points next to the finder
+      # patterns ({[x, y] => [px, py]}, possibly incomplete).
+      def initialize(detector, transform, dimension, module_size, finder_corners = nil)
+        @finder = detector.alignment_finder
+        @transform = transform
+        @dimension = dimension
+        @module_size = module_size
+        @finder_corners = finder_corners
+      end
+
+      # [[x0, x1, y0, y1, transform], ...] covering the whole symbol, or nil
+      # if the version has no alignment grid or a cell is degenerate.
+      def regions
+        version = SymbolVersion.for_dimension(@dimension) or return
+        centres = version.alignment_centers
+        n = centres.size - 1
+        return if n < 1
+
+        positions = locate_all(centres, n)
+        return if positions.any? { |row| row.any?(&:nil?) }
+
+        out = []
+        n.times do |y|
+          n.times do |x|
+            x0 = centres[x]
+            x1 = centres[x + 1]
+            y0 = centres[y]
+            y1 = centres[y + 1]
+            t = PerspectiveTransform.quad_to_quad(
+              [[x0 + 0.5, y0 + 0.5], [x1 + 0.5, y0 + 0.5], [x1 + 0.5, y1 + 0.5], [x0 + 0.5, y1 + 0.5]],
+              [positions[y][x], positions[y][x + 1], positions[y + 1][x + 1], positions[y + 1][x]]
+            )
+            # Cells on the border also cover the modules out to the edge.
+            region = [x.zero? ? 0 : x0, x == n - 1 ? @dimension : x1,
+                      y.zero? ? 0 : y0, y == n - 1 ? @dimension : y1]
+            return unless t&.regular_over?(region[0], region[2], region[1], region[3])
+
+            out << [*region, t]
+          end
+        end
+        out
+      end
+
+      private
+
+      # Pixel positions of all grid points ([y][x]); points next to the
+      # finder patterns and points that cannot be found are projected.
+      def locate_all(centres, n)
+        found = Array.new(n + 1) { Array.new(n + 1) }
+        @finder_corners&.call(n)&.each { |(x, y), p| found[y][x] = p }
+        project = ->(x, y) { @transform.apply(centres[x] + 0.5, centres[y] + 0.5) }
+        best = ->(x, y) { found[y][x] || project.call(x, y) }
+        finder_adjacent = ->(x, y) { (x.zero? && y.zero?) || (x.zero? && y == n) || (x == n && y.zero?) }
+
+        (0..n).each do |y|
+          (0..n).each do |x|
+            next if finder_adjacent.call(x, y) || found[y][x]
+
+            guess =
+              if x.zero? || y.zero?
+                project.call(x, y)
+              else
+                a = best.call(x - 1, y)
+                b = best.call(x, y - 1)
+                c = best.call(x - 1, y - 1)
+                a && b && c ? [a[0] + b[0] - c[0], a[1] + b[1] - c[1]] : project.call(x, y)
+              end
+            found[y][x] = search(guess, centres[x], centres[y]) if guess
+          end
+        end
+
+        (0..n).map do |y|
+          (0..n).map { |x| found[y][x] || interpolate(found, x, y, n) || project.call(x, y) }
+        end
+      end
+
+      # Intersection of the lines through the nearest two found neighbours
+      # in the same row and in the same column, if both exist.
+      def interpolate(found, x, y, n)
+        row = nearest(n) { |i| found[y][x + i] if (x + i).between?(0, n) }
+        col = nearest(n) { |i| found[y + i][x] if (y + i).between?(0, n) }
+        return unless row.size == 2 && col.size == 2
+
+        intersect(row[0], row[1], col[0], col[1])
+      end
+
+      def nearest(n)
+        out = []
+        (1..n).each do |d|
+          [-d, d].each do |i|
+            p = yield(i)
+            out << p if p && out.size < 2
+          end
+        end
+        out
+      end
+
+      def intersect(p1, p2, p3, p4)
+        d = (p1[0] - p2[0]) * (p3[1] - p4[1]) - (p1[1] - p2[1]) * (p3[0] - p4[0])
+        return if d.abs < 1e-9
+
+        a = p1[0] * p2[1] - p1[1] * p2[0]
+        b = p3[0] * p4[1] - p3[1] * p4[0]
+        [(a * (p3[0] - p4[0]) - (p1[0] - p2[0]) * b) / d, (a * (p3[1] - p4[1]) - (p1[1] - p2[1]) * b) / d]
+      end
+
+      # Alignment pattern near +guess+ (module vectors from the transform).
+      def search(guess, mx, my)
+        c = @transform.apply(mx + 0.5, my + 0.5) or return
+        u = @transform.apply(mx + 1.5, my + 0.5) or return
+        v = @transform.apply(mx + 0.5, my + 1.5) or return
+        @finder.find(guess[0], guess[1], 3 * @module_size + 1, u[0] - c[0], u[1] - c[1], v[0] - c[0], v[1] - c[1])
+      end
+    end
+  end
+end

data/lib/qr_reader/detector/alignment_pattern_finder.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module QrReader
+  class Detector
+    # Finds alignment patterns (a dark module inside a light 3x3 ring inside
+    # a dark 5x5 ring) near a predicted position.
+    #
+    # Rows of a window around the prediction are scanned for light-dark-light
+    # runs of about one module each (from the middle row outwards), hits are
+    # cross-checked vertically and then verified by sampling the 5x5
+    # structure along the symbol's own axes, which rejects the many
+    # look-alikes in the data area. The verified hit closest to the
+    # prediction wins.
+    class AlignmentPatternFinder
+      DARK = BitMatrix::DARK
+      LIGHT = BitMatrix::LIGHT
+      # Of the 25 cells of the 5x5 pattern this many may read wrong.
+      MAX_MISMATCHES = 5
+
+      # Module offsets of the 8 light ring cells and the 16 dark ring cells.
+      LIGHT_RING = [[-1, -1], [0, -1], [1, -1], [-1, 0], [1, 0], [-1, 1], [0, 1], [1, 1]].freeze
+      DARK_RING = ((-2..2).flat_map { |i| [[i, -2], [i, 2]] } + (-1..1).flat_map { |i| [[-2, i], [2, i]] }).freeze
+
+      def initialize(matrix)
+        @matrix = matrix
+        @bits = matrix.bits
+        @width = matrix.width
+        @height = matrix.height
+      end
+
+      # Searches the square window of +radius+ pixels around (x, y).
+      # +ux+, +uy+ / +vx+, +vy+ are the pixel vectors of one module step
+      # along the symbol's x and y axes at that location (for verification).
+      # Returns [cx, cy] or nil.
+      def find(x, y, radius, ux, uy, vx, vy)
+        module_size = Math.sqrt((ux * ux + uy * uy + vx * vx + vy * vy) * 0.5)
+        return if module_size < 0.8 || !x.finite? || !y.finite?
+
+        x0 = (x - radius).floor.clamp(0, @width - 1)
+        x1 = (x + radius).ceil.clamp(0, @width - 1)
+        y0 = (y - radius).floor.clamp(0, @height - 1)
+        y1 = (y + radius).ceil.clamp(0, @height - 1)
+        return if x1 - x0 < 3 || y1 - y0 < 3
+
+        best = nil
+        best_score = Float::INFINITY
+        # Rows through the same pattern confirm the same centre: verify each
+        # centre once. (Exact keys: verification samples whole pixels, so a
+        # centre a fraction of a pixel away can verify when this one fails.)
+        verified = {}
+        mid = y.floor.clamp(y0, y1)
+        max_offset = [mid - y0, y1 - mid].max
+        offset = 0
+        while offset <= max_offset
+          [mid - offset, mid + offset].uniq.each do |row|
+            next if row < y0 || row > y1
+
+            scan_row(row, x0, x1, module_size) do |cx|
+              centre = confirm(cx, row, module_size)
+              next unless centre
+
+              next if verified.key?(centre)
+
+              verified[centre] = true
+              mismatches = verify(centre[0], centre[1], ux, uy, vx, vy)
+              next if mismatches > MAX_MISMATCHES
+
+              score = Math.hypot(centre[0] - x, centre[1] - y) / module_size + mismatches
+              if score < best_score
+                best_score = score
+                best = centre
+              end
+            end
+          end
+          # Stop early once a clean pattern close to the prediction is known.
+          break if best && best_score < offset / module_size - 1.0
+
+          offset += 1
+        end
+        best
+      end
+
+      private
+
+      # Yields the centre column of every light-dark-light run triple with
+      # runs of about one module in row y between columns x0 and x1, where
+      # the dark ring continues on both sides.
+      def scan_row(y, x0, x1, module_size)
+        w = @width
+        off = y * w
+        row = @bits.byteslice(off, w)
+        max = module_size * 1.6 + 1
+        min = module_size * 0.4 - 1
+        pos = row.index(LIGHT, x0) or return
+        while pos < x1
+          d0 = row.index(DARK, pos) or return
+          d1 = row.index(LIGHT, d0) or return
+          l1 = row.index(DARK, d1) or return
+          a = d0 - pos
+          b = d1 - d0
+          c = l1 - d1
+          # The light run before must be preceded by dark (ring), which holds
+          # unless it starts the row segment.
+          if b <= max && b >= min && a <= max && a >= min && c <= max && c >= min &&
+             pos.positive? && row.getbyte(pos - 1) == 1
+            yield (d0 + d1) >> 1
+          end
+          pos = d1
+        end
+      end
+
+      # Vertical then horizontal cross-check through dark pixel (x, y).
+      # Returns the refined centre [cx, cy] or nil.
+      def confirm(x, y, module_size)
+        bits = @bits
+        w = @width
+        h = @height
+        max = module_size * 1.6 + 1
+        min = module_size * 0.4 - 1
+        # Vertical: dark centre, light above/below, dark ring beyond. The
+        # walks stop just past the longest acceptable run, so a long dark
+        # column (page border, large dark area) costs nothing extra.
+        top = y
+        top -= 1 while top > 0 && y - top <= max && bits.getbyte((top - 1) * w + x) == 1
+        bottom = y
+        bottom += 1 while bottom < h - 1 && bottom - y <= max && bits.getbyte((bottom + 1) * w + x) == 1
+        centre_v = bottom - top + 1
+        return if centre_v > max || centre_v < min
+
+        lt = top - 1
+        lt -= 1 while lt >= 0 && top - lt <= max + 1 && bits.getbyte(lt * w + x).zero?
+        lb = bottom + 1
+        lb += 1 while lb < h && lb - bottom <= max + 1 && bits.getbyte(lb * w + x).zero?
+        return if lt.negative? || lb >= h
+
+        light_top = top - lt - 1
+        light_bottom = lb - bottom - 1
+        return if light_top < min || light_top > max || light_bottom < min || light_bottom > max
+
+        cy = (top + bottom + 1) * 0.5
+        span_y = (lt + 1 + lb) * 0.5
+        iy = cy.floor
+        # Horizontal at the vertical centre.
+        row = bits.byteslice(iy * w, w)
+        return unless row.getbyte(x) == 1
+
+        r0 = row.index(LIGHT, x) or return
+        r1 = row.index(DARK, r0) or return
+        l0 = row.rindex(LIGHT, x) or return
+        l1 = row.rindex(DARK, l0) or return
+        centre_h = r0 - l0 - 1
+        return if centre_h > max || centre_h < min || r1 - r0 > max || l0 - l1 > max
+
+        cx = (l0 + 1 + r0) * 0.5
+        span_x = (l1 + 1 + r1) * 0.5
+        [(cx + span_x) * 0.5, (cy + span_y) * 0.5]
+      end
+
+      # Number of cells of the 5x5 pattern centred at (x, y) that have the
+      # wrong colour (out of 25), sampling along the module vectors.
+      # Stops counting past MAX_MISMATCHES.
+      def verify(x, y, ux, uy, vx, vy)
+        bits = @bits
+        w = @width
+        h = @height
+        wrong = dark_at?(bits, w, h, x, y) ? 0 : 1
+        k = 0
+        while k < 8
+          i, j = LIGHT_RING[k]
+          wrong += 1 if dark_at?(bits, w, h, x + i * ux + j * vx, y + i * uy + j * vy)
+          k += 1
+        end
+        return wrong if wrong > MAX_MISMATCHES
+
+        k = 0
+        while k < 16
+          i, j = DARK_RING[k]
+          wrong += 1 unless dark_at?(bits, w, h, x + i * ux + j * vx, y + i * uy + j * vy)
+          return wrong if wrong > MAX_MISMATCHES
+
+          k += 1
+        end
+        wrong
+      end
+
+      def dark_at?(bits, w, h, x, y)
+        x >= 0 && y >= 0 && x < w && y < h && bits.getbyte(y.to_i * w + x.to_i) == 1
+      end
+    end
+  end
+end