mork 0.12.0 → 0.13.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: b30b33a147b248a73592bcea2dd9ff4d7952a4fb
-  data.tar.gz: e85ca2b34c0b579ec8bf7a3885331ac9ef74c62b
+SHA256:
+  metadata.gz: 2d3d6ed3d87702211f4671ed0897c00b47104502865c71c7880583b81a872db3
+  data.tar.gz: 8106f2dfc61c23142bc215421686d3033960cab7831be8906051bf33c35a5894
 SHA512:
-  metadata.gz: 0649c313f2db3af8d358c03787c0c773c4962cd40ea245758b1bfcb40bec331568c05523371410e81dc4e845ab370d42028331bb685241538856c4875c213e57
-  data.tar.gz: 283fe8d57acd7451bca93920e1049218c1b6574c2944e5c8711dd43a2dbc25a096d802bf2929bcd91719c86efbfb44fe603043e1af60ac33a6375e9be54c2efa
+  metadata.gz: ab2fb5a733b621dc3ca6c1097644190eaf0b613acb91aa79e7b0910f684a68c0b88170e904ee4516c90548186184ee748af3001ecb5feb96850af0b97b4fc184
+  data.tar.gz: 6121d3469a8128c696db1c9c4be71a6b99608040b8e1cc9f25216234b60f3f1a687dcd324ab964baee6989c2b009ba89cbbf480edd849eb5e6bf69b84363f54b

data/.gitignore

