qr_reader 0.0.1

data/lib/qr_reader/detector/geometry.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module QrReader
+  class Detector
+    # Small geometric helpers shared by the detector parts.
+    module Geometry
+      module_function
+
+      # Lengths (in 1 px steps) of the first three runs - dark, light, dark -
+      # met walking from (x, y) along the unit vector (ux, uy); the first
+      # run includes the start point, which must be dark. The last run may
+      # end at the image border. nil if the start is light, the walk leaves
+      # the image earlier, or the runs exceed +limit+ steps. With +noise+, a
+      # single step of the other colour followed by two of the run's colour
+      # does not end a run.
+      def runs(matrix, x, y, ux, uy, limit, noise: false)
+        bits = matrix.bits
+        w = matrix.width
+        h = matrix.height
+        counts = [0, 0, 0]
+        state = 0
+        colour = 1
+        t = 0
+        while t <= limit
+          px = x + ux * t
+          py = y + uy * t
+          return state == 2 ? counts : nil unless px >= 0 && py >= 0 && px < w && py < h
+
+          c = bits.getbyte(py.to_i * w + px.to_i)
+          if c != colour
+            if noise && t.positive? && bit(bits, w, h, x + ux * (t + 1), y + uy * (t + 1)) == colour &&
+               bit(bits, w, h, x + ux * (t + 2), y + uy * (t + 2)) == colour
+              c = colour
+            else
+              return if t.zero?
+
+              state += 1
+              return counts if state == 3
+
+              colour = c
+            end
+          end
+          counts[state] += 1
+          t += 1
+        end
+        nil
+      end
+
+      # Bit at continuous position (x, y); nil outside the image.
+      def bit(bits, w, h, x, y)
+        bits.getbyte(y.to_i * w + x.to_i) if x >= 0 && y >= 0 && x < w && y < h
+      end
+
+      # 1:1:3:1:1 test: each run within 0.5 module (0.75 if relaxed) plus
+      # half a pixel of its nominal width, the centre run 0.25 module more;
+      # or the dot gain tolerant test (dark and light runs measured against
+      # their own module sizes, see QrReaderKernels::FinderScanner#gain_ratio?).
+      def finder_ratio?(a, b, c, d, e, relaxed: false)
+        total = a + b + c + d + e
+        return false if total < 7
+
+        # In units of 1/28 module.
+        tol = (relaxed ? 3 * total : 2 * total) + 14
+        return true if (28 * a - 4 * total).abs <= tol &&
+                       (28 * b - 4 * total).abs <= tol &&
+                       (28 * c - 12 * total).abs <= tol + total &&
+                       (28 * d - 4 * total).abs <= tol &&
+                       (28 * e - 4 * total).abs <= tol
+
+        gain_ratio?(a, b, c, d, e)
+      end
+
+      # 1:1:3:1:1 under dot gain or loss (see finder_ratio?).
+      def gain_ratio?(a, b, c, d, e)
+        dark = a + c + e
+        light = b + d
+        return false if dark < 10 || light.zero? || dark > 10 * light || 5 * light > 8 * dark
+
+        tol = 2 * dark + 10
+        (20 * a - 4 * dark).abs <= tol && (20 * c - 12 * dark).abs <= tol && (20 * e - 4 * dark).abs <= tol &&
+          (6 * b - 3 * light).abs <= light + 3 && (6 * d - 3 * light).abs <= light + 3
+      end
+
+      # Least-squares line through +points+ as [x, y, vx, vy] (centroid and
+      # unit direction); nil if the RMS distance of the points from the
+      # line exceeds +max_rms+.
+      def fit_line(points, max_rms)
+        n = points.size.to_f
+        mx = points.sum { |x, _| x } / n
+        my = points.sum { |_, y| y } / n
+        sxx = sxy = syy = 0.0
+        points.each do |x, y|
+          dx = x - mx
+          dy = y - my
+          sxx += dx * dx
+          sxy += dx * dy
+          syy += dy * dy
+        end
+        angle = 0.5 * Math.atan2(2 * sxy, sxx - syy)
+        vx = Math.cos(angle)
+        vy = Math.sin(angle)
+        # Residual = spread perpendicular to the direction.
+        rms = Math.sqrt(((vy * vy * sxx) - (2 * vx * vy * sxy) + (vx * vx * syy)).abs / n)
+        rms > max_rms ? nil : [mx, my, vx, vy]
+      end
+
+      # Intersection point [x, y] of two lines given as [x, y, vx, vy];
+      # nil if they are (nearly) parallel.
+      def intersect_lines(a, b)
+        cross = a[2] * b[3] - a[3] * b[2]
+        return if cross.abs < 0.05
+
+        t = ((b[0] - a[0]) * b[3] - (b[1] - a[1]) * b[2]) / cross
+        [a[0] + a[2] * t, a[1] + a[3] * t]
+      end
+    end
+  end
+end

