mork 0.16.1 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 120d2749d8734418de4f7606f4dd29d1a626962ee64653ecbad1ede0ff61a0d4
-  data.tar.gz: d85f525368c11bf3fe2e67c481b7da94098f8668aab5af2d5689233c30d97c9d
+  metadata.gz: a0c88481311d1eeaf37c2df7f308dbde8e72968a23cdd8a649012d1591898412
+  data.tar.gz: 90ff649618ec8c71c75e2c1b6fa09a36d0bd9016a1bc529628ab5f4027b4bf97
 SHA512:
-  metadata.gz: 9f8846c5201c97c5da75e84efb1ef00f478fb6ec2e6dbbcf8fb5151894a81cc9f08996d40254ea64d1190f98b4927fe51ef81f0d6fad529fe5fa4ebfdf6a2d9d
-  data.tar.gz: 6145fc639a13bd1fcdc2c4224bdfc2462a01b40a23fc964db9ef74d60839e2375465224390ab8b85daae98765c2879a900f8e6ef96f1f62983d289bfa901d1e0
+  metadata.gz: 16bbe20136a27742f2247b7ac00856e3dd1bb68349149c65ba94ab5bb06656ecf92e2400a509953251af5074bfbc1bbbd7db63b74a299e9c785db751750e4d10
+  data.tar.gz: 30b783689b3bac8dc7785fcaeac7681eb3da5f1d9f6a679a7a08be267094b918e71fc103c3ab7d69d4ac90a4de77a164e39aa4717fa047d42fa46eddc6b3c8d4

data/README.md

