README.md

omr

omr is a small Python 3 optical mark recognition script. It takes as input an image of an answered answer sheet and outputs which alternatives were marked. The project is generally optimized for conciseness and teachability, and the goal is to provide a reasonable starting point for learning and hopefully building more powerful applications.

Usage

$ python omr.py --help
usage: omr.py [-h] --input INPUT [--output OUTPUT] [--show]

optional arguments:
  -h, --help       show this help message and exit
  --input INPUT    Input image filename
  --output OUTPUT  Output annotated image filename
  --show           Displays annotated image

Example

$ python omr.py --input img/answered-sheet-photo.jpg  --output /tmp/results.png --show

Q1: A
Q2: C
Q3: C
Q4: E
Q5: N/A
Q6: N/A
Q7: A
Q8: N/A
Q9: N/A
Q10: N/A

In this case, we used the following image as input:

And got the following output:

Installation

Using pipenv with pyenv

Install pyenv

$ git clone https://github.com/rbaron/omr
$ cd omr/
$ pyenv install 3.7.5
$ pyenv local 3.7.5
$ pipenv --python 3.7.5
$ pipenv install
$ pipenv shell
$ py.test

Using virtualenv

$ git clone https://github.com/rbaron/omr
$ cd omr/
$ virtualenv --python=`which python3` venv
$ source venv/bin/activate
(venv) $ pip install -r requirements.txt
(venv) $ python omr.py --help

Anwer Sheet

The answer sheet is available in the sheet/ directory.

Development

Run unit tests

test_omr.py contains unit tests that can be run using:

$ py.test
=========================================================== test session starts ===========================================================
platform darwin -- Python 3.7.5, pytest-5.2.4, py-1.8.0, pluggy-0.13.0
collected 1 item

test_omr.py .                                                                                                                       [100%]

============================================================ 1 passed in 0.31s ============================================================