qr_reader 0.0.1

data/lib/qr_reader/detector/perspective_transform.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module QrReader
+  class Detector
+    # A planar projective transform (homography):
+    #
+    #   x' = (m0 x + m1 y + m2) / (m6 x + m7 y + m8)
+    #   y' = (m3 x + m4 y + m5) / (m6 x + m7 y + m8)
+    #
+    # Built from four point correspondences, like ZXing's PerspectiveTransform.
+    class PerspectiveTransform
+      attr_reader :m
+
+      # +m+ - the 9 coefficients, row-major.
+      def initialize(m)
+        @m = m.freeze
+        freeze
+      end
+
+      class << self
+        # Maps quad (x0,y0)..(x3,y3) onto quad (u0,v0)..(u3,v3); points
+        # correspond in order. Returns nil for degenerate quads.
+        def quad_to_quad(src, dst)
+          to_square = square_to_quad(src)&.adjoint
+          from_square = square_to_quad(dst)
+          return unless to_square && from_square
+
+          t = from_square * to_square
+          t.finite? ? t : nil
+        end
+
+        # Maps the unit square (0,0), (1,0), (1,1), (0,1) onto the quad
+        # [[x0, y0], [x1, y1], [x2, y2], [x3, y3]]. nil if degenerate.
+        def square_to_quad(quad)
+          (x0, y0), (x1, y1), (x2, y2), (x3, y3) = quad
+          # Three corners on a line make the quad degenerate.
+          return if collinear?(x3, y3, x0, y0, x1, y1) || collinear?(x0, y0, x1, y1, x2, y2) ||
+                    collinear?(x1, y1, x2, y2, x3, y3) || collinear?(x2, y2, x3, y3, x0, y0)
+
+          dx3 = x0 - x1 + x2 - x3
+          dy3 = y0 - y1 + y2 - y3
+          if dx3.abs < 1e-9 && dy3.abs < 1e-9
+            new([x1 - x0, x3 - x0, x0, y1 - y0, y3 - y0, y0, 0.0, 0.0, 1.0])
+          else
+            dx1 = x1 - x2
+            dx2 = x3 - x2
+            dy1 = y1 - y2
+            dy2 = y3 - y2
+            den = (dx1 * dy2 - dx2 * dy1).to_f
+            return if den.abs < 1e-12
+
+            g = (dx3 * dy2 - dx2 * dy3) / den
+            h = (dx1 * dy3 - dx3 * dy1) / den
+            new([x1 - x0 + g * x1, x3 - x0 + h * x3, x0.to_f,
+                 y1 - y0 + g * y1, y3 - y0 + h * y3, y0.to_f,
+                 g, h, 1.0])
+          end
+        end
+      end
+
+      # True if (bx, by) lies on the line through (ax, ay) and (cx, cy).
+      def self.collinear?(ax, ay, bx, by, cx, cy)
+        ((bx - ax) * (cy - ay) - (by - ay) * (cx - ax)).abs < 1e-9
+      end
+      private_class_method :collinear?
+
+      # Transformed point as [x', y'] (nil if the point maps to infinity).
+      def apply(x, y)
+        m = @m
+        den = m[6] * x + m[7] * y + m[8]
+        return if den.abs < 1e-12
+
+        [(m[0] * x + m[1] * y + m[2]) / den, (m[3] * x + m[4] * y + m[5]) / den]
+      end
+
+      # Matrix product (self after other).
+      def *(other)
+        a = @m
+        b = other.m
+        PerspectiveTransform.new([
+          a[0] * b[0] + a[1] * b[3] + a[2] * b[6],
+          a[0] * b[1] + a[1] * b[4] + a[2] * b[7],
+          a[0] * b[2] + a[1] * b[5] + a[2] * b[8],
+          a[3] * b[0] + a[4] * b[3] + a[5] * b[6],
+          a[3] * b[1] + a[4] * b[4] + a[5] * b[7],
+          a[3] * b[2] + a[4] * b[5] + a[5] * b[8],
+          a[6] * b[0] + a[7] * b[3] + a[8] * b[6],
+          a[6] * b[1] + a[7] * b[4] + a[8] * b[7],
+          a[6] * b[2] + a[7] * b[5] + a[8] * b[8]
+        ])
+      end
+
+      # Adjugate matrix: the inverse up to a scale factor, which is all a
+      # homography needs.
+      def adjoint
+        a0, a1, a2, a3, a4, a5, a6, a7, a8 = @m
+        PerspectiveTransform.new([
+          a4 * a8 - a5 * a7, a2 * a7 - a1 * a8, a1 * a5 - a2 * a4,
+          a5 * a6 - a3 * a8, a0 * a8 - a2 * a6, a2 * a3 - a0 * a5,
+          a3 * a7 - a4 * a6, a1 * a6 - a0 * a7, a0 * a4 - a1 * a3
+        ])
+      end
+
+      def finite?
+        @m.all? { |v| v.finite? }
+      end
+
+      # True if the denominator keeps one sign (no point maps through
+      # infinity) over the quad with corners (x0, y0) and (x1, y1).
+      def regular_over?(x0, y0, x1, y1)
+        m = @m
+        dens = [[x0, y0], [x1, y0], [x1, y1], [x0, y1]].map { |x, y| m[6] * x + m[7] * y + m[8] }
+        dens.all? { |d| d > 1e-9 } || dens.all? { |d| d < -1e-9 }
+      end
+    end
+  end
+end

