qrio 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fd4e00a1a67e02acd047f575462bc7998fdf534d
+  data.tar.gz: e2f71bd39d091c83d3266ed82817dd04bd509717
+SHA512:
+  metadata.gz: 1ee2434d16b4c5aecc718adc92aa33720b8f50b56057b3613f2d0484329c7e981c293952a14f03e86d2a5d141e064b51722fd728d5faa98e46e9277edf795005
+  data.tar.gz: 674c0edb17097ede3282e38c6585ec12a3cd005da0d9f46104f5f8c7efd38cc4b629636b2f26a490892a192ba5b5a9a1ad961d4694e1b4a9035e9662e49ea4d2

data/.gitignore

@@ -0,0 +1,5 @@
+.bundle
+.rvmrc
+Gemfile.lock
+vendor/bundle
+tmp

data/.rvmrc.example

@@ -0,0 +1 @@
+rvm use 1.9.2@qrio --create

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/README.md

@@ -0,0 +1,66 @@
+# QRio
+
+QRio is a QR code decoder for Ruby
+
+## Usage
+
+QRio can extract QR contents in one step:
+
+    require 'qrio'
+    puts Qrio::Qr.load("some-image.png").qr.text
+
+If you know / are curious about the decoding process, QRio can generate
+an image illustrating the intermediate steps to decoding:
+
+    require 'qrio'
+    qr = Qrio::Qr.load("some-image.png")
+
+    qr.save_image(
+      "some-image-annotated.png",
+      :crop => true,      # crop output image to detected QR bounds
+      :annotate => [
+        :finder_patterns, # outline detected finder patterns
+        :angles           # draw lines connecting finder pattern centers
+      ]
+    )
+
+
+
+
+## Dependencies
+
+* Ruby 1.9.2 (will be backported to 1.8.7)
+* ChunkyPNG (tested with version 1.2.0)
+
+## STATUS
+
+*NOTE* : QRio is not yet fully functional.  If you'd like to help out, fork and
+submit a tested pull request.  :)
+
+### TODO
+
+* support numeric / alphanumeric / kanji mode QR codes
+* refine alignment pattern location and adjust module sampling grid
+  accordingly
+* error correction support
+* support more image formats (limited to PNG at the moment)
+* native thresholding for input images
+* support more QR versions
+* speed improvements
+
+### Does *anything* work?
+
+Yeah, it's coming along.  Here's what should be working now:
+
+* find and extract a QR code from an image.  I've been cheating
+  somewhat, using image magick to threshold the image for me:
+
+      convert raw.jpg -colorspace Gray -lat 90x90-3% -median 1x1 cooked.png
+
+* detect and correct orientation of extracted QR
+* extract modules via a sampling grid
+* extract raw bytes from data / error correction blocks
+* de-interlace blocks into final bitstream
+* extract text from bitstream (ascii mode only)
+
+

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rake/testtask'
+
+Rake::TestTask.new('test') do |t|
+  t.pattern = 'test/**/*_test.rb'
+  t.warning = true
+end
+
+task :default => :test

data/examples/extract_qr

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+require_relative '../lib/qrio'
+$stdout.sync = true
+
+filename = ARGV.shift || nil
+if filename.nil?
+  puts "Usage #{ $0 } filename"
+  exit 1
+end
+
+qr = Qrio::Qr.load(filename)
+
+qr.save_image(
+  'debug.png',
+  :crop => true,
+  :annotate => [:matches, :finder_patterns, :angles,
+    :alignment_patterns, :extracted_pixels]
+)

data/lib/qrio.rb

@@ -0,0 +1,15 @@
+require 'chunky_png'
+
+require_relative 'qrio/region'
+require_relative 'qrio/finder_pattern_slice'
+require_relative 'qrio/horizontal_match'
+require_relative 'qrio/vertical_match'
+require_relative 'qrio/neighbor'
+require_relative 'qrio/matrix'
+require_relative 'qrio/qr_matrix'
+require_relative 'qrio/sampling_grid'
+
+require_relative 'qrio/image_dumper'
+require_relative 'qrio/image_loader/png_image_loader'
+
+require_relative 'qrio/qr'

data/lib/qrio/finder_pattern_slice.rb

