mork 0.10.0 → 0.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4aab0200b0c68dc3f3720fef8b8ae239d1c3d521
-  data.tar.gz: 7b1dcdfea624a8d99f98230ee3899c51ce5f90ed
+  metadata.gz: 23ab6d5cb32c6c9474e304f619305b1841afb6a7
+  data.tar.gz: 021b401aeb958368de5bdaaf64908bbc42dc1e14
 SHA512:
-  metadata.gz: 4002e21d4604887c06c75dedfd6689316364766276f3dff453cd7dd774ae752a9293098d18a72a236ce607eb81ac8b53d65d985b83b67b157f844e2f1706de5a
-  data.tar.gz: d9720227584eef5a59d842cd4b713b6c021b7eac3d6398124c6affbf65f21e2d0d44751ba436e0aee5d305721fb49d27441e5b2aa48a5d1539b5d12c780dc108
+  metadata.gz: be6f8857ff7c2559204d40a5d7ac743a1b64cc2f6b9a84ee7c4b54956db55754180d07d3ecf0a36fc77e838f4758e55d99b710740328e36e76b1b58b2e1834d3
+  data.tar.gz: 3bef5ff687f155a1094ff2a384e7b0cb4b504b1cdc7c47e68b5766cdb714b4214752a24154e7f9170ba4b3a96c2a1bc6b544a6e1adc319d33498935c5fef3664

data/README.md

