mork 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cedc2c2924bff45051c7d4fdace910882b95ade7
-  data.tar.gz: 4a97e442ee44a1e615e9d92dd1be2dfa8af01545
+  metadata.gz: 59b94f585fff925a78dc0fc848c267503cfdc8c0
+  data.tar.gz: 0a71421a1f6a1fd9790047ea4b913397572799ea
 SHA512:
-  metadata.gz: 77283aab2e31e1189a7579f49b6a535b374381254df3b75a4ded1eb2ea871ba11987b441237afef320e59a5fd605a8b9a1863b80c27547221064696f52a75642
-  data.tar.gz: b2ea3c69c2fd974d4d047af7ad2aec052dcd34046ca06a5ad20666dd31df1485dd906b52164929ae8c826c857783f7ac25f0aa84da5ea6f2f1266e6548f7226e
+  metadata.gz: 2d8863ac600a282190b719b433db6ac761422f4ad8485fe979230b6e1ee609685e1a611f996ef2fe33785e2185dfde23ac9f8253c5c4351d0f937a262ef487df
+  data.tar.gz: ec876a3c40eb586f462d9b7127537b5562a0402a7ad6f96063ca5434dd5ad5d6151e96de92913b6ee8845fb677c0133766c63986f5c475dd271705b641d0013f

data/README.md

@@ -152,18 +152,19 @@ If the `layout` argument is omitted, Mork will search for a file named `layout.y
 
 ## Scoring response sheets with `SheetOMR`
 
-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:
+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. Three pieces of information must be provided to the class constructor:
 
 - **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
+- **choices**: equivalent to the `choices` array of integers passed to the `SheetPDF` constructor as part of the `content` parameter (see above)
+- **layout**: 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`:
 
 ```ruby
 # instantiating the object
-s = SheetOMR.new 'image.jpg', 'layout.yml'
+s = SheetOMR.new 'image.jpg', [5]*100, 'layout.yml'
 # detecting darkened choice cells for the 100 items
-chosen = s.mark_array 100
+chosen = s.mark_array
 ```
 
 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:

data/lib/mork/mimage.rb

@@ -2,12 +2,14 @@ require 'mini_magick'
 require 'mork/npatch'
 
 module Mork
-  # The class Mimage is a wrapper for the core image library, currently mini_magick
+  # The class Mimage manages the image. It is also a wrapper for the core image library
+  # currently mini_magick. TODO: consider moving out the interaction with mini_magick.
+  # Note that Mimage is NOT intended as public API, it should only be called by SheetOMR
   class Mimage
-    def initialize(path, grom, page=0)
-      raise "File '#{path}' not found" unless File.exists? path
-      @path = path
-      @grom = grom
+    def initialize(path, nitems, grom)
+      @path   = path
+      @grom   = grom
+      @nitems = nitems
       @grom.set_page_size width, height
       @rm   = {} # registration mark centers
       @rmsa = {} # registration mark search area
@@ -30,24 +32,12 @@ module Mork
       }
     end
     
-    def ink_black
-      reg_pixels.average @grom.ink_black_area
-    end
-    
-    def paper_white
-      reg_pixels.average @grom.paper_white_area
-    end
-    
-    def cal_cell_mean
-      @grom.calibration_cell_areas.collect { |c| reg_pixels.average c }.mean
+    def marked?(q,c)
+      shade_of(q,c) < choice_threshold
     end
     
-    def shade_of_barcode_bit(i)
-      reg_pixels.average @grom.barcode_bit_area i+1
-    end
-    
-    def shade_of(q,c)
-      reg_pixels.average @grom.choice_cell_area(q, c)
+    def barcode_bit?(i)
+      reg_pixels.average(@grom.barcode_bit_area i+1) < barcode_threshold
     end
     
     def width
@@ -65,7 +55,7 @@ module Mork
     def outline(cells, roundedness=nil)
       return if cells.empty?
       @cmd << [:stroke, 'green']