@@ -0,0 +1,136 @@
+module Qrio
+  # QR codes have a finder pattern in three corners.  any horizontal or
+  # vertical slice through the center square will be a band of:
+  # black, white, black, white, black, with widths matching ratio:
+  # 1, 1, 3, 1, 1.  According to spec, the tolerance should be +/- 0.5.
+  class FinderPatternSlice < Region
+    ONE   = 0.5..1.5
+    THREE = 2.1..3.9 # not to spec, but required for some "in-the-wild" QR
+
+    ENDPOINT_TOLERANCE = 0.05 # origin/terminus delta between adjacent slices
+    OFFSET_TOLERANCE   = 0.25 # how many non-matching slices can be skipped?
+
+    LENGTH_TOLERANCE = 0.35 # allowed length delta bewteen 2 intersecting slices
+    WIDTH_TOLERANCE  = 0.15 # allowed width delta bewteen 2 intersecting slices
+
+    attr_accessor :neighbors
+    attr_reader :offset, :origin, :terminus
+
+    def initialize(*args)
+      @neighbors = []
+      super
+    end
+
+    def to_s
+      "#{ class_name_prefix }[#{ to_coordinates.join(',') }]"
+    end
+
+    def class_name_prefix
+      self.class.to_s.gsub(/^.*::/, '')[0,1]
+    end
+
+    def aspect_ratio
+      breadth / length.to_f
+    end
+
+    # based on the 1, 1, 3, 1, 1 width ratio, a finder pattern has total
+    # width of 7.  an ideal grouped slice would then have aspect ratio
+    # of 3/7, since slice breadth would be 3 (just the center square)
+    # and length would be 7 (entire slice)
+    def matches_aspect_ratio?
+      (0.25..0.59).include? aspect_ratio
+    end
+    
+
+    class << self
+      # given a width buffer extracted from a given coordinate, test
+      # for ratio matching.  if it matches, return a match object of
+      # the appropriate orientation
+      def build_matching(offset, origin, widths, direction)
+        return nil unless matches_ratio?(widths)
+
+        match_class = direction == :horizontal ? HorizontalMatch : VerticalMatch
+        terminus = origin + widths.inject(0){|s,w| s + w } - 1
+
+        match_class.build(offset, origin, terminus)
+      end
+
+      def matches_ratio?(widths)
+        norm = normalized_ratio(widths)
+
+        ONE.include?(norm[0]) &&
+        ONE.include?(norm[1]) &&
+        THREE.include?(norm[2]) &&
+        ONE.include?(norm[3]) &&
+        ONE.include?(norm[4])
+      end
+
+      def normalized_ratio(widths)
+        scale = (widths[0] + widths[1] + widths[3] + widths[4]) / 4.0
+        widths.map{|w| w / scale }
+      end
+    end
+
+    def <=>(other)
+      return -1 if offset < other.offset
+      return  1 if offset > other.offset
+      origin <=> other.origin
+    end
+
+    def intersects?(other)
+      ! orientation_matches?(other) &&
+      (other.origin..other.terminus).include?(offset) &&
+      (origin..terminus).include?(other.offset) &&
+      length_matches?(other) &&
+      breadth_matches?(other)
+    end
+
+    def adjacent?(other)
+      endpoints_match?(other) && offset_matches?(other)
+    end
+
+    def endpoints_match?(other)
+      origin_matches?(other) && terminus_matches?(other)
+    end
+
+    def origin_diff(other)
+      (origin - other.origin).abs / length.to_f
+    end
+
+    def origin_matches?(other)
+      origin_diff(other) <= ENDPOINT_TOLERANCE
+    end
+
+    def terminus_diff(other)
+      (terminus - other.terminus).abs / length.to_f
+    end
+
+    def terminus_matches?(other)
+      terminus_diff(other) <= ENDPOINT_TOLERANCE
+    end
+
+    def normalized_offset_diff(other)
+      offset_diff(other) / length.to_f
+    end
+
+    def offset_matches?(other)
+      normalized_offset_diff(other) <= OFFSET_TOLERANCE
+    end
+
+    def length_diff(other)
+      (length - other.length).abs / length.to_f
+    end
+
+    def length_matches?(other)
+      length_diff(other) <= LENGTH_TOLERANCE
+    end
+
+    def breadth_diff(other)
+      (breadth - other.breadth).abs / breadth.to_f
+    end
+
+    def breadth_matches?(other)
+      breadth_diff(other) <= WIDTH_TOLERANCE
+    end
+  end
+end

data/lib/qrio/horizontal_match.rb

@@ -0,0 +1,31 @@
+module Qrio
+  class HorizontalMatch < FinderPatternSlice
+    def self.build(offset, origin, terminus)
+      new(origin, offset, terminus, offset)
+    end
+
+    def offset;   top;   end
+    def origin;   left;  end
+    def terminus; right; end
+
+    def length
+      width
+    end
+
+    def breadth
+      height
+    end
+
+    def above?(other)
+      other.top > bottom
+    end
+
+    def below?(other)
+      other.bottom < top
+    end
+
+    def offset_diff(other)
+      above?(other) ? other.top - bottom : top - other.bottom
+    end
+  end
+end

data/lib/qrio/image_dumper.rb

