udayraj123/omrchecker

Evaluate OMR sheets fast and accurately using a scanner 🖨 or your phone 🤳.

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
• User Guide
• Contributor Guide
• Project Ideas List

---

🎯 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 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.

💡 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:

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

Install Python3

To install python3 follow instructions here

To install pip - follow instructions here

Install OpenCV

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.

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):

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

1. 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

2. 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.

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.
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).
• 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. 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!

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!

The only requirement is disclose usage of this software in your (public) code.

It is published under the GPLv3 license.

What are the ways to contribute?

• Join the developer community on Discord to fix 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 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):

Stargazers over time

---

Made with ❤️ by Awesome Contributors

---

License

For more details see LICENSE.

Donate

Find OMRChecker on Product Hunt | Reddit | Discord | Linkedin | goodfirstissue.dev | codepeak.tech | fossoverflow.dev | Interview on Console by CodeSee | Open Source Hub

omrchecker's Issues

[Feature] Support for images in PDF format

Is your feature request related to a problem? Please describe.
It appears that existing commercial products use PDF as the format for processing OMRs. Supporting this in OMRChecker will help with making it easy for adoption.

Describe the solution you'd like
Use a popular pdf reading library to convert the pdf into jpg image and then forward that image to the existing solution. This can be implemented as a plugin as well (discussion needed). We can also support multi-page pdfs this way.

Describe alternatives you've considered
Currently we would need to use third party bulk converters to achieve this.

Additional context
NA

[Windows]<ERROR: Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt'>

Ideas/Feedback

Discuss any ideas or suggestions/feedbacks you have here.

[New Idea][Figma][React] Want to work on making a browser interface(React)?

There is a project under progress to migrate OMRChecker into the browser(currently in a private repository). It shall eradicate the need of having to install python or opencv on user's device.

Contact the developer to get access and updates. Tech Stack: React, Redux, Saga

Note: this issue is marked with the hacktoberfest label. Follow #hacktoberfest-discussions on Discord for further details .

Setting dimensions dynamically

Hi,

In my requirement, I want to set dimension and orig as per respective dimension of OMR sheet dynamically.
I tried setting up the the "dims" array of template object inside process_files for loop. Although I can see that dimension have been added to the template object as per file, the output doesn't reflect that.
If I manually put the dimension values the get reflected to the output correctly.
Can you help me to set dimensions based on my files dynamically to the template for each OMR sheet dynamically.

Thanks,
Ram

[Windows] AttributeError: 'FigureCanvasTkAgg' object has no attribute 'set_window_title'

Environment

Windows OS, with matlplotlib version >=3.6.0

Steps to reproduce

1. Open OMRChecker\src\defaults\config.json
2. Line 24: Set show image level to anything >=5 say "show_image_level": 5,
3. From the command line run: python3 main.py -i samples/sample1

Details