-      @cmd << [:strokewidth, '4']
+      @cmd << [:strokewidth, '2']
       @cmd << [:fill, 'none']
       coordinates_of(cells).each do |c|
         roundedness ||= [c[:h], c[:w]].min / 2
@@ -163,6 +153,44 @@ module Mork
       @cmd.each { |cmd| c.send *cmd }
     end
     
+    def shade_of(q,c)
+      choice_cell_averages[q][c]
+    end
+    
+    def choice_cell_averages
+      @choice_cell_averages ||= begin
+        @nitems.each_with_index.collect do |cho, q|
+          cho.times.collect do |c|
+            reg_pixels.average @grom.choice_cell_area(q, c)
+          end
+        end
+      end
+    end
+    
+    def choice_threshold
+      @choice_threshold ||= (cal_cell_mean - darkest_cell_mean) * 0.75 + darkest_cell_mean
+    end
+    
+    def barcode_threshold
+      @barcode_threshold ||= (paper_white + ink_black) / 2
+    end    
+
+    def cal_cell_mean
+      @grom.calibration_cell_areas.collect { |c| reg_pixels.average c }.mean
+    end
+
+    def darkest_cell_mean
+      @choice_cell_averages.flatten.min
+    end
+
+    def ink_black
+      reg_pixels.average @grom.ink_black_area
+    end
+    
+    def paper_white
+      reg_pixels.average @grom.paper_white_area
+    end
+    
     def img_size
       @img_size ||= IO.read("|identify -format '%w,%h' #{@path}").split ','
     end

data/lib/mork/npatch.rb

@@ -22,6 +22,10 @@ module Mork
       crop(c).mean
     end
     
+    def stddev(c=nil)
+      crop(c).stddev
+    end
+    
     def length
       @patch.length
     end

data/lib/mork/sheet_omr.rb

@@ -4,9 +4,19 @@ require 'mork/mimage_list'
 
 module Mork
   class SheetOMR
-    def initialize(path, grom=nil)
-      @grom = GridOMR.new grom
-      @mim = Mimage.new path, @grom
+    
+    def initialize(path, nitems=nil, grom=nil)
+      raise "File '#{path}' not found" unless File.exists? path
+      @grom   = GridOMR.new grom
+      @nitems = case nitems
+                when nil
+                  [@grom.max_choices_per_question] * @grom.max_questions
+                when Fixnum
+                  [@grom.max_choices_per_question] * nitems 
+                when Array
+                  nitems
+                end
+      @mim    = Mimage.new path, @nitems, @grom
     end
     
     def valid?
@@ -31,7 +41,7 @@ module Mork
     # bits long, with most significant bits to the left
     def barcode_string
       return if not_registered
-      cs = @grom.barcode_bits.times.inject("") { |c, v| c << barcode_bit_value(v) }
+      cs = @grom.barcode_bits.times.inject("") { |c, v| c << barcode_bit_string(v) }
       cs.reverse
     end
     
@@ -41,17 +51,18 @@ module Mork
     # false otherwise
     def marked?(q, c)
       return if not_registered
-      @mim.shade_of(q, c) < choice_threshold
+      @mim.marked? q, c
     end
     
     # TODO: define method ‘mark’ to retrieve the choice array for a single item
     
+    
     # mark_array(range)
     # 
     # returns an array of arrays of marked choices.
     # takes either a range of questions, an array of questions, or a fixnum,
     # in which case the choices for the first n questions will be returned.
-    # if called without arguments, all available choices will be evaluated
+    # if called without arguments, all available choices will be evaluated.
     def mark_array(r = nil)
       return if not_registered
       question_range(r).collect do |q|
@@ -63,6 +74,24 @@ module Mork
       end
     end
     
