OMR Checker

Grade exams fast and accurately using a scanner 🖨 or your phone 🤳.

TLDR; Jump to Getting Started.

🎯 Features

A full-fledged OMR checking software that can read and evaluate OMR sheets scanned at any angle and having any color. Support is also provided for a customisable marking scheme with section-wise marking, bonus questions, etc.

Specs
💯 Accurate	Currently nearly 100% accurate on good quality document scans; and about 90% accurate on mobile images.
💪🏿 Robust	Supports low resolution, xeroxed sheets. See Robustness for more.
⏩ Fast	Current processing speed without any optimization is 200 OMRs/minute.
✅ Extensible	Easily apply to different OMR layouts, surveys, etc.
📊 Visually Rich Outputs	Get insights to configure and debug easily.
🎈 Extremely lightweight	Core code size is less than 500 KB(Samples excluded).
🏫 Large Scale	Used on tens of thousands of OMRs at Technothlon.
👩🏿‍💻 Dev Friendly	Well documented repository based on python and openCV with an active discussion group.

Note: For solving live challenges, developers can checkout TODOs. See all details in Project Wiki.

💡 What can OMRChecker do for me?

Once you configure the OMR layout, just throw images of the sheets at the software; and you'll get back the graded responses in an excel sheet!

Images can be taken from various angles as shown below-

Code in action on images taken by scanner:

Code in action on images taken by a mobile phone:

See step by step processing of any OMR sheet:

*Note: This image is generated by the code itself!*

Output: A CSV sheet containing the detected responses and evaluated scores:

There are many visuals in the wiki. Check them out!

Getting started

Operating System

Although windows is supported, Linux is recommended for a bug-free experience.

1. Install dependencies

Note: To get a copy button for below commands, use CodeCopy Chrome | CodeCopy Firefox.

python3 -m pip install --user --upgrade pip
python3 -m pip install --user opencv-python
python3 -m pip install --user opencv-contrib-python

More details on pip install openCV here.

Note: On a fresh computer some of the libraries may get missing in above pip install.

Install them using the following commands: Windows users may skip this step.

sudo apt-get install -y build-essential cmake unzip pkg-config
sudo apt-get install -y libjpeg-dev libpng-dev libtiff-dev
sudo apt-get install -y libavcodec-dev libavformat-dev libswscale-dev libv4l-dev
sudo apt-get install -y libatlas-base-dev gfortran

2. Clone the repo

# Shallow clone - takes latest code with minimal size
git clone https://github.com/Udayraj123/OMRChecker --depth=1

Note: Contributors should take a full clone(without the --depth flag).

Install other requirements

cd OMRChecker/
python3 -m pip install --user -r requirements.txt

Note: If you face a distutils error, use --ignore-installed flag in above command.

3. Run the code

Put your data in inputs folder. You can copy sample data as shown below:
```
# Note: you may remove previous inputs if any with `mv inputs/* ~/.trash` 
cp -r ./samples/sample1 inputs/
```
Note: Change the number N in sampleN to see more examples
Run OMRChecker: python3 main.py

These samples demonstrate different ways OMRChecker can be used.

Running it on your own OMR Sheets

First create your own template.json.
Open globals.py and check the tuning parameters.

Run OMRChecker with appropriate arguments.

Full Usage
```
python3 main.py [--setLayout] [--noCropping] [--autoAlign] [--inputDir dir1] [--outputDir dir1] [--template path/to/template.json]
```
Explanation for the arguments:

--setLayout: Set up OMR template layout - modify your json file and run again until the template is set.

--autoAlign: (experimental) Enables automatic template alignment - use if the scans show slight misalignments.

--noCropping: Disables page contour detection - used when page boundary is not visible e.g. document scanner.

--inputDir: Specify an input directory.

--outputDir: Specify an output directory.

--template: Specify a default template if no template file in input directories.

💡 Why is this software free?

The idea for this project began at Technothlon, which is a non-profit international school championship. After seeing it work fabulously at such a large scale, we decided to share this simple and powerful tool with the world to perhaps help revamp OMR checking processes and help greatly reduce the tediousness of the work involved.

And we believe in the power of open source! Currently, OMRChecker is in its initial stage where only developers can use it. We hope to see it become more user-friendly and even more robust with exposure to different inputs from you!

Can I use this code in my work?

OMRChecker can be forked and modified. You are encouraged to play with it and we would love to see your own projects in action! The only requirement is disclose usage of this software in your code. It is published under the GPLv3 license

Credits

A Huge thanks to : The creative master Adrian Rosebrock for his blog : https://pyimagesearch.com

The legendary Harrison aka sentdex for his video tutorials.

And the james bond of computer vision Satya Mallic for his blog: https://www.learnopencv.com

And many other amazing people over the globe without whom this project would never have completed. Thank you!

This project is dedicated to Technothlon where the idea of making such solution was conceived. Technothlon is a logic-based examination organized by students of IIT Guwahati.

License

Copyright © 2019 Udayraj Deshmukh
OMRChecker : Grade exams fast and accurately using a scanner 🖨 or your phone 🤳
This is free software, and you are welcome to redistribute it under certain conditions;

For more details see

Related Projects

Here's a sneak peak of the Android OMR Helper App(WIP):

Other ways you can contribute:

Help OMRChecker cross 560 stars ⭐ to become #1 (Currently #4). Current stars:
Buy Me A Coffee ☕ - To keep my brain juices flowing and help me create more such projects 💡
If this project saved you large costs on OMR Software licenses, or saved efforts to make one.

Find OMRChecker on Product Hunt | Hacker News | Reddit | Swyya |

simonwoodhead/OMRChecker