mork 0.6.0 → 0.7.0

data/lib/mork/mimage.rb

@@ -1,27 +1,25 @@
-require 'mini_magick'
 require 'mork/npatch'
+require 'mork/magicko'
 
 module Mork
-  # The class Mimage manages the image. It is also a wrapper for the core image library
-  # currently mini_magick. TODO: consider moving out the interaction with mini_magick.
+  # The class Mimage processes the image.
   # Note that Mimage is NOT intended as public API, it should only be called by SheetOMR
   class Mimage
+    attr_reader :rm
+
     def initialize(path, nitems, grom)
-      @path   = path
-      @grom   = grom
+      @mack   = Magicko.new path
       @nitems = nitems
-      @grom.set_page_size width, height
-      @rm   = {} # registration mark centers
-      @rmsa = {} # registration mark search area
+      @grom   = grom.set_page_size @mack.width, @mack.height
+      @rm     = {} # registration mark centers
       @valid = register
-      @writing = nil
-      @cmd = []
+      # @writing = nil
     end
-    
+
     def valid?
       @valid
     end
-    
+
     def status
       {
         tl: @rm[:tl][:status],
@@ -31,132 +29,70 @@ module Mork
         write: @writing
       }
     end
-    
+
     def marked?(q,c)
       shade_of(q,c) < choice_threshold
     end
-    
+
     def barcode_bit?(i)
       reg_pixels.average(@grom.barcode_bit_area i+1) < barcode_threshold
     end
-    
-    def width
-      img_size[0].to_i
-    end
-    
-    def height
-      img_size[1].to_i
-    end
-        
-    # outline(cells, roundedness)
-    # 
-    # draws on the Mimage a set of cell outlines
-    # typically used to highlight the expected responses
-    def outline(cells, roundedness=nil)
+
+    def outline(cells)
       return if cells.empty?
-      @cmd << [:stroke, 'green']
-      @cmd << [:strokewidth, '2']
-      @cmd << [:fill, 'none']
-      coordinates_of(cells).each do |c|
-        roundedness ||= [c[:h], c[:w]].min / 2
-        pts = [c[:x], c[:y], c[:x]+c[:w], c[:y]+c[:h], roundedness, roundedness].join ' '
-        @cmd << [:draw, "roundrectangle #{pts}"]
-      end
+      @mack.outline coordinates_of(cells)
     end
-    
-    def highlight_all_choices
-      cells = (0...@grom.max_questions).collect { |i| (0...@grom.max_choices_per_question).to_a }
-      highlight_cells cells
-    end
-    
+
     # highlight_cells(cells, roundedness)
-    # 
+    #
     # partially transparent yellow on top of choice cells
-    def highlight_cells(cells, roundedness=nil)
+    def highlight_cells(cells)
       return if cells.empty?
-      @cmd << [:stroke, 'none']
-      @cmd << [:fill, 'rgba(255, 255, 0, 0.3)']
-      coordinates_of(cells).each do |c|
-        roundedness ||= [c[:h], c[:w]].min / 2
-        pts = [c[:x], c[:y], c[:x]+c[:w], c[:y]+c[:h], roundedness, roundedness].join ' '
-        @cmd << [:draw, "roundrectangle #{pts}"]
-      end
+      @mack.highlight_cells coordinates_of(cells)
     end
-    
-    def highlight_reg_area
-      highlight_rect [@rmsa[:tl], @rmsa[:tr], @rmsa[:br], @rmsa[:bl]]
-      return unless valid?
-      join [@rm[:tl], @rm[:tr], @rm[:br], @rm[:bl]]
+
+    def highlight_all_choices
+      cells = (0...@grom.max_questions).collect { |i| (0...@grom.max_choices_per_question).to_a }
+      highlight_cells cells
     end
-    
+
     def highlight_barcode(bitstring)
-      highlight_rect @grom.barcode_bit_areas bitstring
+      @mack.highlight_rect @grom.barcode_bit_areas bitstring
     end
-    
-    def highlight_rect(areas)
-      return if areas.empty?
-      @cmd << [:fill, 'none']
-      @cmd << [:stroke, 'yellow']
-      @cmd << [:strokewidth, 3]
-      areas.each do |c|
-        pts = [c[:x], c[:y], c[:x]+c[:w], c[:y]+c[:h]].join ' '
-        @cmd << [:draw, "rectangle #{pts}"]
-      end
+
+    def highlight_rm_centers
+      each_corner { |c| @mack.plus @rm[c][:x], @rm[c][:y], 20 }
+    end
+
+    def highlight_rm_areas
+      each_corner { |c| @mack.highlight_area @grom.rm_crop_area(c) }
     end