+    # mark_char_array(range)
+    # 
+    # returns an array of arrays of the characters corresponding to marked choices.
+    # WARNING: at this time, only the latin sequence 'A, B, C...' is supported.
+    # takes either a range of questions, an array of questions, or a fixnum,
+    # in which case the choices for the first n questions will be returned.
+    # if called without arguments, all available choices will be evaluated.
+    def mark_char_array(r = nil)
+      return if not_registered
+      question_range(r).collect do |q|
+        cho = []
+        (0...@grom.max_choices_per_question).each do |c|
+          cho << (65+c).chr if marked?(q, c)
+        end
+        cho
+      end
+    end
+    
     def mark_logical_array(r = nil)
       return if not_registered
       question_range(r).collect do |q|
@@ -134,10 +163,15 @@ module Mork
     # ============================================================#
     private                                                       #
     # ============================================================#
-
+    
+    def barcode_bit_string(i)
+      @mim.barcode_bit?(i) ? "1" : "0"
+    end
+    
     def question_range(r)
+      # TODO: help text: although not API, people need to know this! 
       if r.nil?
-        (0...@grom.max_questions)
+        (0...@nitems.length)
       elsif r.is_a? Fixnum
         (0...r)
       elsif r.is_a? Array
@@ -146,23 +180,7 @@ module Mork
         raise "Invalid argument"
       end
     end
-    
-    def barcode_bit_value(i)
-      @mim.shade_of_barcode_bit(i) < barcode_threshold ? "1" : "0"
-    end
-    
-    def barcode_threshold
-      @barcode_threshold ||= (@mim.paper_white + ink_black) / 2
-    end
-    
-    def choice_threshold
-      @choice_threshold ||= (@mim.cal_cell_mean - ink_black) * 0.9 + ink_black
-    end
-    
-    def ink_black
-      @ink_black ||= @mim.ink_black
-    end
-    
+        
     def not_registered
       unless valid?
         puts "---=={ Unregistered image. Reason: '#{@mim.status.inspect}' }==---"

data/lib/mork/version.rb

@@ -1,3 +1,3 @@
 module Mork
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/spec/mork/mimage_spec.rb

@@ -2,45 +2,74 @@ require 'spec_helper'
 
 module Mork
   describe Mimage do
-    let(:sgi) { sample_img 'sample-gray' }
-    let(:sg)  { Mimage.new sgi.filename, GridOMR.new(sgi.grid_file) }
-    
-    describe 'basics' do
-      it 'returns the width' do
-        expect(sg.width).to eq sgi.width
-      end
+    let(:qna) { [5] * 100 }
+    context 'problematic sheets' do
+      let(:mim)  { Mimage.new 'spec/samples/out-1.jpg', qna, GridOMR.new('spec/samples/grid.yml')  }
+      let(:bila) { Mimage.new 'spec/samples/syst/bila0.jpg', qna, GridOMR.new('spec/samples/grid.yml') }
       
-      it 'returns the height' do
-        expect(sg.height).to eq sgi.height
+      xit 'writes all cell values to a text file' do
+        d=Dir['spec/samples/syst/*.jpg']
+        d.each do |f|
+          fn = File.basename f, '.jpg'
+          m = Mimage.new "spec/samples/syst/#{fn}.jpg", qna, GridOMR.new('spec/samples/grid.yml')
+          puts fn
+          File.open("spec/samples/syst/#{fn}.txt",'w') do |f|
+            f.puts "ink:#{m.send :ink_black}"
+            f.puts "drk:#{m.send :darkest_cell_mean}"
+            f.puts "pap:#{m.send :paper_white}"
+            f.puts "cal:#{m.send :cal_cell_mean}"
+            f.puts "cho:#{m.send :choice_threshold}"
+            100.times do |q|
+              5.times do |c|
+                f.puts m.send('choice_cell_averages')[q, c]
+              end
+            end
+          end
+        end
       end
+    end
+    
+    context 'Old specs' do
+      let(:sgi) { sample_img 'sample-gray' }
+      let(:sg)  { Mimage.new sgi.filename, qna, GridOMR.new(sgi.grid_file) }
+    
+      describe 'basics' do
+        it 'returns the width' do
+          expect(sg.width).to eq sgi.width
+        end
       
