{"id":28440719,"url":"https://github.com/abynxv/automatedexamsheetgrader-ocr","last_synced_at":"2025-06-27T14:31:15.033Z","repository":{"id":295465222,"uuid":"990160459","full_name":"abynxv/AutomatedExamSheetGrader-OCR","owner":"abynxv","description":"This Python project automates grading of handwritten or printed answer sheets using OCR (Optical Character Recognition). It extracts student answers from scanned images, compares them to an answer key, and generates a detailed report with class statistics.","archived":false,"fork":false,"pushed_at":"2025-05-25T17:24:45.000Z","size":23,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-06T04:06:30.149Z","etag":null,"topics":["numpy","ocr-recognition","opencv","pandas","python3","tesseract"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abynxv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-25T16:16:17.000Z","updated_at":"2025-05-27T08:13:12.000Z","dependencies_parsed_at":"2025-05-25T18:36:09.287Z","dependency_job_id":"a47cda28-1ec7-4f2a-84a9-f602482791be","html_url":"https://github.com/abynxv/AutomatedExamSheetGrader-OCR","commit_stats":null,"previous_names":["abynxv/automatedexamsheetgrader-ocr"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/abynxv/AutomatedExamSheetGrader-OCR","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abynxv%2FAutomatedExamSheetGrader-OCR","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abynxv%2FAutomatedExamSheetGrader-OCR/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abynxv%2FAutomatedExamSheetGrader-OCR/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abynxv%2FAutomatedExamSheetGrader-OCR/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abynxv","download_url":"https://codeload.github.com/abynxv/AutomatedExamSheetGrader-OCR/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abynxv%2FAutomatedExamSheetGrader-OCR/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262273323,"owners_count":23285658,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["numpy","ocr-recognition","opencv","pandas","python3","tesseract"],"created_at":"2025-06-06T04:06:30.023Z","updated_at":"2025-06-27T14:31:15.028Z","avatar_url":"https://github.com/abynxv.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Automated Exam Sheet Grader using OCR\n\n\u003e This project was developed with the assistance of AI tools to help accelerate my learning. Most technologies used were new to me, and I’m working step-by-step to understand and improve over time.\n\nThis Python project automates grading of handwritten or printed answer sheets using OCR (Optical Character Recognition). It extracts student answers from scanned images, compares them to an answer key, and generates a detailed report with class statistics.\n\n## Features\n\n- **OCR-based answer extraction** using Tesseract\n- **Image preprocessing**: orientation correction, deskewing, enhancement\n- **Flexible grading**: supports objective and short-text answers\n- **Detailed reports** in JSON format with scores, grades, and analytics\n\n## Installation\n\n### 1. Install Tesseract OCR\n\n#### Ubuntu/Debian\n```bash\nsudo apt update\nsudo apt install tesseract-ocr\nsudo apt install libtesseract-dev\n```\n\n#### macOS (using Homebrew)\n```bash\nbrew install tesseract\n```\n\n#### Windows\n1. Download installer from: https://github.com/tesseract-ocr/tesseract/wiki\n2. Install and add the install path to your system's PATH\n   - Example path: `C:\\Program Files\\Tesseract-OCR`\n\n**Verify installation:**\n```bash\ntesseract --version\n```\n\n### 2. Python Environment Setup\n\n#### Using venv\n```bash\npython3 -m venv venv\nsource venv/bin/activate  # For Windows: venv\\Scripts\\activate\n```\n\n### 3. Install Dependencies\n\n```bash\npip install -r requirements.txt\n```\n\n**requirements.txt:**\n```\npytesseract\nopencv-python\nnumpy\nPillow\nscikit-image\n```\n\n### 4. Verify Setup\n\n```bash\npython main.py --help\ntesseract --version\n```\n\n## Project Structure\n\n```\nproject-root/\n│\n├── main.py\n├── requirements.txt\n├── README.md\n├── sample_data/\n│   ├── images/\n│   ├── answer_key.csv\n│   └── sample_report.json\n├── src/\n│   ├── preprocessor.py\n│   ├── ocr.py\n│   ├── grader.py\n│   └── utils.py\n└── tests/\n    └── test_grader.py\n```\n\n## Usage\n\n### Basic Command\n```bash\npython main.py --input_dir sample_data/images --key sample_data/answer_key.csv --output sample_data/report.json\n```\n\n### Verbose Debugging\n```bash\npython main.py --input_dir sample_data/images --key sample_data/answer_key.csv --output sample_data/report.json --verbose\n```\n\n## Input Formats\n\n### Answer Key (answer_key.csv)\n```csv\nquestion_id,correct_answer,points\n1,A,2\n2,B,2\n3,Photosynthesis,4\n4,C,2\n5,Mitochondria,2\n```\n\n### Answer Sheet Images\n- **Supported formats**: `.jpg`, `.png`, `.jpeg`\n- **Expected OCR output format**:\n  ```\n  1: A  \n  2: B  \n  3: Photosynthesis  \n  4: C  \n  5: Mitochondria\n  ```\n## Output Formats\n\n  ![image](https://github.com/user-attachments/assets/f2de450c-a7dd-4001-b295-b33a5a3145a9)\n  ![image](https://github.com/user-attachments/assets/dcc7dcce-cb54-4b59-8171-3d427f68f04a)\n\n## Testing\n\n### Running Tests\n```bash\npython -m unittest discover tests\n```\n\n### Test Coverage\n\nThe test suite includes:\n\n#### Image Preprocessing\n- Orientation correction\n- Deskewing\n- Image enhancement\n\n#### OCR Extraction\n- Extract text accurately from test images\n\n#### Grading Logic\n- Handle case-insensitive matching\n- Allow partial credit (if applicable)\n- Ensure correct score computation\n\n#### Utility Functions\n- JSON writing\n- Statistics calculation\n\n### Example Test Structure\n\n```python\n# tests/test_grader.py\nimport unittest\nimport pandas as pd\nfrom src.grader import grade_student\n\n\nclass TestGrader(unittest.TestCase):\n\n    def setUp(self):\n        self.answer_key = pd.DataFrame([\n            {'question_id': 1, 'correct_answer': 'A', 'points': 2},\n            {'question_id': 2, 'correct_answer': 'B', 'points': 3},\n            {'question_id': 3, 'correct_answer': 'Photosynthesis', 'points': 5}\n        ])\n\n    def test_all_correct(self):\n        answers = {'1': 'a', '2': 'b', '3': 'photosynthesis'}\n        score, _ = grade_student(answers, self.answer_key)\n        self.assertEqual(score, 10)\n\n    def test_partial_correct(self):\n        answers = {'1': 'a', '2': 'x'}\n        score, _ = grade_student(answers, self.answer_key)\n        self.assertEqual(score, 2)\n\n    def test_all_wrong(self):\n        answers = {'1': 'x', '2': 'y', '3': 'z'}\n        score, _ = grade_student(answers, self.answer_key)\n        self.assertEqual(score, 0)\n\n```\n\n## Troubleshooting\n\n### OCR Not Extracting Text\n- Ensure image quality is sufficient (300 DPI recommended)\n- Use grayscale or binarized images\n- Test Tesseract manually:\n  ```bash\n  tesseract path/to/image.png stdout\n  ```\n\n### Common Errors\n\n| Error Message | Solution |\n|---------------|----------|\n| `tesseract is not installed or it's not in PATH` | Install Tesseract and add to system PATH |\n| `OCR failed to extract any text` | Check image clarity or preprocessing methods |\n| `KeyError during grading` | Ensure answer_key has all question IDs |\n| `DeprecationWarning: datetime.utcnow()` | Use `datetime.now(timezone.utc)` instead |\n\n## License\n\nThis project is open-source under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabynxv%2Fautomatedexamsheetgrader-ocr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabynxv%2Fautomatedexamsheetgrader-ocr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabynxv%2Fautomatedexamsheetgrader-ocr/lists"}