qr_reader 0.0.1

data/lib/qr_reader/decoder/format_reader.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module QrReader
+  module Decoder
+    # Reads the format information (EC level + mask) and version information
+    # words from a module grid. Bit order is exactly that of ISO/IEC 18004
+    # §7.9/§7.10 as implemented by ZXing's BitMatrixParser: the first module
+    # read becomes the most significant bit.
+    #
+    # +bits+ is the symbol's module String (0/1 bytes, row-major), +n+ its
+    # dimension. With +mirrored+ the symbol is read transposed.
+    module FormatReader
+      # Copy 1 around the top-left finder, as [x, y].
+      FORMAT_COPY1 = [[0, 8], [1, 8], [2, 8], [3, 8], [4, 8], [5, 8], [7, 8], [8, 8],
+                      [8, 7], [8, 5], [8, 4], [8, 3], [8, 2], [8, 1], [8, 0]].freeze
+
+      # Version information code words for versions 7..40.
+      VERSION_CODES = (7..40).map { |v| SymbolVersion[v].version_info_bits }.freeze
+      POPCOUNT9 = Array.new(512) { |i| i.to_s(2).count("1") }.freeze
+      NO_CANDIDATES = [].freeze
+      private_constant :POPCOUNT9, :NO_CANDIDATES
+
+      @format_table = nil
+      @positions = {}
+
+      class << self
+        # The two 15-bit format information words [copy1, copy2]. Copy 2 runs
+        # up column 8 from the bottom-left corner (7 modules, above them is the
+        # dark module), then along row 8 to the right edge (8 modules).
+        def format_bits(bits, n, mirrored: false)
+          copy1, copy2 = positions(n, mirrored)
+          [read_word(bits, copy1), read_word(bits, copy2)]
+        end
+
+        # The two 18-bit version information words [top_right, bottom_left].
+        def version_bits(bits, n, mirrored: false)
+          top_right, bottom_left = positions(n, mirrored)[2]
+          [read_word(bits, top_right), read_word(bits, bottom_left)]
+        end
+
+        # Decodes the two format words like FormatInformation.decode (nearest
+        # code word within Hamming distance 3 of either copy, ties to the lower
+        # code; then the same for copies lacking the 0x5412 mask), but with one
+        # Array lookup per word. Returns [FormatInformation, distance] or nil.
+        def decode_format(copy1, copy2)
+          table = format_table
+          mask = FormatInformation::MASK
+          entry = closer(table[copy1 & 0x7FFF], table[copy2 & 0x7FFF]) ||
+                  closer(table[(copy1 ^ mask) & 0x7FFF], table[(copy2 ^ mask) & 0x7FFF])
+          entry && [FormatInformation::ALL[entry >> 2], entry & 3]
+        end
+
+        # Every format information worth trying for the two copies, most
+        # likely first: Array of up to two [FormatInformation, distance].
+        #
+        # Each copy proposes the code word within Hamming distance 3 of it
+        # (as in #decode_format, masked code words first, then copies lacking
+        # the 0x5412 mask). When the copies propose different code words, the
+        # one needing fewer bit errors in both copies together goes first
+        # (ties: the smaller distance of a single copy, then the lower code):
+        # ranking by one copy alone picks the wrong one when both copies are
+        # damaged, and trying the runner-up rescues the symbol when it is.
+        # +distance+ is the smaller distance of the two copies.
+        def format_candidates(copy1, copy2)
+          table = format_table
+          copy1 &= 0x7FFF
+          copy2 &= 0x7FFF
+          a = table[copy1]
+          b = table[copy2]
+          unless a || b
+            mask = FormatInformation::MASK
+            copy1 ^= mask
+            copy2 ^= mask
+            a = table[copy1]
+            b = table[copy2]
+            return NO_CANDIDATES unless a || b
+          end
+          return [candidate(a, copy2)] unless b
+          return [candidate(b, copy1)] if a.nil? || a >> 2 == b >> 2
+
+          first = candidate(a, copy2)
+          second = candidate(b, copy1)
+          first_rank = [(a & 3) + popcount15(copy2 ^ first[0].bits), a & 3, a >> 2]
+          second_rank = [(b & 3) + popcount15(copy1 ^ second[0].bits), b & 3, b >> 2]
+          (second_rank <=> first_rank).negative? ? [second, first] : [first, second]
+        end
+
+        # Version number (7..40) whose code word is nearest to the 18-bit
+        # +word+ within Hamming distance 3 (ties to the lower version), or nil.
+        # Same result as SymbolVersion.decode_version_info, without allocation.
+        def decode_version(word)
+          best = nil
+          best_distance = 4
+          i = 0
+          while i < 34
+            x = VERSION_CODES[i] ^ word
+            return i + 7 if x.zero?
+
+            distance = POPCOUNT9[x & 511] + POPCOUNT9[(x >> 9) & 511]
+            if distance < best_distance
+              best = i + 7
+              best_distance = distance
+            end
+            i += 1
+          end
+          best
+        end
+
+        private
+
+        # Word made of the modules at +indices+, first index = most significant bit.
+        def read_word(bits, indices)
+          word = 0
+          i = 0
+          count = indices.size
+          while i < count
+            word = (word << 1) | bits.getbyte(indices[i])
+            i += 1
+          end
+          word
+        end
+
+        # Module String indices, in reading order, of format copy 1, format
+        # copy 2 and the two version information blocks for dimension +n+,
+        # cached per dimension and orientation.
+        def positions(n, mirrored)
+          @positions[mirrored ? -n : n] ||= begin
+            index = mirrored ? ->(x, y) { x * n + y } : ->(x, y) { y * n + x }
+            copy2 = (n - 1).downto(n - 7).map { |y| [8, y] } + (n - 8).upto(n - 1).map { |x| [x, 8] }
+            top_right = 5.downto(0).flat_map { |y| (n - 9).downto(n - 11).map { |x| [x, y] } }
+            bottom_left = 5.downto(0).flat_map { |x| (n - 9).downto(n - 11).map { |y| [x, y] } }
+            words = [FORMAT_COPY1, copy2, top_right, bottom_left].map do |coords|
+              coords.map { |x, y| index.call(x, y) }.freeze
+            end
+            [words[0], words[1], words[2, 2].freeze].freeze
+          end
+        end
+
+        # [FormatInformation, distance] for a format table +entry+ proposed by
+        # one copy; +other+ is the other copy (it may be closer).
+        def candidate(entry, other)
+          info = FormatInformation::ALL[entry >> 2]
+          distance = entry & 3
+          other_distance = popcount15(other ^ info.bits)
+          [info, other_distance < distance ? other_distance : distance]
+        end
+
+        def popcount15(word)
+          POPCOUNT9[word & 511] + POPCOUNT9[word >> 9]
+        end
+
+        def closer(a, b)
+          return b unless a
+          return a unless b
+
+          da = a & 3
+          db = b & 3
+          return a if da < db
+          return b if db < da
+
+          a < b ? a : b
+        end
+
+        def format_table
+          @format_table ||= build_format_table
+        end
+
+        # 32768 entries: (format data bits << 2 | distance) for every 15-bit
+        # word within distance 3 of a format code word, else nil. The code has
+        # minimum distance 7, so these neighbourhoods never overlap. (Plain
+        # loops in a method that runs once: YJIT would spend more time
+        # compiling blocks here than running them.)
+        def build_format_table
+          table = Array.new(1 << 15)
+          data = 0
+          while data < 32
+            code = FormatInformation::ALL[data].bits
+            base = data << 2
+            table[code] = base
+            a = 0
+            while a < 15
+              one = code ^ (1 << a)
+              table[one] = base | 1
+              b = 0
+              while b < a
+                two = one ^ (1 << b)
+                table[two] = base | 2
+                c = 0
+                while c < b
+                  table[two ^ (1 << c)] = base | 3
+                  c += 1
+                end
+                b += 1
+              end
+              a += 1
+            end
+            data += 1
+          end
+          table.freeze
+        end
+      end
+    end
+  end
+end