-      it 'returns the pixels as an array' do
-        expect(sg.send :raw_pixels).to be_a NPatch
-      end
+        it 'returns the height' do
+          expect(sg.height).to eq sgi.height
+        end
       
-      it 'returns the correct number of pixels' do
-        expect(sg.send(:raw_pixels).length).to eq sgi.width * sgi.height
-      end
+        it 'returns the pixels as an array' do
+          expect(sg.send :raw_pixels).to be_a NPatch
+        end
+      
+        it 'returns the correct number of pixels' do
+          expect(sg.send(:raw_pixels).length).to eq sgi.width * sgi.height
+        end
 
-      it 'returns the stretched array' do
-        expect(sg.send(:reg_pixels).length).to eq sgi.width * sgi.height
-      end
+        it 'returns the stretched array' do
+          expect(sg.send(:reg_pixels).length).to eq sgi.width * sgi.height
+        end
       
-      it 'raises an error if the file is not found' do
-        expect { Mimage.new 'non_existing_file' }.to raise_error
+        it 'raises an error if the file is not found' do
+          expect { Mimage.new 'non_existing_file' }.to raise_error
+        end
       end
-    end
 
-    describe 'inspecting' do
-      it 'writes out average whiteness of choice cells' do
-        qz = sample_img 'silvia'
-        s = Mimage.new qz.filename, GridOMR.new(qz.grid_file)
-        File.open('spec/out/choices.txt', 'w') do |f|
-          120.times do |q|
-            t = (0..4).collect do |c|
-              s.send(:shade_of, q, c).round
+      describe 'inspecting' do
+        xit 'writes out average whiteness of choice cells' do
+          qz = sample_img 'silvia'
+          s = Mimage.new qz.filename, [5] * 5, GridOMR.new(qz.grid_file)
+          File.open('spec/out/choices.txt', 'w') do |f|
+            5.times do |q|
+              t = (0..4).collect do |c|
+                s.send(:shade_of, q, c).round
+              end
+              f.puts "#{q+1}: #{t.join(' ')}"
             end
-            f.puts "#{q+1}: #{t.join(' ')}"
           end
         end
       end

data/spec/mork/sheet_omr_spec.rb

@@ -32,7 +32,7 @@ module Mork
       # since these specs change the @crop, they must be run in isolation
       # with the SheetOMR rebuilt each time, even though it is time consuming!
       let(:shinfo) { sample_img 'sample-gray' }
-      let(:sheet)  { SheetOMR.new shinfo.filename, shinfo.grid_file }
+      let(:sheet)  { SheetOMR.new shinfo.filename, [5]*100, shinfo.grid_file }
       
       it 'highlights the registration areas and frame' do
         sheet.highlight_registration
@@ -66,7 +66,7 @@ module Mork
 
       it 'outlines some responses in-place (rewriting the source image)' do
         FileUtils.cp shinfo.filename, 'spec/out/inplace.jpg'
-        tsheet = SheetOMR.new 'spec/out/inplace.jpg', shinfo.grid_file
+        tsheet = SheetOMR.new 'spec/out/inplace.jpg', [5]*100, shinfo.grid_file
         tsheet.outline [[1],[1],[2],[2],[3,4],[],[0,1,2,3,4], [],[1],[2],[2],[3,4],[],[0,1,2,3,4]]
         tsheet.write
       end
@@ -76,26 +76,26 @@ module Mork
         sheet.outline [[1],[1],[2],[2],[3,4],[],[0,1,2,3,4], [],[1],[2],[2],[3,4],[],[0,1,2,3,4]]
         sheet.write 'spec/out/marks_and_outs.jpg'
       end
-      
+
       it 'highlights marked cells of a problematic one' do
         si = sample_img 'silvia'
