mork 0.0.9 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3929e72d06e1a597ab7bdd0dcc207487da5e3bcc
-  data.tar.gz: e4edcffb033afeed7317f439e7857611d45f6b7a
+  metadata.gz: cdc12cd7f6628650dd014afd86ed58f415b3167b
+  data.tar.gz: f39a614c5641b14b63cf0c7ba2f5cbda76219aff
 SHA512:
-  metadata.gz: fc76809688ef966f779724a0eb358de007d79eaa4a1b14bbe37a0791f7e77da0678d68219b2fb184d57c2bc3cbdaeaf03fd14f03b9e8a74eebc823633557cc77
-  data.tar.gz: a410e9ad165da458bcc27cd7d3928af11a548ae78c51dfcc0410b9e683012c3837ff571fcea7a3d2400d9530f5ba281ccb10d73417bea1ea1eaf8a7b23fec72d
+  metadata.gz: a17ad3a56ba66c46b7b1e583ce5d7a0184e365280814dc1144c4ff4594a63451a46344cf618e0ac07f87425ed88d92d2ec634434fd93ebcee3e6fa1a8ff802d0
+  data.tar.gz: adcdd8f1d6ca75d97dbd10f10e2195ee7203288196af55b85844352390a6275ff2c84d1464470b8619180116a8d6978b183a22ab29e5a77e1b02062149588c43

data/.gitignore

