mork 0.9.3 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6ad2fa0bbdc2867005194207a5b864712f960086
-  data.tar.gz: c41bb8ee3b1d79498f3bcebd589f5ffbd1203bfb
+  metadata.gz: 4aab0200b0c68dc3f3720fef8b8ae239d1c3d521
+  data.tar.gz: 7b1dcdfea624a8d99f98230ee3899c51ce5f90ed
 SHA512:
-  metadata.gz: 967dff2829c9fc983e77cab161dc5ed612bc977d4c3ed1e98ef81a16a60c440f5a91633a7440df77166d71b42e7cd46ae4ce3808061dcee6ce06acd0750a203b
-  data.tar.gz: 0027ebe1c08ea06573322608a56320618ea7a57bcf0235076f9fbf9134dc62999a81a77eb7755191a99ba1b15c877c77cc00a7f9c5eeb564f18860d72b6fbf0a
+  metadata.gz: 4002e21d4604887c06c75dedfd6689316364766276f3dff453cd7dd774ae752a9293098d18a72a236ce607eb81ac8b53d65d985b83b67b157f844e2f1706de5a
+  data.tar.gz: d9720227584eef5a59d842cd4b713b6c021b7eac3d6398124c6affbf65f21e2d0d44751ba436e0aee5d305721fb49d27441e5b2aa48a5d1539b5d12c780dc108

data/.yardopts

@@ -1 +1 @@
---no-private
+--no-private --markup markdown

data/README.md