@@ -296,6 +296,29 @@ s.save 'marked_choices_and_outlines.jpg'
 system 'open marked_choices_and_outlines.jpg' # this works in macOS
 ```
 
+For single-answer tests, Mork also provides a higher-level method that compares the detected responses against an answer key and applies the overlays automatically:
+
+```ruby
+correct = [3, 0, 2, 1, 2] # one zero-based correct choice per question
+s.overlay_corrections correct
+s.save 'corrections.jpg'
+system 'open corrections.jpg' # this works in macOS
+```
+
+`overlay_corrections` applies:
+
+- a green outline on the marked cell when the response is correct
+- a red outline on the expected cell and a red cross on the marked cell when the response is incorrect
+- a red outline on the expected cell when the response is blank or invalid
+
+By default, `overlay_corrections` uses the unique marked response for each question, so if a responder marks more than one choice, the response is treated as invalid and no red cross is applied. To cross all marked cells for incorrect or multi-marked responses:
+
+```ruby
+s.overlay_corrections correct, marked: :all
+```
+
+The answer key must contain one entry per configured question, and each entry must be either a zero-based choice index, a one-element array containing that index, or `nil` to skip overlaying a question.
+
 Scoring can only be performed if the sheet gets properly registered, which in turn depends on the quality of the scanned image.
 
 ### Improving sheet registration and marking

data/lib/mork/grid_omr.rb

@@ -5,6 +5,8 @@ require 'deep_merge/rails_compat'
 module Mork
   # @private
   class GridOMR < Grid
+    OVERLAY_STROKE_WIDTH_MM = 0.5
+
     def initialize(options=nil)
       super options
     end
@@ -15,6 +17,10 @@ module Mork
       self
     end
 
+    def overlay_stroke_width_px
+      [(pixels_per_unit * OVERLAY_STROKE_WIDTH_MM).round, 1].max
+    end
+
     def barcode_areas(bits)
       [].tap do |areas|
         bits.each_with_index do |b, i|
@@ -61,6 +67,7 @@ module Mork
 
     def cx()    @px / reg_frame_width  end
     def cy()    @py / reg_frame_height end
+    def pixels_per_unit() (ppu_x + ppu_y) / 2.0 end
     def ppu_x() @px / page_width       end
     def ppu_y() @py / page_height      end
 

data/lib/mork/magicko.rb

@@ -8,10 +8,12 @@ module Mork
   class Magicko
     attr_reader :width
     attr_reader :height
+    attr_reader :overlay_stroke_width
 
     def initialize(path)
       @path = path
       @cmd = []
+      @overlay_stroke_width = 3
       # a density is required for processing PDF or other vector-based images;
       # a default of 150 dpi seems sensible. It should not affect bitmaps.
       density = 150
@@ -39,6 +41,10 @@ module Mork
       end
     end
 
+    def overlay_stroke_width=(width)
+      @overlay_stroke_width = [width.to_i, 1].max
+    end
+
     def valid?
       @valid
     end
@@ -71,14 +77,36 @@ module Mork
     end
 
     def outline(coords, rounded)
-      @cmd << [:stroke, 'green']
-      @cmd << [:strokewidth, '3']
+      outline_with_color(coords, rounded, 'green')
+    end
+
+    def outline_green(coords, rounded)
+      outline_with_color(coords, rounded, 'green')
+    end
+
+    def outline_red(coords, rounded)
+      outline_with_color(coords, rounded, 'red')
+    end
+
+    def check(coords, rounded)
+      check_with_color(coords, 'red')
+    end
+
+    def check_red(coords, rounded)
+      check_with_color(coords, 'red')
+    end
+
+    def outline_with_color(coords, rounded, color)
+      return if coords.empty?
+      @cmd << [:stroke, color]
+      @cmd << [:strokewidth, overlay_stroke_width]
       @cmd << [:fill, 'none']
       coords.each { |c| @cmd << [:draw, shape(c, rounded)] }
     end
 
-    def check(coords, rounded)
-      @cmd << [:stroke, 'red']
+    def check_with_color(coords, color)
+      return if coords.empty?
+      @cmd << [:stroke, color]
       @cmd << [:strokewidth, '3']
       coords.each do |c|
         @cmd << [:draw, "line #{c.cross1}"]
@@ -115,7 +143,7 @@ module Mork
     def join(p)
       @cmd << [:fill, 'none']
       @cmd << [:stroke, 'green']
-      @cmd << [:strokewidth, 3]
+      @cmd << [:strokewidth, overlay_stroke_width]
       pts = [
         p[0][:x], p[0][:y],
         p[1][:x], p[1][:y],

data/lib/mork/mimage.rb

@@ -14,6 +14,7 @@ module Mork
       @mack  = Magicko.new path
 
       @grom  = grom.set_page_size @mack.width, @mack.height
+      @mack.overlay_stroke_width = @grom.overlay_stroke_width_px
       @choxq = [(0...@grom.max_choices_per_question).to_a] * grom.max_questions
       @rm    = {} # registration mark centers
       @valid = register
@@ -86,7 +87,10 @@ module Mork
                 fail ArgumentError, 'Invalid overlay argument “where”'
               end
       round = where != :barcode
-      @mack.send what, areas, round
+      unless @mack.respond_to?(what)
+        fail ArgumentError, 'Invalid overlay argument “what”'
+      end
+      @mack.public_send what, areas, round
     end
 
     # write the underlying MiniMagick::Image to disk;

data/lib/mork/sheet_omr.rb

@@ -163,6 +163,47 @@ module Mork
       @mim.overlay what, where
     end
 
+    # Applies correctness-aware overlays to the image using an answer key.
+    #
+    # Correct responses receive a green outline on the marked cell. Incorrect
+    # responses receive a red outline on the expected cell and a red cross on
+    # the given cell. Blank or invalid responses receive only the red outline
+    # on the expected cell.
+    #
+    # @param correct_choices [Array<Integer, Array<Integer>, nil>] one entry per
+    #   question. Each entry can be an integer choice index, a 1-element array
+    #   containing that index, or nil to skip that question.
+    # @param marked [Symbol] `:unique` treats multi-marked responses as invalid
+    #   and does not cross them out; `:all` crosses all marked cells for
+    #   incorrect responses.
+    def overlay_corrections(correct_choices, marked: :unique)
+      return if not_registered
+
+      expected = normalize_correct_choices(correct_choices)
+      actual = marked_responses(marked)
+
+      green_outlines = Array.new(expected.length) { [] }
+      red_outlines = Array.new(expected.length) { [] }
+      red_crosses = Array.new(expected.length) { [] }
+
+      expected.each_with_index do |choice, question|
+        next if choice.nil?
+
+        marked_cells = actual[question]
+        if marked_cells == [choice]
+          green_outlines[question] = [choice]
+          next
+        end
+
+        red_outlines[question] = [choice]
+        red_crosses[question] = marked_cells if marked_cells.any?
+      end
+
+      @mim.overlay :outline_green, green_outlines
+      @mim.overlay :outline_red, red_outlines
+      @mim.overlay :check_red, red_crosses
+    end
+
     # Saves a copy of the source image after registration;
     # the output image will also contain any previously applied overlays.
     #
@@ -187,6 +228,53 @@ module Mork
     private                                                       #
     # ============================================================#
 
+    def normalize_correct_choices(correct_choices)
+      unless correct_choices.is_a?(Array)
+        fail ArgumentError, 'Correct choices must be an array'
+      end
+
+      if correct_choices.length != @mim.choxq.length
+        fail ArgumentError, 'Correct choices must match the configured number of questions'
+      end
+
+      correct_choices.map.with_index do |choice, question|
+        normalized =
+          case choice
+          when nil
+            nil
+          when Integer
+            choice
+          when Array
+            if choice.length > 1
+              fail ArgumentError, 'Each question supports a single correct choice'
+            end
+            choice.first
+          else
+            fail ArgumentError, 'Correct choices must contain integers, 1-element arrays, or nil'
+          end
+
+        next if normalized.nil?
+
+        max_choice = @mim.choxq[question].length
+        if normalized.negative? || normalized >= max_choice
+          fail ArgumentError, 'Correct choice exceeds the configured number of choices'
+        end
+
+        normalized
+      end
+    end
+
+    def marked_responses(mode)
+      case mode
+      when :unique
+        marked_choices.map { |choices| choices.length == 1 ? choices : [] }
+      when :all
+        marked_choices
+      else
+        fail ArgumentError, 'Invalid marked argument'
+      end
+    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.16.1'
+  VERSION = '0.17.0'
 end

data/spec/mork/grid_omr_spec.rb

@@ -56,6 +56,20 @@ module Mork
       end
     end
 
+    describe '#overlay_stroke_width_px' do
+      it 'keeps the default visual width on the reference scan' do
+        grom = GridOMR.new 'spec/samples/jdoe/layout.yml'
+        grom.set_page_size 1240, 1754
+        expect(grom.overlay_stroke_width_px).to eq 3
+      end
+
+      it 'scales with scan resolution' do
+        grom = GridOMR.new 'spec/samples/jdoe/layout.yml'
+        grom.set_page_size 2480, 3508
+        expect(grom.overlay_stroke_width_px).to eq 6
+      end
+    end
+
     describe '#paper_white_area' do
       it 'returns the coordinates of the white area used for barcode calibration' do
         expect(@grom.paper_white_area).to have_coords(93, 2260, 25, 21)

data/spec/mork/magicko_spec.rb

@@ -38,5 +38,17 @@ module Mork
         expect(ma.registered_bytes(pp).length).to eq sh.height*sh.width
       end
     end
+
+    describe 'overlay stroke width' do
+      it 'defaults to the legacy 3-pixel width' do
+        expect(ma.overlay_stroke_width).to eq 3
+      end
+
+      it 'uses the configured width for green outlines' do
+        ma.overlay_stroke_width = 6
+        ma.outline [co], false
+        expect(ma.instance_variable_get(:@cmd)).to include([:strokewidth, 6])
+      end
+    end
   end
 end

data/spec/mork/sheet_omr_spec.rb

@@ -148,6 +148,58 @@ module Mork
           omr.overlay :outline
           omr.save "spec/out/JD-outline-marked.jpeg"
         end
+
+        it 'applies correctness-aware overlays and saves the result' do
+          omr.set_choices [5] * 5
+          omr.overlay_corrections [0, 0, 2, 3, 1]
+          omr.save "spec/out/JD-corrections.jpeg"
+        end
+      end
+
+      context 'applying correctness-aware overlays' do
+        let(:mim) { omr.instance_variable_get(:@mim) }
+
+        before do
+          omr.set_choices [5] * 4
+        end
+
+        it 'batches green outlines, red outlines, and red crosses by correctness' do
+          allow(omr).to receive(:marked_choices).and_return([[1], [2], [], [3, 4]])
+
+          expect(mim).to receive(:overlay).with(:outline_green, [[1], [], [], []]).ordered
+          expect(mim).to receive(:overlay).with(:outline_red, [[], [0], [2], [3]]).ordered
+          expect(mim).to receive(:overlay).with(:check_red, [[], [2], [], []]).ordered
+
+          omr.overlay_corrections [1, 0, 2, 3]
+        end
+
+        it 'can cross all marked cells for incorrect responses' do
+          allow(omr).to receive(:marked_choices).and_return([[1, 2], [0]])
+
+          omr.set_choices [5] * 2
+
+          expect(mim).to receive(:overlay).with(:outline_green, [[], []]).ordered
+          expect(mim).to receive(:overlay).with(:outline_red, [[3], [1]]).ordered
+          expect(mim).to receive(:overlay).with(:check_red, [[1, 2], [0]]).ordered
+
+          omr.overlay_corrections [3, 1], marked: :all
+        end
+
+        it 'raises an ArgumentError if the answer key length does not match the questions' do
+          expect { omr.overlay_corrections([0, 1, 2]) }.to raise_error(ArgumentError)
+        end
+
+        it 'raises an ArgumentError if a correct choice exceeds the configured choices' do
+          expect { omr.overlay_corrections([0, 1, 5, 2]) }.to raise_error(ArgumentError)
+        end
+
+        it 'raises an ArgumentError if a question has multiple correct choices' do
+          expect { omr.overlay_corrections([0, [1, 2], 2, 3]) }.to raise_error(ArgumentError)
+        end
+
+        it 'raises an ArgumentError if the marked mode is invalid' do
+          expect { omr.overlay_corrections([0, 1, 2, 3], marked: :invalid) }.to raise_error(ArgumentError)
+        end
       end
 
       context 'requesting invalid responses and choices' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mork
 version: !ruby/object:Gem::Version
-  version: 0.16.1
+  version: 0.17.0
 platform: ruby
 authors:
 - Giuseppe Bertini
@@ -283,7 +283,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.4
 specification_version: 4
 summary: Optical mark recognition of multiple-choice tests and surveys
 test_files: []