@@ -11,3 +11,4 @@ tmp/*
 .rspec
 .byebug_history
 doc
+spec/out

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.5.1

data/README.md

@@ -15,7 +15,7 @@ Mork is a low-level library, and very much work in progress. It is not, and will
 
 - the PDF files generated by Mork are intended to be printed on regular printer paper
 - the entire response sheet must fit into a single page
-- after collecting the responses, a filled-out form should be acquired as a JPEG, PNG, or PDF image by a normal optical scanner or camera (i.e., no specialized equipment is necessary)
+- after marking the responses with a blue or black pen, a filled-out form should be acquired as a JPEG, PNG, or PDF image by a normal optical scanner or camera (i.e., no specialized equipment is necessary)
 - independent of how the sheet is printed and the image is acquired, all internal processing is done on a grayscale version of the bitmap
 - the response sheet always contains the following items:
   - registration marks at each page corner
@@ -29,15 +29,13 @@ Mork is a low-level library, and very much work in progress. It is not, and will
 
 ## Getting started
 
-First, make sure that ImageMagick is installed in your system. Typing `convert in a terminal shell should print out a long help message. If instead you get a “command not found”-like error, you will need to install ImageMagick.
+First, make sure that ImageMagick is installed in your system. Typing `convert` in a terminal shell should print out a long help message. If instead you get a “command not found”-like error, you will need to install ImageMagick.
 
-In OS X, `brew` is an excellent package manager:
+In macOS, `brew` is an excellent package manager:
 
     brew install imagemagick
 
-In a Debian-based Linux distro (e.g., Ubuntu) you would do:
-
-    sudo apt-get install imagemagick
+Please visit [ImageMagick’s home page](http://www.imagemagick.org/script/index.php) for instructions on how to install the software on other platforms.
 
 To create a small ruby project that uses Mork, `cd` into a directory of choice, then execute the following shell commands:
 
@@ -215,7 +213,7 @@ layout = {
 
 sheet = SheetPDF.new content, layout
 s.save 'sheet.pdf'
-system 'open sheet.pdf' # this works in OSX
+system 'open sheet.pdf' # this works in macOS
 ```
 
 ## Analyzing response sheets with `SheetOMR`
@@ -279,7 +277,7 @@ It is also possible to show the scoring graphically by applying an overlay on to
 ```ruby
 s.overlay :check, :marked
 s.save 'marked_choices.jpg'
-system 'open marked_choices.jpg' # this works in OSX
+system 'open marked_choices.jpg' # this works in macOS
 ```
 
 More than one overlay can be applied on a sheet. For example, in addition to checking the marked choice cells, the expected choices can be outlined to show correct vs. wrong responses:
@@ -289,7 +287,7 @@ correct = [[3], [0], [2], [1], [2]] # and so on...
 s.overlay :outline, correct
 s.overlay :check, :marked
 s.save 'marked_choices_and_outlines.jpg'
-system 'open marked_choices_and_outlines.jpg' # this works in OSX
+system 'open marked_choices_and_outlines.jpg' # this works in macOS
 ```
 
 Scoring can only be performed if the sheet gets properly registered, which in turn depends on the quality of the scanned image.
@@ -312,7 +310,7 @@ end
 Experiment with the following layout settings to improve sheet registration:
 
 ```yaml
-reg_marks:         
+reg_marks:
   radius:    3 # a bigger registration mark can sometimes help
   crop:     20 # make sure the registration mark lies comfortably
                # inside the crop area

data/Rakefile

@@ -1 +1,4 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+task default: :spec
+RSpec::Core::RakeTask.new

data/lib/mork/extensions.rb

@@ -1,5 +1,5 @@
 # @private
-class Fixnum
+class Integer
   def mm
     self * 2.83464566929134
   end

data/lib/mork/grid.rb

@@ -21,7 +21,7 @@ module Mork
       when String
         @params.deeper_merge! symbolize YAML.load_file(options)
       else
-        raise ArgumentError, "Invalid parameter in the Grid constructor: #{options.class.inspect}"
+        fail ArgumentError, "Invalid parameter in the Grid constructor: #{options.class.inspect}"
       end
     end
 

data/lib/mork/grid_const.rb

@@ -58,14 +58,14 @@ module Mork
         },
         # student's unique id
         uid: {
-          digits:  6,
-          left:  150,
-          top:    30,
-          width:  50,
-          height: 40,
-          cell_width: 4,
-          cell_height: 3,
-          box:    true
+          digits:        6,
+          left:        150,
+          top:          30,
+          width:        50,
+          height:       40,
+          cell_width:    4,
+          cell_height:   3,
+          box:        true
         }
       }
     end

data/lib/mork/grid_omr.rb

@@ -41,7 +41,7 @@ module Mork
     end
 
     def calibration_cell_areas
-      rows.times.collect do |q|
+      rows.times.map do |q|
         coord cal_cell_x, cell_y(q), cell_width, cell_height
       end
     end

data/lib/mork/grid_pdf.rb

@@ -29,7 +29,7 @@ module Mork
 
     def barcode_xy_for(code)
       black = barcode_bits.times.reject { |x| (code>>x)[0]==0 }
-      black.collect { |x| barcode_xy x+1 }
+      black.map { |x| barcode_xy x+1 }
     end
 
     def ink_black_xy
@@ -37,7 +37,7 @@ module Mork
     end
 
     def calibration_cells_xy
-      rows.times.collect do |q|
+      rows.times.map do |q|
         [(reg_frame_width-cell_spacing).mm, item_y(q).mm]
       end
     end

data/lib/mork/magicko.rb

@@ -1,21 +1,46 @@
 require 'mini_magick'
+require 'open3'
 
 module Mork
   # @private
-  # Magicko: image management, done in two ways: 1) direct system calls to
+  # Magicko: low-level image management, done in two ways: 1) direct system calls to
   # imagemagick tools; 2) via the MiniMagick gem
   class Magicko
+    attr_reader :width
+    attr_reader :height
+
     def initialize(path)
       @path = path
       @cmd = []
+      # a density is required for processing PDF or other vector-based images;
+      # a default of 150 dpi seems sensible. It should not affect bitmaps.
+      density = 150
+      # inspect the source file
+      s1, s2, s3 = Open3.capture3 "identify -density #{density} -format '%w %h %m' #{path}"
+      if s3.success?
+        # parse the identify command output
+        w, h, @type = s1.split(' ')
+        @width  = w.to_i
+        @height = h.to_i
+        if @type.downcase == 'pdf'
+          # remember density for later use
+          @density = density
+        end
+      else
+        # Inspect the stderr and raise appropriate errors
+        case s2
+        when /No such file/
+          fail Errno::ENOENT
+        when /The file has been damaged/
+          fail IOError, 'Invalid image. File may have been damaged'
+        else
+          fail IOError, 'Unknown problem with image file'
+        end
+      end
     end
 
-    def width
-      img_size[0]
-    end
-
-    def height
-      img_size[1]
+    def valid?
+      @valid
     end
 
     # registered_bytes returns an array of the same size as the original image,
@@ -26,7 +51,9 @@ module Mork
       read_bytes "-distort Perspective '#{pps pp}'"
     end
 
-    # def rm_patch(coord, blur_factor, dilate_factor)
+    # Reading from the image file the bytes from one of the four corner
+    # squares encompassing each registration mark; the blur and dilation
+    # manipulations may prevent registration misalignments due to stray dark pixels
     def rm_patch(c, blr=0, dlt=0)
       b = blr==0 ? '' : " -blur #{blr*3}x#{blr}"
       d = dlt==0 ? '' : " -morphology Dilate Octagon:#{dlt}"
@@ -37,10 +64,6 @@ module Mork
     # Constructing MiniMagick commands
     ##################################
 
-    def write_registration(fname)
-
-    end
-
     def highlight(coords, rounded)
       @cmd << [:stroke, 'none']
       @cmd << [:fill, 'rgba(255, 255, 0, 0.3)']
@@ -49,7 +72,7 @@ module Mork
 
     def outline(coords, rounded)
       @cmd << [:stroke, 'green']
-      @cmd << [:strokewidth, '2']
+      @cmd << [:strokewidth, '3']
       @cmd << [:fill, 'none']
       coords.each { |c| @cmd << [:draw, shape(c, rounded)] }
     end
@@ -104,6 +127,7 @@ module Mork
 
     def save(fname, reg)
       MiniMagick::Tool::Convert.new(whiny: false) do |img|
+        img << '-density' << @density if @density
         img << @path
         img.distort(:perspective, pps(reg)) if reg
         @cmd.each { |cmd| img.send(*cmd) }
@@ -120,7 +144,8 @@ module Mork
     # calling imagemagick and capturing the converted image
     # into an array of bytes
     def read_bytes(params=nil)
-      s = "|convert #{@path} #{params} gray:-"
+      d = @density ? "-density #{@density}" : nil
+      s = "|convert -depth 8 #{d} #{@path} #{params} gray:-"
       IO.read(s).unpack 'C*'
     end
 
@@ -135,12 +160,33 @@ module Mork
         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
+
+# @pdf = File.extname(path).strip.downcase[1..-1] == 'pdf'
+# @pdf_den = 150 # dpi
+# get_info_and_test_sanity
+
+# def width
+#   img_size[0]
+# end
+
+# def height
+#   img_size[1]
+# end
+# if s1.downcase=='pdf'
+#   @density = 150
+#   @den_str = "-density #{@density}"
+# end
+
+# def img_size
+#   @img_size ||= begin
+#     s = "|identify -format '%w,%h' #{@density} #{@path}"
+#     IO.read(s).split(',').map(&:to_i)
+#   end
+# end
+
+# def parse_from_stdout(s1)
+#   w, h, t = s1.split ','
+#   return w.to_i, h.to_i, t
+# end

data/lib/mork/mimage.rb

@@ -8,11 +8,12 @@ module Mork
 
     attr_reader :rm
     attr_reader :choxq # choices per question
+    attr_reader :status
 
     def initialize(path, grom)
       @mack  = Magicko.new path
+
       @grom  = grom.set_page_size @mack.width, @mack.height
-      # @choxq = [grom.max_choices_per_question] * grom.max_questions
       @choxq = [(0...@grom.max_choices_per_question).to_a] * grom.max_questions
       @rm    = {} # registration mark centers
       @valid = register
@@ -22,6 +23,10 @@ module Mork
       @valid
     end
 
+    def low_contrast?
+      @rm.any? { |k,v| v < @grom.reg_min_contrast }
+    end
+
     def status
       {
         tl: @rm[:tl][:status],
@@ -78,7 +83,7 @@ module Mork
               when Array
                 choice_cell_areas where
               else
-                raise ArgumentError, 'Invalid overlay argument “where”'
+                fail ArgumentError, 'Invalid overlay argument “where”'
               end
       round = where != :barcode
       @mack.send what, areas, round
@@ -109,6 +114,12 @@ module Mork
     end
 
     def choice_cell_areas(cells)
+      if cells.length > @grom.max_questions
+        fail ArgumentError, 'Maximum number of responses exceeded'
+      end
+      if cells.any? { |q| q.any? { |c| c >= @grom.max_choices_per_question } }
+        fail ArgumentError, 'Maximum number of choices exceeded'
+      end
       itemator(cells) { |q,c| @grom.choice_cell_area q, c }.flatten
     end
 
@@ -124,7 +135,7 @@ module Mork
     end
 
     def cal_cell_mean
-      m = @grom.calibration_cell_areas.collect { |c| reg_pixels.average c }
+      m = @grom.calibration_cell_areas.map { |c| reg_pixels.average c }
       m.inject(:+) / m.length.to_f
     end
 
@@ -156,6 +167,7 @@ module Mork
     def rm_centroid_on(corner)
       c = @grom.rm_crop_area(corner)
       p = @mack.rm_patch(c, @grom.rm_blur, @grom.rm_dilate)
+      # byebug
       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)

data/lib/mork/sheet_omr.rb

@@ -18,7 +18,6 @@ module Mork
     #   containing the parameters. See the README file for a full listing
     #   of the available parameters.
     def initialize(path, layout=nil)
-      raise IOError, "File '#{path}' not found" unless File.exists? path
       grom = GridOMR.new layout
       @mim = Mimage.new path, grom
     end
@@ -30,28 +29,8 @@ module Mork
       @mim.valid?
     end
 
-    # Setting the choices/questions to analyze. If this function is not called,
-    # the maximum number of choices/questions allowed by the layout will be
-    # evaluated.
-    #
-    # @param choices [Fixnum, Array] the questions/choices we want subsequent
-    #   scoring/overlaying to apply to. Normally, `choices` should be an array
-    #   of integers, with each element indicating the number of available
-    #   choices for the corresponding question (i.e. `choices.length` is the
-    #   number of questions). As a shortcut, `choices` can also be a single
-    #   integer value, indicating the number of questions; in such case, the
-    #   maximum number of choices allowed by the layout will be considered.
-    #
-    # @return [Boolean] True if the sheet is properly registered and ready to
-    #   be marked; false otherwise.
-    def set_choices(choices)
-      return false unless valid?
-      @mim.set_ch case choices
-                  when Fixnum; @mim.choxq[0...choices]
-                  when Array; choices
-                  else raise ArgumentError, 'Invalid choice set'
-                  end
-      true
+    def low_contrast?
+      @mim.low_contrast?
     end
 
     # Registration status for each of the four corners
@@ -65,7 +44,7 @@ module Mork
 
     # Sheet barcode as an integer
     #
-    # @return [Fixnum]
+    # @return [Integer]
     def barcode
       return if not_registered
       barcode_string.to_i(2)
@@ -82,10 +61,34 @@ module Mork
       end.join.reverse
     end
 
+    # Setting the choices/questions to analyze. If this function is not called,
+    # the maximum number of choices/questions allowed by the layout will be
+    # evaluated.
+    #
+    # @param choices [Integer, Array] the questions/choices we want subsequent
+    #   scoring/overlaying to apply to. Normally, `choices` should be an array
+    #   of integers, with each element indicating the number of available
+    #   choices for the corresponding question (i.e. `choices.length` is the
+    #   number of questions). As a shortcut, `choices` can also be a single
+    #   integer value, indicating the number of questions; in such case, the
+    #   maximum number of choices allowed by the layout will be considered.
+    #
+    # @return [Boolean] True if the sheet is properly registered and ready to
+    #   be marked; false otherwise.
+    def set_choices(choices)
+      return false unless valid?
+      @mim.set_ch case choices
+                  when Integer; @mim.choxq[0...choices]
+                  when Array; choices
+                  else fail ArgumentError, 'Invalid choice set'
+                  end
+      true
+    end
+
     # True if the specified question/choice cell has been marked
     #
-    # @param question [Fixnum] the question number, zero-based
-    # @param choice [Fixnum] the choice number, zero-based
+    # @param question [Integer] the question number, zero-based
+    # @param choice [Integer] the choice number, zero-based
     # @return [Boolean]
     def marked?(question, choice)
       return if not_registered