mork 0.0.12 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f6930d8ee718dadb56c51c8f4ab776a489b017ac
-  data.tar.gz: 8cbaef664dc24c91748e4f4cfb61724a7c38e2ef
+  metadata.gz: cb22bdfc594a05367dee16e6d9f214523d7c111c
+  data.tar.gz: 2bcafa2a1c6f0af97cb8da71bb586c10c607d817
 SHA512:
-  metadata.gz: 3ae5c320ba47ce34331bcf0d5bbff6e8dc7a2fdc359de092843f54bff6bbf545430ccf8f294ac4e79ec9c13217980f8319079a5ba11d7b8670ddae49f62e9109
-  data.tar.gz: 76c6f22dced2dc12e41534d51066a1c9e8c07b1cd3c0fbb5fcc7f63d12b04dcb7d034bb01549732e643879531615e0bdfb3d7853002d9245a3e8d892f2505be1
+  metadata.gz: 39db655371def69bc1d6c3db65bb1f6fece0c14fd347fda7621714415775859823eaafff2d87e5da8513d4a994017b548b8fc625313f8b01ad3fb7ceee87777c
+  data.tar.gz: d727fdde4bacbd0b5ed86f59afe3382441a76f3eec11dc1bcae5b11d8a866f04f807c1458c6c1edbac96029fa84406117ae0f4e6a6ad259e55c4c60cca586b71

data/.gitignore

