Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/udayraj123/omrchecker
Evaluate OMR sheets fast and accurately using a scanner 🖨 or your phone 🤳.
https://github.com/udayraj123/omrchecker
checker correction document document-scanner exam grader hacktoberfest image-processing mcq multiple-choice omr omr-layout omr-scanner omr-scanning omr-sheet opencv scanned-documents scanner scoring template
Last synced: 2 days ago
JSON representation
Evaluate OMR sheets fast and accurately using a scanner 🖨 or your phone 🤳.
- Host: GitHub
- URL: https://github.com/udayraj123/omrchecker
- Owner: Udayraj123
- License: mit
- Created: 2018-03-25T11:56:23.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-09-29T09:37:52.000Z (4 days ago)
- Last Synced: 2024-10-01T04:43:10.302Z (2 days ago)
- Topics: checker, correction, document, document-scanner, exam, grader, hacktoberfest, image-processing, mcq, multiple-choice, omr, omr-layout, omr-scanner, omr-scanning, omr-sheet, opencv, scanned-documents, scanner, scoring, template
- Language: Python
- Homepage:
- Size: 36.3 MB
- Stars: 745
- Watchers: 25
- Forks: 304
- Open Issues: 47
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# 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**
- [Installation](#getting-started)
- [User Guide](https://github.com/Udayraj123/OMRChecker/wiki)
- [Contributor Guide](https://github.com/Udayraj123/OMRChecker/blob/master/CONTRIBUTING.md)
- [Project Ideas List](https://github.com/users/Udayraj123/projects/2/views/1)
[](https://github.com/Udayraj123/OMRChecker/pull/new/master)
[](https://github.com/Udayraj123/OMRChecker/pulls?q=is%3Aclosed)
[](https://GitHub.com/Udayraj123/OMRChecker/issues?q=is%3Aissue+is%3Aclosed)
[](https://github.com/Udayraj123/OMRChecker/issues/5)
[](https://GitHub.com/Udayraj123/OMRChecker/stargazers/)
[](https://hits.seeyoufarm.com)
[](https://discord.gg/qFv2Vqf)
## 🎯 Features
A full-fledged OMR checking software that can read and evaluate OMR sheets scanned at any angle and having any color.
| 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**](https://github.com/Udayraj123/OMRChecker/wiki/Robustness) for more. |
| ⏩ **Fast** | Current processing speed without any optimization is 200 OMRs/minute. |
| ✅ **Customizable** | [Easily apply](https://github.com/Udayraj123/OMRChecker/wiki/User-Guide) to custom OMR layouts, surveys, etc. |
| 📊 **Visually Rich** | [Get insights](https://github.com/Udayraj123/OMRChecker/wiki/Rich-Visuals) to configure and debug easily. |
| 🎈 **Lightweight** | Very minimal core code size. |
| 🏫 **Large Scale** | Tested on a large scale at [Technothlon](https://en.wikipedia.org/wiki/Technothlon). |
| 👩🏿💻 **Dev Friendly** | [Pylinted](http://pylint.pycqa.org/) and [Black formatted](https://github.com/psf/black) code. Also has a [developer community](https://discord.gg/qFv2Vqf) on discord. |
Note: For solving interesting challenges, developers can check out [**TODOs**](https://github.com/Udayraj123/OMRChecker/wiki/TODOs).
See the complete guide and details at [Project Wiki](https://github.com/Udayraj123/OMRChecker/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 marked 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:
## Visuals
### Processing steps
See step-by-step processing of any OMR sheet:
*Note: This image is generated by the code itself!*
### Output
Get a CSV sheet containing the detected responses and evaluated scores:
We now support [colored outputs](https://github.com/Udayraj123/OMRChecker/wiki/%5Bv2%5D-About-Evaluation) as well. Here's a sample output on another image -
#### There are many more visuals in the wiki. Check them out [here!](https://github.com/Udayraj123/OMRChecker/wiki/Rich-Visuals)
## 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:
```bash
python3 --version
python3 -m pip --version
```
Install Python3
To install python3 follow instructions [here](https://www.python.org/downloads/)
To install pip - follow instructions [here](https://pip.pypa.io/en/stable/installation/)
Install OpenCV
**Any installation method is fine.**
Recommended:
```bash
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](https://www.pyimagesearch.com/2018/09/19/pip-install-opencv/).
Extra steps(for Linux users only)
Installing missing libraries(if any):
On a fresh computer, some of the libraries may get missing in event after a successful pip install. Install them using following commands[(ref)](https://www.pyimagesearch.com/2018/05/28/ubuntu-18-04-how-to-install-opencv/):
```bash
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
```bash
git clone https://github.com/Udayraj123/OMRChecker
cd OMRChecker/
```
Install pip requirements
```bash
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
1. First copy and examine the sample data to know how to structure your inputs:
```bash
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
```
2. Run OMRChecker:
```bash
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.
### Common Issues
1. [Windows] ERROR: Could not open requirements file
Command: python3 -m pip install --user -r requirements.txt
Link to Solution: #54
2. [Linux] ERROR: No module named pip
Command: python3 -m pip install --user --upgrade pip
Link to Solution: #70
## OMRChecker for custom OMR Sheets
1. First, [create your own template.json](https://github.com/Udayraj123/OMRChecker/wiki/User-Guide).
2. Configure the tuning parameters.
3. Run OMRChecker with appropriate arguments (See full usage).
## Full Usage
```
python3 main.py [--setLayout] [--inputDir dir1] [--outputDir dir1]
```
Explanation for the arguments:
`--setLayout`: Set up OMR template layout - modify your json file and run again until the template is set.
`--inputDir`: Specify an input directory.
`--outputDir`: Specify an output directory.
Deprecation logs
- The old `--noCropping` flag has been replaced with the 'CropPage' plugin in "preProcessors" of the template.json(see [samples](https://github.com/Udayraj123/OMRChecker/tree/master/samples)).
- The `--autoAlign` flag is deprecated due to low performance on a generic OMR sheet
- The `--template` flag is deprecated and instead it's recommended to keep the template file at the parent folder containing folders of different images
## FAQ
Why is this software free?
This project was born out of a student-led organization called as [Technothlon](https://technothlon.techniche.org.in). It is a logic-based international school championship organized by students of IIT Guwahati. Being a non-profit organization, and after seeing it work fabulously at such a large scale we decided to share this tool with the world. The OMR checking processes still involves so much tediousness which we aim to reduce dramatically.
We believe in the power of open source! Currently, OMRChecker is in an intermediate stage where only developers can use it. We hope to see it become more user-friendly as well as robust from exposure to different inputs from you all!
[](https://github.com/ellerbrock/open-source-badges/)
Can I use this code in my (public) 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!
It is published under the [MIT license](https://github.com/Udayraj123/OMRChecker/blob/master/LICENSE).
What are the ways to contribute?
- Join the developer community on [Discord](https://discord.gg/qFv2Vqf) to fix [issues](https://github.com/Udayraj123/OMRChecker/issues) with OMRChecker.
- If this project saved you large costs on OMR Software licenses, or saved efforts to make one. Consider donating an amount of your choice(donate section).
## Credits
_A Huge thanks to:_
_**Adrian Rosebrock** for his exemplary blog:_ https://pyimagesearch.com
_**Harrison Kinsley** aka sentdex for his [video tutorials](https://www.youtube.com/watch?v=Z78zbnLlPUA&list=PLQVvvaa0QuDdttJXlLtAJxJetJcqmqlQq) and many other resources._
_**Satya Mallic** for his resourceful blog:_ https://www.learnopencv.com
_And to other amazing people from all over the globe who've made significant improvements in this project._
_Thank you!_
## Related Projects
Here's a snapshot of the [Android OMR Helper App (archived)](https://github.com/Udayraj123/AndroidOMRHelper):
## Stargazers over time
[](https://starchart.cc/Udayraj123/OMRChecker)
---
Made with ❤️ by Awesome Contributors
---
### License
[](https://github.com/Udayraj123/OMRChecker/blob/master/LICENSE)
For more details see [LICENSE](https://github.com/Udayraj123/OMRChecker/blob/master/LICENSE).
### Donate
[](https://www.paypal.me/Udayraj123/500)
_Find OMRChecker on_ [**_Product Hunt_**](https://www.producthunt.com/posts/omr-checker/) **|** [**_Reddit_**](https://www.reddit.com/r/computervision/comments/ccbj6f/omrchecker_grade_exams_using_python_and_opencv/) **|** [**Discord**](https://discord.gg/qFv2Vqf) **|** [**Linkedin**](https://www.linkedin.com/pulse/open-source-talks-udayraj-udayraj-deshmukh/) **|** [**goodfirstissue.dev**](https://goodfirstissue.dev/language/python) **|** [**codepeak.tech**](https://www.codepeak.tech/) **|** [**fossoverflow.dev**](https://fossoverflow.dev/projects) **|** [**Interview on Console by CodeSee**](https://console.substack.com/p/console-140) **|** [**Open Source Hub**](https://opensourcehub.io/udayraj123/omrchecker)