-    
+
     def cross(cells)
       return if cells.empty?
       cells = [cells] if cells.is_a? Hash
-      @cmd << [:stroke, 'red']
-      @cmd << [:strokewidth, '3']
-      coordinates_of(cells).each do |c|
-        pts = [
-          c[:x]+corner,
-          c[:y]+corner,
-          c[:x]+c[:w]-corner,
-          c[:y]+c[:h]-corner
-        ].join ' '
-        @cmd << [:draw, "line #{pts}"]
-        pts = [
-          c[:x]+corner,
-          c[:y]+c[:h]-corner,
-          c[:x]+c[:w]-corner,
-          c[:y]+corner
-        ].join ' '
-        @cmd << [:draw, "line #{pts}"]
-      end
+      @mack.cross coordinates_of(cells)
     end
-    
+
     # write the underlying MiniMagick::Image to disk;
     # if no file name is given, image is processed in-place;
     # if the 2nd arg is false, then stretching is not applied
     def write(fname=nil, reg=true)
-      if fname
-        MiniMagick::Tool::Convert.new(false) do |img|
-          img << @path
-          exec_mm_cmd img, reg
-          img << fname
-        end
-      else
-        MiniMagick::Tool::Mogrify.new(false) do |img|
-          img << @path
-          exec_mm_cmd img, reg
-        end
-      end
+      pp = reg ? @rm : nil
+      @mack.write fname, pp
     end
-    
+
     # ============================================================#
     private                                                       #
     # ============================================================#
-    def exec_mm_cmd(c, reg)
-      c.distort(:perspective, perspective_points) if reg
-      @cmd.each { |cmd| c.send *cmd }
+    def each_corner
+      [:tl, :tr, :br, :bl].each { |c| yield c }
     end
-    
+
     def shade_of(q,c)
       choice_cell_averages[q][c]
     end
-    
+
     def choice_cell_averages
       @choice_cell_averages ||= begin
         @nitems.each_with_index.collect do |cho, q|
@@ -166,109 +102,98 @@ module Mork
         end
       end
     end
-    
+
+    # TODO: 0.75 should be a parameter
     def choice_threshold
       @choice_threshold ||= (cal_cell_mean - darkest_cell_mean) * 0.75 + darkest_cell_mean
     end
-    
+
     def barcode_threshold
       @barcode_threshold ||= (paper_white + ink_black) / 2
-    end    
+    end
 
     def cal_cell_mean
       @grom.calibration_cell_areas.collect { |c| reg_pixels.average c }.mean
     end
 
     def darkest_cell_mean
-      @choice_cell_averages.flatten.min
+      choice_cell_averages.flatten.min
     end
 
     def ink_black
       reg_pixels.average @grom.ink_black_area
     end
-    
+
     def paper_white
       reg_pixels.average @grom.paper_white_area
     end
-    
-    def img_size
-      @img_size ||= IO.read("|identify -format '%w,%h' #{@path}").split ','
-    end
-    
-    def raw_pixels
-      @raw_pixels ||= begin
-        bytes = IO.read("|convert #{@path} gray:-").unpack 'C*'
-        NPatch.new bytes, width, height
-      end
-    end
-    
+
     def reg_pixels
-      @reg_pixels ||= begin
-        bytes = IO.read("|convert #{@path} -distort Perspective '#{perspective_points}' gray:-").unpack 'C*'
-        NPatch.new bytes, width, height
-      end
-    end
-    
-    def perspective_points
-      [
-        @rm[:tl][:x], @rm[:tl][:y],     0,      0,
-        @rm[:tr][:x], @rm[:tr][:y], width,      0,
-        @rm[:br][:x], @rm[:br][:y], width, height,
-        @rm[:bl][:x], @rm[:bl][:y],     0, height
-      ].join ' '
+      @reg_pixels ||= NPatch.new @mack.registered_bytes(@rm), @mack.width, @mack.height
     end
 
-    def join(p)
-      @cmd << [:fill, 'none']
-      @cmd << [:stroke, 'green']
-      @cmd << [:strokewidth, 3]
-      pts = [p[0][:x], p[0][:y], p[1][:x], p[1][:y], p[2][:x], p[2][:y], p[3][:x], p[3][:y]].join ' '
-      @cmd << [:draw, "polygon #{pts}"]
-    end
-        
     def coordinates_of(cells)
       cells.collect.each_with_index do |q, i|
         q.collect { |c| @grom.choice_cell_area(i, c) }
       end.flatten
     end