data/lib/qr_reader/detector/grid_sampler.rb

@@ -0,0 +1,350 @@
+# frozen_string_literal: true
+
+module QrReader
+  class Detector
+    # Reads the module grid of a symbol through a PerspectiveTransform
+    # that maps module coordinates (module (i, j) covers [i, i + 1) x
+    # [j, j + 1)) to continuous pixel coordinates:
+    #
+    # * sample           - from the binarized image, one or more transforms
+    #                      (piecewise), optionally voting over five pixels
+    # * sample_warped    - the same plus a separable displacement field
+    # * sample_luminance - from the grayscale image, thresholding module
+    #                      luminances against their neighbourhood
+    #
+    # Modules whose centre falls outside the image read as light.
+    module GridSampler
+      # Scale of the fixed-point arithmetic of sample_row / vote_row.
+      FIXED_ONE = (1 << 24).to_f
+      # Scaled coordinates beyond this (pixels about 2**30 away) are not
+      # sampled, so that the stepping stays within Fixnum range.
+      FIXED_LIMIT = 2.0**54
+
+      module_function
+
+      # Samples a dimension x dimension grid. +regions+ lists
+      # [x0, x1, y0, y1, transform], each covering modules x0...x1 and
+      # y0...y1 (use whole(d, transform) for a single transform). With an
+      # +offset+ (pixels; an Integer or [horizontal, vertical], see
+      # vote_offsets) a module is the majority vote of its centre pixel and
+      # the four pixels that far left, right, above and below it, which
+      # ignores isolated noise.
+      def sample(matrix, dimension, regions, offset: 0)
+        out = "\0".b * (dimension * dimension)
+        bits = matrix.bits
+        w = matrix.width
+        h = matrix.height
+        ox, oy = offset_pair(offset)
+        regions.each do |x0, x1, y0, y1, transform|
+          m = transform.m
+          my = y0
+          while my < y1
+            if ox > 0 || oy > 0
+              vote_row(bits, w, h, out, my * dimension, m, my + 0.5, x0, x1, ox, oy)
+            else
+              sample_row(bits, w, h, out, my * dimension, m, my + 0.5, x0, x1)
+            end
+            my += 1
+          end
+        end
+        BitMatrix.new(dimension, dimension, out)
+      end
+
+      # Samples a grid through +transform+ plus a separable pixel
+      # displacement: module (mx, my) is read at
+      # transform(mx + 0.5, my + 0.5) + col_shift[mx] + row_shift[my], where
+      # the shifts are [dx, dy] pairs (see Candidate#warped_sample).
+      def sample_warped(matrix, dimension, transform, col_shift, row_shift, offset: 0)
+        out = "\0".b * (dimension * dimension)
+        bits = matrix.bits
+        w = matrix.width
+        h = matrix.height
+        ox, oy = offset_pair(offset)
+        m = transform.m
+        my = 0
+        while my < dimension
+          v = my + 0.5
+          rdx, rdy = row_shift[my]
+          base = my * dimension
+          mx = 0
+          while mx < dimension
+            u = mx + 0.5
+            den = m[6] * u + m[7] * v + m[8]
+            if den > 1e-9 || den < -1e-9
+              cdx, cdy = col_shift[mx]
+              px = (m[0] * u + m[1] * v + m[2]) / den + cdx + rdx
+              py = (m[3] * u + m[4] * v + m[5]) / den + cdy + rdy
+              if px >= 0.0 && py >= 0.0 && px < w && py < h && dark_vote?(bits, w, h, px.to_i, py.to_i, ox, oy)
+                out.setbyte(base + mx, 1)
+              end
+            end
+            mx += 1
+          end
+          my += 1
+        end
+        BitMatrix.new(dimension, dimension, out)
+      end
+
+      # Samples the grid from the grayscale +image+ instead of the binarized
+      # one: each module's luminance is the mean of its centre pixel and the
+      # pixels a quarter module away (bilinear at the centre for modules
+      # under 3 px), and a module is dark if it is darker than the mean of
+      # the (2r+1) x (2r+1) modules around it. +regions+ as in
+      # sample. Keeps information the binarization lost (blur, uneven light,
+      # small modules). +inverted+ reads light-on-dark symbols. +offset+
+      # overrides the quarter module offsets derived from +module_size+
+      # (see vote_offsets).
+      def sample_luminance(image, dimension, regions, module_size, radius: 4, inverted: false, offset: nil)
+        lum = Array.new(dimension * dimension, 0)
+        ox, oy = offset_pair(offset || vote_offset(module_size))
+        regions.each do |x0, x1, y0, y1, transform|
+          m = transform.m
+          my = y0
+          while my < y1
+            luminance_row(image.data, image.width, image.height, lum, my * dimension, m, my + 0.5, x0, x1, ox, oy)
+            my += 1
+          end
+        end
+        grid = threshold_grid(lum, dimension, radius)
+        inverted ? grid.invert : grid
+      end
+
+      # The region list covering a whole grid with one transform.
+      def whole(dimension, transform)
+        [[0, dimension, 0, dimension, transform]]
+      end
+
+      # Majority sampling offset for a module size: a quarter module, none
+      # below 3 px.
+      def vote_offset(module_size)
+        module_size >= 3 ? (module_size / 4.0).round : 0
+      end
+
+      # [horizontal, vertical] majority sampling offsets for the modules
+      # of +transform+ at the centre of a dimension x dimension grid: a
+      # quarter of the module's horizontal (vertical) chord through its
+      # centre, none below 3 px. Unlike vote_offset this keeps the samples
+      # inside modules that are not square in the image - fax pages
+      # (204 x 98 dpi), strong perspective.
+      def vote_offsets(transform, dimension)
+        c = dimension * 0.5
+        o = transform.apply(c, c) or return [0, 0]
+        u = transform.apply(c + 1, c) or return [0, 0]
+        v = transform.apply(c, c + 1) or return [0, 0]
+        ux = u[0] - o[0]
+        uy = u[1] - o[1]
+        vx = v[0] - o[0]
+        vy = v[1] - o[1]
+        area = (ux * vy - uy * vx).abs
+        horizontal = area / [uy.abs, vy.abs].max
+        vertical = area / [ux.abs, vx.abs].max
+        [chord_offset(horizontal), chord_offset(vertical)]
+      end
+
+      def chord_offset(chord)
+        chord.finite? && chord >= 3 ? (chord / 4.0).round : 0
+      end
+
+      # [ox, oy] from an Integer or a pair.
+      def offset_pair(offset)
+        offset.is_a?(Array) ? offset : [offset, offset]
+      end
+
+      # Like sample_row, voting over five pixels per module: the centre and
+      # those +ox+ left and right, +oy+ above and below.
+      def vote_row(bits, w, h, out, off, m, v, x0, x1, ox, oy)
+        nx, ny, nd, sx, sy, sd = fixed_row(m, v, x0, x1)
+        return unless nx
+
+        max_x = w - 1
+        max_y = h - 1
+        mx = x0
+        while mx < x1
+          if nd != 0
+            ix = nx / nd
+            iy = ny / nd
+            if ix >= 0 && iy >= 0 && ix < w && iy < h
+              row = iy * w
+              l = ix - ox
+              l = 0 if l < 0
+              r = ix + ox
+              r = max_x if r > max_x
+              t = iy - oy
+              t = 0 if t < 0
+              b = iy + oy
+              b = max_y if b > max_y
+              votes = bits.getbyte(row + ix) + bits.getbyte(row + l) + bits.getbyte(row + r) +
+                      bits.getbyte(t * w + ix) + bits.getbyte(b * w + ix)
+              out.setbyte(off + mx, 1) if votes >= 3
+            end
+          end
+          nx += sx
+          ny += sy
+          nd += sd
+          mx += 1
+        end
+      end
+
+      # Fixed-point stepping along a module row: the transform's numerators
+      # and denominator at module (x0 + 0.5, v) and their increments per
+      # module, as Integers scaled so that the denominator's magnitude is
+      # about FIXED_ONE. Pixel (nx / nd, ny / nd) is then found with integer
+      # floor division, which is exact up to rounding of the scaled values
+      # and 3x faster than Float arithmetic. nil if the row is degenerate.
+      def fixed_row(m, v, x0, x1)
+        u = x0 + 0.5
+        d0 = m[6] * u + m[7] * v + m[8]
+        d1 = d0 + m[6] * (x1 - x0 - 1)
+        d0a = d0.abs
+        d1a = d1.abs
+        mag = d0a > d1a ? d0a : d1a
+        return unless mag > 1e-12 && mag < Float::INFINITY
+
+        s = FIXED_ONE / mag
+        nx = (m[0] * u + m[1] * v + m[2]) * s
+        ny = (m[3] * u + m[4] * v + m[5]) * s
+        # Rows far outside the image would need Bignums; they read as light.
+        return unless nx.abs < FIXED_LIMIT && ny.abs < FIXED_LIMIT && (m[0] * s).abs < FIXED_LIMIT &&
+                      (m[3] * s).abs < FIXED_LIMIT
+
+        [nx.round, ny.round, (d0 * s).round, (m[0] * s).round, (m[3] * s).round, (m[6] * s).round]
+      end
+
+      # Mean luminance (x 4, as Integer) of modules x0...x1 of one module
+      # row: half the centre pixel, an eighth each of the pixels +ox+ left
+      # and right, +oy+ above and below (bilinear at the centre if both are 0).
+      def luminance_row(data, w, h, lum, off, m, v, x0, x1, ox, oy)
+        bx = m[1] * v + m[2]
+        by = m[4] * v + m[5]
+        bd = m[7] * v + m[8]
+        m0 = m[0]
+        m3 = m[3]
+        m6 = m[6]
+        mx = x0
+        while mx < x1
+          u = mx + 0.5
+          den = m6 * u + bd
+          value = 1020
+          if den > 1e-9 || den < -1e-9
+            px = (m0 * u + bx) / den
+            py = (m3 * u + by) / den
+            if px >= 0.0 && py >= 0.0 && px < w && py < h
+              ix = px.to_i
+              iy = py.to_i
+              value =
+                if ox == 0 && oy == 0
+                  bilinear4(data, w, h, px - 0.5, py - 0.5)
+                else
+                  l = ix - ox
+                  l = 0 if l < 0
+                  r = ix + ox
+                  r = w - 1 if r >= w
+                  t = iy - oy
+                  t = 0 if t < 0
+                  b = iy + oy
+                  b = h - 1 if b >= h
+                  c = iy * w
+                  (4 * data.getbyte(c + ix) + data.getbyte(c + l) + data.getbyte(c + r) +
+                   data.getbyte(t * w + ix) + data.getbyte(b * w + ix)) >> 1
+                end
+            end
+          end
+          lum[off + mx] = value
+          mx += 1
+        end
+      end
+
+      # Bilinearly interpolated luminance x 4 at continuous pixel position
+      # (x, y) measured from pixel centres.
+      def bilinear4(data, w, h, x, y)
+        x = 0.0 if x.negative?
+        y = 0.0 if y.negative?
+        ix = x.to_i
+        iy = y.to_i
+        ix1 = ix + 1 < w ? ix + 1 : ix
+        iy1 = iy + 1 < h ? iy + 1 : iy
+        fx = x - ix
+        fy = y - iy
+        top = data.getbyte(iy * w + ix) * (1 - fx) + data.getbyte(iy * w + ix1) * fx
+        bottom = data.getbyte(iy1 * w + ix) * (1 - fx) + data.getbyte(iy1 * w + ix1) * fx
+        ((top + (bottom - top) * fy) * 4).round
+      end
+
+      # BitMatrix of modules darker than their neighbourhood mean (summed
+      # area table over the module luminances).
+      def threshold_grid(lum, n, radius)
+        stride = n + 1
+        sat = Array.new(stride * stride, 0)
+        y = 0
+        while y < n
+          row_sum = 0
+          x = 0
+          while x < n
+            row_sum += lum[y * n + x]
+            sat[(y + 1) * stride + x + 1] = sat[y * stride + x + 1] + row_sum
+            x += 1
+          end
+          y += 1
+        end
+        out = "\0".b * (n * n)
+        y = 0
+        while y < n
+          y0 = y - radius
+          y0 = 0 if y0.negative?
+          y1 = y + radius + 1
+          y1 = n if y1 > n
+          x = 0
+          while x < n
+            x0 = x - radius
+            x0 = 0 if x0.negative?
+            x1 = x + radius + 1
+            x1 = n if x1 > n
+            sum = sat[y1 * stride + x1] - sat[y0 * stride + x1] - sat[y1 * stride + x0] + sat[y0 * stride + x0]
+            out.setbyte(y * n + x, 1) if lum[y * n + x] * (y1 - y0) * (x1 - x0) < sum
+            x += 1
+          end
+          y += 1
+        end
+        BitMatrix.new(n, n, out)
+      end
+
+      # Majority of the pixel (ix, iy) and the pixels +ox+ left and right,
+      # +oy+ above and below (just the pixel when both are 0).
+      def dark_vote?(bits, w, h, ix, iy, ox, oy)
+        row = iy * w
+        return bits.getbyte(row + ix) == 1 if ox == 0 && oy == 0
+
+        l = ix - ox
+        l = 0 if l < 0
+        r = ix + ox
+        r = w - 1 if r >= w
+        t = iy - oy
+        t = 0 if t < 0
+        b = iy + oy
+        b = h - 1 if b >= h
+        bits.getbyte(row + ix) + bits.getbyte(row + l) + bits.getbyte(row + r) +
+          bits.getbyte(t * w + ix) + bits.getbyte(b * w + ix) >= 3
+      end
+
+      # Samples modules x0...x1 of the module row at height v (a module
+      # centre) into out[off + x].
+      def sample_row(bits, w, h, out, off, m, v, x0, x1)
+        nx, ny, nd, sx, sy, sd = fixed_row(m, v, x0, x1)
+        return unless nx
+
+        mx = x0
+        while mx < x1
+          if nd != 0
+            ix = nx / nd
+            iy = ny / nd
+            out.setbyte(off + mx, 1) if ix >= 0 && iy >= 0 && ix < w && iy < h && bits.getbyte(iy * w + ix) == 1
+          end
+          nx += sx
+          ny += sy
+          nd += sd
+          mx += 1
+        end
+      end
+    end
+  end
+end