-        s = SheetOMR.new si.filename, si.grid_file
+        s = SheetOMR.new si.filename, [5]*100, si.grid_file
         s.highlight_marked
         s.write 'spec/out/problem.jpg'
       end
       
       it 'highlights the barcode' do
         si = sample_img 'sample-gray'
-        s = SheetOMR.new si.filename, si.grid_file
+        s = SheetOMR.new si.filename, [5]*100, si.grid_file
         s.highlight_barcode
         s.write 'spec/out/code_bits.jpg'
       end
     end
-
+    
     context 'marking a nicely printed and scanned sheet' do
       before(:all) do
         @shinfo = sample_img 'sample-gray'
-        @sheet = SheetOMR.new @shinfo.filename, @shinfo.grid_file
+        @sheet = SheetOMR.new @shinfo.filename, [5]*120, @shinfo.grid_file
       end
       
       describe '#valid?' do
@@ -118,8 +118,7 @@ module Mork
         end
 
         it 'writes out markedness' do
-          puts "Choice threshold: #{@sheet.send :choice_threshold}"
-          mf = File.open('spec/out/marked.txt',   'w')
+          mf = File.open('spec/out/marked.txt', 'w')
           120.times do |q|
             x = 5.times.collect do |c|
               @sheet.marked?(q,c) ? '1' : '0'
@@ -164,19 +163,90 @@ module Mork
         
         it 'should read another bit string' do
           barcode_string = '0000000000000000000000000010000110100000'
-          s2 = SheetOMR.new('spec/samples/sample02.jpg')
+          s2 = SheetOMR.new('spec/samples/sample02.jpg', [5]*100)
           s2.barcode_string.should == barcode_string
           s2.barcode.should == 8608
         end
 
         it 'should read the 666 bit string' do
           sh = sample_img 'code666'
-          s2 = SheetOMR.new sh.filename, sh.grid_file
+          s2 = SheetOMR.new sh.filename, [5]*100, sh.grid_file
           s2.barcode.should == sh.barcode_int
         end
       end
       
     end