-    
-    def corner
-      @corner_size ||= @grom.cell_corner_size
-    end
 
+    # find the XY coordinates of the 4 registration marks,
+    # plus the stdev of the search area as quality control
     def register
-      # find the XY coordinates of the 4 registration marks
-      @rm[:tl] = reg_centroid_on(:tl)
-      # puts "TL: #{@rm[:tl][:status].inspect}"
-      @rm[:tr] = reg_centroid_on(:tr)
-      # puts "TR: #{@rm[:tr][:status].inspect}"
-      @rm[:br] = reg_centroid_on(:br)
-      # puts "BR: #{@rm[:br][:status].inspect}"
-      @rm[:bl] = reg_centroid_on(:bl)
-      # puts "BL: #{@rm[:bl][:status].inspect}"
-      @rm.all? { |k,v| v[:status] == :ok }      
+      each_corner { |c| @rm[c] = rm_centroid_on c }
+      # puts "TL: #{@rm[:tl].inspect}"
+      # puts "TR: #{@rm[:tr].inspect}"
+      # puts "BR: #{@rm[:br].inspect}"
+      # puts "BL: #{@rm[:bl].inspect}"
+      @rm.all? { |k,v| v[:status] == :ok }
     end
-    
+
     # returns the centroid of the dark region within the given area
     # in the XY coordinates of the entire image
-    def reg_centroid_on(corner)
-      1000.times do |i|
-        @rmsa[corner] = @grom.rm_search_area(corner, i)
-        # puts "================================================================"
-        # puts "Corner #{corner} - Iteration #{i} - Coo #{@rmsa[corner].inspect}"
-        cx, cy = raw_pixels.dark_centroid @rmsa[corner]
-        if cx.nil?
-          status = :no_contrast  
-        elsif (cx < @grom.rm_edgy_x) or
-              (cy < @grom.rm_edgy_y) or
-              (cy > @rmsa[corner][:h] - @grom.rm_edgy_y) or
-              (cx > @rmsa[corner][:w] - @grom.rm_edgy_x)
-          status = :edgy
-        else
-          return {status: :ok, x: cx + @rmsa[corner][:x], y: cy + @rmsa[corner][:y]}
-        end
-        return {status: status, x: nil, y: nil} if @rmsa[corner][:w] > @grom.rm_max_search_area_side
-      end
+    def rm_centroid_on(corner)
+      c = @grom.rm_crop_area(corner)
+      p = @mack.rm_patch(c, @grom.rm_blur, @grom.rm_dilate)
+      # puts "REG #{@grom.rm_blur} - #{@grom.rm_dilate} - C #{c.inspect}"
+      n = NPatch.new(p, c.w, c.h)
+      cx, cy, sd = n.centroid
+      st = (cx < 2) or (cy < 2) or (cy > c.h-2) or (cx > c.w-2)
+      status = st ? :edgy : :ok
+      return {x: cx+c.x, y: cy+c.y, sd: sd, status: status}
     end
   end
 end
+
+# def corner
+#   @corner_size ||= @grom.cell_corner_size
+# end
+
+# 1000.times do |i|
+#   @rmsa[corner] = @grom.rm_search_area(corner, i)
+#   # puts "================================================================"
+#   # puts "Corner #{corner} - Iteration #{i} - Coo #{@rmsa[corner].inspect}"
+#   cx, cy = raw_pixels.dark_centroid @rmsa[corner]
+#   if cx.nil?
+#     status = :no_contrast
+#   elsif (cx < @grom.rm_edgy_x) or
+#         (cy < @grom.rm_edgy_y) or
+#         (cy > @rmsa[corner][:h] - @grom.rm_edgy_y) or
+#         (cx > @rmsa[corner][:w] - @grom.rm_edgy_x)
+#     status = :edgy
+#   else
+#     return {status: :ok, x: cx + @rmsa[corner][:x], y: cy + @rmsa[corner][:y]}
+#   end
+#   return {status: status, x: nil, y: nil} if @rmsa[corner][:w] > @grom.rm_max_search_area_side
+# end
+
+# TAKE OUT
+# def highlight_reg_area
+#   @mack.highlight_rect [@rmsa[:tl], @rmsa[:tr], @rmsa[:br], @rmsa[:bl]]
+#   return unless valid?
+#   @mack.join [@rm[:tl], @rm[:tr], @rm[:br], @rm[:bl]]
+# end
+
+# def raw_pixels
+#   @mack.raw_patch
+# end
+

data/lib/mork/npatch.rb