data/lib/qr_reader/detector/pure_detector.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module QrReader
+  class Detector
+    # Fast path for clean, axis-aligned, unrotated-or-quarter-turned symbols
+    # such as generated images: the symbol is the bounding box of all dark
+    # pixels, three of its corners must hold finder patterns (checked
+    # along the corner diagonals, which also yields the module size), and
+    # modules are sampled at their centres. Costs a few String#index calls
+    # when the image is not such a symbol.
+    module PureDetector
+      DARK = BitMatrix::DARK
+
+      # A detected pure symbol; same interface as Candidate.
+      class Result
+        attr_reader :bits, :points, :finder_patterns, :dimension, :module_size
+
+        def initialize(bits, points, finder_patterns, module_size)
+          @bits = bits
+          @points = points
+          @finder_patterns = finder_patterns
+          @dimension = bits.width
+          @module_size = module_size
+        end
+
+        def alternatives
+          return enum_for(:alternatives) unless block_given?
+
+          nil
+        end
+
+        def uses?(_pattern)
+          false
+        end
+
+        def key
+          @finder_patterns.map { |x, y| [x.round, y.round] }
+        end
+
+        def inspect
+          "#<PureDetector::Result dim=#{@dimension} module_size=#{@module_size.round(2)}>"
+        end
+      end
+
+      module_function
+
+      # Result or nil.
+      def detect(matrix)
+        box = bounding_box(matrix) or return
+        left, top, right, bottom = box
+        width = right - left
+        height = bottom - top
+        return if width < 21 || height < 21 || (width - height).abs > 2 + width / 50
+
+        # Diagonal walks into each corner: TL, TR, BR, BL.
+        corners = [[left, top, 1, 1], [right - 1, top, -1, 1],
+                   [right - 1, bottom - 1, -1, -1], [left, bottom - 1, 1, -1]]
+        sizes = corners.map { |x, y, dx, dy| corner_finder(matrix, x, y, dx, dy, width) }
+        missing = sizes.each_index.select { |i| sizes[i].nil? }
+        return unless missing.size == 1
+
+        module_size = sizes.compact.sum / 3.0
+        dimension = ((width + height) * 0.5 / module_size).round
+        return unless SymbolVersion.for_dimension(dimension)
+
+        mx = width.to_f / dimension
+        my = height.to_f / dimension
+        return if (mx / module_size - 1).abs > 0.2 || (my / module_size - 1).abs > 0.2
+
+        bits = sample(matrix, left, top, mx, my, dimension)
+        # Turn the symbol so that the corner without finder is bottom-right.
+        quarter_turns = (2 - missing.first) % 4
+        bits = rotate(bits, quarter_turns)
+        points = [[left, top], [right, top], [right, bottom], [left, bottom]].rotate(-quarter_turns % 4)
+        mid_x = (left + right) * 0.5
+        mid_y = (top + bottom) * 0.5
+        centre = ->(px, py) { [px + (mid_x <=> px) * 3.5 * mx, py + (mid_y <=> py) * 3.5 * my] }
+        finders = [centre.call(*points[0]), centre.call(*points[1]), centre.call(*points[3])]
+        Result.new(bits, points.map { |x, y| [x.to_f, y.to_f] }, finders, module_size)
+      end
+
+      # [left, top, right, bottom] (right/bottom exclusive) of the dark pixels.
+      def bounding_box(matrix)
+        bits = matrix.bits
+        w = matrix.width
+        first = bits.index(DARK) or return
+        last = bits.rindex(DARK)
+        top = first / w
+        bottom = last / w + 1
+        left = w
+        right = 0
+        y = top
+        off = top * w
+        while y < bottom
+          # No substring per row: the first dark pixel at or after the row
+          # start is in this row, or rows without any are skipped at once.
+          l = bits.index(DARK, off)
+          if l >= off + w
+            y = l / w
+            off = y * w
+            next
+          end
+          left = l - off if l - off < left
+          r = bits.rindex(DARK, off + w - 1)
+          right = r - off + 1 if r - off >= right
+          off += w
+          y += 1
+        end
+        [left, top, right, bottom]
+      end
+
+      # Module size of a finder pattern whose outer corner is at (x, y),
+      # from the 1:1:3:1:1 runs along the diagonal (dx, dy); the edges
+      # leaving the corner must be dark for 7 modules, then light. nil if
+      # there is no finder pattern.
+      def corner_finder(matrix, x, y, dx, dy, limit)
+        runs = diagonal_runs(matrix, x, y, dx, dy, limit)
+        return unless runs.size == 5 && Geometry.finder_ratio?(*runs, relaxed: true)
+
+        module_size = runs.sum / 7.0
+        return unless edge_run?(matrix, x, y, dx, 0, module_size) && edge_run?(matrix, x, y, 0, dy, module_size)
+
+        module_size
+      end
+
+      # Up to five alternating run lengths along a diagonal, starting dark.
+      def diagonal_runs(matrix, x, y, dx, dy, limit)
+        bits = matrix.bits
+        w = matrix.width
+        h = matrix.height
+        runs = [0]
+        dark = true
+        steps = 0
+        while steps < limit && x >= 0 && y >= 0 && x < w && y < h
+          if (bits.getbyte(y * w + x) == 1) == dark
+            runs[-1] += 1
+          else
+            break if runs.size == 5
+
+            runs << 1
+            dark = !dark
+          end
+          x += dx
+          y += dy
+          steps += 1
+        end
+        runs
+      end
+
+      # True if the dark run from (x, y) along (dx, dy) is 7 modules long.
+      def edge_run?(matrix, x, y, dx, dy, module_size)
+        bits = matrix.bits
+        w = matrix.width
+        h = matrix.height
+        n = 0
+        while x >= 0 && y >= 0 && x < w && y < h && bits.getbyte(y * w + x) == 1
+          n += 1
+          x += dx
+          y += dy
+        end
+        (n / module_size - 7).abs < 1.0
+      end
+
+      def sample(matrix, left, top, mx, my, dimension)
+        bits = matrix.bits
+        w = matrix.width
+        out = "\0".b * (dimension * dimension)
+        j = 0
+        while j < dimension
+          y = (top + (j + 0.5) * my).to_i
+          off = y * w
+          i = 0
+          while i < dimension
+            out.setbyte(j * dimension + i, 1) if bits.getbyte(off + (left + (i + 0.5) * mx).to_i) == 1
+            i += 1
+          end
+          j += 1
+        end
+        BitMatrix.new(dimension, dimension, out)
+      end
+
+      # Rotates a square matrix by +turns+ quarter turns clockwise.
+      def rotate(matrix, turns)
+        turns.times do
+          n = matrix.width
+          src = matrix.bits
+          out = "\0".b * (n * n)
+          n.times do |y|
+            n.times { |x| out.setbyte(x * n + (n - 1 - y), src.getbyte(y * n + x)) }
+          end
+          matrix = BitMatrix.new(n, n, out)
+        end
+        matrix
+      end
+    end
+  end
+end