@@ -4,5 +4,7 @@ Gemfile.lock
 quick.rb
 pkg/*
 tmp/*
-.rvmrc
 .rspec
+.yardoc
+.ruby-version
+.ruby-gemset

data/.ruby-version

@@ -1 +1 @@
-ruby-2.0.0-p451
+ruby-2.1.2

data/README.md

@@ -1,46 +1,152 @@
 Mork
 ====
 
-A ruby [optical mark recognition](http://en.wikipedia.org/wiki/Optical_mark_recognition) (OMR) library to accomplish two tasks:
+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/sheet1.pdf) in PDF format (for tests, surveys, etc.)
-2. capturing the responses provided on the [printed sheet](/spec/samples/sheet1.jpg) by a human with a pen or a pencil.
+1. generating [response sheets](/spec/samples/sample01.pdf) in PDF format
+2. capturing the responses provided on the [printed sheet](/spec/samples/sample01.jpg) by a human with a pen or a pencil.
 
 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 to what the library is capable of apply.
 
-- the generated PDF file is intended to be printed on regular printer paper, and the filled-out form to be acquired as a bitmap image by a normal optical scanner or camera (i.e., no specialized equipment is necessary)
-- the [response sheet](/spec/samples/sheet1.pdf) contains the following items:
+- the PDF files generated by Mork [such as this one](/spec/samples/sample01.pdf) are intended to be printed on regular printer paper
+- all items must fit within the allocated response area of a single sheet
+- after collecting the responses, a filled-out form can be acquired as a bitmap image by a normal optical scanner or camera (i.e., no specialized equipment is necessary)
+- the response sheet contains the following items:
   - registration marks at each page corner
   - a bar code along the bottom margin to uniquely identify the sheet
   - a header area to print arbitrary information
   - a response area containing a list of numbered items (questions)
-  - each item contains an arbitrary number of choices, each marked with a capital letter (A, B, C, ...). In order to maximize contrast, choice "cells" are printed in red
+  - each item contains an arbitrary number of choices, each marked with a capital letter (A, B, C, ...). In order to maximize contrast, assuming that responses will be given using a black or blue pen, choice cells are printed in red
+  - the far right side of the response area is reserved for a column of calibration cells that must remain blank
 - with some restrictions, the number of columns in the response area, the numer of items, the number of choices per item, the size and shape of the choice cells can be set by the user
-- all items must fit within the allocated response area of a single sheet
-
-Installing
-----------
-
-Install the gem in your system:
-
-    $ gem install mork
-
-If you are using bundler in your project, as you should, make sure your `Gemfile` contains the following, before running `bundle install`:
-
-    source 'http://rubygems.org'
-    gem 'mork'
-
-Usage
------
 
-The layout of the response sheet is described in a YAML file
+Creating response sheets
+------------------------
+
+To create a small ruby project for testing purposes, cd into a directory of choice, then execute the following shell commands:
+
+```
+mkdir mork_test
+cd mork_test
+echo "source 'http://rubygems.org'" > Gemfile
+echo "gem 'mork'" >> Gemfile
+echo "require 'mork'" > mork_test.rb
+echo "include Mork" >> mork_test.rb
+bundle install
+```
+
+Creating response sheets is done through the `Mork::SheetPDF` class. 
+
+[...work in progress...]
+
+For example, add the following code to `mork_test.rb`:
+
+```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,
+  # stuff to print in the header
+  header: {
+    name: 'John Doe UI354320',
+    title: 'Anatomy and Physiology test, Sept 20, 2014',
+    code:  '201.48',
+    signature: 'Signature'
+  }
+}
+s = SheetPDF.new content
+s.save 'sheet.pdf'
+system 'open sheet.pdf' # this works in OSX
+```
+
+In the shell, execute the following and inspect the output PDF file
+
+    bundle exec ruby mork_test.rb
+
+The “content” hash provides SheetPDF with the information necessary to create a meaningful response sheet. These are the key-value pairs that the hash should contain:
+
+- `barcode`: an integer number, the sheet's unique identifier
+- `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)
+- `header`: a 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 Grid object (see below)
+
+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.)
+
+But where is the layout itself defined? In the above example, creating the SheetPDF with a single initialization parameter (the `content` hash) caused a default boilerplate layout to be invoked. In real life, however, you will want to have full control of the layout. This is accomplished by passing a `Mork::Grid` object as a second argument in the SheetPDF constructor call.
+
+The Grid is a layout descriptor, it tells the SheetPDF object in detail where to render what on the sheet. To get a rough idea of the information managed by a Grid, try this:
+
+```ruby
+g = Grid.new
+g.show
+```
+
+The YAML-formatted output you see is the full list of parameters that describe the default Grid.
+
+```yaml
+---
+:page_size:
+  :width: 210
+  :height: 297
+:regmarks:
+  :margin: 10
+  :radius: 2.5
+  :search: 10
+  :offset: 2
+:header:
+  :name:
+    :top: 5
+    :left: 7.5
+    :width: 170
+    :size: 14
+
+...more...
+```
+
+Thus, if you replace the call to SheetPDF with the following:
+
+```ruby
+s = SheetPDF.new content, Grid.new
+```
+
+...you get exactly the same result as before. In order to actually customize the layout, the Grid object must be constructed according to your own specifications. One way to initialize a custom Grid is to send the constructor a YAML path/file name. Copy the file `grid01.yml` from the `spec/samples` directory to your working directory. Edit some values, save, and execute:
+
+```ruby
+s = SheetPDF.new content, Grid.new('grid01.yml')
+s.save 'sheet.pdf'
+```
+
+Although this will work as well:
+
+```ruby
+s = SheetPDF.new content, 'grid01.yml'
+s.save 'sheet.pdf'
+```
+
+Please note that currently there are no sanity checks on Grid parameters. The user is entirely responsible for providing values that actually produce the desired layout.
+  
+Scoring response sheets
+-----------------------
+
+Copy the file `sample01.jpg` from `spec/samples` to your working directory, along with a fresh copy of `grid01.yml` and run the following:
+
+```ruby
+s = SheetOMR.new 'sample01.jpg', 'grid01.yml'
+s.highlight
+s.write 'highlights.jpg'
+system 'open highlights.jpg' # OSX only
+```
+
+Print out the PDF file you produced, and fill in a few response cells with a black pen. Be sure to also fill in the calibration ‘T’ cell. Now scan the sheet and save the image as a JPEG file (e.g. `img01.jpg`). A resolution of 150-200 dpi should be sufficient. Place the JPEG file in your working directory and run the following:
 
 License
 -------
 
-Copyright (c) 2013 Giuseppe Bertini
+Copyright (c) 2014 Giuseppe Bertini
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

data/lib/mork/extensions.rb

@@ -0,0 +1,26 @@
+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
+
+class Fixnum
+  def mm
+    self * 2.83464566929134
+  end
+end
+
+class Float
+  def mm
+    self * 2.83464566929134
+  end
+end

data/lib/mork/grid.rb

@@ -1,306 +1,60 @@
 require 'yaml'
+require 'mork/grid_const'
 
 module Mork
   # The Grid is a set of expectations on what the response sheet should look like
-  # It knows nothing about the actual scanned image
+  # It knows nothing about the actual scanned image.
   # All returned values are in the arbitrary units given in the configuration file
   class Grid
-    
+    # Calling Grid.new without arguments creates the default boilerplate Grid
     def initialize(options=nil)
       @params = DGRID
-      case options.class.to_s
-      when 'NilClass'
-        if File.exists? 'config/grid.yml'
+      case options
+      when NilClass
+        if File.exists?('config/grid.yml')
           @params.merge! symbolize YAML.load_file('config/grid.yml')
         end
-      when "Hash"
+      when Hash
         @params.merge! symbolize options
-      when "String"
+      when String
         @params.merge! symbolize YAML.load_file(options)
       else
-        raise "Invalid options parameter: #{options.class.inspect}"
+        raise "Invalid parameter in the Grid constructor: #{options.class.inspect}"
       end
     end
     
-    # symbolize(object)
-    #
-    # 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
+    # Puts out the Grid parameters in YAML format; the entire hash is displayed
+    # if no arguments are given; you can specify what to show by passing one of:
+    # :page_size, :regmarks, :header, :items, :barcode, :control
+    def show(subset=nil)
+      out = subset ? @params[subset] : @params
+      puts out.to_yaml
     end
     
     def options
       @params
     end
     
-    def set_page_size(x, y)
-      @px = x.to_f
-      @py = y.to_f
-    end
-    
     def max_questions
       columns * rows
     end
     
-    def max_choices_per_question
-      @params[:items][:max_cells].to_i
-    end
-    
-    def code_bits
-      @params[:code][:bits].to_i
-    end
-    
-    # ====================================================
-    # = Returning {x, y, w, h} hashes for area locations =
-    # ====================================================
-    # {} = rm_search_area(x, y)
-    #
-    # the 4 values needed to locate a single registration mark
-    def rm_search_area(corner, i)
-      {
-        x: (ppu_x * rmx(corner, i)).round,
-        y: (ppu_y * rmy(corner, i)).round,
-        w: (ppu_x * (reg_search + reg_step * i)).round,
-        h: (ppu_y * (reg_search + reg_step * i)).round
-      }
-    end
-    
-    def rm_edgy_x
-      (ppu_x * reg_radius).round + 5
-    end
-    
-    def rm_edgy_y
-      (ppu_y * reg_radius).round + 5
-    end
-    
-    def rm_max_search_area_side
-      (ppu_x * page_width / 4).round
-    end
-    
-    def choice_cell_area(q, c)
-      cell_area cell_x(q, c), cell_y(q)
-    end
-    
-    def ctrl_area_dark
-      cell_area ctrl_cell_x, ctrl_cell_y
-    end
-    
-    def ctrl_area_light
-      cell_area ctrl_cell_x + cell_spacing, ctrl_cell_y
-    end
-    
-    def cal_area_white
-      code_cell_area -1
-    end
-    
-    def cal_area_black
-      code_cell_area 0
-    end
-    
-    def code_bit_area(i)
-      raise "Invalid code bit" if i >= code_bits
-      code_cell_area i+1
-    end
-    
-    # ============
-    # = to Prawn =
-    # ============
-    def pdf_page_size
-      [page_width.mm, page_height.mm]
-    end
-    
-    def pdf_margins
-      reg_margin.mm
-    end
-    
-    def pdf_reg_marks
-      r = reg_radius.mm
-      [
-        { p: [0,                  0                  ], r: r },
-        { p: [0,                  reg_frame_height.mm], r: r },
-        { p: [reg_frame_width.mm, reg_frame_height.mm], r: r },
-        { p: [reg_frame_width.mm, 0                  ], r: r }
-      ]
-    end
-    
-    def pdf_dark_calibration_area
-      pdf_code_cell_area 0
-    end
-
-    def pdf_code_areas_for(code)
-      a = []
-      code_bits.times do |bit|
-        a << pdf_code_cell_area(bit+1) if code[bit] == 1
-      end
-      a
-    end
-
-    def pdf_code_bit_areas
-      (1..code_bits).collect do |bit|
-        pdf_code_cell_area bit
-      end
-    end
-    
-    def pdf_code_cell_area(i)
-      {
-        p: [code_cell_x(i).mm, (reg_frame_height - code_y).mm],
-        w: code_width.mm,
-        h: code_height.mm * 2
-      }
-    end
-
-    def pdf_choice_cell_area(q, c)
-      {
-        p: [cell_x(q, c).mm, (reg_frame_height - cell_y(q)).mm],
-        w: cell_width.mm,
-        h: cell_height.mm
-      }
-    end
-
-    def pdf_choice_letter_xy(q, c)
-      [
-        cell_x(q, c).mm + 2.mm,
-        (reg_frame_height - cell_y(q)).mm - (cell_height*2)
-      ]
-    end
-
-    def pdf_qnum_xy(q)
-      [
-        cell_x(q, 0).mm - pdf_qnum_width - @params[:items][:number_margin].to_f.mm,
-        (reg_frame_height - cell_y(q)).mm - cell_height
-      ]
-    end
-    
-    def pdf_qnum_size
-      @params[:items][:number_size].to_f
-    end
-    
-    def pdf_chlett_size
-      @params[:items][:letter_size].to_f
-    end
-
-    def pdf_qnum_width
-      @params[:items][:number_width].to_f.mm
-    end
-    
-    def pdf_header_xy(k)
-      [
-        @params[:header][k][:left].to_f.mm,
-        (reg_frame_height - @params[:header][k][:top].to_f).mm
-      ]
-    end
-    
-    def pdf_header_padding(k)
-      [
-        1.mm,
-        pdf_header_height(k) - 1.mm
-      ]
-    end
-    
-    def pdf_header_width(k)
-      @params[:header][k][:width].to_f.mm
-    end
-
-    def pdf_header_height(k)
-      @params[:header][k][:height].to_f.mm
-    end
-
-    def pdf_header_size(k)
-      @params[:header][k][:size].to_f
-    end
-    
-    def pdf_header_boxed?(k)
-      @params[:header][k][:box] == true
-    end
-    
-    def pdf_ctrl_area_dark
-      {
-        p: [pdf_control_xy[0]+pdf_control_width+ctrl_margin.mm, pdf_control_xy[1]],
-        w: cell_width.mm,
-        h: cell_height.mm
-      }
-    end
-    
-    def pdf_ctrl_area_light
-      {
-        p: [
-          cell_spacing.mm +
-          pdf_control_xy[0] +
-          pdf_control_width +
-          ctrl_margin.mm,
-          pdf_control_xy[1]
-        ],
-        w: cell_width.mm,
-        h: cell_height.mm
-      }
+    def barcode_bits
+      @params[:barcode][:bits].to_i
     end
     
-    def pdf_dark_control_letter_xy
-      xy = pdf_ctrl_area_dark[:p]
-      [
-        xy[0] + 2.mm,
-        xy[1] - 4.mm
-      ]
-    end
-
-    def pdf_light_control_letter_xy
-      xy = pdf_ctrl_area_light[:p]
-      [
-        xy[0] + 2.mm,
-        xy[1] - 4.mm
-      ]
-    end
-    
-    def pdf_control_width
-      @params[:control][:width].to_f.mm
-    end
-    
-    def pdf_control_xy
-      [
-        @params[:control][:left].to_f.mm,
-        (reg_frame_height - ctrl_cell_y).mm
-      ]
-    end
+    #====================#
+    private
+    #====================#
     
-    def pdf_control_size
-      @params[:control][:size]
+    # 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
-
-  private
   
-    def cx
-      @px / reg_frame_width
-    end
-    
-    def cy
-      @py / reg_frame_height
-    end
-    
-    def ppu_x
-      # horizontal pixels per unit of length (mm by def)
-      @px / page_width
-    end
-    
-    def ppu_y
-      # vertical pixels per unit of length (mm by def)
-      @py / page_height
-    end
-    
-    # {} = cell_area(x, y)
-    #
-    # the 4 values needed to locate a single cell area
-    def cell_area(x,y)
-      {
-        x: (cx * x           ).round,
-        y: (cy * y           ).round,
-        w: (cx * cell_width  ).round,
-        h: (cy * cell_height ).round
-      }
-    end
-
     # cell_y(q)
     # 
     # the distance from the registration frame to the top edge
@@ -317,63 +71,29 @@ module Mork
       first_x + column_width * (q / rows) + cell_spacing * c - cell_width / 2
     end
     
-    # ==============
-    # = sheet code =
-    # ==============
-    def code_cell_area(i)
-      {
-        x: (cx * code_cell_x(i)).round,
-        y: (cy * code_y        ).round,
-        w: (cx * code_width    ).round,
-        h: (cy * code_height   ).round
-      }
-    end
-  
-    def code_cell_x(i)
-      @params[:code][:left] + @params[:code][:spacing] * i
-    end
-
-    def code_y
-      reg_frame_height - code_height
+    def cal_cell_x
+      reg_frame_width - cell_spacing
     end
     
-    # ======================
-    # = registration sides =
-    # ======================
-
-    def rmx(corner, i)
-      case corner
-      when :tl; reg_off
-      when :tr; page_width - reg_search - reg_off - reg_step * i
-      when :br; page_width - reg_search - reg_off - reg_step * i
-      when :bl; reg_off
-      end
-    end
+    # ===========
+    # = barcode =
+    # ===========
     
-    def rmy(corner, i)
-      case corner
-      when :tl; reg_off
-      when :tr; reg_off
-      when :br; page_height - reg_search - reg_off - reg_step * i
-      when :bl; page_height - reg_search - reg_off - reg_step * i
-      end
+    # def barcode_bit_area(i)
+    #   raise "Invalid barcode bit" if i >= barcode_bits
+    #   cal_cell_x i+1
+    # end
+
+    def barcode_bit_x(i)
+      @params[:barcode][:left] + @params[:barcode][:spacing] * i
     end
     
-    def reg_step
-      reg_radius
-    end
-
     # ===============================
     # = Simple parameter extraction =
     # ===============================
-    def ctrl_cell_x()       @params[:control][:left].to_f + ctrl_width + ctrl_margin  end
-    def ctrl_margin()       @params[:control][:margin].to_f      end
-    def ctrl_width()        @params[:control][:width].to_f       end
-    def ctrl_cell_y()       @params[:control][:top].to_f         end
-    def code_height()       @params[:code][:height].to_f         end
-    def code_width()        @params[:code][:width].to_f          end
-    def page_width()        @params[:page_size][:width].to_f     end
-    def page_height()       @params[:page_size][:height].to_f    end
+    def barcode_y()         reg_frame_height - barcode_height    end
+    def barcode_height()    @params[:barcode][:height].to_f      end
+    def barcode_width()     @params[:barcode][:width].to_f       end
     def cell_width()        @params[:items][:cell_width].to_f    end
     def cell_height()       @params[:items][:cell_height].to_f   end
     def cell_spacing()      @params[:items][:x_spacing].to_f     end
@@ -384,11 +104,13 @@ module Mork
     def first_y()           @params[:items][:first_y].to_f       end
     def rows()              @params[:items][:rows]               end
     def columns()           @params[:items][:columns]            end
-    def reg_margin()        @params[:regmarks][:margin].to_f     end
     def reg_search()        @params[:regmarks][:search].to_f     end
-    def reg_radius()        @params[:regmarks][:radius].to_f     end
+    def reg_off()           @params[:regmarks][:offset].to_f     end
     def reg_frame_width()   page_width  - reg_margin * 2         end
     def reg_frame_height()  page_height - reg_margin * 2         end
-    def reg_off()           @params[:regmarks][:offset].to_f     end
+    def page_width()        @params[:page_size][:width].to_f     end
+    def page_height()       @params[:page_size][:height].to_f    end
+    def reg_margin()        @params[:regmarks][:margin].to_f     end
+    def reg_radius()        @params[:regmarks][:radius].to_f     end
   end
-end
+end