@@ -7,4 +7,5 @@ tmp/*
 .rspec
 .yardoc
 .ruby-version
-.ruby-gemset
+.ruby-gemset
+.rspec

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Giuseppe
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -1,31 +1,29 @@
-Mork
-====
+# Mork
 
 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/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.
+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.
+
+## Assumptions and limitations
 
-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 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 PDF files generated by Mork are intended to be printed on regular printer paper
+- the entire response sheet must fit into a single page
+- after collecting the responses, a filled-out form should be acquired as a JPEG, PNG, or PDF image by a normal optical scanner or camera (i.e., no specialized equipment is necessary)
 - 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, assuming that responses will be given using a black or blue pen, choice cells are printed in red
+  - each item contains an arbitrary number of choice “cells”, each marked with a capital letter (A, B, C, ...)
   - 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
+- it is entirely up to the user to provide parameters that produce the desired response sheet layout; in particular, making sure that the header elements and choice cells fit in the available space, as Mork does not provide any type of "sanity" check at this time.
 
-Creating response sheets
-------------------------
+## Getting started
 
-To create a small ruby project for testing purposes, cd into a directory of choice, then execute the following shell commands:
+To create a small ruby project that uses Mork, `cd` into a directory of choice, then execute the following shell commands:
 
 ```
 mkdir mork_test
@@ -37,11 +35,22 @@ echo "include Mork" >> mork_test.rb
 bundle install
 ```
 
-Creating response sheets is done through the `Mork::SheetPDF` class. 
+Edit the file `mork_test.rb` with the code snippets below, then execute the following shell command to see the result:
+
+    bundle exec ruby mork_test.rb
+
+## 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 object:
+
+- **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
+
+Let’s look at each argument in turn.
 
-[...work in progress...]
+### content
 
-For example, add the following code to `mork_test.rb`:
+The `content` argument should be a hash like the following:
 
 ```ruby
 content = {
@@ -59,97 +68,109 @@ content = {
     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
+These are the key-value pairs that the `content` hash should contain:
 
-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 (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`: 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)
+### layout
 
-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.)
+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).
 
-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.
+```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:           2.5   # registration mark radius
+  search:          12     # initial size of the registration mark search area (*)
+  offset:           2     # distance between the search area and each page border (*)
+header:           
+  name:                   # ‘name’ is just a label; you can add arbitrary header elements
+    top:            5     # margin relative to registration frame top side
+    left:           7.5   # margin relative to registration frame left side
+    width:         170    # text will be fitted to this width
+    size:           14    # font size
+  title:
+    top:            15
+    left:           7.5
+    width:         180
+    size:           12
+  code:
+    top:             5
+    left:          165
+    width:          20
+    size:           14
+  signature:
+    top:            30
+    left:            7.5
+    width:         120
+    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
+```
 
-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:
+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:
 
 ```ruby
-g = Grid.new
-g.show
+s = SheetPDF.new content, 'layout.yml'
+s.write 'sheet.pdf'
+system 'open sheet.pdf' # this works in OSX
 ```
 
-The YAML-formatted output you see is the full list of parameters that describe the default Grid.
+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.)
 
-```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...
-```
+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).
 
-Thus, if you replace the call to SheetPDF with the following:
+## Scoring response sheets with `SheetOMR`
 
-```ruby
-s = SheetPDF.new content, Grid.new
-```
+Assuming that a person has filled out a response sheet by darkening with a pen the selected choices, and that sheet has been acquired as an image file, response scoring is performed by the `Mork::SheetOMR` class. Again, two pieces of information must be provided to the class constructor:
 
-...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:
+- **image**: the path/filename of the bitmap image (currently accepts JPG, JPEG, PNG, PDF extensions; a resolution of 150-200 dpi is usually more than sufficient to obtain accurate readings)
+- **layout**: same as for the SheetPDF class
 
-```ruby
-s = SheetPDF.new content, Grid.new('grid01.yml')
-s.save 'sheet.pdf'
-```
-
-Although this will work as well:
+The following code shows how to create and analyze a SheetOMR based on a bitmap file named `image.jpg`:
 
 ```ruby
-s = SheetPDF.new content, 'grid01.yml'
-s.save 'sheet.pdf'
+# instantiating the object
+s = SheetOMR.new 'image.jpg', 'layout.yml'
+# detecting darkened choice cells for the 100 items
+chosen = s.mark_array 100
 ```
 
-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:
+If all goes well, the `chosen` array will contain 100 sub-arrays, each containing the list of darkened 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:
 
 ```ruby
-s = SheetOMR.new 'sample01.jpg', 'grid01.yml'
+s = SheetOMR.new 'image.jpg', 'layout.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) 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:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+#### Wait, why Mork?
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Because I used to have a crush on Mindy

data/lib/mork/grid.rb

@@ -11,8 +11,8 @@ module Mork
       @params = DGRID
       case options
       when NilClass
-        if File.exists?('config/grid.yml')
-          @params.merge! symbolize YAML.load_file('config/grid.yml')
+        if File.exists?('layout.yml')
+          @params.merge! symbolize YAML.load_file('layout.yml')
         end
       when Hash
         @params.merge! symbolize options
@@ -25,7 +25,7 @@ module Mork
     
     # 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
+    # :page_size, :reg_marks, :header, :items, :barcode, :control
     def show(subset=nil)
       out = subset ? @params[subset] : @params
       puts out.to_yaml
@@ -78,12 +78,6 @@ module Mork
     # ===========
     # = barcode =
     # ===========
-    
-    # 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
@@ -91,26 +85,25 @@ module Mork
     # ===============================
     # = Simple parameter extraction =
     # ===============================
-    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
-    def item_spacing()      @params[:items][:y_spacing].to_f     end
-    def column_width()      @params[:items][:column_width].to_f  end
-    def row_spacing()       @params[:items][:y_spacing].to_f     end
-    def first_x()           @params[:items][:first_x].to_f       end
-    def first_y()           @params[:items][:first_y].to_f       end
-    def rows()              @params[:items][:rows]               end
-    def columns()           @params[:items][:columns]            end
-    def reg_search()        @params[:regmarks][:search].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 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
+    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
+    def item_spacing()      @params[:items][:y_spacing].to_f    end
+    def column_width()      @params[:items][:column_width].to_f end
+    def first_x()           @params[:items][:left].to_f         end
+    def first_y()           @params[:items][:top].to_f          end
+    def rows()              @params[:items][:rows]              end
+    def columns()           @params[:items][:columns]           end
+    def reg_search()        @params[:reg_marks][:search].to_f    end
+    def reg_off()           @params[:reg_marks][: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 page_width()        @params[:page_size][:width].to_f    end
+    def page_height()       @params[:page_size][:height].to_f   end
+    def reg_margin()        @params[:reg_marks][:margin].to_f    end
+    def reg_radius()        @params[:reg_marks][:radius].to_f    end
   end
 end

data/lib/mork/grid_const.rb

@@ -7,12 +7,12 @@ module Mork
       width:      210,
       height:     297
     }, # page end
-    regmarks: {
+    reg_marks: {
       margin:      10,
       radius:       2.5,
       search:      10,
       offset:       2
-    }, # regmarks end
+    }, # reg_marks end
     header: {
       name: {
         top:        5,
@@ -47,8 +47,8 @@ module Mork
       rows:         30,
       # from the top-left registration mark
       # to the center of the first choice cell
-      first_x:      10.5,
-      first_y:      55.5,
+      left:      10.5,
+      top:      55.5,
       # between choices
       x_spacing:     7,
       # between rows

data/lib/mork/mimage.rb

@@ -65,6 +65,16 @@ module Mork
       end
     end
     
+    def cross_cells!(cells)
+      cells = [cells] if cells.is_a? Hash
+      cells.each do |c|
+        out = Magick::Draw.new
+        out.stroke 'yellow'
+        out.stroke_width 3
+        out.line
+      end
+    end
+    
     def join!(p)
       poly = Magick::Draw.new
       poly.fill_opacity 0

data/lib/mork/sheet_omr.rb

@@ -98,9 +98,6 @@ module Mork
       @crop.highlight_cells! @grom.calibration_cell_areas
       @crop.highlight_rect! [@grom.ink_black_area, @grom.paper_white_area]
       @crop.highlight_rect! @grom.barcode_bit_areas
-      # @grom.barcode_bits.times do |bit|
-      #   @crop.highlight_rect! @grom.barcode_bit_area bit
-      # end
     end
     
     def highlight_marked

data/lib/mork/version.rb

@@ -1,3 +1,3 @@
 module Mork
-  VERSION = "0.0.12"
+  VERSION = "0.1.0"
 end

data/mork.gemspec

@@ -8,13 +8,12 @@ Gem::Specification.new do |s|
   s.licenses    = ['MIT']
   s.authors     = ["Giuseppe Bertini"]
   s.email       = ["giuseppe.bertini@gmail.com"]
-  s.homepage    = ""
-  s.summary     = %q{Optical mark recognition of multiple-choice response sheets}
-  s.description = %q{sorry, no docs until v.0.1.0}
-  s.rubyforge_project = "mork"
+  s.homepage    = 'https://github.com/giuseb/mork'
+  s.summary     = %q{Optical mark recognition of multiple-choice tests and surveys}
+  s.description = %q{Producing response sheets as PDF files and automatically scoring manually filled-out sheets}
 
   s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.test_files    = `git ls-files -- {spec}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]