mork 0.8.1 → 0.9.0

data/lib/mork/sheet_omr.rb

@@ -3,186 +3,165 @@ require 'mork/mimage'
 require 'mork/mimage_list'
 
 module Mork
+  # Optical mark recognition of a response sheet that was: 1) generated
+  # with SheetPDF, 2) printed on plain paper, 3) filled out by a responder,
+  # and 4) acquired as a image file.
+  #
+  # The sheet is automatically registered upon object creation, after which it
+  # is possible to perform queries, as well as save a copy of the scanned
+  # image with various overlays superimposed, highlighting the expected correc
+  # choices, the actually marked ones, etc.
   class SheetOMR
-
-    def initialize(path, nitems=nil, grom=nil)
+    # @param path [String] the required path/filename to the saved image
+    #   (.jpg, .jpeg, .png, or .pdf)
+    # @param choices [Fixnum, Array] the questions/choices we want scored, as
+    #   an optional named argument. Scoring is done on all available questions,
+    #   if the argument is omitted, on the first N questions, If an integer
+    #   is passed, or on the indicated questions, if the argument is an array.
+    # @param layout [String, Hash] the sheet description. Use a string to
+    #   specify the path/filename of a YAML file containing the parameters,
+    #   or directly a hash of parameters. See the README file for a full listing
+    #   of the available parameters.
+    def initialize(path, choices: nil, layout: nil)
       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
+      grom    = GridOMR.new layout
+      nitems  = case choices
+                when NilClass
+                  [grom.max_choices_per_question] * grom.max_questions
                 when Fixnum
-                  [@grom.max_choices_per_question] * nitems
+                  [grom.max_choices_per_question] * choices
                 when Array
-                  nitems
+                  choices
                 end
-      @mim    = Mimage.new path, @nitems, @grom
+      @mim    = Mimage.new path, nitems, grom
     end
 
+    # True if sheet registration completed successfully
+    #
+    # @return [Boolean]
     def valid?
       @mim.valid?
     end
 
+    # Registration status for each of the four corners
+    #
+    # @return [Hash] { tl: Symbol, tr: Symbol, br: Symbol, bl: Symbol } where
+    #   symbol is either `:ok` or `:edgy`, meaning that the centroid was found
+    #   to be too close to the edge of the search area to be considered reliable
     def status
       @mim.status
     end
 
-    # barcode
+    # Sheet barcode as an integer
     #
-    # returns the sheet barcode as an integer
+    # @return [Fixnum]
     def barcode
       return if not_registered
       barcode_string.to_i(2)
     end
 
-    # barcode_string
+    # Sheet barcode as a binary-like 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
+    # @return [String] a string of 0s and 1s; the string is `barcode_bits`
+    #   bits long, with most significant bits to the left
     def barcode_string
       return if not_registered
-      cs = @grom.barcode_bits.times.inject("") { |c, v| c << barcode_bit_string(v) }
-      cs.reverse
+      @mim.barcode_bits.map do |b|
+        b ? '1' : '0'
+      end.join.reverse
     end
 
-    # marked?(question, choice)
+    # True if the specified question/choice cell has been marked
     #
-    # returns true if the specified question/choice cell has been darkened
-    # false otherwise
-    def marked?(q, c)
+    # @param question [Fixnum] the question number, zero-based
+    # @param choice [Fixnum] the choice number, zero-based
+    # @return [Boolean]
+    def marked?(question, choice)
       return if not_registered
-      @mim.marked? q, c
+      @mim.marked[question][choice]
     end
 
-    # TODO: define method ‘mark’ to retrieve the choice array for a single item
-
-
-    # mark_array(range)
+    # The set of choice indices marked on the response sheet
     #
-    # 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.
-    # if called without arguments, all available choices will be evaluated.
-    def mark_array(r = nil)
-      return if not_registered
-      question_range(r).collect do |q|
-        cho = []
-        (0...@grom.max_choices_per_question).each do |c|
-          cho << c if marked?(q, c)
-        end
-        cho
-      end
-    end
-
-    # mark_char_array(range)
+    # @return [Array] an array of arrays of integers; each element contains
+    #   the (zero-based) list of marked choices for the corresponding question.
+    #   For example, the following `marked_choices` array: `[[0], [], [3,4]]`
+    #   indicates that the responder has marked the first choice for the first
+    #   question, none for the second, and the fourth and fifth choices for the
+    #   third question.
     #