@@ -1,58 +1,39 @@
 require 'narray'
 
 module Mork
-  # NPatch handles low-level computations on pixels
-  # it is basically a wrapper around NArray
+  # NPatch handles low-level computations on pixels by leveraging NArray
   class NPatch
+    # NPatch.new(source, width, height) constructs an NPatch object
+    # from the `source` linear array of bytes, to be reshaped as a
+    # `width` by `height` matrix
     def initialize(source, width, height)
-      @patch = NArray.byte(width, height)
-      @patch[true] = case source
-                     when Array
-                       source
-                     when String
-                       IO.read("|convert #{source} gray:-").unpack 'C*'
-                     else
-                       raise 'Invalid NPatch init param'
-                     end
+      @patch = NArray.float(width, height)
+      @patch[true] = source
       @width  = width
       @height = height
     end
-    
-    def average(c=nil)
-      crop(c).mean
+
+    def average(c)
+      @patch[c.x_rng, c.y_rng].mean
     end
-    
-    def stddev(c=nil)
-      crop(c).stddev
+
+    def stddev(c)
+      @patch[c.x_rng, c.y_rng].stddev
     end
-    
+
     def length
+      # is this only going to be used for testing purposes?
       @patch.length
     end
-    
-    def dark_centroid(c = nil)
-      p = crop c
-      sufficient_contrast?(p) or return
-      xp = p.sum(1).to_a
-      yp = p.sum(0).to_a
-      # find the intensity trough
-      ctr_x = xp.find_index(xp.min)
-      ctr_y = yp.find_index(yp.min)
-      # puts "Centroid: #{ctr_x}, #{ctr_y} - MinX #{xp.min/xp.length}, MaxX #{xp.max/xp.length}, MinY #{yp.min/yp.length}, MaxY #{yp.max/yp.length}"
-      return ctr_x, ctr_y
+
+    def centroid
+      xp = @patch.sum(1).to_a
+      yp = @patch.sum(0).to_a
+      return xp.find_index(xp.min), yp.find_index(yp.min), @patch.stddev
     end
-    
+
     private
-    
-    def crop(c)
-      c =  {x: 0, y: 0, w: @width, h: @height} if c.nil?
-      x = c[:x]...c[:x]+c[:w]
-      y = c[:y]...c[:y]+c[:h]
-      p = NArray.float c[:w], c[:h]
-      p[true,true] = @patch[x, y]
-      p
-    end
-    
+
     def sufficient_contrast?(p)
       # puts "Contrast: #{p.stddev}"
       # tested with the few examples: spec/samples/rm0x.jpeg
@@ -61,21 +42,22 @@ module Mork
   end
 end
 
-
-# def edgy?(x, y)
-#   tol = 5
-#   (x < tol) or (y < tol) or (y > @height - tol) or (x > @width - tol)
-# end
-#
-# def patch
-#   @the_npatch ||= blurry_narr.reshape!(@width, @height)
+# def dark_centroid(c = nil)
+#   p = crop c
+#   sufficient_contrast?(p) or return
+#   xp = p.sum(1).to_a
+#   yp = p.sum(0).to_a
+#   # find the intensity trough
+#   ctr_x = xp.find_index(xp.min)
+#   ctr_y = yp.find_index(yp.min)
+#   # puts "Centroid: #{ctr_x}, #{ctr_y} - MinX #{xp.min/xp.length}, MaxX #{xp.max/xp.length}, MinY #{yp.min/yp.length}, MaxY #{yp.max/yp.length}"
+#   return ctr_x, ctr_y
 # end
-#
-# def narr
-#   NArray[@mim.pixels]
-# end
-#
-# def blurry_narr
-#   @blurry_narr ||= NArray[@mim.blur!(10,5).pixels]
+
+# def crop(c)
+#   raise "crop HELL" if c.nil?
+#   p = NArray.float c.w, c.h
+#   p[true,true] = @patch[c.x_rng, c.y_rng]
+#   p
 # end
-#
+

data/lib/mork/sheet_omr.rb

@@ -4,39 +4,39 @@ require 'mork/mimage_list'
 
 module Mork
   class SheetOMR
-    
+
     def initialize(path, nitems=nil, grom=nil)
-      raise "File '#{path}' not found" unless File.exists? path
+      raise IOError, "File '#{path}' not found" unless File.exists? path
       @grom   = GridOMR.new grom
       @nitems = case nitems
                 when nil
                   [@grom.max_choices_per_question] * @grom.max_questions
                 when Fixnum