data/lib/qr_reader/decoder/function_patterns.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module QrReader
+  module Decoder
+    # Which modules of a symbol are function modules (finder patterns with
+    # separators, format and version information, timing patterns, alignment
+    # patterns, dark module) and therefore carry no data. Same regions as
+    # ZXing's Version#buildFunctionPattern.
+    module FunctionPatterns
+      @cache = Array.new(41)
+
+      class << self
+        # Binary String of dimension**2 bytes, row-major, "\x01" for function
+        # modules. Cached per version (1..40).
+        def for_version(number)
+          @cache[number] ||= build(SymbolVersion[number])
+        end
+
+        private
+
+        # (Plain loops: this runs once per version, and YJIT would spend more
+        # time compiling blocks here than running them.)
+        def build(version)
+          n = version.dimension
+          grid = "\0".b * (n * n)
+          fill(grid, n, 0, 0, 9, 9)          # top-left finder + separator + format info
+          fill(grid, n, n - 8, 0, 8, 9)      # top-right finder + separator + format info
+          fill(grid, n, 0, n - 8, 9, 8)      # bottom-left finder + separator + format info + dark module
+          centers = version.alignment_centers
+          last = centers.size - 1
+          iy = 0
+          while iy <= last
+            ix = 0
+            while ix <= last
+              # the three corners occupied by finder patterns carry none
+              finder = (ix.zero? && (iy.zero? || iy == last)) || (ix == last && iy.zero?)
+              fill(grid, n, centers[ix] - 2, centers[iy] - 2, 5, 5) unless finder
+              ix += 1
+            end
+            iy += 1
+          end
+          fill(grid, n, 6, 9, 1, n - 17)     # vertical timing pattern
+          fill(grid, n, 9, 6, n - 17, 1)     # horizontal timing pattern
+          if version.number >= 7
+            fill(grid, n, n - 11, 0, 3, 6)   # version info, top right
+            fill(grid, n, 0, n - 11, 6, 3)   # version info, bottom left
+          end
+          grid.freeze
+        end
+
+        def fill(grid, n, left, top, width, height)
+          row = "\x01".b * width
+          y = top
+          while y < top + height
+            grid[y * n + left, width] = row
+            y += 1
+          end
+        end
+      end
+    end
+  end
+end