-    # 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,
-    # in which case the choices for the first n questions will be returned.
-    # if called without arguments, all available choices will be evaluated.
-    def mark_char_array(r = nil)
+    # Note that only the questions/choices indicated via the `choices` argument
+    # during object creation are evaluated.
+    def marked_choices
       return if not_registered
-      question_range(r).collect do |q|
-        cho = []
-        (0...@grom.max_choices_per_question).each do |c|
-          cho << (65+c).chr if marked?(q, c)
-        end
-        cho
-      end
+      @mim.marked_int
     end
 
-    def mark_logical_array(r = nil)
+    # The set of letters marked on the response sheet. At this time, only the
+    # latin sequence 'A, B, C...' is supported.
+    #
+    # @return [Array] an array of arrays of 1-character strings; each element
+    #   contains the list of letters marked for the corresponding question.
+    #
+    # Note that only the questions/choices indicated via the `choices` argument
+    # during object creation are evaluated.
+    def marked_letters
       return if not_registered
-      question_range(r).collect do |q|
-        (0...@grom.max_choices_per_question).collect {|c| marked?(q, c)}
+      marked_choices.map do |q|
+        q.map { |cho| (65+cho).chr }
       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
+    # Marked choices as boolean values
+    #
+    # @return [Array] an array of arrays of true/false values corresponding to
+    #   marked vs unmarked choice cells.
+    def marked_logicals
       return if not_registered
-      @mim.highlight_all_choices
+      @mim.marked
     end
 
-    def highlight_barcode
+    # Apply an overlay on the image
+    #
+    # @param what [Symbol] the overlay type, choose from `:outline`, `:check`,
+    #   `:highlight`
+    # @param where [Array, Symbol] where to apply the overlay. Either an array
+    #   of arrays of (zero-based) indices to specify target cells, or one of
+    #   the following symbols: `:marked`: all marked cells, among those
+    #   specified by the `choices` argument during object creation
+    #   (this is the default); `:all`: all cells in `choices`;
+    #   `:max`: maximum number of cells allowed by the layout (can be larger
+    #    than `:all`); `:barcode`: the dark barcode elements; `:cal` the
+    #    calibration cells
+    def overlay(what, where=:marked)
       return if not_registered
-      @mim.highlight_barcode barcode_string
+      @mim.overlay what, where
     end
 
-    # write(output_path_file_name)
+    # Saves a copy of the source image after registration;
+    # the output image will also contain any previously applied overlays.
     #
-    # writes out a copy of the source image after 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(fname=nil)
+    # @param fname [String] the path/filename of the target image, including
+    #   the extension (`.jpg`, `.png`)
+    def save(fname)
       return if not_registered
-      @mim.write(fname)
+      @mim.save(fname, true)
     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)
-    # end
-
-    def write_registration(fname)
-      @mim.highlight_rm_areas
-      @mim.highlight_rm_centers
-      @mim.write fname, false
+    # Saves a copy of the original image with overlays showing the crop areas
+    # used to localize the registration marks and the detected registration
+    # mark centers.
+    #
+    # @param fname [String] the path/filename of the target image, including
+    #   the extension (`.jpg`, `.png`)
+    def save_registration(fname)
+      @mim.save_registration fname
     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!
-      if r.nil?
-        (0...@nitems.length)
-      elsif r.is_a? Fixnum
-        (0...r)
-      elsif r.is_a? Array
-        r
-      else
-        raise "Invalid argument"
-      end
-    end
-
     def not_registered
       unless valid?
         puts "---=={ Unregistered image. Reason: '#{@mim.status.inspect}' }==---"
@@ -191,3 +170,109 @@ module Mork
     end
   end
 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)