+    
+    context 'marking a problematic sheet' do
+      let(:sheet) { SheetOMR.new 'spec/samples/out-1.jpg', [5]*100, 'spec/samples/grid.yml' }
+      
+      it 'highlights marked cells and outline correct responses' do
+        sheet.cross_marked
+        sheet.outline [[0,1,2,3,4]] * 100
+        sheet.write 'spec/out/marks_and_outs.jpg'
+      end
+      
+      it 'highlights the barcode' do
+        sheet.highlight_barcode
+        sheet.write 'spec/out/barcode.jpg'
+      end
+    end
+
+    context 'systematic tests' do
+      let(:bila)  { 'CCEBEBCEEACCDCABDBEBCADEADDCCCACCACDBBDAECDDABDEEBCEEDCBAAADEEEEDCADEABCBDECCCCDDDCABBECAADADBBEEABA'.split '' }
+      let(:bila0) { SheetOMR.new 'spec/samples/syst/bila0.jpg', [5]*100,  'spec/samples/grid.yml'}
+      let(:bila1) { SheetOMR.new 'spec/samples/syst/bila1.jpg', [5]*100,  'spec/samples/grid.yml'}
+      let(:bila2) { SheetOMR.new 'spec/samples/syst/bila2.jpg', [5]*100,  'spec/samples/grid.yml'}
+      let(:bila3) { SheetOMR.new 'spec/samples/syst/bila3.jpg', [5]*100,  'spec/samples/grid.yml'}
+      let(:dald)  { 'DDDBECAAADBAEEEAEEEBAACAEDBDECDBDCDCDDEDCCDCDBDCADEEDBCCBEBBAADDCDBBECBBBDEABADABADADBABAEABACBDADDA'.split '' }
+      let(:dald0) { SheetOMR.new 'spec/samples/syst/dald0.jpg', [5]*100,  'spec/samples/grid.yml'}
+      let(:dald1) { SheetOMR.new 'spec/samples/syst/dald1.jpg', [5]*100,  'spec/samples/grid.yml'}
+      let(:dald2) { SheetOMR.new 'spec/samples/syst/dald2.jpg', [5]*100,  'spec/samples/grid.yml'}
+      let(:dald3) { SheetOMR.new 'spec/samples/syst/dald3.jpg', [5]*100,  'spec/samples/grid.yml'}
+      let(:cost)  { 'ABBDDBAEAEBAADEAAECBCDBBDABABADEECCACBCAEDDAEBEABBCDABECAACEEEBADECBBEAADBBBEABDAEBDEEABBABEBEDDAEEC'.split '' }
+      let(:cost0) { SheetOMR.new 'spec/samples/syst/cost0.jpg', [5]*100,  'spec/samples/grid.yml'}
+      let(:cost1) { SheetOMR.new 'spec/samples/syst/cost1.jpg', [5]*100,  'spec/samples/grid.yml'}
+      let(:cost2) { SheetOMR.new 'spec/samples/syst/cost2.jpg', [5]*100,  'spec/samples/grid.yml'}
+      let(:cost3) { SheetOMR.new 'spec/samples/syst/cost3.jpg', [5]*100,  'spec/samples/grid.yml'}
+      let(:bone)  { 'CECBBABAECADEDCACBBDEECBADBECDCEDECABCAADCBDEDACAEEDCCADBEDCEBCCBBDCCACDEDDAAECEBDBADCBAAEBAEDABCBDC'.split '' }
+      let(:bone0) { SheetOMR.new 'spec/samples/syst/bone0.jpg', [5]*100,  'spec/samples/grid.yml'}
+      let(:bone1) { SheetOMR.new 'spec/samples/syst/bone1.jpg', [5]*100,  'spec/samples/grid.yml'}
+      let(:barr)  { 'ACECAAADDBCECCCDBEBECDEDAECEDDEEDCDEADDCCBCCCBBEACBCAEDEEDDDABBBBABEBDCEADEEDEBCBADBCEDCDBACEBCBDCDA'.split '' }
+      let(:barr0) { SheetOMR.new 'spec/samples/syst/barr0.jpg', [5]*100,  'spec/samples/grid.yml'}
+      let(:barr1) { SheetOMR.new 'spec/samples/syst/barr1.jpg', [5]*100,  'spec/samples/grid.yml'}
+            
+      it 'checks bila' do
+        expect(bila0.mark_char_array.flatten).to eq(bila)
+        expect(bila1.mark_char_array.flatten).to eq(bila)
+        expect(bila2.mark_char_array.flatten).to eq(bila)
+        expect(bila3.mark_char_array.flatten).to eq(bila)
+      end
+
+      it 'checks dald' do
+        expect(dald0.mark_char_array.flatten).to eq(dald)
+        expect(dald1.mark_char_array.flatten).to eq(dald)
+        expect(dald2.mark_char_array.flatten).to eq(dald)
+        expect(dald3.mark_char_array.flatten).to eq(dald)
+      end
+
+      it 'checks cost' do
+        expect(cost0.mark_char_array.flatten).to eq(cost)
+        expect(cost1.mark_char_array.flatten).to eq(cost)
+        expect(cost2.mark_char_array.flatten).to eq(cost)
+        expect(cost3.mark_char_array.flatten).to eq(cost)
+      end
+
+      it 'checks bone' do
+        expect(bone0.mark_char_array.flatten).to eq(bone)
+        expect(bone1.mark_char_array.flatten).to eq(bone)
+      end
+
+      it 'checks barr' do
+        expect(barr0.mark_char_array.flatten).to eq(barr)
+        expect(barr1.mark_char_array.flatten).to eq(barr)
+      end
+
+    end
 
     # context "multi-page pdf" do
     #   before(:all) do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mork
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Giuseppe Bertini
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-02 00:00:00.000000000 Z
+date: 2015-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: narray