data/lib/qr_reader/detector.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require_relative "binarizer"
+require_relative "kernels/detector"
+require_relative "detector/geometry"
+require_relative "detector/finder_pattern"
+require_relative "detector/finder_pattern_finder"
+require_relative "detector/pattern_sets"
+require_relative "detector/perspective_transform"
+require_relative "detector/grid_sampler"
+require_relative "detector/alignment_pattern_finder"
+require_relative "detector/alignment_grid"
+require_relative "detector/candidate"
+require_relative "detector/pure_detector"
+
+module QrReader
+  # Locates QR symbols in a binarized image and samples their module grids.
+  #
+  #   detector = QrReader::Detector.new(QrReader::Binarizer.hybrid(image), image: image)
+  #   detector.each_candidate do |candidate|
+  #     result = QrReader::Decoder.decode(candidate.bits) ||
+  #              candidate.alternatives.lazy.filter_map { |bits| QrReader::Decoder.decode(bits) }.first
+  #     break result if result
+  #   end
+  #
+  # Candidates are produced lazily, most likely first: finder patterns are
+  # searched once per mode and cached; every plausible triple of them is
+  # scored (PatternSets) and turned into a Candidate whose module grid is
+  # only sampled when asked for.
+  class Detector
+    # Finder pattern triples tried per mode.
+    FAST_TRIPLES = 12
+    HARD_TRIPLES = 40
+    MULTI_TRIPLES = 120
+    # With multi, up to this many finder patterns are considered...
+    MULTI_PATTERNS = 400
+    # ... and at most this many "foreign" triples (with other finder
+    # patterns inside, see PatternSets.partition_clean): on pages with
+    # several symbols nearly all triples joining finders of different
+    # symbols are foreign, real symbols practically never.
+    MULTI_FOREIGN = 12
+    # Score penalty of foreign triples in single-symbol mode (a perfect
+    # triple scores 0, see PatternSets.evaluate).
+    FOREIGN_PENALTY = 0.5
+    # Besides the best scored triples overall, each finder pattern is
+    # combined with pairs of this many of its nearest neighbours.
+    NEIGHBOURS = 8
+
+    attr_reader :matrix, :image
+
+    # Fast path for clean axis-aligned symbols (see PureDetector);
+    # returns a candidate or nil.
+    def self.detect_pure(matrix)
+      PureDetector.detect(matrix)
+    end
+
+    # +matrix+ - binarized image (BitMatrix, 1 = dark)
+    # +image+  - the grayscale Image it came from (optional; ignored unless
+    #            it has the matrix's size)
+    def initialize(matrix, image: nil)
+      @matrix = matrix
+      @image = image if image && image.width == matrix.width && image.height == matrix.height
+      @finder = FinderPatternFinder.new(matrix)
+      @confirmed = []
+    end
+
+    # Yields Candidates, most likely first (Enumerator without a block).
+    # Candidates whose timing patterns read like noise (false finder
+    # triples, mostly) are only produced with try_harder, after all others
+    # (with multi, the FAST_TRIPLES best of those that span no other finder
+    # pattern).
+    #
+    # try_harder: scan every row and try more finder pattern triples.
+    # multi: look for all symbols - also triples of neighbouring finder
+    # patterns (pages with many symbols), skipping triples that share a
+    # finder pattern with (or lie inside) a candidate passed to #confirm.
+    def each_candidate(try_harder: false, multi: false)
+      return enum_for(:each_candidate, try_harder: try_harder, multi: multi) unless block_given?
+
+      patterns, triples = multi ? multi_triples(try_harder) : single_triples(try_harder)
+      deferred = []
+      triples.each do |triple|
+        next if multi && confirmed?(triple)
+
+        candidate = Candidate.locate(self, triple) or next
+        if candidate.likely?
+          yield candidate
+        elsif try_harder && !(multi && spans_others?(candidate, patterns))
+          deferred << candidate
+        end
+      end
+      deferred = deferred.first(FAST_TRIPLES) if multi
+      deferred.each { |candidate| yield candidate unless multi && confirmed?(candidate) }
+      nil
+    end
+
+    # Records a decoded symbol, so that multi-symbol detection skips
+    # triples that reuse its finder patterns or lie inside it: a Candidate
+    # (or detect_pure result), anything else with #points (e.g. a Result
+    # decoded earlier from another binarization of the same image, its
+    # points scaled to this matrix), or the corner quad [[x, y], ...]
+    # itself. Returns self.
+    def confirm(symbol)
+      quad = symbol.is_a?(Array) ? symbol : symbol.points
+      if quad.is_a?(Array) && quad.size == 4 && quad.flatten.all? { |v| v.is_a?(Numeric) && v.finite? }
+        @confirmed << [quad, symbol.respond_to?(:uses?) ? symbol : nil]
+      end
+      self
+    end
+
+    # Finder patterns found in the image (cached per mode).
+    def finder_patterns(try_harder: false)
+      @finder.find(try_harder: try_harder)
+    end
+
+    def alignment_finder
+      @alignment_finder ||= AlignmentPatternFinder.new(@matrix)
+    end
+
+    # True if the bit matrix is the negative of the image (dark cells are
+    # brighter on average), e.g. when a caller inverted it to read
+    # light-on-dark symbols; luminance sampling then flips its comparison.
+    def inverted_image?
+      return @inverted_image unless @inverted_image.nil?
+
+      @inverted_image = false
+      return false unless @image && @image.width == @matrix.width && @image.height == @matrix.height
+
+      data = @image.data
+      bits = @matrix.bits
+      step = [data.bytesize / 4096, 1].max
+      sums = [0, 0]
+      counts = [0, 0]
+      i = 0
+      while i < data.bytesize
+        b = bits.getbyte(i)
+        sums[b] += data.getbyte(i)
+        counts[b] += 1
+        i += step
+      end
+      @inverted_image = counts.all?(&:positive?) && sums[1] * counts[0] > sums[0] * counts[1]
+    end
+
+    private
+
+    # [patterns, triples] for single-symbol detection: the best scored
+    # triples of the most consistent finder patterns and of each pattern's
+    # nearest neighbours, those with other symbols' finder patterns inside
+    # (foreign, see PatternSets.partition_clean) ranked as if their score
+    # were FOREIGN_PENALTY worse: on a sheet of labels the best shaped
+    # triples join finders of neighbouring symbols, but a large symbol
+    # with small modules can have finder look-alikes in its data area and
+    # must still beat the ill-shaped triples of those look-alikes.
+    def single_triples(try_harder)
+      patterns = finder_patterns(try_harder: try_harder)
+      limit = try_harder ? HARD_TRIPLES : FAST_TRIPLES
+      clean, foreign = ranked_triples(PatternSets.generate(patterns, 4 * limit), patterns, patterns)
+      ranked = clean.each_with_index.map { |t, i| [t.score, i, t] }
+      foreign.each_with_index { |t, i| ranked << [t.score + FOREIGN_PENALTY, clean.size + i, t] }
+      [patterns, ranked.sort!.first(limit).map(&:last)]
+    end
+
+    # [patterns, triples] for multi-symbol detection: as for a single
+    # symbol, but from up to MULTI_PATTERNS patterns and MULTI_TRIPLES
+    # triples (a page with that many symbols), MULTI_FOREIGN of them
+    # foreign.
+    def multi_triples(try_harder)
+      all = @finder.find(try_harder: try_harder, limit: MULTI_PATTERNS)
+      best = if all.size > FinderPatternFinder::MAX_PATTERNS
+               all.max_by(FinderPatternFinder::MAX_PATTERNS) { |p| p.quality * Math.sqrt(p.count) }
+             else
+               all
+             end
+      clean, foreign = ranked_triples(PatternSets.generate(best, MULTI_TRIPLES), all, all)
+      [all, (clean + foreign.first(MULTI_FOREIGN)).first(MULTI_TRIPLES)]
+    end
+
+    # +triples+ plus the neighbourhood triples of +near+, split into
+    # [clean, foreign] (see PatternSets.partition_clean against +all+), the
+    # clean ones best first.
+    def ranked_triples(triples, near, all)
+      seen = triples.to_h { |t| [t.patterns.map(&:object_id), true] }
+      PatternSets.neighbourhood(near, NEIGHBOURS).each do |t|
+        triples << t unless seen[t.patterns.map(&:object_id)]
+      end
+      clean, foreign = PatternSets.partition_clean(triples, all)
+      [clean.sort_by!(&:score), foreign]
+    end
+
+    # True if a triple (or candidate) shares a finder pattern with a
+    # confirmed symbol or has one inside it.
+    def confirmed?(set)
+      patterns = set.respond_to?(:patterns) ? set.patterns : [set.tl, set.tr, set.bl]
+      @confirmed.any? do |quad, owner|
+        patterns.any? { |p| owner&.uses?(p) || inside?(quad, p.x, p.y) }
+      end
+    end
+
+    # True if a finder pattern other than the candidate's own lies inside
+    # its symbol area.
+    def spans_others?(candidate, patterns)
+      quad = candidate.points
+      patterns.any? { |p| !candidate.uses?(p) && inside?(quad, p.x, p.y) }
+    end
+
+    # Point-in-convex-quad test (either winding).
+    def inside?(quad, x, y)
+      signs = quad.each_with_index.map do |(x0, y0), i|
+        x1, y1 = quad[(i + 1) % 4]
+        (x1 - x0) * (y - y0) - (y1 - y0) * (x - x0)
+      end
+      signs.all?(&:positive?) || signs.all?(&:negative?)
+    end
+  end
+end