+# end
+
+# # Array of arrays of marked choices.
+# #
+# # @param questions [Fixnum, Range, or Array] look for the first n questions
+# #   If the argument is omitted, all available choices are evaluated.
+# # @return [Array] The list of marked choices as an array (one element per
+# #   question) of arrays (the indices of all marked choices for the question)
+# def mark_array(questions = nil)
+#   return if not_registered
+#   x = question_range questions
+#   byebug
+#   x.collect do |q|
+#     [].tap do |cho|
+#       (0...@grom.max_choices_per_question).each do |c|
+#         cho << c if marked?(q, c)
+#       end
+#     end
+#   end
+# end
+
+# # Array of arrays of the characters corresponding to marked choices.
+# # At this time, only the latin sequence 'A, B, C...' is supported.
+# #
+# # @param questions [Fixnum, Range, Array] same as for `mark_array`
+# # @return [Array] The list of marked choices as an array (one element per
+# #   question) of arrays (the indices of all marked choices for the question)
+# def mark_char_array(questions = nil)
+#   return if not_registered
+#   question_range(questions).collect do |q|
+#     [].tap do |cho|
+#       (0...@grom.max_choices_per_question).each do |c|
+#         cho << (65+c).chr if marked?(q, c)
+#       end
+#     end
+#   end
+# end
+
+# # Array of logical arrays of marked choices
+# #
+# # @param [Fixnum, Range, Array]
+# 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
+
+# def question_range(r)
+#   # TODO: help text: although not API, people need to know this!
+#   if r.nil?
+#     (0...@nitems.length)
+#   elsif r.is_a? Fixnum
+#     (0...r)
+#   elsif r.is_a? Array
+#     r
+#   else
+#     raise "Invalid argument"
+#   end
+# end
+
+# 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_all_choices
+#   return if not_registered
+#   @mim.highlight_all_choices
+# end
+
+# def highlight_marked
+#   return if not_registered
+#   @mim.highlight_cells mark_array
+# end
+
+# def highlight_barcode
+#   return if not_registered
+#   @mim.highlight_barcode barcode_string
+# end
+
+# def barcode_bit_string(i)
+#   @mim.barcode_bit?(i) ? "1" : "0"
+# end

data/lib/mork/sheet_pdf.rb

@@ -3,13 +3,14 @@ require 'prawn'
 
 module Mork
 
-  #TODO: read the prawn manual, we should probably use views
-
+  # Generating response sheets as PDF files.
+  # See the README file for usage
   class SheetPDF < Prawn::Document
-    def initialize(content, grip=GridPDF.new)
-      @grip = case grip
-              when String, Hash; GridPDF.new grip
-              when Mork::GridPDF; grip
+    def initialize(content, layout=nil)
+      @grip = case layout
+              when NilClass; GridPDF.new
+              when String, Hash; GridPDF.new layout
+              when Mork::GridPDF; layout
               else raise ArgumentError, 'Invalid initialization parameter'
               end
       super my_page_params
@@ -19,15 +20,21 @@ module Mork
       process
     end
 
-    def save(fn)
-      render_file fn
+    # Saving the PDF file to disk
+    #
+    # @param fname [String] the path/filename for the target PDF document
+    def save(fname)
+      render_file fname
     end
 
+    # The PDF document as a string
     def to_pdf
       render
     end
 
+    ###########################################################################
     private
+    ###########################################################################
 
     def my_page_params
       {

data/lib/mork/version.rb

@@ -1,3 +1,3 @@
 module Mork
-  VERSION = "0.8.1"
+  VERSION = "0.9.0"
 end

data/mork.gemspec

@@ -21,6 +21,7 @@ Gem::Specification.new do |s|
   s.add_dependency 'narray',      '~> 0.6'
   s.add_dependency 'mini_magick', '~> 4.5'
   s.add_dependency 'prawn',       '~> 2.1'
+  s.add_dependency 'deep_merge', '~> 1.0'
   s.add_development_dependency 'rake',          '~> 10.3'
   s.add_development_dependency 'rspec',         '~>  3.1'
   s.add_development_dependency 'guard',         '~>  2.6'
@@ -28,4 +29,5 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'guard-shell',   '~>  0.6'
   # s.add_development_dependency 'rb-fsevent'
   s.add_development_dependency 'awesome_print', '~>  1.2'
+  s.add_development_dependency 'byebug', '~>  9.0'
 end

data/mork.sublime-project

@@ -3,7 +3,7 @@
 	[
 		{
 			"path": ".",
-			"folder_exclude_patterns": ["tmp", "log"]
+			"folder_exclude_patterns": ["tmp", "log", "doc", ".yardoc"]
 		}
 	]
 }

data/spec/mork/extensions_spec.rb

@@ -2,9 +2,9 @@ require 'spec_helper'
 
 module Mork
   describe Array do
-    it 'should give the standard deviation' do
-      a = [ 20, 23, 23, 24, 25, 22, 12, 21, 29 ]
-      a.stdev.should == 4.594682917363407
+    it 'computes the average' do
+      a = [ 20, 23, 23, 24, 25, 22, 12, 21, 28 ]
+      expect(a.mean).to eq 22
     end
   end
 end