data/lib/qr_reader/decoder/galois_field.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module QrReader
+  module Decoder
+    # Arithmetic in GF(256) as used by QR codes: field polynomial
+    # x^8 + x^4 + x^3 + x^2 + 1 (0x11D), primitive element alpha = 2.
+    # Addition is XOR; multiplication goes through log/antilog tables.
+    module GaloisField
+      PRIMITIVE = 0x11D
+
+      exp = Array.new(512, 0)
+      log = Array.new(256, 0)
+      x = 1
+      255.times do |i|
+        exp[i] = x
+        log[x] = i
+        x <<= 1
+        x ^= PRIMITIVE if x > 255
+      end
+      255.upto(511) { |i| exp[i] = exp[i - 255] }
+
+      # EXP[i] = alpha**i for 0 <= i < 512. Doubled in length so that
+      # EXP[LOG[a] + LOG[b]] needs no modulo.
+      EXP = exp.freeze
+      # LOG[a] = discrete log of a (1..255). LOG[0] is undefined (stored as 0).
+      LOG = log.freeze
+
+      # MULTIPLY_BY_ALPHA_POWER[j][s] = s * alpha**j, for j < 31 (enough for the
+      # largest QR block's 30 error correction codewords). Lets a syndrome
+      # Horner step be one Array lookup: s = table[s] ^ codeword.
+      MULTIPLY_BY_ALPHA_POWER = Array.new(31) do |j|
+        Array.new(256) { |s| s.zero? ? 0 : exp[log[s] + j] }.freeze
+      end.freeze
+
+      @multiplication_table = nil
+
+      # Full multiplication table: multiplication_table[a][b] = a * b. Built on
+      # first use because only error correction needs it. Row a is EXP
+      # shifted by LOG[a] and permuted by LOG, gathered at C speed.
+      def self.multiplication_table
+        @multiplication_table ||= begin
+          logs = LOG[1, 255]
+          zero = Array.new(256, 0).freeze
+          Array.new(256) do |a|
+            next zero if a.zero?
+
+            EXP[LOG[a], 255].values_at(*logs).unshift(0).freeze
+          end.freeze
+        end
+      end
+
+      module_function
+
+      def multiply(a, b)
+        a.zero? || b.zero? ? 0 : EXP[LOG[a] + LOG[b]]
+      end
+
+      # a / b for b != 0.
+      def divide(a, b)
+        a.zero? ? 0 : EXP[LOG[a] + 255 - LOG[b]]
+      end
+
+      # alpha**power for any integer power (negative allowed).
+      def power(power)
+        EXP[power % 255]
+      end
+    end
+  end
+end