data/lib/qr_reader/errors.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module QrReader
+  class Error < StandardError; end
+
+  # The input could not be turned into an image (unknown or corrupt format).
+  class ImageError < Error; end
+
+  # The image format was recognised but is not supported (e.g. arithmetic-coded JPEG).
+  class UnsupportedImageError < ImageError; end
+
+  # Raised by QrReader.decode! when no QR code could be read.
+  class NotFoundError < Error; end
+end

data/lib/qr_reader/format_information.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module QrReader
+  # The 15-bit format information word: error correction level + mask pattern,
+  # protected by a BCH(15,5) code and XOR-masked with 0x5412.
+  class FormatInformation
+    MASK = 0x5412
+    GENERATOR = 0x537
+
+    attr_reader :ec_level, :mask, :bits
+
+    def initialize(data_bits)
+      @ec_level = SymbolVersion::EC_LEVEL_FOR_BITS[(data_bits >> 3) & 0x03]
+      @mask = data_bits & 0x07
+      @bits = self.class.encode(data_bits)
+      freeze
+    end
+
+    def ==(other)
+      other.is_a?(FormatInformation) && other.bits == bits
+    end
+    alias eql? ==
+
+    def hash
+      bits.hash
+    end
+
+    def inspect
+      "#<QrReader::FormatInformation ec=#{@ec_level} mask=#{@mask}>"
+    end
+
+    class << self
+      # 15-bit masked code word for 5 data bits (2 EC level bits + 3 mask bits).
+      def encode(data_bits)
+        rem = data_bits
+        10.times { rem = (rem << 1) ^ ((rem >> 9) * GENERATOR) }
+        ((data_bits << 10) | rem) ^ MASK
+      end
+
+      # Decodes the two 15-bit copies read from a symbol (pass the same value
+      # twice when only one copy is available). Returns the FormatInformation
+      # closest in Hamming distance to either copy if that distance is <= 3,
+      # else nil. Also accepts copies that lack the 0x5412 XOR mask, as
+      # written by some broken encoders.
+      def decode(bits1, bits2 = bits1)
+        closest(bits1, bits2) || closest(bits1 ^ MASK, bits2 ^ MASK)
+      end
+
+      def closest(bits1, bits2)
+        best = nil
+        best_distance = 4
+        ALL.each do |info|
+          code = info.bits
+          return info if code == bits1 || code == bits2
+
+          distance = popcount(bits1 ^ code)
+          d2 = popcount(bits2 ^ code)
+          distance = d2 if d2 < distance
+          if distance < best_distance
+            best = info
+            best_distance = distance
+          end
+        end
+        best
+      end
+
+      def popcount(value)
+        count = 0
+        while value != 0
+          value &= value - 1
+          count += 1
+        end
+        count
+      end
+    end
+
+    ALL = (0..31).map { |d| new(d) }.freeze
+  end
+end