data/spec/mork/grid_omr_spec.rb

@@ -3,12 +3,13 @@ require 'spec_helper'
 module Mork
   describe GridOMR do
     before(:each) do
-      @grom = GridOMR.new 'spec/samples/layout.yml'
+      @grom = GridOMR.new 'spec/samples/grid_omr_layout.yml'
       @grom.set_page_size 1601, 2281
     end
 
     describe '#choice_cell_area' do
       it 'returns the coordinates of the first choice cell' do
+        puts
         expect(@grom.choice_cell_area(0,0)).to have_coords(63, 436, 51, 41)
       end
 

data/spec/mork/grid_spec.rb

@@ -4,7 +4,7 @@ module Mork
   describe Grid do
     context 'init params' do
       it 'does not work with an integer' do
-        expect {Grid.new 1}.to raise_error RuntimeError
+        expect {Grid.new 1}.to raise_error ArgumentError
       end
     end
 
@@ -25,39 +25,6 @@ module Mork
         end
       end
     end
-
-
-    # describe "#cell_x" do
-    #   context "for 1st-column questions" do
-    #     it "returns the distance from the registration frame of the left edge of the 1st choice" do
-    #       grid.send(:cell_x,0,0).should == 7.5
-    #     end
-    #
-    #     it "returns the distance from the registration frame of the left edge of the 2nd choice" do
-    #       grid.send(:cell_x,0,1).should == 14.5
-    #     end
-    #   end
-    #
-    #   context "for 4th-column questions" do
-    #     it "returns the distance from the registration frame of the left edge of the 1st choice" do
-    #       grid.send(:cell_x,120,0).should == 157.5
-    #     end
-    #
-    #     it "returns the distance from the registration frame of the left edge of the 2nd choice" do
-    #       grid.send(:cell_x,120,1).should == 164.5
-    #     end
-    #   end
-    # end
-    #
-    # describe "#cell_y" do
-    #   it "returns the distance from the registration frame of the top edge of the 1st row of cells" do
-    #     grid.send(:cell_y,0).should == 33.5
-    #   end
-    #
-    #   it "returns the distance from the registration frame of the 40th row of cells" do
-    #     grid.send(:cell_y,39).should == 267.5
-    #   end
-    # end
   end
 end
 
@@ -98,9 +65,41 @@ end
 #     @grid.ctrl_area_dark.should == {:x=>1479, :y=>329, :w=>51, :h=>41}
 #   end
 # end
-#
+
 # describe '#ctrl_area_light' do
 #   it 'returns the coordinates of the control cell used to set the darkened threshold' do
 #     @grid.ctrl_area_light.should == {:x=>1538, :y=>329, :w=>51, :h=>41}
 #   end
 # end
+
+# describe "#cell_x" do
+#   context "for 1st-column questions" do
+#     it "returns the distance from the registration frame of the left edge of the 1st choice" do
+#       grid.send(:cell_x,0,0).should == 7.5
+#     end
+#
+#     it "returns the distance from the registration frame of the left edge of the 2nd choice" do
+#       grid.send(:cell_x,0,1).should == 14.5
+#     end
+#   end
+#
+#   context "for 4th-column questions" do
+#     it "returns the distance from the registration frame of the left edge of the 1st choice" do
+#       grid.send(:cell_x,120,0).should == 157.5
+#     end
+#
+#     it "returns the distance from the registration frame of the left edge of the 2nd choice" do
+#       grid.send(:cell_x,120,1).should == 164.5
+#     end
+#   end
+# end
+#
+# describe "#cell_y" do
+#   it "returns the distance from the registration frame of the top edge of the 1st row of cells" do
+#     grid.send(:cell_y,0).should == 33.5
+#   end
+#
+#   it "returns the distance from the registration frame of the 40th row of cells" do
+#     grid.send(:cell_y,39).should == 267.5
+#   end
+# end

data/spec/mork/magicko_spec.rb

@@ -2,8 +2,8 @@ require 'spec_helper'
 
 module Mork
   describe Magicko do
-    let(:sh) { sample_img :slanted }
-    let(:ma) { Magicko.new sh.filename }
+    let(:sh) { sample_img :jdoe1 }
+    let(:ma) { Magicko.new sh.image_path }
     let(:co) { Coord.new 50}
     let(:pp) { { tl: {x: 10, y: 10}, tr: {x: 1000, y: 10}, bl: {x: 10, y: 1700}, br: {x: 1000, y: 1700}} }