-                  [@grom.max_choices_per_question] * nitems 
+                  [@grom.max_choices_per_question] * nitems
                 when Array
                   nitems
                 end
       @mim    = Mimage.new path, @nitems, @grom
     end
-    
+
     def valid?
       @mim.valid?
     end
-    
+
     def status
       @mim.status
     end
-    
+
     # barcode
-    # 
+    #
     # returns the sheet barcode as an integer
     def barcode
       return if not_registered
       barcode_string.to_i(2)
     end
-    
+
     # barcode_string
-    # 
+    #
     # returns the sheet barcode as a string of 0s and 1s. The string is barcode_bits
     # bits long, with most significant bits to the left
     def barcode_string
@@ -44,21 +44,21 @@ module Mork
       cs = @grom.barcode_bits.times.inject("") { |c, v| c << barcode_bit_string(v) }
       cs.reverse
     end
-    
+
     # marked?(question, choice)
-    # 
+    #
     # returns true if the specified question/choice cell has been darkened
     # false otherwise
     def marked?(q, c)
       return if not_registered
       @mim.marked? q, c
     end
-    
+
     # TODO: define method ‘mark’ to retrieve the choice array for a single item
-    
-    
+
+
     # mark_array(range)
-    # 
+    #
     # returns an array of arrays of marked choices.
     # takes either a range of questions, an array of questions, or a fixnum,
     # in which case the choices for the first n questions will be returned.
@@ -73,9 +73,9 @@ module Mork
         cho
       end
     end
-    
+
     # mark_char_array(range)
-    # 
+    #
     # returns an array of arrays of the characters corresponding to marked choices.
     # WARNING: at this time, only the latin sequence 'A, B, C...' is supported.
     # takes either a range of questions, an array of questions, or a fixnum,
@@ -91,53 +91,49 @@ module Mork
         cho
       end
     end
-    
+
     def mark_logical_array(r = nil)
       return if not_registered
       question_range(r).collect do |q|
         (0...@grom.max_choices_per_question).collect {|c| marked?(q, c)}
       end
     end
-    
+
     # ================
     # = HIGHLIGHTING =
     # ================
-    
+
     def outline(cells)
       return if not_registered
       raise "Invalid ‘cells’ argument" unless cells.kind_of? Array
       @mim.outline cells
     end
-    
+
     def cross(cells)
       return if not_registered
       raise "Invalid ‘cells’ argument" unless cells.kind_of? Array
       @mim.cross cells
     end
-    
+
     def cross_marked
       return if not_registered
       @mim.cross mark_array
     end
-    
+
     def highlight_marked
       return if not_registered
       @mim.highlight_cells mark_array
     end
-    
+
     def highlight_all_choices
       return if not_registered
       @mim.highlight_all_choices
     end
-    
+
     def highlight_barcode
       return if not_registered
       @mim.highlight_barcode barcode_string
     end
-    
-    def highlight_registration
-      @mim.highlight_reg_area
-    end
 
     # write(output_path_file_name)
     #
@@ -149,27 +145,33 @@ module Mork
       return if not_registered
       @mim.write(fname)
     end
-    
-    # write_raw(output_path_file_name)
-    #
-    # writes out a copy of the source image before registration;
-    # the output image will also contain any previously applied overlays
-    # if the argument is omitted, the image is created in-place,
-    # i.e. the original source image is overwritten.
-    def write_raw(fname=nil)
-      @mim.write(fname, false)
+
+    # # write_raw(output_path_file_name)
+    # #
+    # # writes out a copy of the source image before registration;
+    # # the output image will also contain any previously applied overlays
+    # # if the argument is omitted, the image is created in-place,
+    # # i.e. the original source image is overwritten.
+    # def write_raw(fname=nil)
+    #   @mim.write(fname, false)
+    # end
+
+    def write_registration(fname)
+      @mim.highlight_rm_areas
+      @mim.highlight_rm_centers
+      @mim.write fname, false
     end
-    
+
     # ============================================================#
     private                                                       #
     # ============================================================#
-    
+
     def barcode_bit_string(i)
       @mim.barcode_bit?(i) ? "1" : "0"
     end
-    
+
     def question_range(r)
-      # TODO: help text: although not API, people need to know this! 
+      # TODO: help text: although not API, people need to know this!
       if r.nil?
         (0...@nitems.length)
       elsif r.is_a? Fixnum
@@ -180,7 +182,7 @@ module Mork
         raise "Invalid argument"
       end
     end
-        
+
     def not_registered
       unless valid?
         puts "---=={ Unregistered image. Reason: '#{@mim.status.inspect}' }==---"