OMR Detection API

A production-ready Flask API for detecting and processing OMR (Optical Mark Recognition) sheets, specifically designed for Bengali educational institutions.

Features

• ✅ Header Detection: Automatically extracts student information

  • Class (calculated from serial)
  • Roll Number (6 digits)
  • Subject Code (3 digits)
  • Set Code (Bengali letters)

• ✅ Answer Detection: Detects marked answers from MCQ bubbles

• ✅ Answer Checking: Compares detected answers with answer key

• ✅ Visual Feedback: Generates marked images showing correct/incorrect answers

• ✅ Bengali Support: Full support for Bengali characters

Quick Start

Installation

# Clone the repository
git clone <repository-url>
cd python-omr-scraper-v2

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On Linux/Mac:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Running the Server

python api.py

Server will start at http://0.0.0.0:5001

API Endpoints

1. /check-omr - Check OMR with Header Detection

Detects student information and checks answers against an answer key.

Request:

POST /check-omr
Content-Type: multipart/form-data

image: [OMR sheet image file]
answer_key: {"1":"ক","2":"খ","3":"গ",...}

Response:

{
  "success": true,
  "header": {
    "class": "10",
    "roll": "246802",
    "subject_code": "131",
    "set_code": "চ"
  },
  "results": {
    "total_questions": 50,
    "correct": 45,
    "incorrect": 5,
    "unattempted": 0,
    "score_percentage": 90.0
  },
  "details": {...},
  "output_image": "output/filename_marked.jpg"
}

2. /detect-omr - Detect OMR Information Only

Detects student information and answers without checking.

Request:

POST /detect-omr
Content-Type: multipart/form-data

image: [OMR sheet image file]

Response:

{
  "success": true,
  "header": {
    "class": "10",
    "roll": "246802",
    "subject_code": "131",
    "set_code": "চ"
  },
  "answers": {
    "1": 3,
    "2": 1,
    ...
  },
  "metadata": {
    "total_answers_detected": 50,
    "filename": "omr_sheet.jpg"
  }
}

3. /health - Health Check

GET /health

Returns: {"status": "ok"}

Header Detection Details

Class Calculation

Class is automatically calculated from the serial number:

• Formula: Class = Serial + 5
• Serial is detected internally but not included in response

Serial	Class
1	6
2	7
3	8
4	9
5	10
6	11
7	12

Detection Areas

• Header Section: Top 20-40% of page
• Answer Section: Bottom 60% of page

OMR Sheet Requirements

Layout

• Serial/Class bubbles in leftmost column
• Roll number: 6 columns, 10 bubbles each (0-9)
• Subject code: 3 columns, 10 bubbles each (0-9)
• Set code: 1 column, Bengali letter bubbles (ক, খ, গ, ঘ, etc.)
• Answer bubbles: 4 options per question

Image Quality

• Resolution: Minimum 1500x2000 pixels recommended
• Format: JPG, JPEG, or PNG
• Max Size: 16MB
• Quality: Clear, well-lit, minimal shadows
• Marking: Dark, filled bubbles (pen or pencil)

Example Usage

Python

import requests

url = 'http://localhost:5001/check-omr'

with open('omr_sheet.jpg', 'rb') as f:
    files = {'image': f}
    data = {'answer_key': '{"1":"ক","2":"খ","3":"গ"}'}
    response = requests.post(url, files=files, data=data)

result = response.json()
print(f"Roll: {result['header']['roll']}")
print(f"Class: {result['header']['class']}")
print(f"Score: {result['results']['score_percentage']}%")

cURL

curl -X POST \
  -F "image=@omr_sheet.jpg" \
  -F 'answer_key={"1":"ক","2":"খ"}' \
  http://localhost:5001/check-omr

JavaScript (Fetch)

const formData = new FormData();
formData.append('image', fileInput.files[0]);
formData.append('answer_key', JSON.stringify({"1":"ক","2":"খ"}));

fetch('http://localhost:5001/check-omr', {
  method: 'POST',
  body: formData
})
.then(res => res.json())
.then(data => console.log(data));

Configuration

Edit api.py to configure:

# File size limit (default: 16MB)
app.config['MAX_CONTENT_LENGTH'] = 16 * 1024 * 1024

# Upload and output folders
UPLOAD_FOLDER = 'uploads'
OUTPUT_FOLDER = 'output'

# Allowed file extensions
ALLOWED_EXTENSIONS = {'jpg', 'jpeg', 'png'}

Project Structure

python-omr-scraper-v2/
├── api.py                 # Flask API server
├── omr_detector.py        # OMR detection logic
├── requirements.txt       # Python dependencies
├── README.md             # This file
├── API_DOCUMENTATION.md  # Detailed API docs
├── .gitignore           # Git ignore rules
├── uploads/             # Temporary upload folder
└── output/              # Marked images output

Performance

• Processing Time: 2-5 seconds per image
• Accuracy:
  • Header detection: ~95%
  • Answer detection: ~98%
• Concurrent Requests: Supported

Error Handling

All endpoints return standardized error responses:

{
  "error": "Error description"
}

Common HTTP status codes:

• 200: Success
• 400: Bad request (missing/invalid parameters)
• 404: Not found
• 500: Server error

Production Deployment

Using Gunicorn (Recommended)

pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5001 api:app

Using Docker

FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 5001
CMD ["python", "api.py"]

Environment Variables

export FLASK_ENV=production
export MAX_CONTENT_LENGTH=16777216  # 16MB in bytes

Security Considerations

• ✅ File type validation
• ✅ File size limits (16MB)
• ✅ Secure filename handling
• ⚠️ Add authentication for production use
• ⚠️ Add rate limiting for API endpoints
• ⚠️ Use HTTPS in production

Troubleshooting

Server won't start

• Check if port 5001 is available
• Verify all dependencies are installed

Low detection accuracy

• Ensure image quality meets requirements
• Check OMR sheet is properly scanned
• Verify bubbles are clearly marked

Memory issues

• Reduce image size before processing
• Increase server memory allocation

License

[Add your license here]

Support

For issues or questions, please contact [your contact info] or create an issue in the repository.

Changelog

Version 1.0.0 (2025-10-31)

• Initial production release
• Header detection with class calculation
• Answer detection and checking
• Bengali character support
• Marked image generation