OMRChecker
Evaluate OMR sheets fast and accurately using a scanner 🖨 or your phone 🤳.
Install / Use
/learn @Udayraj123/OMRCheckerREADME
OMR Checker
Read OMR sheets fast and accurately using a scanner 🖨 or your phone 🤳.
What is OMR?
OMR stands for Optical Mark Recognition, used to detect and interpret human-marked data on documents. OMR refers to the process of reading and evaluating OMR sheets, commonly used in exams, surveys, and other forms.
Quick Links
<hr />
<!-- [](https://github.com/Udayraj123/OMRChecker/wiki/TODOs) -->
🎯 Features
A full-fledged OMR checking software that can read and evaluate OMR sheets scanned at any angle and having any color.
| Specs <img width=200/> | 
<img width=200/> |
| :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 💯 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. |
| ✅ Customizable | Easily apply to custom OMR layouts, surveys, etc. |
| 📊 Visually Rich | Get insights to configure and debug easily. |
| 🎈 Lightweight | Very minimal core code size. |
| 🏫 Large Scale | Tested on a large scale at Technothlon. |
| 👩🏿💻 Dev Friendly | Pylinted and Black formatted code. Also has a developer community on discord. |
Note: For solving interesting challenges, developers can check out TODOs.
See the complete guide and details at Project Wiki.
<!-- 💁🏿♂️ **User Friendly** - WIP, Help by contributing! -->💡 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 marked responses in an excel sheet!
Images can be taken from various angles as shown below-
<p align="center"> <img alt="sample_input" width="400" src="https://raw.githubusercontent.com/wiki/Udayraj123/OMRChecker/extras/Progress/2019-04-26/images/sample_input.PNG"> </p>Code in action on images taken by scanner:
<p align="center"> <img alt="document_scanner" height="300" src="https://raw.githubusercontent.com/wiki/Udayraj123/OMRChecker/extras/mini_scripts/outputs/gif/document_scanner.gif"> </p>Code in action on images taken by a mobile phone:
<p align="center"> <img alt="checking_xeroxed_mobile" height="300" src="https://raw.githubusercontent.com/wiki/Udayraj123/OMRChecker/extras/mini_scripts/outputs/gif/checking_xeroxed_mobile.gif"> </p>Visuals
Processing steps
See step-by-step processing of any OMR sheet:
<p align="center"> <a href="https://github.com/Udayraj123/OMRChecker/wiki/Rich-Visuals"> <img alt="rotation_stack" width="650" src="https://raw.githubusercontent.com/wiki/Udayraj123/OMRChecker/extras/Progress/2019-04-26/images/rotation.PNG"> </a> <br> *Note: This image is generated by the code itself!* </p>Output
Get a CSV sheet containing the detected responses and evaluated scores:
<p align="center"> <a href="https://github.com/Udayraj123/OMRChecker/wiki/Rich-Visuals"> <img alt="csv_output" width="550" src="https://raw.githubusercontent.com/wiki/Udayraj123/OMRChecker/extras/Progress/2019-04-26/images/csv_output.PNG"> </a> </p>We now support colored outputs as well. Here's a sample output on another image -
<p align="center"> <a href="https://github.com/Udayraj123/OMRChecker/wiki/%5Bv2%5D-About-Evaluation"> <img alt="colored_output" width="550" src="./docs/assets/colored_output.jpg"> </a> </p>There are many more visuals in the wiki. Check them out here!
Getting started
Operating system: OSX or Linux is recommended although Windows is also supported.
1. Install global dependencies
To check if python3 and pip is already installed:
python3 --version
python3 -m pip --version
To install python3 follow instructions here
To install pip - follow instructions here
</details> <details> <summary><b>Install OpenCV</b></summary>Any installation method is fine.
Recommended:
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.
</details> <details> <summary><b>Extra steps(for Linux users only)</b></summary><b>Installing missing libraries(if any):</b>
On a fresh computer, some of the libraries may get missing in event after a successful pip install. Install them using following commands(ref):
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. Install project dependencies
Clone the repo
git clone https://github.com/Udayraj123/OMRChecker
cd OMRChecker/
Install pip requirements
python3 -m pip install --user -r requirements.txt
Note: If you face a distutils error in pip, use --ignore-installed flag in above command.
3. Run the code
- First copy and examine the sample data to know how to structure your inputs:
cp -r ./samples/sample1 inputs/ # Note: you may remove previous inputs (if any) with `mv inputs/* ~/.trash` # Change the number N in sampleN to see more examples - Run OMRChecker:
python3 main.py
Alternatively you can also use python3 main.py -i ./samples/sample1.
Each example in the samples folder demonstrates different ways in which OMRChecker can be used.
