mork 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 59b94f585fff925a78dc0fc848c267503cfdc8c0
-  data.tar.gz: 0a71421a1f6a1fd9790047ea4b913397572799ea
+  metadata.gz: 805582a3e749af1de651277c4a3f2f4cd6507989
+  data.tar.gz: 5d552b668eedbea2261c4d722620f2b3534859e7
 SHA512:
-  metadata.gz: 2d8863ac600a282190b719b433db6ac761422f4ad8485fe979230b6e1ee609685e1a611f996ef2fe33785e2185dfde23ac9f8253c5c4351d0f937a262ef487df
-  data.tar.gz: ec876a3c40eb586f462d9b7127537b5562a0402a7ad6f96063ca5434dd5ad5d6151e96de92913b6ee8845fb677c0133766c63986f5c475dd271705b641d0013f
+  metadata.gz: a37d3e1a738d0593efa9e8c2bb1f8599e4954ae34140344bbc60e03957cd49ad5837e45b0617b724830b62b3a582e43f6fa9a91dc8c1fb5177ce01d9bdbaba30
+  data.tar.gz: fb52e0048d8068804fdb78e1530d96e9312ecd353e1fde01a8d2d0f7d0fb4a74ba728cb3b6d08b015acc079996d12aa8eced2e759ad9bd6a0bc3aa1c0fc15d30

data/README.md

@@ -91,8 +91,10 @@ page_size:                # all measurements in mm
 reg_marks:         
   margin:          10     # distance from each page border to registration mark center
   radius:           2.5   # registration mark radius
-  search:          12     # initial size of the registration mark search area (*)
+  crop:            12     # size of the registration mark search area (*)
   offset:           2     # distance between the search area and each page border (*)
+  blur:             2     # size of a gaussian blur filter to smooth overly pixelated registration marks (0 to skip)
+  dilate:           5     # size of a “dilate” filter to get rid of stray noise (0 to skip)
 header:           
   name:                   # ‘name’ is just a label; you can add arbitrary header elements
     top:            5     # margin relative to registration frame top side