@@ -3,11 +3,11 @@
 A ruby [optical mark recognition](http://en.wikipedia.org/wiki/Optical_mark_recognition) (OMR) library aimed at accomplishing two tasks in the context of paper-based, multiple-choice tests and surveys:
 
 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.
+2. detecting 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
+## Roadmap
 
-__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.__
+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
 
@@ -29,7 +29,7 @@ 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 an 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:
 
@@ -57,10 +57,14 @@ Edit the file `mork_test.rb` with the code snippets below, then execute the foll
 
 ## Generating response sheets with `SheetPDF`
 
-Response sheets are created through the `Mork::SheetPDF` class. Two pieces of information must be provided to the class constructor to produce a meaningful sheet:
+Response sheets are created through the `Mork::SheetPDF` class. Two pieces of information must be provided to the class constructor to produce a meaningful sheet or, more commonly, a set of similar sheets:
 
-- **content**: what to place on the sheet, such as how many response items and choices, what to write in the header, the number to print as a barcode
-- **layout**: sizes, margins, spacing, fonts, etc., of each of the printed elements
+- **content**: what to place specifically on each sheet, such as how many response items and choices, what to write in the header, the number to print as a barcode
+- **layout**: the sheet description in terms of element positioning, sizes, margins, spacing, fonts, etc. Layout settings apply equally to all generated sheets
+
+```ruby
+s = SheetPDF.new content, layout
+```
 
 Let’s look at each argument in turn.
 
@@ -70,16 +74,16 @@ The `content` argument should be a hash like the following:
 
 ```ruby
 content = {
-  # the response sheet's unique identifier; it is printed
-  # in binary form as a barcode at the bottom of the sheet
-  barcode: 123456,
   # number of items and number of choices per item
   # in this case: 100 items with 5 choices each
   choices: [5] * 100,
+  # the response sheet's unique identifier; it is printed
+  # in binary form as a barcode at the bottom of the sheet
+  barcode: 123456,
   # stuff to print in the header
   header: {
     name: 'John Doe UI354320',
-    title: 'Anatomy and Physiology test, Sept 20, 2014',
+    title: 'A serious, difficult test - 31 December 1999',
     code:  '201.48',
     signature: 'Signature'
   }
@@ -89,86 +93,131 @@ 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 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
+- **barcode**: an integer number, the sheet's unique identifier to be printed as a binary barcode along the bottom edge of the sheet; if omitted, no barcode is printed
+- **header**: a (sub)hash defining header elements, where each key is the element’s name and each value is the content to be rendered; you can place an arbitrary number of elements in the header, as long as the same element names are also defined in the `layout` (see below); if omitted, no header elements are printed
+
+In most situations, you will want to generate several sheets at once. To do that, simply pass an array of content hashes to the constructor.
+
+```ruby
+content = [
+  {
+    barcode: 1001,
+    header: { name: 'John Doe UI354320', code:  '1001'}
+  },
+  {
+    barcode: 1002,
+    header: { name: 'Jane Roe UI354321', code:  '1002'}
+  }
+]
+```
+
+The `content` can also be specified by passing a string with the path/name of a YAML file like the following:
+
+```yaml
+- barcode: 1001
+  header:
+    name: 'John Doe UI354320'
+    code: '1001'
+- barcode: 1002
+  header:
+    name: 'Jane Roe UI354321'
+    code: '1002'
+```
 
 ### layout
 
-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).
+The layout specifies exactly the size and location of choice cells, header elements, and barcode bits; it also specifies parameters to fine tune detection of marked cells and of registration marks (see below).
+
+The layout hash is put together in 3 steps during `SheetPDF` initialization:
+
+1. at first, the layout is generated based on a set of built-in options
+2. next, if a file named `layout.yml` exists in the current path, Mork automatically parses it; any values found override the built-in ones
+3. finally, values specified in the constructor argument override the existing ones
+
+This is the list of built-in values that the layout is initially based on. 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
-  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
-  crop:            20     # 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) (*)
-  contrast:        20     # minimum contrast between registration mark circles and the surrounding white paper (*)
-header:           
-  name:                   # ‘name’ is just a label; you can add arbitrary header elements
-    top:            5     # margin relative to registration frame top side
-    left:          15     # margin relative to registration frame left side
-    width:        160     # text will be fitted to this width
-    height:         7     # ...and this height
-    size:          14     # font size
-  title:
-    top:           15
-    left:          15
-    width:        160
-    height:        12
-    size:          12
-  code:
-    top:           35
-    left:         130
-    width:         57
-    height:        10
-    size:          14
-  signature:
-    top:            30
-    left:           15
-    width:         120
-    height:         15
-    size:            7
-    box:          true    # header element will be enclosed in a box
+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    # size of the registration mark search area (*)
+  dilate:         5    # size of a “dilate” filter to get rid of stray noise (0 to skip) (*)
+  blur:           2    # size of a gaussian blur filter to smooth overly pixelated registration marks (0 to skip) (*)
+  contrast:      20    # minimum contrast between registration mark circles and the surrounding white paper (*)
+header:
+  title:               # ‘title’ is a label of your choosing; you can add arbitrary header elements
+    top:         15    # margin relative to registration frame top side
+    left:        15    # margin relative to registration frame left side
+    width:      160    # text will be fitted to this width
+    height:      12    # text will be fitted to this height
+    size:        12    # font size
+    box:      false    # if true, header element will be enclosed in a frame
 items:
-  threshold:         0.75 # mark detection threshold (*)
-  top:              55    # response area margin, relative to reg frame
-  left:             11    # 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
+  threshold:      0.75 # mark detection threshold (*)
+  columns:        4    # number of columns
+  column_width:  44    #
+  rows:          30    # number of items per column
+  left:          11    # response area margin, relative to reg frame
+  top:           55    # response area margin, relative to reg frame
+  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    # the maximum number of choices per question
+  font_size:      9    # for the question number and choice letters
+  number_width:   8    # width of question number text box
+  number_margin:  2    # distance between right side of q num and left side of first choice cell
 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:            3    # height of each barcode bit from the registration frame bottom side
-  spacing:           4    # horizontal distance between adjacent barcode bit centers
+  bits:          38    # 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:         3    # height of each barcode bit from the registration frame bottom side
+  spacing:        4    # horizontal distance between adjacent barcode bit centers
+```
+
+A `layout.yml` file may be used on top of the above to always apply settings that you would consider your own defaults. A good example might be to override the built-in A4 paper size with Letter paper width and height. For example, if everthing in the built-in layout fits your needs except for paper size, the `layout.yml` file should contain just the following:
+
+```yaml
+page_size:
+  width:   215.9
+  height:  279.4
 ```
 
-Assuming that the above text is written in a file named `layout.yml`, here's how to create a `SheetPDF` object and write the PDF file to disk:
+Finally, the `layout` argument into the `SheetPDF` constructor can be either a hash or a string indicating the path/name of a YAML file.
+
+The specification of header elements is slightly different than all other settings, in that you are free to add any number of elements with arbitrary names, as long as each element is given the following properties: `top`, `left`, `width`, `height`, and `size` (see the built-in title element above). The `box` property is optional. As already noted, header elements can be used in the `content` only if their properties are defined in the `layout`.
+
+In summary, the following sample code shows how to create a 2-page PDF document:
 
 ```ruby
-s = SheetPDF.new content, 'layout.yml'
+content = [
+  {
+    barcode: 1001,
+    header: { name: 'John Doe UI354320', title: 'Final exam', code:  '1001'}
+  },
+  {
+    barcode: 1002,
+    header: { name: 'Jane Roe UI354321', title: 'Final exam', code:  '1002'}
+  }
+]
+
+layout = {
+  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: 15, left: 155, width:  35, height: 10, size: 14 }
+  }
+}
+
+sheet = SheetPDF.new content, layout
 s.save 'sheet.pdf'
 system 'open sheet.pdf' # this works in OSX
 ```
 
-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).
-
-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`
 
 ### Preparing a `SheetOMR` object
@@ -176,13 +225,13 @@ Importantly, if `content` is an array of hashes, Mork will produce one sheet for
 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)
-- **layout_file**: same as for the `SheetPDF` class
+- **layout**: same as for the `SheetPDF` class
 
 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', 'layout.yml'
+s = SheetOMR.new 'image.jpg', 'mylayout.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:
@@ -208,18 +257,18 @@ We are now ready to mark the sheet:
 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:
+Since the function `set_choices` returns true only if the sheet is properly registered, you can write something like the following (instead of calling `valid?`):
 
 ```ruby
