Skip to content

Improve README formatting and add usage example #284

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Jags-08 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Improve README formatting and add usage example #284

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 16 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,7 +152,7 @@ More details on pip install openCV [here](https://www.pyimagesearch.com/2018/09/

<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)](https://www.pyimagesearch.com/2018/05/28/ubuntu-18-04-how-to-install-opencv/):
On a fresh computer, some libraries may be missing even 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
Expand Down Expand Up @@ -249,6 +249,21 @@ Explanation for the arguments:
- The `--template` flag is deprecated and instead it's recommended to keep the template file at the parent folder containing folders of different images
</details>

## Usage Example

Here is a simple example of how to use OMRChecker in a complete workflow:

1. Place your scanned OMR sheets in a folder, such as `inputs/`.
2. Create or copy your layout definition into a `template.json` file.
3. Run the checker script targeting your inputs:

```bash
python3 main.py --inputDir inputs/ --outputDir outputs/
```
Comment on lines +256 to +262
Copy link
Copy Markdown

@qodo-free-for-open-source-projects qodo-free-for-open-source-projects Bot May 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

1. Template path requirement missing 🐞 Bug ≡ Correctness

The new Usage Example does not state that template.json must be located inside the directory tree
rooted at --inputDir; if users put template.json elsewhere (e.g., repo root) and run with
--inputDir inputs/, the program raises "No template file found in the directory tree" and exits.
This makes the documented workflow fail for a common interpretation of step (2).
Agent Prompt 
## Issue description
The README "Usage Example" omits where `template.json` must be placed relative to `--inputDir`. The code only discovers `template.json` inside the directory tree rooted at the provided input directory and raises an exception if images are found without a discovered template.

## Issue Context
Users may reasonably interpret step (2) as creating `template.json` in the repo root (or current working directory) and then run `--inputDir inputs/`. That setup fails because `template.json` is not searched outside the input directory tree.

## Fix Focus Areas
- README.md[247-262]

## Suggested documentation change
Update the steps to explicitly say one of the following:
- Place `template.json` inside `inputs/` (or an ancestor directory *within* the `--inputDir` tree), e.g. `inputs/template.json`.
- Or, if you want `template.json` to live in a parent folder of multiple scan subfolders, set `--inputDir` to that parent folder (the one containing `template.json`).

Optionally add a small directory tree example to remove ambiguity.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Copy link
Copy Markdown
Owner

@Udayraj123 Udayraj123 May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Jags-08 can you please address this?


4. Check the `outputs/` folder for your parsed results in CSV format and visual feedback images!


<!-- #### Testing the code
Datasets to test on :
Low Quality Dataset(For CV Based methods)) (1.5 GB)
Expand Down