data/lib/qr_reader/detector/pattern_sets.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module QrReader
+  class Detector
+    # Chooses which finder patterns may form a symbol (like zxing-cpp's
+    # GenerateFinderPatternSets): every combination of three patterns with
+    # similar module sizes is scored by how close it comes to an isosceles
+    # right triangle and how well the module sizes agree; implausible ones
+    # (angle off by more than 45 degrees, legs differing by more than 2.6x,
+    # impossible module counts) are dropped.
+    module PatternSets
+      COS_45 = Math.cos(Math::PI / 4)
+      # Legs may differ by up to this factor: perspective, and pixels that
+      # are not square (standard resolution fax pages: 204 x 98 dpi).
+      MAX_LEG_RATIO = 2.6
+      # Module sizes within one symbol may differ by up to this factor.
+      MAX_SIZE_RATIO = 2.5
+
+      # A scored triple. bl, tl, tr are ordered so that tl is the corner and
+      # (tr - tl) x (bl - tl) > 0 (clockwise tl -> tr -> bl on screen) -
+      # a mirrored symbol appears with tr and bl swapped.
+      Triple = Struct.new(:bl, :tl, :tr, :score) do
+        def patterns
+          [bl, tl, tr]
+        end
+      end
+
+      module_function
+
+      # Up to +limit+ triples, best first.
+      def generate(patterns, limit)
+        sorted = patterns.sort_by(&:module_size)
+        n = sorted.size
+        sets = []
+        i = 0
+        while i < n - 2
+          a = sorted[i]
+          j = i + 1
+          while j < n - 1
+            b = sorted[j]
+            break if b.module_size > a.module_size * MAX_SIZE_RATIO
+
+            k = j + 1
+            while k < n
+              c = sorted[k]
+              break if c.module_size > a.module_size * MAX_SIZE_RATIO
+
+              set = evaluate(a, b, c)
+              sets << set if set
+              k += 1
+            end
+            j += 1
+          end
+          i += 1
+        end
+        sets.sort_by!(&:score)
+        sets.first(limit)
+      end
+
+      # Triples formed by each pattern and two of its +k+ nearest neighbours
+      # of similar module size, best first. Unlike #generate this scales to
+      # pages with many symbols (label sheets), where the best-shaped
+      # triples of a global search mostly join finders of different symbols
+      # laid out on a regular grid.
+      def neighbourhood(patterns, k)
+        sets = {}
+        patterns.each do |b|
+          nearest(patterns, b, k).combination(2) do |a, c|
+            next unless similar_size?(a, c)
+
+            set = evaluate(a, b, c) or next
+            sets[[set.bl, set.tl, set.tr].map(&:object_id)] ||= set
+          end
+        end
+        sets.values.sort_by!(&:score)
+      end
+
+      # The (up to) k patterns of a similar module size nearest to +b+.
+      def nearest(patterns, b, k)
+        near = []
+        dists = []
+        bx = b.x
+        by = b.y
+        size = b.module_size
+        i = 0
+        n = patterns.size
+        while i < n
+          p = patterns[i]
+          i += 1
+          next if p.equal?(b) || p.module_size >= size * MAX_SIZE_RATIO || size >= p.module_size * MAX_SIZE_RATIO
+
+          dx = p.x - bx
+          dy = p.y - by
+          d = dx * dx + dy * dy
+          next if near.size == k && d >= dists[-1]
+
+          j = dists.bsearch_index { |e| e > d } || dists.size
+          dists.insert(j, d)
+          near.insert(j, p)
+          if near.size > k
+            dists.pop
+            near.pop
+          end
+        end
+        near
+      end
+
+      # Splits +triples+ into [clean, foreign]: foreign triples have at least
+      # two other patterns of a similar module size inside (or within 1.5
+      # modules of) their symbol area, the parallelogram of the three
+      # finder centres. A triple joining finders of neighbouring symbols on
+      # a sheet of labels always has (the finders of the symbol it spans lie
+      # on its edges); a real symbol has at most a false pattern or so in
+      # its data area - its neighbours' finders are 7 modules plus the quiet
+      # zone away. Foreign triples come with the fewest such patterns first.
+      def partition_clean(triples, patterns)
+        by_x = patterns.sort_by(&:x)
+        xs = by_x.map(&:x)
+        counted = triples.map { |t| [foreign_count(t, by_x, xs), t] }
+        clean, foreign = counted.partition { |count, _| count < 2 }
+        [clean.map(&:last), foreign.sort_by { |count, t| [count, t.score] }.map(&:last)]
+      end
+
+      # True if +triple+ is foreign (see partition_clean). +by_x+ are the
+      # patterns sorted by x, +xs+ their x coordinates.
+      def foreign?(triple, by_x, xs)
+        foreign_count(triple, by_x, xs) >= 2
+      end
+
+      # Number of patterns (other than the triple's own, of similar module
+      # size) inside the triple's parallelogram or within 1.5 modules of it,
+      # counted up to +cap+. Points are tested in the parallelogram's own
+      # coordinates (tl + s * (tr - tl) + t * (bl - tl)), with the margin
+      # converted to s and t units.
+      def foreign_count(triple, by_x, xs, cap = 4)
+        tl = triple.tl
+        tr = triple.tr
+        bl = triple.bl
+        x0 = tl.x
+        y0 = tl.y
+        ux = tr.x - x0
+        uy = tr.y - y0
+        vx = bl.x - x0
+        vy = bl.y - y0
+        det = ux * vy - uy * vx
+        return 0 if det.zero?
+
+        size = (tl.module_size + tr.module_size + bl.module_size) / 3.0
+        margin = 1.5 * size
+        ms = margin * Math.hypot(vx, vy) / det.abs
+        mt = margin * Math.hypot(ux, uy) / det.abs
+        corners_x = [x0, x0 + ux, x0 + ux + vx, x0 + vx]
+        corners_y = [y0, y0 + uy, y0 + uy + vy, y0 + vy]
+        min_x = corners_x.min - margin
+        max_x = corners_x.max + margin
+        min_y = corners_y.min - margin
+        max_y = corners_y.max + margin
+        i = xs.bsearch_index { |x| x >= min_x } or return 0
+        count = 0
+        n = by_x.size
+        while i < n
+          p = by_x[i]
+          i += 1
+          px = p.x
+          break if px > max_x
+
+          py = p.y
+          next if py < min_y || py > max_y || p.equal?(tl) || p.equal?(tr) || p.equal?(bl)
+          next unless p.module_size < size * MAX_SIZE_RATIO && p.module_size * MAX_SIZE_RATIO > size
+
+          dx = px - x0
+          dy = py - y0
+          s = (dx * vy - dy * vx) / det
+          t = (ux * dy - uy * dx) / det
+          next unless s > -ms && s < 1 + ms && t > -mt && t < 1 + mt
+
+          count += 1
+          return count if count >= cap
+        end
+        count
+      end
+
+      def similar_size?(p, q)
+        p.module_size < q.module_size * MAX_SIZE_RATIO && q.module_size < p.module_size * MAX_SIZE_RATIO
+      end
+
+      # Scores one combination; nil if it cannot be a symbol.
+      def evaluate(a, b, c)
+        ab = dist2(a, b)
+        bc = dist2(b, c)
+        ac = dist2(a, c)
+        # Make b the corner (opposite the longest side, which becomes ac).
+        if bc >= ab && bc >= ac
+          a, b = b, a
+          bc, ac = ac, bc
+        elsif ab >= bc && ab >= ac
+          b, c = c, b
+          ab, ac = ac, ab
+        end
+        return if ab <= 0 || bc <= 0
+
+        dab = Math.sqrt(ab)
+        dbc = Math.sqrt(bc)
+        return if dab > MAX_LEG_RATIO * dbc || dbc > MAX_LEG_RATIO * dab
+
+        mean_size = (a.module_size + b.module_size + c.module_size) / 3.0
+        modules = (dab + dbc) / (2 * mean_size) + 7
+        return if modules < 21 * 0.8 || modules > 177 * 1.4
+
+        cos = (ab + bc - ac) / (2 * dab * dbc)
+        return if cos.abs > COS_45
+
+        # 0 for an isosceles right triangle, scale invariant.
+        shape = ((ac - 2 * ab).abs + (ac - 2 * bc).abs) / ac
+        sizes = [a.module_size, b.module_size, c.module_size]
+        size_spread = sizes.max / sizes.min - 1.0
+        score = shape + 2 * size_spread + 0.5 * (1.0 - [a.quality, b.quality, c.quality].min)
+
+        a, c = c, a if cross(b, c, a).negative?
+        Triple.new(a, b, c, score)
+      end
+
+      def dist2(p, q)
+        dx = p.x - q.x
+        dy = p.y - q.y
+        dx * dx + dy * dy
+      end
+
+      # z component of (c - b) x (a - b).
+      def cross(b, c, a)
+        (c.x - b.x) * (a.y - b.y) - (c.y - b.y) * (a.x - b.x)
+      end
+    end
+  end
+end