@@ -5,6 +5,10 @@ A ruby [optical mark recognition](http://en.wikipedia.org/wiki/Optical_mark_reco
 1. generating [response sheets](/spec/samples/sheet.jpg) in PDF format
 2. capturing the responses provided on the [printed sheet](/spec/samples/sample_gray.jpg) by a human with a pen or a pencil.
 
+## First, a word of caution
+
+__Please note that this library is under active development. Until v.1.0 is reached, the API should be regarded as unstable and bound to change without notice.__
+
 ## Assumptions and limitations
 
 Mork is a low-level library, and very much work in progress. It is not, and will likely never be a complete OMR solution. While suggestions and contributions are more than welcome, for the time being several assumptions and restrictions apply.
@@ -84,13 +88,13 @@ content = {
 
 These are the key-value pairs that the `content` hash may contain:
 
-- **choices**: an array of integers, specifiying the number of items in the test (the length of the array) and the number of choices available for each item (the array values); if omitted, the maximum number of items and choices per item are printed
+- **choices**: an array of integers, specifiying the number of items in the test (the length of the array) and the number of choices available for each item (the array values); if omitted, the maximum number of items and choices per item allowed by the layout (see below) are printed
 - **header**: optional; a (sub)hash of key-value pairs defining the content of named header elements; in each pair, the key is the name of one header element, while the value is the rendered content; the actually available elements are defined in the `layout` (see below)
 - **barcode**: optional; an integer number, the sheet's unique identifier to be printed as a binary barcode along the bottom edge of the sheet
 
 ### layout
 
-The layout argument is also defined as a hash, but because of its length and since the layout often stays identical across many response sheets, it is usually more convenient to write the information in a YAML file and pass its path/filename to the `SheetPDF` constructor instead. Here is the YAML version of a standard layout hash. Please note that the parameters with an (*) in the comment have no effect on PDF production, but are relevant to OMR scan (see further below).
+The layout is also defined as a hash, but because of its length and since the layout often stays identical across many response sheets, it is usually more convenient to write the information in a YAML file and pass its path/filename to the `SheetPDF` constructor instead. Here is the YAML version of a standard layout hash. Please note that the parameters with an (*) in the comment have no effect on PDF production, but are relevant to OMR scan (see further below).
 
 ```yaml
 page_size:                # all measurements in mm
@@ -161,31 +165,69 @@ s.save 'sheet.pdf'
 system 'open sheet.pdf' # this works in OSX
 ```
 
-It's easy to see that by iterating over a series of `content` hashes you can produce any number of sheets, all based on the same layout but each containing unique information (notably the barcode, but also names, dates, etc.)
-
 If the `layout` argument is omitted, Mork will search for a file named `layout.yml` and load it. If such file cannot be found, Mork will fall back to a default, boilerplate layout (incidentally, this is the layout shown above).
 
-## Scoring response sheets with `SheetOMR`
+Importantly, if `content` is an array of hashes, Mork will produce one sheet for each hash, all based on the same layout but each containing unique information (the barcode, names, dates, a specific number of questions/choices, etc.)
+
+## Analyzing response sheets with `SheetOMR`
 
-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:
+### Preparing a `SheetOMR` object
+
+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. Two pieces of information must be provided to the object constructor:
 
 - **path**: mandatory path/filename of the bitmap image (accepts JPG, JPEG, PNG, PDF extensions; a resolution of 150-200 dpi is usually more than sufficient to obtain accurate readings)
-- **choices**: a named argument (ruby-2 style) equivalent to the `choices` array of integers passed to the `SheetPDF` constructor as part of the `content` parameter (see above). If omitted, the `choices` parameter is inferred from the layout
 - **layout_file**: same as for the `SheetPDF` class
 
-The following code shows how to create and analyze a SheetOMR based on a bitmap file named `image.jpg`:
+The following code shows how to create a SheetOMR based on a bitmap file named `image.jpg`:
 
 ```ruby
 # instantiating the object
-s = SheetOMR.new 'image.jpg', choices: [5]*100, layout_file: 'layout.yml'
-# detecting darkened choice cells for the 100 items
-chosen = s.marked_choices
+s = SheetOMR.new 'image.jpg', 'layout.yml'
+```
+
+When the object is initialized, Mork attempts to register the image, a necessary step before marking can be performed. To find out if registration succeeded:
+
+```ruby
+s.valid?
+```
+
+Next, we need to indicate the questions/choices of interest for subsequent operations. For example, the following instructs Mork to evaluate 5 choices for each of the first 50 questions:
+
+```ruby
+choices = [5] * 50
+s.set_choices choices
 ```
 
-If all goes well, the `chosen` array will contain 100 sub-arrays, each containing the list of marked choices for that item, where the first cell is indicated by a 0, the second by a 1, etc. It is also possible to show the scoring graphically by applying an overlay on top of the scanned image.
+`choices` is equivalent to the array of integers passed to the `SheetPDF` constructor as part of the `content` parameter (see above).
+
+### Marking the response sheet
+
+We are now ready to mark the sheet:
+
+```ruby
+mc = s.marked_choices
+```
+
+Since the function `set_choices` returns true only if the sheet is properly registered, it can replace the call to `valid?`, allowing you to write something like:
+
+```ruby
+s = SheetOMR.new 'image.jpg', 'layout.yml'
+if s.set_choices [5] * 50
+  marked = s.marked_choices
+else
+  puts "The sheet is not registered!"
+end
+```
+
+If all goes well, the `marked` array will contain 100 sub-arrays, each containing the list of marked choices for that item, where the first cell is indicated by a 0, the second by a 1, etc.
+
+Read the [API documentation](http://www.rubydoc.info/gems/mork) to learn about additional methods to extract marked responses.
+
+### Applying overlays on the original image
+
+It is also possible to show the scoring graphically by applying an overlay on top of the scanned image.
 
 ```ruby
-s = SheetOMR.new 'image.jpg', choices: [5]*100, layout_file: 'layout.yml'
 s.overlay :check, :marked
 s.save 'marked_choices.jpg'
 system 'open marked_choices.jpg' # this works in OSX
@@ -194,14 +236,13 @@ system 'open marked_choices.jpg' # this works in OSX
 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:
 
 ```ruby
-...
 correct = [[3], [0], [2], [1], [2]] # and so on...
-s.overlay :check, :marked
 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
 ```
 
-
 Scoring can only be performed if the sheet gets properly registered, which in turn depends on the quality of the scanned image.
 
 ### Improving sheet registration and marking
@@ -213,14 +254,14 @@ Mork tries to be tolerant of variations in the above parameters, but you should
 Check for object “validity” to make sure that registration succeeded:
 
 ```ruby
-s = SheetOMR.new 'image.jpg', choices: [5]*100, layout_file: 'layout.yml'
+s = SheetOMR.new 'image.jpg', 'layout.yml'
 s.valid?
 ```
 
 When registration fails, it is possible to get some information by displaying the status and by applying a dedicated overlay on the original image:
 
 ```ruby
-s = SheetOMR.new 'image.jpg', choices: [5]*100, layout_file: 'layout.yml'
+s = SheetOMR.new 'image.jpg', 'layout.yml'
 unless s.valid?
   s.save_registration 'unregistered.jpg'
 end

data/lib/mork/grid.rb

@@ -9,7 +9,7 @@ module Mork
   class Grid
     # Calling Grid.new without arguments creates the default boilerplate Grid
     def initialize(options=nil)
-      @params = DGRID
+      @params = default_grid
       if File.exists?('layout.yml')
         @params.deeper_merge! symbolize YAML.load_file('layout.yml')
       end

data/lib/mork/grid_const.rb

@@ -1,86 +1,60 @@
 module Mork
-  # this is the default grid!
-  # default units are millimiters
-  DGRID = {
-    # size of the paper sheet
-    page_size: {
-      # this is A4
-      width:      210,
-      height:     297
-    },
-    # size, location, search parameters of registration marks
-    reg_marks: {
-      margin:      10,
-      radius:       3,
-      offset:       2, # distance between page edge and registraton mark search area
-      crop:        20, # size of square where the regmark should be located
-      dilate:       5, # set to >0 to apply a dilate IM operation
-      blur:         2, # set to >0 to apply a blur IM operation
-      contrast:    20  # minimum contrast between registration mark circles and the white paper
-    },
-    header: {
-      name: {
-        top:        5,
-        left:      15,
-        width:    160,
-        height:     7,
-        size:      14
-      },
-      title: {
-        top:       15,
-        left:      15,
-        width:    160,
-        height:    12,
-        size:      12
-      },
-      code: {
-        top:        35,
-        left:      130,
-        width:      57,
-        height:     10,
-        size:       14,
-        align:   :right
-      },
-      signature: {
-        top:        30,
-        left:       15,
-        width:     120,
-        height:     15,
-        size:        7,
-        box:      true
+  class Grid
+    # this is the default grid!
+    # default units are millimiters
+    def default_grid
+      {
+        # size of the paper sheet
+        page_size: {
+          width:      210, # A4
+          height:     297
+        },
+        # size, location, search parameters of registration marks
+        reg_marks: {
+          margin:      10, # from sheet edge to registration mark center
+          radius:       3, # of the registration circle
+          offset:       2, # distance between page edge and registraton mark search area
+          crop:        20, # size of square where the regmark should be located
+          dilate:       5, # set to >0 to apply a dilate IM operation
+          blur:         2, # set to >0 to apply a blur IM operation
+          contrast:    20  # minimum contrast between registration mark circles and the white paper
+        },
+        # you can place multiple elements in the header; title is the only default
+        header: {
+          title: {
+            top:       15,
+            left:      15,
+            width:    160,
+            height:    12,
+            size:      12
+          }
+        },
+        # questions and answers
+        items: {
+          threshold:     0.75, # how much darker a marked cell should be compared to cal cells
+          columns:       4,
+          column_width: 44,
+          rows:         30,
+          left:         11, # distance from the top-left registration mark...
+          top:          55, # ...to the center of the first choice cell
+          x_spacing:     7, # between choices
+          y_spacing:     7, # between rows
+          cell_width:    6, # choice cell size
+          cell_height:   5, # choice cell size
+          max_cells:     5, # the maximum number of choices per question
+          font_size:     9, # for the question number and choice letters
+          number_width:  8, # distance between right side of q num and left side of first choice cell
+          number_margin: 2  # width of question number text box
+        },
+        # unique sheet ID as a binary barcode
+        barcode: {
+          bits:         38,
+          left:         15,
+          width:         3,
+          height:        3,
+          spacing:       4
+        }
       }
-    }, # header end
-    items: {
-      threshold:     0.75,
-      columns:       4,
-      column_width: 44,
-      rows:         30,
-      # from the top-left registration mark
-      # to the center of the first choice cell
-      left:         11,
-      top:          55,
-      # between choices
-      x_spacing:     7,
-      # between rows
-      y_spacing:     7,
-      # darkened area
-      cell_width:    6,
-      cell_height:   5,
-      # the maximum number of choices per question
-      max_cells:     5,
-      # font size for the question number and choice letters
-      font_size:     9,
-      # distance between right side of q num and left side of first choice cell
-      number_width:  8,
-      # width of question number text box
-      number_margin: 2
-    }, # items end
-    barcode: {
-      bits:         40,
-      left:         15,
-      width:         3,
-      height:        3,
-      spacing:       4
-    } # barcode end
-  }
+    end
+  end
 end

data/lib/mork/grid_pdf.rb

@@ -70,6 +70,10 @@ module Mork
       @cround ||= [width_of_cell, height_of_cell].min / 2
     end
 
+    def missing_header?(k)
+      @params[:header][k].nil?
+    end
+
     def page_size()      [page_width.mm, page_height.mm]         end
     def margins()        reg_margin.mm                           end
     def qnum_margin()    @params[:items][:number_margin].to_f.mm end

data/lib/mork/mimage.rb

@@ -5,12 +5,13 @@ module Mork
   # @private
   class Mimage
     attr_reader :rm
+    attr_reader :choxq # choices per question
 
-    def initialize(path, nitems, grom)
-      @mack   = Magicko.new path
-      @nitems = nitems
-      @grom   = grom.set_page_size @mack.width, @mack.height
-      @rm     = {} # registration mark centers
+    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
+      @rm    = {} # registration mark centers
       @valid = register
     end
 
@@ -27,17 +28,19 @@ module Mork
       }
     end
 
-    def marked
-      @logical_array_of_marked_cells ||= begin # memoization necessary?
-        itemator { |q, c| shade_of(q, c) < choice_threshold }
-      end
+    def set_ch(cho)
+      @choxq = cho
+      # if set_ch is called more than once, discard memoization
+      @marked_choices = nil
     end
 
-    def marked_int
-      marked.map do |q|
-        [].tap do |choices|
-          q.each_with_index do |choice, idx|
-            choices << idx if choice
+    def marked
+      @marked_choices ||= begin
+        @choxq.map.with_index do |ncho, q|
+          [].tap do |choices|
+            ncho.times do |c|
+              choices << c if shade_of(q, c) < choice_threshold
+            end
           end
         end
       end
@@ -58,11 +61,12 @@ module Mork
               when :cal
                 @grom.calibration_cell_areas
               when :marked
-                choice_cell_areas marked_int
+                choice_cell_areas marked
               when :all
                 all_choice_cell_areas
               when :max
-                @grom.max_questions.times.map { |i| (0...@grom.max_choices_per_question).to_a }
+                choice_cell_areas [@grom.max_choices_per_question] * @grom.max_questions
+                # @grom.max_questions.times.map { |i| (0...@grom.max_choices_per_question).to_a }
               when Array
                 choice_cell_areas where
               else
@@ -90,7 +94,7 @@ module Mork
     private                                                       #
     # ============================================================#
 
-    def itemator(items=@nitems)
+    def itemator(items=@choxq)
       items.map.with_index do |cho, q|
         if cho.is_a? Fixnum
           cho.times.map { |c| yield q, c }
@@ -105,7 +109,7 @@ module Mork
     end
 
     def all_choice_cell_areas
-      @all_choice_cell_areas ||= choice_cell_areas(@nitems)
+      @all_choice_cell_areas ||= choice_cell_areas(@choxq)
     end
 
     def each_corner
@@ -122,10 +126,10 @@ module Mork
       end
     end
 
-    # TODO: 0.75 should be a parameter
     def choice_threshold
-      # puts "CT #{@grom.choice_threshold.inspect}"
-      @choice_threshold ||= (cal_cell_mean - darkest_cell_mean) * @grom.choice_threshold + darkest_cell_mean
+      @choice_threshold ||= begin
+        (cal_cell_mean-darkest_cell_mean) * @grom.choice_threshold + darkest_cell_mean
+      end
     end
 
     def barcode_threshold
@@ -258,3 +262,13 @@ end
 # puts "BL: #{@rm[:bl].inspect}"
 
 # puts "REG #{@grom.rm_blur} - #{@grom.rm_dilate} - C #{c.inspect}"
+
+# def marked_int
+#   marked.map do |q|
+#     [].tap do |choices|
+#       q.each_with_index do |choice, idx|
+#         choices << idx if choice
+#       end
+#     end
+#   end
+# end

data/lib/mork/npatch.rb

@@ -10,8 +10,6 @@ module Mork
     def initialize(source, width, height)
       @patch = NArray.float(width, height)
       @patch[true] = source
-      # @width  = width
-      # @height = height
     end
 
     def average(coord)
@@ -22,11 +20,6 @@ module Mork
       @patch[coord.x_rng, coord.y_rng].stddev
     end
 
-    # def length
-    #   # is this only going to be used for testing purposes?
-    #   @patch.length
-    # end
-
     def centroid
       xp = @patch.sum(1).to_a
       yp = @patch.sum(0).to_a
@@ -59,3 +52,8 @@ end
 #   # tested with the few examples: spec/samples/rm0x.jpeg
 #   p.stddev > 20
 # end
+
+# def length
+#   # is this only going to be used for testing purposes?
+#   @patch.length
+# end

data/lib/mork/sheet_omr.rb

@@ -14,26 +14,14 @@ module Mork
   class SheetOMR
     # @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
+    # @param layout [String, Hash] the sheet description. Send a hash of
+    #   parameters or a string to specify the path/filename of a YAML file
+    #   containing the parameters. See the README file for a full listing
     #   of the available parameters.
-    def initialize(path, choices: nil, layout: nil)
+    def initialize(path, layout=nil)
       raise IOError, "File '#{path}' not found" unless File.exists? path
-      grom    = GridOMR.new layout
-      nitems  = case choices
-                when NilClass
-                  [grom.max_choices_per_question] * grom.max_questions
-                when Fixnum
-                  [grom.max_choices_per_question] * choices
-                when Array
-                  choices
-                end
-      @mim    = Mimage.new path, nitems, grom
+      grom = GridOMR.new layout
+      @mim = Mimage.new path, grom
     end
 
     # True if sheet registration completed successfully
@@ -43,6 +31,30 @@ 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(cho)
+      return false unless valid?
+      @mim.set_ch case cho
+                  when Fixnum; @mim.choxq[0...cho]
+                  when Array; cho
+                  else raise ArgumentError, 'Invalid choice set'
+                  end
+      true
+    end
+
     # Registration status for each of the four corners
     #
     # @return [Hash] { tl: Symbol, tr: Symbol, br: Symbol, bl: Symbol } where
@@ -78,7 +90,7 @@ module Mork
     # @return [Boolean]
     def marked?(question, choice)
       return if not_registered
-      @mim.marked[question][choice]
+      marked_choices[question].find {|x| x==choice} ? true : false
     end
 
     # The set of choice indices marked on the response sheet
@@ -89,12 +101,22 @@ module Mork
     #   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.
-    #
-    # Note that only the questions/choices indicated via the `choices` argument
-    # during object creation are evaluated.
     def marked_choices
       return if not_registered
-      @mim.marked_int
+      @mim.marked
+    end
+
+    # The set of choice indices marked on the response sheet. If more than one
+    # choice was marked for a question, the response is regarded as invalid and
+    # treated as if it had been left blank.
+    #
+    # @return [Array] an array of integers; each element contains
+    #   the (zero-based) marked choice for the corresponding question.
+    def marked_choices_unique
+      return if not_registered
+      marked_choices.map do |c|
+        c.length == 1 ? c.first : nil
+      end
     end
 
     # The set of letters marked on the response sheet. At this time, only the
@@ -102,9 +124,6 @@ module Mork
     #
     # @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
       marked_choices.map do |q|
@@ -112,13 +131,17 @@ module Mork
       end
     end
 
-    # Marked choices as boolean values
+    # The set of letters marked on the response sheet. At this time, only the
+    # latin sequence 'A, B, C...' is supported. If more than one choice was
+    # marked for an item, the response is regarded as invalid and treated as if
+    # it had been left blank.
     #
-    # @return [Array] an array of arrays of true/false values corresponding to
-    #   marked vs unmarked choice cells.
-    def marked_logicals
+    # @return [Array] an array of 1-character strings
+    def marked_letters_unique
       return if not_registered
-      @mim.marked
+      marked_choices_unique.map do |c|
+        c.nil?? '' : (65+c).chr
+      end
     end
 
     # Apply an overlay on the image
@@ -131,8 +154,8 @@ module Mork
     #   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
+    #   than `:all`); `:barcode`: the dark barcode elements; `:cal` the
+    #   calibration cells
     def overlay(what, where=:marked)
       return if not_registered
       @mim.overlay what, where
@@ -276,3 +299,26 @@ end
 # def barcode_bit_string(i)
 #   @mim.barcode_bit?(i) ? "1" : "0"
 # end
+
+# def validate_choices(ch=nil)
+#   return false unless valid?
+#   cho = case ch
+#         when NilClass; [@mc] * @mq
+#         when Fixnum;   [@mc] * [[ch, @mq].min, 1].max
+#         when Array;     ch
+#         else raise ArgumentError, 'Invalid choice set'
+#         end
+#   @marked_choices = @mim.marked cho
+#   true
+# end
+
+# # 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
+#   # this is the only marking function calling the mimage object
+#   @marked_choices ||= @mim.marked
+# end
+

data/lib/mork/sheet_pdf.rb

@@ -90,8 +90,11 @@ module Mork
       @grip.barcode_xy_for(code).each { |c| stamp_at 'barcode', c }
     end
 
-    def header(content)
-      content.each do |k,v|
+    def header(elements)
+      elements.each do |k,v|
+        if @grip.missing_header? k
+          raise ArgumentError, "The header element '#{k}' is not described in the layout"
+        end
         font_size @grip.header_size(k) do
           align = @grip.header_align(k).nil?? :left : @grip.header_align(k).to_sym
           if @grip.header_boxed?(k)

data/lib/mork/version.rb

@@ -1,3 +1,3 @@
 module Mork
-  VERSION = '0.9.3'
+  VERSION = '0.10.0'
 end

data/spec/mork/mimage_spec.rb

@@ -7,7 +7,7 @@ module Mork
     context 'John Doe' do
       let(:img) { sample_img 'jdoe1' }
       let(:fn)  { File.basename(img.image_path) }
-      let(:mim) { Mimage.new img.image_path, [img.nchoices]*img.nitems, GridOMR.new(img.grid_path)  }
+      let(:mim) { Mimage.new img.image_path, GridOMR.new(img.grid_path)  }
       describe 'basics' do
         it 'should be valid' do
           expect(mim.valid?).to be_truthy

data/spec/mork/sheet_omr_spec.rb

@@ -6,7 +6,7 @@ module Mork
     context 'with a valid response sheet' do
       let(:img) { sample_img 'jdoe1' }
       let(:fn)  { File.basename(img.image_path) }
-      let(:omr) { SheetOMR.new img.image_path, choices: [img.nchoices]*img.nitems, layout: img.grid_path }
+      let(:omr) { SheetOMR.new img.image_path, layout: img.grid_path }
       describe '#new' do
         it 'creates a SheetOMR object' do
           expect(omr).to be_a SheetOMR
@@ -17,6 +17,12 @@ module Mork
         end
       end
 
+      describe '#set_choices' do
+        it 'returns true if all goes well' do
+          expect(omr.set_choices(10)).to be_truthy
+        end
+      end
+
       describe '#valid?' do
         it 'registers correctly' do
           expect(omr.valid?).to be_truthy
@@ -50,29 +56,18 @@ module Mork
         end
       end
 
-      describe '#marked_choices' do
-        it 'returns an array of marked choices as position indices' do
-          expect(omr.marked_choices).to eq standard_mark_array(24)
-        end
-      end
-
       describe '#marked_choices' do
         it 'returns an array of marked choices as position indexes' do
           expect(omr.marked_choices ).to eq standard_mark_array(24)
         end
 
-        let(:om2) { SheetOMR.new img.image_path, choices: [5, 4, 3, 2, 1], layout: img.grid_path }
+        let(:om2) { SheetOMR.new img.image_path, layout: img.grid_path }
         it 'returns marked choices only for existing choice cells' do
+          om2.set_choices [5, 4, 3, 2, 1]
           expect(om2.marked_choices).to eq [[0], [1], [2], [], []]
         end
       end
 
-      describe '#marked_logicals' do
-        it 'returns an array of logicals for the marked choices' do
-          expect(omr.marked_logicals).to eq standard_mark_logical_array(24)
-        end
-      end
-
       describe '#marked_letters' do
         it 'returns an array of characters for the marked choices' do
           expect(omr.marked_letters).to eq standard_mark_char_array(24)
@@ -96,8 +91,15 @@ module Mork
         end
 
         it 'highlights all choice cells' do
+          omr.set_choices [5] * 32
           omr.overlay :highlight, :all
-          omr.save "spec/out/highlight/#{fn}"
+          omr.save "spec/out/highlight/all-#{fn}"
+        end
+
+        it 'highlights all possible choice cells' do
+          omr.set_choices [5] * 30
+          omr.overlay :highlight, :max
+          omr.save "spec/out/highlight/max-#{fn}"
         end
 
         it 'highlights marked cells' do
@@ -110,6 +112,12 @@ module Mork
           omr.save "spec/out/mark/#{fn}"
         end
 
+        it 'checks the first 32 marked cells' do
+          omr.set_choices [5] * 32
+          omr.overlay :check, :marked
+          omr.save "spec/out/mark/part-#{fn}"
+        end
+
         it 'outlines and crosses marked cells' do
           omr.overlay :outline, standard_mark_array(24)
           omr.overlay :check

data/spec/mork/sheet_pdf_spec.rb

@@ -4,13 +4,10 @@ module Mork
   describe SheetPDF do
     let(:content) {
       {
-        barcode: 1234566,
+        barcode: 183251937962,
         choices: [5] * 120,
         header: {
-          name: 'John Doe UI01234',
-          title: 'A really serious and difficult test - 18 January 2013',
-          code:  '201.48',
-          signature: 'Signature'
+          title: 'A serious, difficult test - 31 December 1999',
         }
       }
     }
@@ -29,6 +26,12 @@ module Mork
       lambda { SheetPDF.new(content, 2) }.should raise_error ArgumentError
     end
 
+    it 'raises an error if a header part is not described in the layout' do
+      lambda {
+        SheetPDF.new({header: {dummy: 'yes I am'}})
+        }.should raise_error ArgumentError
+    end
+
     it 'assigns an array to @content' do
       s = SheetPDF.new(content)
       s.instance_variable_get('@content').should be_an Array
@@ -39,62 +42,67 @@ module Mork
       s.instance_variable_get('@content').first.should be_a Hash
     end
 
-    it 'creates a basic PDF sheet' do
-      s = SheetPDF.new(content)
-      s.save('spec/out/pdf/sheet.pdf')
+    it 'creates a minimal PDF sheet' do
+      s = SheetPDF.new({})
+      s.save dest 'minimal'
+    end
+
+    it 'creates a PDF sheet with a big barcode' do
+      s = SheetPDF.new({barcode: 183251937962})
+      s.save dest 'bigbarcode'
     end
 
-    it 'creates a boxed PDF sheet' do
+    it 'creates a PDF sheet with several boxed header elements' do
       h = {
         name: lorem,
         title: lorem,
         code: '1000.10.100',
         signature: 'Signature'
       }
-      s = SheetPDF.new(content.merge({header: h}), 'spec/samples/boxy.yml')
-      s.save('spec/out/pdf/boxy.pdf')
+      s = SheetPDF.new({header: h}, 'spec/samples/boxy.yml')
+      s.save dest 'boxy'
     end
 
-    it 'creates a basic PDF sheet with a code of 15' do
-      s = SheetPDF.new(content.merge({barcode: 15}))
-      s.save('spec/out/pdf/sheet16.pdf')
-    end
-
-    it 'creates a basic PDF sheet with a code of 666666666666' do
-      s = SheetPDF.new(content.merge({barcode: 666666666666}))
-      s.save('spec/out/pdf/sheet666.pdf')
-    end
-
-    it 'creates a PDF sheet with the maximum possible barcode' do
-      s = SheetPDF.new(content.merge({barcode: 1099511627775}))
-      s.save('spec/out/pdf/maxcode.pdf')
+    it 'creates a PDF sheet with the maximum possible barcode for 38 bits' do
+      c = {
+        barcode: 274877906943,
+        header: {
+          title: 'The maximum barcode for 38 bits is 274877906943'
+        }
+      }
+      s = SheetPDF.new(c)
+      s.save dest 'maxcode'
     end
 
     it 'creates a PDF sheet with 160 items' do
       s = SheetPDF.new(content.merge({choices: [5] * 160}), 'spec/samples/grid160.yml')
-      s.save('spec/out/pdf/i160.pdf')
+      s.save dest 'i160'
     end
 
     it 'creates a PDF sheet with unequal choices per item' do
-      s = SheetPDF.new(content.merge({choices: [5, 4, 3, 2, 1, 5, 4, 3, 2, 1, 5, 4, 3, 2, 1, 5, 4, 3, 2, 1, 5, 4, 3, 2, 1, 5, 4, 3, 2, 1, 5, 4, 3, 2, 1]}), 'spec/samples/layout.yml')
-      s.save('spec/out/pdf/uneq.pdf')
+      c = {
+        choices: [5, 4, 3, 2, 1, 5, 4, 3, 2, 1, 5, 4, 3, 2, 1, 5, 4, 3, 2, 1, 5, 4, 3, 2, 1, 5, 4, 3, 2, 1, 5, 4, 3, 2, 1],
+        header: {
+          title: 'Each question can have an arbitrary number of choices'
+        }
+      }
+      SheetPDF.new(c).save dest('uneq')
     end
 
     it 'creates 20 PDF sheets' do
-      c = content
-      s = SheetPDF.new([c,c,c,c,c,c,c,c,c,c,c,c,c,c,c,c,c,c,c,c])
-      s.save('spec/out/pdf/p20.pdf')
-    end
-
-    it 'creates a pdf with minimal content' do
-      s = SheetPDF.new({choices: [4] * 30})
-      s.save 'spec/out/pdf/mincont.pdf'
+      c = 20.times.collect do |x|
+        content.merge({ header: {title: "Test #{x+1}"}, barcode: x})
+      end
+      SheetPDF.new(c).save dest('p20')
     end
 
     it 'creates a PDF with the maximum possible choice cells if none are specified' do
       ct = [{}, {choices: [3]*20}]
-      s = SheetPDF.new ct
-      s.save 'spec/out/pdf/nocontent.pdf'
+      SheetPDF.new(ct).save dest('nocontent')
+    end
+
+    def dest(fname)
+      "spec/out/pdf/#{fname}.pdf"
     end
   end
 end

data/spec/samples/boxy.yml

@@ -1,13 +1,3 @@
-page_size:             # all measurements in mm
-  width:        210    # width of the paper sheet
-  height:       297    # height of the paper sheet
-reg_marks:
-  margin:        10    # distance from each page border to registration mark center
-  radius:         3    # registration mark radius
-  offset:         2    # distance between the search area and each page border (*)
-  crop:          20
-  blur:           2
-  dilate:         5
 header:
   name:                # ‘name’ is just a label; you can add arbitrary header elements
     top:          5    # margin relative to registration frame top side
@@ -15,7 +5,7 @@ header:
     width:      160    # text will be fitted to this width
     height:       7    # text will be fitted to this height
     size:        14    # font size
-    # box:       true
+    box:       true
   title:
     top:         15
     left:        15
@@ -38,23 +28,3 @@ header:
     height:      15
     size:         7
     box:       true    # header element will be enclosed in a box
-items:
-  top:           55.5  # response area margin, relative to reg frame
-  left:          10.5  # response area margin, relative to reg frame
-  rows:          30    # number of items per column
-  columns:        4    # number of columns
-  column_width:  44    #
-  x_spacing:      7    # horizontal distance between ajacent cell centers
-  y_spacing:      7    # vertical distance between ajacent cell centers
-  cell_width:     6    # width of each choice and calibration cell
-  cell_height:    5    # height of each choice and calibration cell
-  max_cells:      5    # maximum number of choices per item
-  font_size:      9    # size of both the item number and choice cell letter
-  number_width:   8    #
-  number_margin:  2    # margin between
-barcode:
-  bits:          40    # the maximum sheet identifier is 2 to the power or bits
-  left:          15    # distance between registration frame side and the first barcode bit
-  width:          3    # width of each barcode bit
-  height:         2.5  # height of each barcode bit from the registration frame bottom side
-  spacing:        4    # horizontal distance between adjacent barcode bit centers

data/spec/samples/info.yml

@@ -4,7 +4,7 @@ jdoe1:
   nchoices:    5
   nitems:      120
   barcode_int: 1234566
-  barcode_str: '0000000000000000000100101101011010000110'
+  barcode_str: '00000000000000000100101101011010000110'
   width:       1240
   height:      1754
   mark_array:  [[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4],[0],[1],[2],[3],[4]]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mork
 version: !ruby/object:Gem::Version
-  version: 0.9.3
+  version: 0.10.0
 platform: ruby
 authors:
 - Giuseppe Bertini
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-15 00:00:00.000000000 Z
+date: 2016-06-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: narray