-s = SheetOMR.new 'image.jpg', 'layout.yml'
+s = SheetOMR.new 'image.jpg'
 if s.set_choices [5] * 50
-  marked = s.marked_choices
+  puts 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.
+If all goes well, the `marked` array will contain 50 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.
 
@@ -247,21 +296,14 @@ Scoring can only be performed if the sheet gets properly registered, which in tu
 
 ### Improving sheet registration and marking
 
-For Mork to be able to register the response sheet, the acquired image should be of _sufficient_ resolution and contrast, and it should be straight, with some white margin around the 4 registration circles.
+For Mork to be able to register the response sheet, the acquired image must be of _sufficient_ resolution and contrast, and it should be _reasonably_ straight, with some white margin around the 4 registration circles.
 
 Mork tries to be tolerant of variations in the above parameters, but you should experiment with your own layout, actual printout, and actual scans.
 
-Check for object “validity” to make sure that registration succeeded:
-
-```ruby
-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', 'layout.yml'
+s = SheetOMR.new 'image.jpg', 'mylayout.yml'
 unless s.valid?
   s.save_registration 'unregistered.jpg'
 end

data/lib/mork.rb

@@ -2,3 +2,4 @@ require 'mork/version'
 require 'mork/extensions'
 require 'mork/sheet_omr'
 require 'mork/sheet_pdf'
+require 'yaml'

data/lib/mork/extensions.rb

@@ -1,19 +1,3 @@
-# @private
-class Array
-  def mean
-    @the_sample_mean ||= inject(:+)/length.to_f
-  end
-
-  def sample_variance
-    sum = inject(0){|accum, i| accum + (i-mean)**2 }
-    sum/(length - 1).to_f
-  end
-
-  def stdev
-    Math.sqrt sample_variance
-  end
-end
-
 # @private
 class Fixnum
   def mm
@@ -27,3 +11,29 @@ class Float
     self * 2.83464566929134
   end
 end
+
+module Mork
+  # @private
+  module Extensions
+    def symbolize(obj)
+      return obj.inject({}){|memo,(k,v)| memo[k.to_sym] =  symbolize(v); memo} if obj.is_a? Hash
+      return obj.inject([]){|memo,v    | memo           << symbolize(v); memo} if obj.is_a? Array
+      return obj
+    end
+  end
+end
+
+# # @private
+# class Array
+#   def mean
+#     @the_sample_mean ||= inject(:+)/length.to_f
+#   end
+#   def sample_variance
+#     sum = inject(0){|accum, i| accum + (i-mean)**2 }
+#     sum/(length - 1).to_f
+#   end
+#   def stdev
+#     Math.sqrt sample_variance
+#   end
+# end
+

data/lib/mork/grid.rb

@@ -1,4 +1,3 @@
-require 'yaml'
 require 'mork/grid_const'
 
 module Mork
@@ -7,6 +6,7 @@ module Mork
   # It knows nothing about the actual scanned image.
   # All returned values are in the arbitrary units given in the configuration file
   class Grid
+    include Extensions
     # Calling Grid.new without arguments creates the default boilerplate Grid
     def initialize(options=nil)
       @params = default_grid
@@ -67,11 +67,11 @@ module Mork
 
     # 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)
-      return obj.inject({}){|memo,(k,v)| memo[k.to_sym] =  symbolize(v); memo} if obj.is_a? Hash
-      return obj.inject([]){|memo,v    | memo           << symbolize(v); memo} if obj.is_a? Array
-      return obj
-    end
+    # def symbolize(obj)
+    #   return obj.inject({}){|memo,(k,v)| memo[k.to_sym] =  symbolize(v); memo} if obj.is_a? Hash
+    #   return obj.inject([]){|memo,v    | memo           << symbolize(v); memo} if obj.is_a? Array
+    #   return obj
+    # end
 
     # cell_y(q)
     #

data/lib/mork/grid_const.rb

@@ -1,5 +1,6 @@
 module Mork
   class Grid
+    # @private
     # this is the default grid!
     # default units are millimiters
     def default_grid
@@ -26,7 +27,8 @@ module Mork
             left:      15,
             width:    160,
             height:    12,
-            size:      12
+            size:      12,
+            box:    false
           }
         },
         # questions and answers
@@ -43,8 +45,8 @@ module Mork
           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
+          number_width:  8, # width of question number text box
+          number_margin: 2  # distance between right side of q num and left side of first choice cell
         },
         # unique sheet ID as a binary barcode
         barcode: {

data/lib/mork/mimage.rb

@@ -4,6 +4,8 @@ require 'mork/magicko'
 module Mork
   # @private
   class Mimage
+    include Extensions
+
     attr_reader :rm
     attr_reader :choxq # choices per question
 
@@ -137,7 +139,8 @@ module Mork
     end
 
     def cal_cell_mean
-      @grom.calibration_cell_areas.collect { |c| reg_pixels.average c }.mean
+      m = @grom.calibration_cell_areas.collect { |c| reg_pixels.average c }
+      m.inject(:+) / m.length.to_f
     end
 
     def darkest_cell_mean

data/lib/mork/sheet_omr.rb

@@ -45,11 +45,11 @@ module Mork
     #
     # @return [Boolean] True if the sheet is properly registered and ready to
     #   be marked; false otherwise.
-    def set_choices(cho)
+    def set_choices(choices)
       return false unless valid?
-      @mim.set_ch case cho
-                  when Fixnum; @mim.choxq[0...cho]
-                  when Array; cho
+      @mim.set_ch case choices
+                  when Fixnum; @mim.choxq[0...choices]
+                  when Array; choices
                   else raise ArgumentError, 'Invalid choice set'
                   end
       true

data/lib/mork/sheet_pdf.rb

@@ -6,17 +6,24 @@ module Mork
   # Generating response sheets as PDF files.
   # See the README file for usage
   class SheetPDF < Prawn::Document
+    include Extensions
     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
+      @content =
+        case content
+        when Array; content
+        when Hash; [content]
+        when String
+          raise IOError, "File '#{content}' not found" unless File.exists? content
+          symbolize YAML.load_file(content)
+        end
+      @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
-      # @content should be an array of hashes, one per page;
-      # convert to array if a single hash was passed
-      @content = content.class == Hash ? [content] : content
       process
     end
 

data/lib/mork/version.rb

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

data/spec/mork/grid_omr_spec.rb

@@ -52,7 +52,7 @@ module Mork
 
     describe '#max_choices_per_question' do
       it 'returns the maximum number of choice cells per question' do
-        @grom.max_choices_per_question.should == 5
+        expect(@grom.max_choices_per_question).to eq 5
       end
     end
 

data/spec/mork/grid_spec.rb

@@ -1,7 +1,16 @@
 require 'spec_helper'
+include Mork::Extensions
 
 module Mork
   describe Grid do
+    let(:base) { symbolize YAML.load_file('spec/samples/base_layout.yml') }
+
+    describe 'hash vs yaml' do
+      it 'makes sure that the default grid and the base_layout.yml are equivalent' do
+        expect(base).to eq(Grid.new.default_grid)
+      end
+    end
+
     context 'init params' do
       it 'does not work with an integer' do
         expect {Grid.new 1}.to raise_error ArgumentError
@@ -9,97 +18,17 @@ module Mork
     end
 
     context 'default grid' do
-      before(:all) do
-        @grid = Grid.new 'spec/samples/layout.yml'
-      end
-
       describe '#max_questions' do
         it 'returns the maximum number of questions in a sheet' do
-          @grid.max_questions.should == 120
+          expect(Grid.new.max_questions).to eq base[:items][:columns]*base[:items][:rows]
         end
       end
 
       describe '#barcode_bits' do
         it 'returns the number of bits used to define the form barcode' do
-          @grid.send(:barcode_bits).should == 40
+          expect(Grid.new.send(:barcode_bits)).to eq base[:barcode][:bits]
         end
       end
     end
   end
 end
-
-# describe "#question_area" do
-#   before(:each) do
-#     grid.reg_marks(@image)
-#   end
-#   it "returns a hash" do
-#     grid.question_area(1).should be_an_instance_of(Hash)
-#   end
-#
-#   it "returns the location in pixels of the first question patch" do
-#     c = grid.question_area(1)
-#     c[:x].should be_within(4).of(90)
-#     c[:y].should be_within(4).of(388)
-#   end
-#   it "returns the location in pixels of the 40th question patch" do
-#     c = grid.question_area(40)
-#     c[:x].should be_within(4).of(90)
-#     c[:y].should be_within(4).of(3120)
-#   end
-#
-#   it "returns the location in pixels of the 121th question patch" do
-#     c = grid.question_area(121)
-#     c[:x].should be_within(4).of(1887)
-#     c[:y].should be_within(4).of(388)
-#   end
-#
-#   it "returns the location in pixels of the last question patch" do
-#     c = grid.question_area(160)
-#     c[:x].should be_within(4).of(1887)
-#     c[:y].should be_within(4).of(3120)
-#   end
-# end
-
-# describe '#ctrl_area_dark' do
-#   it 'returns the coordinates of the control cell used to set the darkened threshold' do
-#     @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/sheet_pdf_spec.rb

@@ -7,39 +7,45 @@ module Mork
         barcode: 183251937962,
         choices: [5] * 120,
         header: {
-          title: 'A serious, difficult test - 31 December 1999',
+          title: 'A serious, difficult test - 31 December 1999'
         }
       }
     }
+    def sp(cnt: {title: 'Hello world'}, grip: nil)
+      SheetPDF.new cnt, grip
+    end
 
     it 'assigns the grid to @grid' do
-      s = SheetPDF.new(content)
-      s.instance_variable_get('@grip').should be_a GridPDF
+      expect(sp.instance_variable_get('@grip')).to be_a GridPDF
+    end
+
+    it 'uses a yaml file as content' do
+      s = 'spec/samples/content.yml'
+      c = sp(cnt: s).instance_variable_get('@content')[0][:choices]
+      expect(c).to eq [5,5,5,4,5,5,5]
     end
 
     it 'creates a grid by loading the specified file' do
-      s = SheetPDF.new(content, 'spec/samples/layout.yml')
-      s.instance_variable_get('@grip').should be_a GridPDF
+      s = 'spec/samples/layout.yml'
+      expect(sp(grip: s).instance_variable_get('@grip')).to be_a GridPDF
     end
 
     it 'raises an error with an invalid init parameter' do
-      lambda { SheetPDF.new(content, 2) }.should raise_error ArgumentError
+      expect { SheetPDF.new(content, 2) }.to 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
+      expect {
+        sp(cnt: {header: {dummy: 'yes I am'}})
+        }.to raise_error ArgumentError
     end
 
     it 'assigns an array to @content' do
-      s = SheetPDF.new(content)
-      s.instance_variable_get('@content').should be_an Array
+      expect(sp.instance_variable_get('@content')).to be_an Array
     end
 
     it 'assigns an array of hashes to @content' do
-      s = SheetPDF.new(content)
-      s.instance_variable_get('@content').first.should be_a Hash
+      expect(sp.instance_variable_get('@content').first).to be_a Hash
     end
 
     it 'creates a minimal PDF sheet' do
@@ -53,6 +59,17 @@ module Mork
     end
 
     it 'creates a PDF sheet with several boxed header elements' do
+      h = {
+        name: 'John Doe UI354320',
+        title: 'A serious, difficult test - 31 December 1999',
+        code: '201.48',
+        signature: 'Signature'
+      }
+      s = SheetPDF.new({header: h, barcode: 2384685871}, 'spec/samples/standard.yml')
+      s.save dest 'standard'
+    end
+
+    it 'creates a PDF sheet with several header elements' do
       h = {
         name: lorem,
         title: lorem,
@@ -75,8 +92,8 @@ module Mork
     end
 
     it 'creates a PDF sheet with 160 items' do
-      s = SheetPDF.new(content.merge({choices: [5] * 160}), 'spec/samples/grid160.yml')
-      s.save dest 'i160'
+      c = { header: {title: '160 items, tighter layout'}, choices: [5]*160}
+      sp(cnt: c, grip: 'spec/samples/grid160.yml').save dest 'i160'
     end
 
     it 'creates a PDF sheet with unequal choices per item' do

data/spec/samples/base_layout.yml

@@ -0,0 +1,40 @@
+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    # size of the registration mark search area (*)
+  dilate:         5    # size of a “dilate” filter to get rid of stray noise (0 to skip) (*)
+  blur:           2    # size of a gaussian blur filter to smooth overly pixelated registration marks (0 to skip) (*)
+  contrast:      20    # minimum contrast between registration mark circles and the surrounding white paper (*)
+header:
+  title:               # ‘title’ is a label of your choosing; you can add arbitrary header elements
+    top:         15    # margin relative to registration frame top side
+    left:        15    # margin relative to registration frame left side
+    width:      160    # text will be fitted to this width
+    height:      12    # text will be fitted to this height
+    size:        12    # font size
+    box:      false    # if true, header element will be enclosed in a box
+items:
+  threshold:      0.75 # mark detection threshold (*)
+  columns:        4    # number of columns
+  column_width:  44    #
+  rows:          30    # number of items per column
+  left:          11    # response area margin, relative to reg frame
+  top:           55    # response area margin, relative to reg frame
+  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    # the maximum number of choices per question
+  font_size:      9    # for the question number and choice letters
+  number_width:   8    # width of question number text box
+  number_margin:  2    # distance between right side of q num and left side of first choice cell
+barcode:
+  bits:          38    # 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:         3    # height of each barcode bit from the registration frame bottom side
+  spacing:        4    # horizontal distance between adjacent barcode bit centers

data/spec/samples/content.yml

@@ -0,0 +1,9 @@
+- choices: [5,5,5,4,5,5,5]
+  barcode: 122
+  header:
+    title: 'A difficult test'
+
+- choices: [2]
+  barcode: 123
+  header:
+    title: 'An easier test'

data/spec/samples/standard.yml

@@ -0,0 +1,27 @@
+header:
+  name:                # ‘name’ is just a label; you can add arbitrary header elements
+    top:          5    # margin relative to registration frame top side
+    left:        15    # margin relative to registration frame left side
+    width:      160    # text will be fitted to this width
+    height:       7    # text will be fitted to this height
+    size:        14    # font size
+  title:
+    top:         15
+    left:        15
+    width:      160
+    height:      12
+    size:        12
+  code:
+    top:         30
+    left:       152
+    width:       35
+    height:      10
+    size:        14
+    align:    right
+  signature:
+    top:         30
+    left:        15
+    width:      120
+    height:      15
+    size:         7
+    box:       true

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mork
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.1
 platform: ruby
 authors:
 - Giuseppe Bertini
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-17 00:00:00.000000000 Z
+date: 2016-06-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: narray
@@ -197,7 +197,6 @@ files:
 - mork.gemspec
 - mork.sublime-project
 - spec/mork/coord_spec.rb
-- spec/mork/extensions_spec.rb
 - spec/mork/grid_omr_spec.rb
 - spec/mork/grid_spec.rb
 - spec/mork/magicko_spec.rb
@@ -216,7 +215,9 @@ files:
 - spec/samples/angolo.jpg
 - spec/samples/angolo2.jpg
 - spec/samples/angolo3.jpg
+- spec/samples/base_layout.yml
 - spec/samples/boxy.yml
+- spec/samples/content.yml
 - spec/samples/grid.yml
 - spec/samples/grid160.yml
 - spec/samples/grid_omr_layout.yml
@@ -226,15 +227,6 @@ files:
 - spec/samples/jdoe/JohnDoe3.jpeg
 - spec/samples/jdoe/layout.yml
 - spec/samples/layout.yml
-- spec/samples/lucrezia/border1.pdf
-- spec/samples/lucrezia/border2.pdf
-- spec/samples/lucrezia/bw1.pdf
-- spec/samples/lucrezia/bw2.pdf
-- spec/samples/lucrezia/gray1.pdf
-- spec/samples/lucrezia/gray2.pdf
-- spec/samples/marisol/marisol1.jpg
-- spec/samples/marisol/marisol2.jpg
-- spec/samples/marisol/marisol3.jpg
 - spec/samples/reg_mark.jpg
 - spec/samples/rm00.jpeg
 - spec/samples/rm01.jpeg
@@ -242,6 +234,8 @@ files:
 - spec/samples/rm03.jpeg
 - spec/samples/rm04.jpeg
 - spec/samples/rm05.jpeg
+- spec/samples/standard.png
+- spec/samples/standard.yml
 - spec/samples/syst/barr0.jpg
 - spec/samples/syst/barr1.jpg
 - spec/samples/syst/barr2.jpg

data/spec/mork/extensions_spec.rb

@@ -1,10 +0,0 @@
-require 'spec_helper'
-
-module Mork
-  describe Array do
-    it 'computes the average' do
-      a = [ 20, 23, 23, 24, 25, 22, 12, 21, 28 ]
-      expect(a.mean).to eq 22
-    end
-  end
-end