@@ -0,0 +1,97 @@
+module Qrio
+  # this module contains the code to dump images of QR decoding
+  # progress.  useful for debugging or those curious about the
+  # detection / decoding algorithms
+  module ImageDumper
+    def save_image(filename, options={})
+      if matrix = @extracted_matrix
+        # extracted matrix is already cropped
+        options[:crop] = false
+        @features = {
+          :candidates      => {},
+          :matches         => @translated_matches,
+          :finder_patterns => @sampling_grid.finder_patterns
+        }
+      else
+        matrix = @input_matrix
+        @features = {
+          :candidates      => @candidates,
+          :matches         => @matches,
+          :finder_patterns => @finder_patterns
+        }
+      end
+
+      save_to_image(matrix, filename, options)
+    end
+
+    def save_to_image(matrix, filename, options={})
+      png = ChunkyPNG::Image.new(
+        matrix.width,
+        matrix.height,
+        ChunkyPNG::Color::WHITE
+      )
+
+      (0..(matrix.width - 1)).to_a.each do |x|
+        (0..(matrix.height - 1)).to_a.each do |y|
+          png[x, y] = ChunkyPNG::Color::BLACK if matrix[x, y]
+        end
+      end
+
+      if options[:annotate].include?(:candidates)
+        @features[:candidates][:horizontal].each do |hmatch|
+          png.rect(*hmatch.to_coordinates, color(:green))
+        end
+
+        @features[:candidates][:vertical].each do |vmatch|
+          png.rect(*vmatch.to_coordinates, color(:magenta))
+        end
+      end
+
+      if options[:annotate].include?(:matches)
+        @features[:matches][:horizontal].each do |hmatch|
+          png.rect(*hmatch.to_coordinates, color(:green))
+        end
+
+        @features[:matches][:vertical].each do |vmatch|
+          png.rect(*vmatch.to_coordinates, color(:magenta))
+        end
+      end
+
+      if options[:annotate].include?(:finder_patterns)
+        @features[:finder_patterns].each do |finder_pattern|
+          png.rect(*finder_pattern.to_coordinates, color(:red))
+        end
+      end
+
+      if options[:annotate].include?(:angles)
+        @sampling_grid.angles[0, 100].each do |angle|
+          png.line_xiaolin_wu(*angle.to_coordinates, color(:cyan))
+        end
+      end
+
+      if options[:annotate].include?(:alignment_patterns)
+        png.rect(*@alignment_pattern.to_coordinates, color(:magenta))
+      end
+
+      if options[:annotate].include?(:extracted_pixels)
+        @sampling_grid.extracted_pixels do |x, y|
+          png.circle(x, y, 1, color(:cyan))
+        end
+      end
+
+      png = png.crop(*@qr_bounds.to_point_size) if options[:crop]
+      png.save(filename, :fast_rgba)
+    end
+
+    def color(name)
+      rgb = {
+        :green   => [  0, 255,   0],
+        :red     => [255,   0,   0],
+        :magenta => [227,  91, 216],
+        :cyan    => [  0, 255, 255],
+      }[name]
+
+      ChunkyPNG::Color.rgb(*rgb)
+    end
+  end
+end

data/lib/qrio/image_loader/png_image_loader.rb

@@ -0,0 +1,18 @@
+module Qrio
+  module ImageLoader
+    class PNGImageLoader
+      def self.load(filename)
+        image = ChunkyPNG::Image.from_file(filename)
+
+        bits = image.pixels.map do |pixel|
+          grayscale = ChunkyPNG::Color.to_grayscale(pixel)
+          level = ChunkyPNG::Color.r(grayscale)
+          level <= 126
+        end
+
+        Matrix.new(bits, image.width, image.height)
+      end
+    end
+  end
+end
+

data/lib/qrio/matrix.rb

@@ -0,0 +1,72 @@
+module Qrio
+  class Matrix
+    attr_reader :width, :height
+
+    def initialize(bits, width, height)
+      @bits   = bits
+      @width  = width
+      @height = height
+    end
+
+    def to_s
+      "<Matrix width:#{ width }, height: #{ height }>"
+    end
+
+    def [](x, y)
+      rows[y][x] rescue nil
+    end
+
+    def []=(x, y, value)
+      raise "Matrix index out of bounds" if x >= width || y >= height
+      @bits[(width * y) + x] = value
+      @rows = @columns = nil
+    end
+
+    def rows
+      @rows ||= begin
+        rows = []
+        bits = @bits.dup
+
+        while row = bits.slice!(0, @width)
+          break if row.nil? || row.empty?
+          rows << row
+        end
+
+        rows
+      end
+    end
+
+    def columns
+      @columns ||= begin
+        columns = []
+        width.times do |index|
+          column = []
+
+          rows.each do |row|
+            column << row[index]
+          end
+
+          columns << column
+        end
+
+        columns
+      end
+    end
+
+    def rotate
+      new_bits = []
+      columns.each do |column|
+        new_bits += column.reverse
+      end
+      self.class.new(new_bits, @height, @width)
+    end
+
+    def extract(x, y, width, height)
+      new_bits = []
+      height.times do |offset|
+        new_bits += rows[y + offset].slice(x, width)
+      end
+      self.class.new(new_bits, width, height)
+    end
+  end
+end