@@ -152,7 +154,7 @@ If the `layout` argument is omitted, Mork will search for a file named `layout.y
 
 ## Scoring response sheets with `SheetOMR`
 
-Assuming that a person has filled out a response sheet by darkening with a pen the selected choices, and that sheet has been acquired as an image file, response scoring is performed by the `Mork::SheetOMR` class. Three pieces of information must be provided to the class constructor:
+Assuming that a person has filled out a response sheet by darkening with a pen the selected choices, and that the sheet has been acquired as an image file, response scoring is performed by the `Mork::SheetOMR` class. Three pieces of information must be provided to the object constructor:
 
 - **image**: the path/filename of the bitmap image (currently accepts JPG, JPEG, PNG, PDF extensions; a resolution of 150-200 dpi is usually more than sufficient to obtain accurate readings)
 - **choices**: equivalent to the `choices` array of integers passed to the `SheetPDF` constructor as part of the `content` parameter (see above)
@@ -178,4 +180,4 @@ system 'open highlights.jpg' # OSX only
 
 #### Wait, why Mork?
 
-Because I used to have a crush on Mindy
+Because I used to have a crush on Mindy

data/lib/mork/coord.rb

@@ -0,0 +1,58 @@
+module Mork
+  # The Coord class takes coordinates in the standard unit (e.g. mm)
+  # and provides pixel-based coordinates useful for image manipulation
+  class Coord
+    attr_reader :x, :y, :w, :h
+
+    def initialize(w, h: w, x: 0, y: 0, cx: 1, cy: cx)
+      @x = (cx*x).round
+      @y = (cy*y).round
+      @w = (cx*w).round
+      @h = (cy*h).round
+    end
+
+    def to_hash
+      { w: @w, h: @h, x: @x, y: @y }
+      5
+    end
+
+    def print
+      puts "X: #{@x}, Y: #{@y}, W: #{@w}, H: #{@h}"
+    end
+
+    def rect_points
+      [@x, @y, @x+@w, @y+@h].join ' '
+    end
+
+    def choice_cell
+      rness = [@h, @w].min / 2
+      rect_points + " #{rness} #{rness}"
+    end
+
+    def cross1
+      [@x+corner, @y+corner, @x+@w-corner, @y+@h-corner].join ' '
+    end
+
+    def cross2
+      [@x+corner, @y+@h-corner, @x+@w-corner, @y+corner].join ' '
+    end
+
+    def cropper
+      "#{@w}x#{@h}+#{@x}+#{@y}"
+    end
+
+    def x_rng
+      @x...@x+@w
+    end
+
+    def y_rng
+      @y...@y+@h
+    end
+
+    private
+
+    def corner
+      (@h - @w).abs
+    end
+  end
+end

data/lib/mork/grid.rb

@@ -22,7 +22,7 @@ module Mork
         raise "Invalid parameter in the Grid constructor: #{options.class.inspect}"
       end
     end
-    
+
     # Puts out the Grid parameters in YAML format; the entire hash is displayed
     # if no arguments are given; you can specify what to show by passing one of:
     # :page_size, :reg_marks, :header, :items, :barcode, :control
@@ -30,27 +30,35 @@ module Mork
       out = subset ? @params[subset] : @params
       puts out.to_yaml
     end
-    
+
     def options
       @params
     end
-    
+
     def max_questions
       columns * rows
     end
-    
+
     def max_choices_per_question
       @params[:items][:max_cells].to_i
     end
-    
+
     def barcode_bits
       @params[:barcode][:bits].to_i
     end
-    
+
+    def rm_dilate
+      @params[:reg_marks][:dilate].to_i
+    end
+
+    def rm_blur
+      @params[:reg_marks][:blur].to_i
+    end
+
     #====================#
     private
     #====================#
-    
+
     # recursively turn hash keys into symbols. pasted from
     # http://stackoverflow.com/questions/800122/best-way-to-convert-strings-to-symbols-in-hash
     def symbolize(obj)
@@ -58,60 +66,61 @@ module Mork
       return obj.inject([]){|memo,v    | memo           << symbolize(v); memo} if obj.is_a? Array
       return obj
     end
-  
+
     # cell_y(q)
-    # 
+    #
     # the distance from the registration frame to the top edge
     # of all choice cells in the q-th question
     def cell_y(q)
       first_y + item_spacing * (q % rows) - cell_height / 2
     end
-    
+
     # cell_x(q,c)
-    # 
+    #
     # the distance from the registration frame to the left edge
     # of the c-th choice cell of the q-th question
     def cell_x(q,c)
       item_x(q) + cell_spacing * c
     end
-    
+
     def item_x(q)
       first_x + column_width * (q / rows) - cell_width / 2
     end
-    
+
     def cal_cell_x
       reg_frame_width - cell_spacing
     end
-    
+
     # ===========
     # = barcode =
     # ===========
     def barcode_bit_x(i)
       @params[:barcode][:left] + @params[:barcode][:spacing] * i
     end
-    
+
     # ===============================
     # = Simple parameter extraction =
     # ===============================
-    def barcode_y()         reg_frame_height - barcode_height   end
-    def barcode_height()    @params[:barcode][:height].to_f     end
-    def barcode_width()     @params[:barcode][:width].to_f      end
-    def cell_width()        @params[:items][:cell_width].to_f   end
-    def cell_height()       @params[:items][:cell_height].to_f  end
-    def cell_spacing()      @params[:items][:x_spacing].to_f    end
-    def item_spacing()      @params[:items][:y_spacing].to_f    end
-    def column_width()      @params[:items][:column_width].to_f end
-    def first_x()           @params[:items][:left].to_f         end
-    def first_y()           @params[:items][:top].to_f          end
-    def rows()              @params[:items][:rows]              end
-    def columns()           @params[:items][:columns]           end
-    def reg_search()        @params[:reg_marks][:search].to_f    end
-    def reg_off()           @params[:reg_marks][:offset].to_f    end
-    def reg_frame_width()   page_width  - reg_margin * 2        end
-    def reg_frame_height()  page_height - reg_margin * 2        end
-    def page_width()        @params[:page_size][:width].to_f    end
-    def page_height()       @params[:page_size][:height].to_f   end
-    def reg_margin()        @params[:reg_marks][:margin].to_f    end
-    def reg_radius()        @params[:reg_marks][:radius].to_f    end
+    def barcode_y()        reg_frame_height - barcode_height   end
+    def barcode_height()   @params[:barcode][:height].to_f     end
+    def barcode_width()    @params[:barcode][:width].to_f      end
+    def cell_width()       @params[:items][:cell_width].to_f   end
+    def cell_height()      @params[:items][:cell_height].to_f  end
+    def cell_spacing()     @params[:items][:x_spacing].to_f    end
+    def item_spacing()     @params[:items][:y_spacing].to_f    end
+    def column_width()     @params[:items][:column_width].to_f end
+    def first_x()          @params[:items][:left].to_f         end
+    def first_y()          @params[:items][:top].to_f          end
+    def rows()             @params[:items][:rows]              end
+    def columns()          @params[:items][:columns]           end
+    def reg_search()       @params[:reg_marks][:search].to_f   end
+    def reg_crop()         @params[:reg_marks][:crop].to_f     end
+    def reg_off()          @params[:reg_marks][:offset].to_f   end
+    def reg_frame_width()  page_width  - reg_margin * 2        end
+    def reg_frame_height() page_height - reg_margin * 2        end
+    def page_width()       @params[:page_size][:width].to_f    end
+    def page_height()      @params[:page_size][:height].to_f   end
+    def reg_margin()       @params[:reg_marks][:margin].to_f   end
+    def reg_radius()       @params[:reg_marks][:radius].to_f   end
   end
 end

data/lib/mork/grid_const.rb

@@ -1,18 +1,23 @@
 module Mork
   # this is the default grid!
+  # default units are millimiters
   DGRID = {
-    # default units are millimiters
+    # size of the paper sheet
     page_size: {
       # this is A4
       width:      210,
       height:     297
-    }, # page end
+    },
+    # size, location, search parameters of registration marks
     reg_marks: {
       margin:      10,
       radius:       2.5,
-      search:      10,
-      offset:       2
-    }, # reg_marks end
+      search:      10, # remove this?
+      offset:       2,
+      crop:        20, # size of square where the regmark should be located
+      dilate:       0, # set to >0 to apply a dilate IM operation
+      blur:         0  # set to >0 to apply a blur IM operation
+    },
     header: {
       name: {
         top:        5,
@@ -42,7 +47,7 @@ module Mork
       }
     }, # header end
     items: {
-      columns:       4, 
+      columns:       4,
       column_width: 44,
       rows:         30,
       # from the top-left registration mark

data/lib/mork/grid_omr.rb

@@ -1,16 +1,18 @@
 require 'mork/grid'
+require 'mork/coord'
 
 module Mork
   class GridOMR < Grid
     def initialize(options=nil)
       super options
     end
-    
+
     def set_page_size(width, height)
       @px = width.to_f
       @py = height.to_f
+      self
     end
-    
+
     def barcode_bit_areas(bitstring = '1' * barcode_bits)
       areas = []
       bitstring.reverse.each_char.with_index do |c, i|
@@ -18,88 +20,100 @@ module Mork
       end
       areas
     end
-    
-    # ====================================================
-    # = Returning {x, y, w, h} hashes for area locations =
-    # ====================================================
+
+    # ===========================================
+    # = Returning Coord sets for area locations =
+    # ===========================================
     def choice_cell_area(q, c)
-      {
-        x: (cx * cell_x(q,c)).round,
-        y: (cy * cell_y(q)  ).round,
-        w: (cx * cell_width ).round,
-        h: (cy * cell_height).round
-      }
+      coord cell_x(q,c), cell_y(q), cell_width, cell_height
     end
-    
+
     def calibration_cell_areas
       rows.times.collect do |q|
-        {
-          x: (cx * cal_cell_x ).round,
-          y: (cy * cell_y(q)  ).round,
-          w: (cx * cell_width ).round,
-          h: (cy * cell_height).round
-        }
+        coord cal_cell_x, cell_y(q), cell_width, cell_height
       end
     end
-    
-    def cell_corner_size
-      d = choice_cell_area(0,0)
-      (d[:w]-d[:h]).abs
-    end
-    
+
     def barcode_bit_area(bit)
-      {
-        x: (cx * barcode_bit_x(bit)).round,
-        y: (cy * barcode_y         ).round,
-        w: (cx * barcode_width     ).round,
-        h: (cy * barcode_height    ).round
-      }
+      coord barcode_bit_x(bit), barcode_y, barcode_width, barcode_height
     end
-    
-    # the 4 values needed to locate a single registration mark
-    # 
-    def rm_search_area(corner, i)
-      {
-        x: (ppu_x * rmx(corner, i)).round,
-        y: (ppu_y * rmy(corner, i)).round,
-        w: (ppu_x * (reg_search + reg_radius * i)).round,
-        h: (ppu_y * (reg_search + reg_radius * i)).round
-      }
+
+    def rm_crop_area(corner)
+      coord rx(corner), ry(corner), reg_crop, reg_crop, ppu_x, ppu_y
     end
-    
-    # a safe distance to determine
-    def rm_edgy_x()                (ppu_x * reg_radius).round + 5    end
-    def rm_edgy_y()                (ppu_y * reg_radius).round + 5    end
-    # areas on the sheet that are certainly white/black
-    def paper_white_area()         barcode_bit_area -1               end
-    def ink_black_area()           barcode_bit_area  0               end
-    def rm_max_search_area_side()  (ppu_x * page_width / 4).round    end
-    
+
+    def paper_white_area() barcode_bit_area(-1) end
+    def ink_black_area()   barcode_bit_area( 0) end
+
     private
-    
+
     def cx()    @px / reg_frame_width  end
     def cy()    @py / reg_frame_height end
     def ppu_x() @px / page_width       end
     def ppu_y() @py / page_height      end
-      
-    # finding the x position of the registration area based on iteration
-    def rmx(corner, i)
+
+    def coord(x, y, w, h, cX=cx, cY=cy)
+      Coord.new w, h: h, x: x, y: y, cx: cX, cy: cY
+    end
+
+    # iterationless x registration
+    def rx(corner)
       case corner
       when :tl; reg_off
-      when :tr; page_width - reg_search - reg_off - reg_radius * i
-      when :br; page_width - reg_search - reg_off - reg_radius * i
+      when :tr; page_width - reg_crop - reg_off
+      when :br; page_width - reg_crop - reg_off
       when :bl; reg_off
       end
     end
-  
-    # finding the y position of the registration area based on iteration
-    def rmy(corner, i)
+
+    def ry(corner)
       case corner
       when :tl; reg_off
       when :tr; reg_off
-      when :br; page_height - reg_search - reg_off - reg_radius * i
-      when :bl; page_height - reg_search - reg_off - reg_radius * i
+      when :br; page_height - reg_crop - reg_off
+      when :bl; page_height - reg_crop - reg_off
       end
     end
   end
-end
+end
+
+# # the 4 values needed to locate a single registration mark
+#
+# def rm_search_area(corner, i)
+#   {
+#     x: (ppu_x * rmx(corner, i)).round,
+#     y: (ppu_y * rmy(corner, i)).round,
+#     w: (ppu_x * (reg_search + reg_radius * i)).round,
+#     h: (ppu_y * (reg_search + reg_radius * i)).round
+#   }
+# end
+
+# # finding the x position of the registration area based on iteration
+# def rmx(corner, i)
+#   case corner
+#   when :tl; reg_off
+#   when :tr; page_width - reg_search - reg_off - reg_radius * i
+#   when :br; page_width - reg_search - reg_off - reg_radius * i
+#   when :bl; reg_off
+#   end
+# end
+
+# # finding the y position of the registration area based on iteration
+# def rmy(corner, i)
+#   case corner
+#   when :tl; reg_off
+#   when :tr; reg_off
+#   when :br; page_height - reg_search - reg_off - reg_radius * i
+#   when :bl; page_height - reg_search - reg_off - reg_radius * i
+#   end
+# end
+
+# def rm_edgy_x()                (ppu_x * reg_radius).round + 5    end
+# def rm_edgy_y()                (ppu_y * reg_radius).round + 5    end
+# def rm_max_search_area_side()  (ppu_x * page_width / 4).round    end
+
+# def cell_corner_size
+#   d = choice_cell_area(0,0)
+#   (d[:w]-d[:h]).abs
+# end
+

data/lib/mork/magicko.rb

@@ -0,0 +1,162 @@
+require 'mini_magick'
+
+module Mork
+  # Magicko: image management, done in two ways: 1) direct system calls to
+  # imagemagick tools; 2) via the MiniMagick gem
+  class Magicko
+    def initialize(path)
+      @path = path
+      @cmd = []
+    end
+
+    def width
+      img_size[0]
+    end
+
+    def height
+      img_size[1]
+    end
+
+    # registered_bytes returns an array of the same size as the original image,
+    # but with pixels stretched out based on the passed perspective points
+    # (i.e. the centers of the four registration marks)
+    # pp: a hash in the form of pp[:tl][:x], pp[:tl][:y], etc.
+    def registered_bytes(pp)
+      read_bytes "-distort Perspective '#{pps pp}'"
+    end
+
+    # def rm_patch(coord, blur_factor, dilate_factor)
+    def rm_patch(c, blr=0, dlt=0)
+      b = blr==0 ? '' : " -blur #{blr*3}x#{blr}"
+      d = dlt==0 ? '' : " -morphology Dilate Octagon:#{dlt}"
+      read_bytes "-crop #{c.cropper}#{b}#{d}"
+    end
+
+    # MiniMagick stuff
+
+    def highlight_cells(coords)
+      @cmd << [:stroke, 'none']
+      @cmd << [:fill, 'rgba(255, 255, 0, 0.3)']
+      coords.each do |c|
+        @cmd << [:draw, "roundrectangle #{c.choice_cell}"]
+      end
+    end
+
+    def outline(coords)
+      @cmd << [:stroke, 'green']
+      @cmd << [:strokewidth, '2']
+      @cmd << [:fill, 'none']
+      coords.each do |c|
+        @cmd << [:draw, "roundrectangle #{c.choice_cell}"]
+      end
+    end
+
+    def cross(coords)
+      @cmd << [:stroke, 'red']
+      @cmd << [:strokewidth, '3']
+      coords.each do |c|
+        @cmd << [:draw, "line #{c.cross1}"]
+        @cmd << [:draw, "line #{c.cross2}"]
+      end
+    end
+
+    def plus(x, y, l)
+      @cmd << [:stroke, 'red']
+      @cmd << [:strokewidth, 1]
+      pts = [ x-l, y, x+l, y ].join ' '
+      @cmd << [:draw, "line #{pts}"]
+      pts = [ x, y-l, x, y+l ].join ' '
+      @cmd << [:draw, "line #{pts}"]
+    end
+
+    def highlight_area(c)
+      @cmd << [:fill, 'none']
+      @cmd << [:stroke, 'yellow']
+      @cmd << [:strokewidth, 3]
+      @cmd << [:draw, "rectangle #{c.rect_points}"]
+    end
+
+    def highlight_rect(areas)
+      return if areas.empty?
+      @cmd << [:fill, 'none']
+      @cmd << [:stroke, 'yellow']
+      @cmd << [:strokewidth, 3]
+      areas.each do |c|
+        @cmd << [:draw, "rectangle #{c.rect_points}"]
+      end
+    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 write(fname, reg)
+      if fname
+        MiniMagick::Tool::Convert.new(whiny: false) do |img|
+          img << @path
+          exec_mm_cmd img, reg
+          img << fname
+        end
+      else
+        MiniMagick::Tool::Mogrify.new(whiny: false) do |img|
+          img << @path
+          exec_mm_cmd img, reg
+        end
+      end
+    end
+
+    private
+
+    # calling imagemagick and capturing the converted image
+    # into an array of bytes
+    def read_bytes(params=nil)
+      s = "|convert #{@path} #{params} gray:-"
+      IO.read(s).unpack 'C*'
+    end
+
+    def exec_mm_cmd(c, pp)
+      c.distort(:perspective, pps(pp)) if pp
+      @cmd.each { |cmd| c.send(*cmd) }
+    end
+
+
+    # perspective points: brings the found registration area centers to the
+    # original image boundaries; the result is that the registered image is
+    # somewhat stretched, which should be okay
+    def pps(pp)
+      [
+        pp[:tl][:x], pp[:tl][:y],     0,      0,
+        pp[:tr][:x], pp[:tr][:y], width,      0,
+        pp[:br][:x], pp[:br][:y], width, height,
+        pp[:bl][:x], pp[:bl][:y],     0, height
+      ].join ' '
+    end
+
+    def img_size
+      @img_size ||= begin
+        s = "|identify -format '%w,%h' #{@path}"
+        IO.read(s).split(',').map(&:to_i)
+      end
+    end
+  end
+end
+
+# def patch(shape: nil, wid: width, hei: height)
+#   s = "|convert #{@path} #{shape} gray:-"
+#   bytes = IO.read(s).unpack 'C*'
+#   NPatch.new bytes, wid, hei
+# end
+
+# # raw_patch returns an array containing the pixels of the original image
+# def raw_patch
+#   @raw_pixels ||= patch
+# end