data/lib/qr_reader/decoder/reed_solomon.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+module QrReader
+  module Decoder
+    # Reed-Solomon error correction for QR code blocks over GF(256) (0x11D).
+    #
+    # The generator polynomial of an EC block with +ec+ codewords has the roots
+    # alpha**0 .. alpha**(ec-1). Decoding computes the syndromes, finds the
+    # error locator with Berlekamp-Massey, its roots with a Chien search and the
+    # error values with Forney's formula, then re-checks the syndromes of the
+    # corrected block. At most floor(ec/2) errors are corrected; anything that
+    # does not lead to a verified codeword is rejected.
+    #
+    # Polynomials are Arrays of coefficients; a block's codewords[0] is the
+    # coefficient of x**(n-1), so codeword i sits at "degree position" n-1-i.
+    module ReedSolomon
+      EXP = GaloisField::EXP
+      LOG = GaloisField::LOG
+      MULTIPLY_BY_ALPHA_POWER = GaloisField::MULTIPLY_BY_ALPHA_POWER
+
+      module_function
+
+      # Corrects +codewords+ (Array of Integers 0..255, data followed by EC
+      # codewords, first element = highest-degree coefficient) in place.
+      # Returns the number of corrected codewords, or nil when the block is
+      # uncorrectable (the Array is then left unchanged).
+      def decode(codewords, ec_count)
+        n = codewords.size
+        return nil if ec_count < 1 || ec_count >= n || n > 255 || ec_count >= MULTIPLY_BY_ALPHA_POWER.size
+
+        syndromes = syndromes(codewords, ec_count)
+        return 0 unless syndromes
+
+        locator = berlekamp_massey(syndromes)
+        errors = locator.size - 1
+        return nil if errors.zero? || 2 * errors > ec_count
+
+        positions = chien_search(locator, n)
+        return nil unless positions
+
+        magnitudes = forney(syndromes, locator, positions)
+        return nil unless magnitudes && corrects_syndromes?(syndromes, positions, magnitudes)
+
+        positions.each_with_index { |e, k| codewords[n - 1 - e] ^= magnitudes[k] }
+        errors
+      end
+
+      # Syndromes S_j = r(alpha**j) for j = 0...ec_count, or nil when all are
+      # zero (the block is a valid codeword). This is the hot path for clean
+      # symbols, so the cheaper of two equivalent methods is used: with a JIT,
+      # Horner's rule over all codewords (allocation-free table lookups);
+      # in the plain interpreter, the remainder r(x) mod g(x) computed with
+      # one Bignum step per codeword, whose syndromes are those of r(x)
+      # because g(alpha**j) = 0 (about 3x faster there).
+      def syndromes(codewords, ec_count)
+        jit? ? horner_syndromes(codewords, ec_count) : remainder_syndromes(codewords, ec_count)
+      end
+
+      # Syndromes by Horner's rule: one lookup and one XOR per codeword and
+      # syndrome. Four syndromes share each pass over the codewords, which
+      # roughly halves the loop overhead.
+      def horner_syndromes(codewords, ec_count)
+        n = codewords.size
+        result = nil
+        j = 0
+        while j + 4 <= ec_count
+          t0 = MULTIPLY_BY_ALPHA_POWER[j]
+          t1 = MULTIPLY_BY_ALPHA_POWER[j + 1]
+          t2 = MULTIPLY_BY_ALPHA_POWER[j + 2]
+          t3 = MULTIPLY_BY_ALPHA_POWER[j + 3]
+          s0 = s1 = s2 = s3 = 0
+          i = 0
+          while i < n
+            c = codewords[i]
+            s0 = t0[s0] ^ c
+            s1 = t1[s1] ^ c
+            s2 = t2[s2] ^ c
+            s3 = t3[s3] ^ c
+            i += 1
+          end
+          if (s0 | s1 | s2 | s3) != 0
+            result ||= Array.new(ec_count, 0)
+            result[j] = s0
+            result[j + 1] = s1
+            result[j + 2] = s2
+            result[j + 3] = s3
+          end
+          j += 4
+        end
+        while j < ec_count
+          table = MULTIPLY_BY_ALPHA_POWER[j]
+          s = 0
+          i = 0
+          while i < n
+            s = table[s] ^ codewords[i]
+            i += 1
+          end
+          if s != 0
+            result ||= Array.new(ec_count, 0)
+            result[j] = s
+          end
+          j += 1
+        end
+        result
+      end
+
+      # Syndromes via the remainder r(x) mod g(x), kept as an Integer of
+      # ec_count bytes (coefficient of x**(ec-1) in the top byte).
+      def remainder_syndromes(codewords, ec_count)
+        table = remainder_table(ec_count)
+        shift = 8 * (ec_count - 1)
+        r = 0
+        i = 0
+        n = codewords.size
+        while i < n
+          r = ((r << 8) | codewords[i]) ^ table[r >> shift]
+          i += 1
+        end
+        return nil if r.zero?
+
+        horner_syndromes([r.to_s(16).rjust(2 * ec_count, "0")].pack("H*").bytes, ec_count)
+      end
+
+      # True when running under a JIT compiler (or a non-CRuby VM).
+      def jit?
+        return true unless RUBY_ENGINE == "ruby"
+
+        yjit = defined?(RubyVM::YJIT) && RubyVM::YJIT.enabled?
+        zjit = defined?(RubyVM::ZJIT) && RubyVM::ZJIT.enabled?
+        yjit || zjit ? true : false
+      end
+
+      @remainder_tables = []
+
+      # remainder_table(ec)[b] = b * g(x) as an Integer of ec + 1 bytes, where
+      # g(x) = (x - alpha**0) ... (x - alpha**(ec-1)) is the monic generator.
+      # The map b -> b * g(x) is GF(2)-linear, so only the eight single-bit
+      # rows need field multiplications; the others are XORs of those.
+      def remainder_table(ec_count)
+        @remainder_tables[ec_count] ||= begin
+          generator = [1]
+          ec_count.times do |i|
+            next_generator = generator + [0]
+            generator.each_with_index { |c, k| next_generator[k + 1] ^= GaloisField.multiply(c, EXP[i]) }
+            generator = next_generator
+          end
+          table = Array.new(256, 0)
+          8.times do |bit|
+            b = 1 << bit
+            table[b] = generator.inject(0) { |acc, c| (acc << 8) | GaloisField.multiply(b, c) }
+          end
+          b = 1
+          while b < 256
+            low = b & -b # lowest set bit; table[b ^ low] is already filled
+            table[b] = table[low] ^ table[b ^ low] unless b == low
+            b += 1
+          end
+          table.freeze
+        end
+      end
+
+      # Error locator polynomial Lambda (coefficients, Lambda[0] = 1) of the
+      # shortest LFSR generating the syndrome sequence. Its length - 1 is the
+      # number of errors assumed (its degree).
+      def berlekamp_massey(syndromes)
+        mul = GaloisField.multiplication_table
+        current = [1]
+        previous = [1]
+        length = 0
+        shift = 1
+        previous_discrepancy = 1
+        count = syndromes.size
+        n = 0
+        while n < count
+          d = syndromes[n]
+          i = 1
+          while i <= length
+            d ^= mul[current[i]][syndromes[n - i]]
+            i += 1
+          end
+          if d.zero?
+            shift += 1
+          else
+            row = mul[EXP[LOG[d] + 255 - LOG[previous_discrepancy]]] # d / previous_discrepancy
+            replaced = 2 * length <= n ? current.dup : nil
+            size = previous.size
+            current << 0 while current.size < size + shift
+            k = 0
+            while k < size
+              current[k + shift] ^= row[previous[k]]
+              k += 1
+            end
+            if replaced
+              length = n + 1 - length
+              previous = replaced
+              previous_discrepancy = d
+              shift = 1
+            else
+              shift += 1
+            end
+          end
+          n += 1
+        end
+        current.pop while current.size > length + 1
+        current << 0 while current.size < length + 1 # degree below length: no valid locator
+        current
+      end
+
+      # Degree positions e (0...n) of the errors: the e with
+      # Lambda(alpha**-e) == 0, by Horner evaluation. Returns nil unless
+      # exactly deg(Lambda) roots lie inside the block.
+      def chien_search(locator, n)
+        mul = GaloisField.multiplication_table
+        errors = locator.size - 1
+        return nil if locator[errors].zero?
+
+        roots = []
+        e = 0
+        while e < n
+          row = mul[EXP[255 - e]] # x = alpha**-e
+          s = locator[errors]
+          k = errors - 1
+          while k >= 0
+            s = row[s] ^ locator[k]
+            k -= 1
+          end
+          if s.zero?
+            roots << e
+            return roots if roots.size == errors
+          end
+          e += 1
+        end
+        nil
+      end
+
+      # Error values by Forney's formula (first consecutive root alpha**0):
+      # e_k = X_k * Omega(X_k^-1) / Lambda'(X_k^-1), Omega = S * Lambda mod x^v.
+      # Returns nil if a value comes out as zero (no valid correction).
+      def forney(syndromes, locator, positions)
+        mul = GaloisField.multiplication_table
+        errors = locator.size - 1
+        omega = Array.new(errors, 0)
+        i = 0
+        while i < errors
+          v = 0
+          k = 0
+          while k <= i
+            v ^= mul[locator[k]][syndromes[i - k]]
+            k += 1
+          end
+          omega[i] = v
+          i += 1
+        end
+
+        count = positions.size
+        magnitudes = Array.new(count)
+        p = 0
+        while p < count
+          e = positions[p]
+          x_inverse = EXP[255 - e]
+          row = mul[x_inverse]
+          numerator = omega[errors - 1]
+          i = errors - 2
+          while i >= 0
+            numerator = row[numerator] ^ omega[i]
+            i -= 1
+          end
+          # Lambda'(x) has only the odd-degree terms (characteristic 2).
+          x_squared = row[x_inverse]
+          denominator = 0
+          power = 1
+          k = 1
+          while k <= errors
+            denominator ^= mul[locator[k]][power]
+            power = mul[power][x_squared]
+            k += 2
+          end
+          return nil if numerator.zero? || denominator.zero?
+
+          magnitudes[p] = EXP[(e + LOG[numerator] + 255 - LOG[denominator]) % 255]
+          p += 1
+        end
+        magnitudes
+      end
+
+      # True if subtracting the error values at the positions zeroes every
+      # syndrome, i.e. the corrected block is a codeword.
+      def corrects_syndromes?(syndromes, positions, magnitudes)
+        mul = GaloisField.multiplication_table
+        count = positions.size
+        locators = Array.new(count) { |k| EXP[positions[k]] }
+        terms = magnitudes.dup # magnitude_k * X_k**j, starting at j = 0
+        j = 0
+        ec_count = syndromes.size
+        while j < ec_count
+          s = syndromes[j]
+          k = 0
+          while k < count
+            term = terms[k]
+            s ^= term
+            terms[k] = mul[term][locators[k]]
+            k += 1
+          end
+          return false unless s.zero?
+
+          j += 1
+        end
+        true
+      end
+    end
+  end
+end