(1) Opening image:      inputs\sample1\MobileCamera\sheet1.jpg  Resolution: (1240, 930)
Found page corners:      [[519, 541], [148, 537], [141, 220], [479, 218]]
Matching Marker:         Q1: max_t 0.451        Q2: max_t 0.582 Q3: max_t 0.692Q4: max_t 0.547  Optimal Scale: 0.46
Thresholding:            global_thr:  175.25    global_std_THR:  255
Traceback (most recent call last):
  File "C:\OMRChecker\main.py", line 79, in <module>
    entry_point(
  File "C:\OMRChecker\src\core.py", line 50, in entry_point
    return process_dir(root_dir, curr_dir, args)
  File "C:\OMRChecker\src\core.py", line 120, in process_dir
    process_dir(root_dir, d, args, template)
  File "C:\OMRChecker\src\core.py", line 120, in process_dir
    process_dir(root_dir, d, args, template)
  File "C:\OMRChecker\src\core.py", line 109, in process_dir
    process_files(omr_files, template, args_local, out)
  File "C:\OMRChecker\src\core.py", line 313, in process_files
    response_dict, final_marked, multi_marked, _ = MainOperations.read_response(
  File "C:\OMRChecker\src\utils\imgutils.py", line 993, in read_response
    raise e
  File "C:\OMRChecker\src\utils\imgutils.py", line 951, in read_response
    f.canvas.set_window_title(name)
AttributeError: 'FigureCanvasTkAgg' object has no attribute 'set_window_title'

This issue is potentially caused by latest release of matplotlib. (Refer: https://matplotlib.org/stable/api/prev_api_changes/api_changes_3.6.0.html#:~:text=get_figure_manager%3B%20use-,frame.canvas.manager,-instead.)

[Feature][Non core] Create visual guides for better tuning/debugging

Current control that we use over debugging OMRChecker for new images is by setting show_image_level to 1 through 6. It is still sometimes not very effective for large number of images. We need a non-intrusive visual guide that helps tune our config for each type of images.

Experienced in data visualizations/analytics?

Contact the developer for a dataset.

Note: this issue is marked with the hacktoberfest label. Follow #hacktoberfest-discussions on Discord for further details .

template using circles??

[Bug] Templates getting merged.

Describe the bug
When running the program for multiple sample types, the templates seem to be merged with that of the previous iteration. This causes rectangles and labels to be generated where it shouldn't be.

To Reproduce
Steps to reproduce the behavior:

1. Setup the project.
2. In src/defaults/config.json set the 'show_image_level' to either 4 or 5.
3. Run the command python main.py -i samples/
4. See error

Expected behavior

Screenshots

Desktop (please complete the following information):

• OS: Linux
• Python version: 3.10.7
• OpenCV version: 4.6.0.66

Additional context
The issue arises due to use of deepmerge library. It can be fixed by modifying the function to make the merge non destructive to the base template.

creating exe and using with the bunch of images

I created template.json and I am using it to detect the bubbles. But now I want to generate an exe file and use the code with a folder containing the multiple sheets. so how could I do this with existing code

[Beginner][Getting Familiar] Submit your sample image and template!

As you setup OMRChecker and run samples according to the Readme, you would maybe want to try it on new public images or some of your own. This issue is created to accept new submissions. This is your chance to feature your template and image in the samples section!

Where can I find OMR sheets? (ideas)

• Tests, Assessments, Exams, Quizzes
• Surveys (some samples here)
• Safety Forms
• Feedbacks
• Lotteries
• Voting/Ballots
• Postal codes
• more

Steps to follow -

1. Pick any OMR sheet image(s) that you can use publicly.
2. Design a template overlay for the image(using --setLayout flag). Discuss on discord for any issues faced.
3. Make sure to see it generates correct output. Rename images properly.
4. Compress your images to jpg 80% - this will keep cloning the repository less bandwidth consuming.
5. Put it in samples/community folder and raise a PR.

Note: this issue is marked with the hacktoberfest label. Follow #hacktoberfest-discussions on Discord for further details .

P.S. We are looking for someone to make template for popular examinations like JEE or UPSC in case of India.

[Enhancement][Core] Improve output image labels

This is an enhancement version of #42

Steps

1. Follow Readme to setup and run OMRChecker
2. Set show_image_level = 4 or 5
3. Run OMRChecker on sample images
4. For each image that you see, try to add appropriate labels to each output image using cv2.putText, etc so that they are more understandable. For any queries discuss in discord.
5. You can create them in separate PRs if needed.

Note: this issue is marked with the hacktoberfest label. Follow #hacktoberfest-discussions on Discord for further details .

[Bug] Unexpected Output(Cropping Issue) in `Template Layout` for the sample `/inputs/AdrianSamples/adrian_omr.png`

Describe the bug
While running the code of the sample example, the command python3 main.py --setLayout should give the cropped template layout automatically. However, the generated template layout is incorrectly cropped.

To Reproduce
Steps to reproduce the behavior:

1. Open (https://github.com/Udayraj123/OMRChecker/wiki/User-Guide) and follow the steps as per the guide.
2. After creating the file inputs/template.json and adding the given text to it. Run the command python3 main.py --setLayout on the terminal.
3. Following the above command produces an template layout improperly cropped.

Expected behavior
The page should have got cropped automatically and show a basic overlay of the template.

Screenshots

Desktop (please complete the following information):

• OS: [Windows]
• Python 3.11.0
• OpenCV 4.6.0

[Feature][Non core] Generate Template Layout directly from a fully bubbled OMR image

Right now, we need to follow a tedious method of creating template.json files. There are two ways to simplify this for a start.

1. Create a drag and drop type interface that let's us make a template overlay and export it as a json file.
2. Input a single fully-bubbled omr sheet to the code, it generates the bubble coordinates by itself.(scope of this task)

Note: this issue is marked with the hacktoberfest label. Follow #hacktoberfest-discussions on Discord for further details .

[Get Familiar]: Improve logging

Some ideas for logs:

1. Explore the code based on the logs you see.
2. Add log levels to them as part of your first contribution!
3. If tidy readable outputs interest you, try using colorama to indicate log levels
4. You can also propose "modes" of logs: dev/user/minimal/silent

Note: this issue is marked with the hacktoberfest label. Follow #hacktoberfest-discussions on Discord for further details .

[Feature][Core] Implement a generalised evaluation script

Is your feature request related to a problem? Please describe.
Need support for a customisable marking scheme with negative marking, section-wise marking, bonus questions, etc. Answer keys may exist for a test booklet code. We can also support custom logic via eval scripts for handling any other cases.

Describe the solution you'd like
Basic evaluation scheme can be stored in template.json file

Criteria for Answer Schema:
- It should allow simplest way to grade +1 -0 case
- Also for +4 -1 case, it should be of minimal effort
- In all other cases we want users to modify 3-4 keys

Describe alternatives you've considered
Right now we can solve this by applying Excel formulae(link to sample sheet) over the output results file. It works fine for simple cases which still requires knowledge about writing formulae in excel.

Additional context
NA

[Readme][Beginner] Add a dynamic Contribution Section

I will add a section where it will show all the contributors profile image and will have a nice tagline too.
Please assign me this under Hacktoberfest.

Thanks & Regards

Understanding template format

Dear team,
Huge thanks for this amazing project.
I'm wondering where I can find template format description in details? Sorry if I missed something. But I don't understand what Concatenations, Singles mean?

[Getting Familiar][Refactor] list out hardcodings in the preprocessors

Describe the bug
There are some hardcodings in the codebase(some of which are tagged by a todo comment). We need to remove them and pick them up from configuration/command line. The first step would be to list out the hardcoded values in a comment below.
Then we'll break it down into new issues to fix them in parts.

To Reproduce
One example is from src/processors/CropPage.py : the parameters passed to cv2.Canny can be taken from something like self.canny_params

Acceptance Criteria
A list of all hardcodings should be populated.

Screenshots
NA

Desktop (please complete the following information):

• OS: any
• Python version: 3.10.6
• OpenCV version: 4.6.0

Additional context
NA

[Get Familiar] Add schema validation for template configuration

Right now, OMRChecker does not handle invalid template.json files. It simply tries to process the file and throws an errors.

We want to extend that an do a json schema validation for the file.

Steps:

1. Study current structure of the Template file
2. Create a json schema for the same.
3. Use python-jsonschema or similar library to throw validation errors when the input file doesn't match with the schema.

Resources:

1. https://python-jsonschema.readthedocs.io/en/stable/
2. https://github.com/python-jsonschema/jsonschema
3. https://github.com/Udayraj123/OMRChecker/wiki/About-Templates
4. https://github.com/Udayraj123/OMRChecker/wiki/User-Guide

Note: this issue is marked with the hacktoberfest label. Follow #hacktoberfest-discussions on Discord for further details .

[Bug] Fix global thresholding for a singleton qBlock case

Describe the bug
For the case of a non-bubbled OMR sheet with single column qBlock(singleton "vals"), the global thresholding logic fails to interpret the OMR response correctly. Example json:

"qNos": [ [ [ "q1", "q2", "q3", "q4", "q5"] ] ],

To Reproduce
Steps to reproduce the behaviour:

1. Use sample provided in PR #91
2. Run python3 main.py -i samples/community/ibrahimkilic
3. Current output

Read Response:   {'q1': 'yes', 'q2': 'yes', 'q3': 'yes', 'q4': 'yes', 'q5': 'yes'} 

Expected behaviour
The output should be the following

Read Response:   {'q1': '', 'q2': '', 'q3': '', 'q4': '', 'q5': ''} 

or after issue #61 is fixed, it should output

Read Response:   {'q1': 'no', 'q2': 'no', 'q3': 'no', 'q4': 'no', 'q5': 'no'} 

Screenshots
NA

Desktop (please complete the following information):

• OS: MacOS
• Python version: 3
• OpenCV version: 4

Error while testing OMRChecker

Hello:

Got this error when launching the main.py script... any ideas?

I'm running an AWS Bitnami LAMP Server which I just updated to python 3

Here is what happened:

~/OMRChecker$ python3 main.py

Traceback (most recent call last):
File "main.py", line 13, in
import cv2
File "/home/bitnami/.local/lib/python3.5/site-packages/cv2/init.py", line 3, in
from .cv2 import *
ImportError: libXrender.so.1: cannot open shared object file: No such file or directory

Best regards

[Bug] changing `show_image_level` gives undesirable results

Describe the bug
when show_image_level=3, we get 3 different stack of images (that are: Warped Sheet,Final Alignment Adjustment, Final marked bubbles). However when show_image_level=4 we get only 2 stack of images (that are: Final Alignment Adjustment, Final marked bubbles)

To Reproduce
Steps to reproduce the behavior:

1. Open \src\defaults\config.json
2. Line 24: Set show_image_level=3
3. From the command line run: python3 main.py -i samples/sample1. 3 image stacks will be displayed.
4. Line 24: Set show_image_level=4
5. From the command line run: python3 main.py -i samples/sample1. 2 image stacks will be displayed.

Expected behavior
For show_image_level=4 four image stacks should be shown.

Desktop (please complete the following information):

• OS: [Windows]
• Python 3.10.7
• OpenCV 4.6.0

Additional context
This issue is continuation of #44 and will expect to work on redefining images displayed for different show_image_levels.

[Windows] ERROR: Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt'

I was facing the issue <ERROR: Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt'> on Windows after I used the command:

$ python3 -m pip install --user -r requirements.txt

[Feature][Core] Auto Rotating the OMR sheet

We want to be able to identify and correct rotation of input images

Some ideas

1. Firstly, we can take expected page orientation(portrait/landscape) from user.
2. For a start, check for height-width ratio and always rotate clockwise (ignore wrongly rotated images, will be separated later).
3. Try both clockwise and anti-clockwise corrections and the one with the "more correct" histogram will be considered.

Acceptance criterion:

1. The code should run for rotated versions of all sample images in the repo.
2. Proper logging of rotations should be done to make debugging easier

Example real user validation: https://discord.com/channels/590134763784896514/590134763784896520/908620446201696316

Note: this issue is marked with the hacktoberfest label. Follow #hacktoberfest-discussions on Discord for further details .

[Logging] Reduce noise in logging and generated files

Currently there are some csv files and directories created in each of the input directories i.e. ErrorFiles, MultiMarkedFiles and BadRollNoFiles. Since they are not yet implemented for general use, they are created and left out empty. This leads to a lot of unnecessary files getting created and extra logs for the same.

Fixing it requires removing some unused/redundant file creations.

[New Idea][Non Core] Document photo plugin (help wanted)

So,This is about my idea of creating a Document photo scanner.

This is from my real life instance where we had a pile load of documents which contained passport size photos of candidates on the top right of the page and we wanted to extract photos from it.

What we did was first he scanned the document and then imported it in a photo editor then cropped photos from each document and obviously it took a lot of time.

So I wanted to create/write a program by which I can easily extract photos from a scanned document multiple at a time which would reduce the effort in future and I think will help many like my friend.

And I guess interacting with OMR Checker can boost it 10x.

[Bug]Error while running the pre-commit as the CONTRIBUTING.md

Describe the bug
I installed pre-commit by commands given in CONTRIBUTING.md after installing when i tried to run pre-commit it gave process error.

To Reproduce
Steps to reproduce the behavior:
pip install -r requirements.dev.txt && pre-commit install
git .add
pre-commit run --files

Expected behavior
should be able to refactor the code

Screenshots

[BUG]Unable to detect the encircled due to their translucent nature

Describe the bug
Most of the read responses on the terminal in sample 6 are incorrectly interpreting the roll numbers

To Reproduce
Steps to reproduce the behavior:

1. Use sample ' samples\sample6\jpg'
2. From the command line run: 'python3 main.py -i samples/sample6.'
3. See Read Response: {'Roll': '} on most of the samples.

Expected behavior
It should be able to read the encircled values for the roll number accurately.

Screenshots
image: samples\sample6\jpg\sample_roll_11.jpg

Desktop (please complete the following information):

• OS: Windows
  -Python 3.10.7
  -OpenCV 4.6.0

Installing opencv on a fresh droplet : segmentation fault (core dumped)

Did the setup on Ubuntu 16.04 and ran the code with sample files available the repo. Please find the code I used.

sudo apt-get update -y
sudo apt-get upgrade -y
sudo reboot
python3 -m pip install --user --upgrade pip
wget https://bootstrap.pypa.io/get-pip.py
sudo python3 get-pip.py
python3 -m pip install --user --upgrade pip
python3 -m pip install --user opencv-python
python3 -m pip install --user opencv-contrib-python
git clone https://github.com/Udayraj123/OMRChecker
cd OMRChecker/
python3 -m pip install --user -r requirements.txt
sudo cp -r inputs/OMR_Files_Sample/ inputs/OMR_Files
python3 main.py

If I run the code, I am getting, "Segmentation fault (core dumped)" error.

General Discussion/Comments (prefer discord)

Comment here if anyone wants to discuss anything about the software

Discord link for quicker response: https://discord.gg/qFv2Vqf

[Get Familiar][Core] Improve output image labels

Steps

1. Follow Readme to setup and run OMRChecker
2. Set show_image_level = 4 or 5
3. Run OMRChecker on sample images
4. For each image that you see, try to add appropriate labels to each output image using cv2.putText, etc so that they are more understandable. For any queries discuss in discord.
5. You can create them in separate PRs if needed.

Note: this issue is marked with the hacktoberfest label. Follow #hacktoberfest-discussions on Discord for further details .

[Linux] pip module not found issue on a fresh linux

I was facing this issue <ERROR: /usr/bin/python3: No module named pip > when running this command:
$ python3 -m pip install --user --upgrade pip

[Feature Request] i need 0('N')-1('Y') with one bubble... is it possible?

I want 'yes' when bubble is full and 'no' when empty, in result csv file.... is it posible?

[Feature] Reading Barcodes & QR codes to organize images and templates

Is your feature request related to a problem? Please describe.
We have received this request multiple times now, reading QR codes in particular sections of the OMR, then splitting the images based on the information in the QR, and using particular template from that information. This can be extended to barcodes as well.

Note: OCR should be tracked in a different issue from this (#99)

Describe the solution you'd like
This can be implemented as a plugin. More details to follow in discussion.

Describe alternatives you've considered
Currently no alternatives present to scan QRs. Manual work needed.

Additional context
Discord discussion

[Enhancement] Extra steps and error messages in schema validation

This extends #43

1. All labels in all of the QBlocks should be covered in either Singles or concatenations (tally the qNo labels to exist in either of them).
2. Also none of the labels in qBlocks should overlap (show warning in this case)
3. User friendly messages: suggestion to convert key into camelCase (in which case validation error should mention that).

Originally posted by @Udayraj123 in #60 (comment)

ORM HELP

results.csv is showing only index like rollno,q1.q20 etc...i want ans along with score,key can you explain more in detail thanks.

[Learning][Core] Add more step-wise images for intuitive understanding

Best part of working with opencv is visually seeing each step. OMRChecker provides a way to see the step-wise images. But they have a scope to improve.

Steps

1. Learn about existing step-wise images that OMRchecker generates (set show_image_level to 4 or 5)
2. Propose and discuss which images can be added to the steps for intuitive understanding of the process.

Resources:

1. https://github.com/Udayraj123/OMRChecker/wiki/Rich-Visuals
2. https://github.com/Udayraj123/OMRChecker/wiki/Diagrams#block-diagram-of-the-program

Note: this issue is marked with the hacktoberfest label. Follow #hacktoberfest-discussions on Discord for further details .

find all question as answer for unanswered question

I have problem. I have a sheet that when correct with this code in some question find two or more answer.
this is my answer sheet

and correction is like this

after 80 , correction is wrong. why?
and in log print "globalTHR: 255 globalStdTHR: 255 (Looks like a Xeroxed OMR)"

[BUG]Unable to detect the fillings due to their translucent nature

[Feature][Core] Calculate thresholding confidence using data

The core logic of OMRChecker revolves around finding the correct separation between Marked and Unmarked bubbles. We want to let the user know if it has been determined confidently.

In the above image there are two possible thresholds based on the jumps in the histogram. In such cases the confidence metric will be useful to separate bad quality images.

More references in Rich Visuals section.

Note: this issue is marked with the hacktoberfest label. Follow #hacktoberfest-discussions on Discord for further details .

[Bug] Unexpected output in `Template Alignment Adjustment` for the sample `\community\Sandeep-1507/CheckedOMRs/omr-1.png`

Describe the bug
While running the code with below configurations, the preview of Template Alignment Adjustment shows unexpected output. The text is not legible, which is due to incorrect spacing of the text displayed.

To Reproduce
Steps to reproduce the behavior:

1. set "show_image_level": 3 in src\defaults\config.json
2. In the terminal run python3 main.py -i samples/community/Sandeep-1507

Expected behavior
Either change the font size or update the spacing of the text displayed.
Try changing (int(s[0] + d[0] - text_in_px[0][0]), int(s[1] - text_in_px[0][1])) or (rect[2] + 2, rect[0] + (box_h * 2) // 3) in src\utils\imgutils.py

Screenshots

Desktop (please complete the following information):

• OS: Windows
• Python 3.9.9
• OpenCV 4.5.4

[Getting Familiar][Core] Change default behavior to use --noCropping flag

The --noCropping flag is particularly annoying to new users who have scanned images(as opposed to mobile camera).

Steps

1. Understand how CLI args are parsed in OMRChecker
2. Change --noCropping flag into --enableCropping with default value as false
3. Update Readme as well as Wiki documentation reflecting above change.

Currently we have this as the CLI documentation, which is often confused with by new users. We can simplify it and improve the CLI experience with above simple change.

It has been repeatedly asked as a query on discord. So this is a high impact, low effort task up for grabs :)

1. https://discord.com/channels/590134763784896514/590134763784896520/1023997697637765130
2. https://discord.com/channels/590134763784896514/590134763784896520/1006898626120908931
3. https://discord.com/channels/590134763784896514/590134763784896520/908613137366913046

Note: this issue is marked with the hacktoberfest label. Follow #hacktoberfest-discussions on Discord for further details .

[Feature] Optical Character Reader [OCR]

Can we also add Optical character reader in this application for reading student names and other detail?

[Bug] `save_image_level` includes max 3 stacks(for all values>=3) when `show_image_level` is 1

Describe the bug
referring to the comment on issue #44
Following undesirable action is being performed:

• If show_image_level is 1 and any value of save_image_level which is greater than 3, the output stack would include max 3 stacks.

To Reproduce

1. Open \src\defaults\config.json
2. Line 24: Set show_image_level=1
3. Line 25: Set save_image_level=5
4. From the command line run: python3 main.py -i samples/sample1
5. Visit \outputs\MobileCamera\CheckedOMRs\stack to see only 3 stacks (instead of expected 5 stacks).

Screenshots

Desktop (please complete the following information):

• OS: [Windows]
• Python 3.10.7

Score is 0 is it a [Bug] or is it not implemented yet?

I have tried with every sample and all i get is score=0 for every run what is the issue, not a python guy so apologies in advance if i am being wrong about it.

[Readme] Clearer setup instructions

As you setup OMRChecker on your own machine, mark your first contribution with the following

1. You can update the Getting Started section with better instructions that makes the setup experience smoother.
2. For a start, you can create a different section for setting up on Windows/Linux, etc. Also, the Installing missing libraries section is confusing for macOS users as it doesn't run for them.
3. Since the setup instructions might have outdated with latest versions of dependencies, try running the project with latest ways of installing them and if it works, share here and propose to use the newer versions.

Note: this issue is marked with the hacktoberfest label. Follow #hacktoberfest-discussions on Discord for further details .

Barcodes ?

Hi,
This looks really great. Any plans to add a barcode reading option ?
Thanks
David de Leeuw
Israel

[DevX] Improve the developer experience by fixing minor issues

Some minor issues I observed while running a sanity check of OMRChecker on my machine.

1. Unnecessary output folder created: _MULTI_/stack for sample1.
2. Spacing issue in the output Matching Marker: Q1: max_t 0.451 Q2: max_t 0.582 Q3: max_t 0.692Q4: max_t 0.547 Optimal Scale: 0.46. Also the name Q1, Q2, etc. can be changed to something more readable.
3. Output file naming: need correction in <outputs/sample1/MobileCamera/CheckedOMRs/stack/sheet1.jpg_1_stack.jpg>.
4. In the output of sample1 and sample4 : 'q8' is not there in excel & q11 is repeated twice.

[Bug][Windows] TypeError: unsupported operand type(s) for *: 'DotMap' and 'float'

Description

Multiplication is being performed between DotMap and float data type, for image level 2,3.

Steps to reproduce

Steps to reproduce the behavior:

1. Open OMRChecker\src\defaults\config.json
2. Line 24: Set show image level to either 2 or 3 say "show_image_level": 2,
3. From the command line run: python3 main.py -i samples/sample1

Expected behaviour

window size gets increased by 1.6 times for image level 2,3.

Error log

  File "C:\OMRChecker\main.py", line 79, in <module>
    entry_point(
  File "C:\OMRChecker\src\core.py", line 50, in entry_point
    return process_dir(root_dir, curr_dir, args)
  File "C:\OMRChecker\src\core.py", line 120, in process_dir
    process_dir(root_dir, d, args, template)
  File "C:\OMRChecker\src\core.py", line 109, in process_dir
    process_files(omr_files, template, args_local, out)
  File "C:\OMRChecker\src\core.py", line 283, in process_files
    in_omr = pre_processor.apply_filter(in_omr, args)
  File "C:\OMRChecker\src\processors\CropOnMarkers.py", line 218, in apply_filter  
    h_stack, int(config.display_width * 1.6)),
TypeError: unsupported operand type(s) for *: 'DotMap' and 'float

Environment

Windows OS
Python 3.10.7
OpenCV 4.6.0