omrkit 2.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- omrkit-2.1.0/.gitignore +55 -0
- omrkit-2.1.0/LICENSE +21 -0
- omrkit-2.1.0/PKG-INFO +284 -0
- omrkit-2.1.0/README.md +226 -0
- omrkit-2.1.0/pyproject.toml +128 -0
- omrkit-2.1.0/src/omrkit/__init__.py +76 -0
- omrkit-2.1.0/src/omrkit/__main__.py +6 -0
- omrkit-2.1.0/src/omrkit/api/__init__.py +5 -0
- omrkit-2.1.0/src/omrkit/api/app.py +75 -0
- omrkit-2.1.0/src/omrkit/api/routes.py +490 -0
- omrkit-2.1.0/src/omrkit/api/settings.py +55 -0
- omrkit-2.1.0/src/omrkit/api/static/assets/index-BFfdzDls.js +224 -0
- omrkit-2.1.0/src/omrkit/api/static/assets/index-DRPOjlrM.css +1 -0
- omrkit-2.1.0/src/omrkit/api/static/index.html +23 -0
- omrkit-2.1.0/src/omrkit/cli/__init__.py +5 -0
- omrkit-2.1.0/src/omrkit/cli/app.py +440 -0
- omrkit-2.1.0/src/omrkit/core/__init__.py +44 -0
- omrkit-2.1.0/src/omrkit/core/auto_scanner.py +132 -0
- omrkit-2.1.0/src/omrkit/core/benchmark.py +204 -0
- omrkit-2.1.0/src/omrkit/core/migrator.py +149 -0
- omrkit-2.1.0/src/omrkit/core/scanner.py +281 -0
- omrkit-2.1.0/src/omrkit/core/validators.py +62 -0
- omrkit-2.1.0/src/omrkit/generator/__init__.py +13 -0
- omrkit-2.1.0/src/omrkit/generator/pdf_sheet.py +508 -0
- omrkit-2.1.0/src/omrkit/generator/presets.py +109 -0
- omrkit-2.1.0/src/omrkit/grading/__init__.py +6 -0
- omrkit-2.1.0/src/omrkit/grading/analytics.py +177 -0
- omrkit-2.1.0/src/omrkit/grading/grader.py +191 -0
- omrkit-2.1.0/src/omrkit/io/__init__.py +37 -0
- omrkit-2.1.0/src/omrkit/io/exporters.py +355 -0
- omrkit-2.1.0/src/omrkit/io/loader.py +207 -0
- omrkit-2.1.0/src/omrkit/models/__init__.py +65 -0
- omrkit-2.1.0/src/omrkit/models/grading.py +222 -0
- omrkit-2.1.0/src/omrkit/models/scan.py +100 -0
- omrkit-2.1.0/src/omrkit/models/template.py +285 -0
- omrkit-2.1.0/src/omrkit/py.typed +0 -0
- omrkit-2.1.0/src/omrkit/vision/__init__.py +30 -0
- omrkit-2.1.0/src/omrkit/vision/detector.py +313 -0
- omrkit-2.1.0/src/omrkit/vision/grid_finder.py +280 -0
- omrkit-2.1.0/src/omrkit/vision/preprocess.py +57 -0
- omrkit-2.1.0/src/omrkit/vision/qr.py +83 -0
- omrkit-2.1.0/src/omrkit/vision/registration.py +486 -0
- omrkit-2.1.0/src/omrkit/vision/visualizer.py +99 -0
omrkit-2.1.0/.gitignore
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
*.so
|
|
6
|
+
.Python
|
|
7
|
+
build/
|
|
8
|
+
develop-eggs/
|
|
9
|
+
dist/
|
|
10
|
+
downloads/
|
|
11
|
+
eggs/
|
|
12
|
+
.eggs/
|
|
13
|
+
lib/
|
|
14
|
+
lib64/
|
|
15
|
+
parts/
|
|
16
|
+
sdist/
|
|
17
|
+
var/
|
|
18
|
+
wheels/
|
|
19
|
+
*.egg-info/
|
|
20
|
+
.installed.cfg
|
|
21
|
+
*.egg
|
|
22
|
+
|
|
23
|
+
# Virtual environments
|
|
24
|
+
.venv/
|
|
25
|
+
venv/
|
|
26
|
+
ENV/
|
|
27
|
+
env/
|
|
28
|
+
|
|
29
|
+
# Testing & tooling caches
|
|
30
|
+
.pytest_cache/
|
|
31
|
+
.mypy_cache/
|
|
32
|
+
.ruff_cache/
|
|
33
|
+
.coverage
|
|
34
|
+
coverage.xml
|
|
35
|
+
htmlcov/
|
|
36
|
+
|
|
37
|
+
# Frontend (Web Studio)
|
|
38
|
+
studio/node_modules/
|
|
39
|
+
studio/dist/
|
|
40
|
+
studio/.vite/
|
|
41
|
+
*.tsbuildinfo
|
|
42
|
+
|
|
43
|
+
# Local runtime outputs & temporary files
|
|
44
|
+
outputs/
|
|
45
|
+
*.log
|
|
46
|
+
.DS_Store
|
|
47
|
+
Thumbs.db
|
|
48
|
+
.env
|
|
49
|
+
.env.local
|
|
50
|
+
|
|
51
|
+
# IDE
|
|
52
|
+
.vscode/
|
|
53
|
+
.idea/
|
|
54
|
+
*.swp
|
|
55
|
+
*.swo
|
omrkit-2.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Duhan Guler and OMRKit Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
omrkit-2.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: omrkit
|
|
3
|
+
Version: 2.1.0
|
|
4
|
+
Summary: Modern Optical Mark Recognition engine with PDF/ArUco alignment, confidence-scored hybrid bubble detection, printable sheet generation, exam psychometrics, REST API, and Visual Web Studio.
|
|
5
|
+
Project-URL: Homepage, https://github.com/duhanguler/omr
|
|
6
|
+
Project-URL: Repository, https://github.com/duhanguler/omr
|
|
7
|
+
Project-URL: Documentation, https://github.com/duhanguler/omr#readme
|
|
8
|
+
Project-URL: Changelog, https://github.com/duhanguler/omr/blob/main/CHANGELOG.md
|
|
9
|
+
Project-URL: Bug Tracker, https://github.com/duhanguler/omr/issues
|
|
10
|
+
Author: Duhan Guler
|
|
11
|
+
License: MIT
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Keywords: aruco,bubble-sheet,computer-vision,edtech,exam-grading,fastapi,omr,opencv,optical-mark-recognition,psychometrics
|
|
14
|
+
Classifier: Development Status :: 4 - Beta
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Intended Audience :: Education
|
|
17
|
+
Classifier: Intended Audience :: Science/Research
|
|
18
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
19
|
+
Classifier: Operating System :: OS Independent
|
|
20
|
+
Classifier: Programming Language :: Python :: 3
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
24
|
+
Classifier: Topic :: Education :: Testing
|
|
25
|
+
Classifier: Topic :: Scientific/Engineering :: Image Recognition
|
|
26
|
+
Requires-Python: >=3.10
|
|
27
|
+
Requires-Dist: numpy>=1.26.0
|
|
28
|
+
Requires-Dist: opencv-python-headless>=4.9.0.80
|
|
29
|
+
Requires-Dist: pillow>=10.3.0
|
|
30
|
+
Requires-Dist: pydantic>=2.7.0
|
|
31
|
+
Requires-Dist: pypdfium2>=4.28.0
|
|
32
|
+
Requires-Dist: pyyaml>=6.0.1
|
|
33
|
+
Requires-Dist: reportlab>=4.1.0
|
|
34
|
+
Requires-Dist: rich>=13.7.0
|
|
35
|
+
Requires-Dist: typer>=0.12.0
|
|
36
|
+
Provides-Extra: all
|
|
37
|
+
Requires-Dist: fastapi>=0.111.0; extra == 'all'
|
|
38
|
+
Requires-Dist: openpyxl>=3.1.2; extra == 'all'
|
|
39
|
+
Requires-Dist: python-multipart>=0.0.9; extra == 'all'
|
|
40
|
+
Requires-Dist: uvicorn[standard]>=0.30.0; extra == 'all'
|
|
41
|
+
Provides-Extra: dev
|
|
42
|
+
Requires-Dist: build>=1.2.1; extra == 'dev'
|
|
43
|
+
Requires-Dist: httpx>=0.27.0; extra == 'dev'
|
|
44
|
+
Requires-Dist: mypy>=1.11.0; extra == 'dev'
|
|
45
|
+
Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
|
|
46
|
+
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
|
|
47
|
+
Requires-Dist: pytest>=8.2.0; extra == 'dev'
|
|
48
|
+
Requires-Dist: ruff>=0.6.0; extra == 'dev'
|
|
49
|
+
Requires-Dist: twine>=5.1.0; extra == 'dev'
|
|
50
|
+
Requires-Dist: types-pyyaml>=6.0.12; extra == 'dev'
|
|
51
|
+
Provides-Extra: excel
|
|
52
|
+
Requires-Dist: openpyxl>=3.1.2; extra == 'excel'
|
|
53
|
+
Provides-Extra: studio
|
|
54
|
+
Requires-Dist: fastapi>=0.111.0; extra == 'studio'
|
|
55
|
+
Requires-Dist: python-multipart>=0.0.9; extra == 'studio'
|
|
56
|
+
Requires-Dist: uvicorn[standard]>=0.30.0; extra == 'studio'
|
|
57
|
+
Description-Content-Type: text/markdown
|
|
58
|
+
|
|
59
|
+
<div align="center">
|
|
60
|
+
|
|
61
|
+
# OMRKit v2.1
|
|
62
|
+
|
|
63
|
+
**Zero-calibration Optical Mark Recognition engine with QR auto-template detection, blank-form auto-grid finder, live browser camera scanner, printable ArUco sheet generator, Classical Test Theory psychometrics, FastAPI REST API, and React Web Studio.**
|
|
64
|
+
|
|
65
|
+
[](https://github.com/duhanguler/omr/actions/workflows/ci.yml)
|
|
66
|
+
[](https://github.com/duhanguler/omr/releases)
|
|
67
|
+
[](LICENSE)
|
|
68
|
+
[](pyproject.toml)
|
|
69
|
+
[](https://github.com/duhanguler/omr/pkgs/container/omr)
|
|
70
|
+
|
|
71
|
+
[English](README.md) · [Türkçe](README.tr.md) · [Deployment & PyPI Guide](docs/DEPLOYMENT.md) · [Examples](examples/) · [Contributing](CONTRIBUTING.md)
|
|
72
|
+
|
|
73
|
+
</div>
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## Why OMRKit?
|
|
78
|
+
|
|
79
|
+
Traditional open-source OMR scripts force you to hand-edit pixel coordinates in brittle JSON files, break on rotated mobile photos, fail on checkmarks/crosses, and dump raw CSVs without confidence scores or grading analytics. **OMRKit v2.1** solves the entire lifecycle in one clean MIT-licensed toolkit:
|
|
80
|
+
|
|
81
|
+
| Capability | Legacy OMR Scripts | **OMRKit v2.1** |
|
|
82
|
+
| :--- | :---: | :---: |
|
|
83
|
+
| **Printable PDF Sheet Generator + Auto Template** | Manual JSON pixels | **1-Click Vector PDF (ArUco + QR) + Exact `template.json`** |
|
|
84
|
+
| **Zero-Template QR Auto-Scanning** | Must pass template manually | **`omrkit scan sheet.jpg` auto-detects template from QR** |
|
|
85
|
+
| **Auto-Detect Grids on Existing Blank Forms** | Measure pixels by hand | **`omrkit detect-layout blank.jpg` + Studio Canvas Wizard** |
|
|
86
|
+
| **Live Webcam / Mobile Browser Scanner** | Static files only | **Real-time `getUserMedia` Viewfinder with Auto-Lock** |
|
|
87
|
+
| **Multi-Page PDF & EXIF Auto-Orientation** | Single images only | **Native `pypdfium2` + EXIF Auto-Orient** |
|
|
88
|
+
| **0° / 90° / 180° / 270° Auto-Rotation** | Breaks when sideways | **ArUco IDs + Template-Structure Disambiguation** |
|
|
89
|
+
| **Checkmarks (✓), Crosses (✗) & Shadow Tolerance** | Global intensity only | **Illumination Normalization + Hybrid Ink Scorer** |
|
|
90
|
+
| **Confidence Scores & Human-in-the-Loop (HITL)** | Silent errors in CSV | **Calibrated `0–1` Confidence + 1-Click Review Queue** |
|
|
91
|
+
| **Exam Psychometrics & Scorecards** | Basic score sum | **CTT Difficulty ($p$), Discrimination ($D$), KR-20, Excel & PDF Cards** |
|
|
92
|
+
| **Legacy `OMRChecker` Template Migration** | Manual rewrite | **`omrkit migrate-template old.json -o new.json`** |
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## Real-World Detection & Generated Sheets
|
|
97
|
+
|
|
98
|
+
<table>
|
|
99
|
+
<tr>
|
|
100
|
+
<td width="54%" align="center">
|
|
101
|
+
<img src="https://raw.githubusercontent.com/duhanguler/omr/main/docs/assets/scan_overlay_demo.jpg" alt="OMRKit real-world phone scan verification overlay" />
|
|
102
|
+
<br />
|
|
103
|
+
<sub><b>Real mobile photo scan:</b> Emerald = confident (including ✓ & ✗ marks), Crimson = multi-marked, Amber = faint marks queued for 1-click HITL review.</sub>
|
|
104
|
+
</td>
|
|
105
|
+
<td width="46%" align="center">
|
|
106
|
+
<img src="https://raw.githubusercontent.com/duhanguler/omr/main/docs/assets/generated_sheet_preview.jpg" alt="OMRKit generated ArUco + QR optical answer sheet" />
|
|
107
|
+
<br />
|
|
108
|
+
<sub><b>Zero-calibration generated PDF:</b> Vector A4/Letter layout with ArUco corners [0,1,2,3], embedded auto-detect QR badge, and exact companion <code>template.json</code>.</sub>
|
|
109
|
+
</td>
|
|
110
|
+
</tr>
|
|
111
|
+
</table>
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
## Quickstart (60 Seconds)
|
|
116
|
+
|
|
117
|
+
### 1. Run Instantly (Docker / One-Click Cloud Demo / Python)
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
# Option A: Prebuilt official Docker image (zero build!)
|
|
121
|
+
docker run -p 8000:8000 ghcr.io/duhanguler/omr:latest
|
|
122
|
+
|
|
123
|
+
# Option B: Install from source (or `pip install "omrkit[all]"` once PyPI publishing is enabled)
|
|
124
|
+
git clone https://github.com/duhanguler/omr.git
|
|
125
|
+
cd omr
|
|
126
|
+
pip install -e ".[all]"
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
**One-Click Free Cloud Live Demo:**
|
|
130
|
+
- **Render Blueprint:** [](https://dashboard.render.com/blueprint/new?repo=https://github.com/duhanguler/omr)
|
|
131
|
+
- **HuggingFace Spaces (Docker + Auto-Sync):** See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for the 2-minute free HTTPS setup (supports browser **Live Camera**!).
|
|
132
|
+
|
|
133
|
+
### 2. Generate a Print-Ready ArUco + QR Sheet
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
omrkit generate --preset standard_mcq_40 -o my_exam
|
|
137
|
+
# Writes: standard_mcq_40_sheet.pdf, template.json, answer_key.json
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Built-in presets (`omrkit generate --list`):
|
|
141
|
+
- `quick_quiz_20` — 20 questions (A–D), 6-digit Student ID
|
|
142
|
+
- `standard_mcq_40` — 40 questions (A–E), 8-digit Student ID, Booklet (A–D)
|
|
143
|
+
- `turkish_exam_50` — 50 questions (A–E), 6-digit Sınav Kodu, 11-digit **TC Kimlik No** (with checksum validation), Booklet
|
|
144
|
+
- `turkish_yks_120` — 120-question YKS / TYT layout (4 columns × 30 rows)
|
|
145
|
+
|
|
146
|
+
### 3. Scan Images or Multi-Page PDFs (Explicit or Zero-Template QR Auto-Scan)
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
# Zero-template QR auto-detection on generated sheets:
|
|
150
|
+
omrkit scan examples/standard_mcq_40q/scans -o outputs/auto_demo
|
|
151
|
+
|
|
152
|
+
# Explicit template + YKS/TYT negative marking + Excel & PDF scorecards:
|
|
153
|
+
omrkit scan examples/standard_mcq_40q/scans \
|
|
154
|
+
-t examples/standard_mcq_40q/template.json \
|
|
155
|
+
-k examples/standard_mcq_40q/answer_key.json \
|
|
156
|
+
--policy yks_tyt \
|
|
157
|
+
--format csv,json,xlsx,scorecards \
|
|
158
|
+
-o outputs/demo
|
|
159
|
+
|
|
160
|
+
# Auto-detect bubble grids from ANY existing blank optical sheet:
|
|
161
|
+
omrkit detect-layout examples/turkish_exam_50q/blank_form.jpg -o auto_template.json
|
|
162
|
+
|
|
163
|
+
# Migrate a legacy OMRChecker v1 template.json in one command:
|
|
164
|
+
omrkit migrate-template old_template.json -o template_v2.json
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Try the real-world hand-marked Turkish 50-question mobile scans too:
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
omrkit scan examples/turkish_exam_50q/scans \
|
|
171
|
+
-t examples/turkish_exam_50q/template.json \
|
|
172
|
+
-o outputs/turkish_demo
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### 4. Launch Visual Web Studio & REST API
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
omrkit studio
|
|
179
|
+
# Web Studio: http://127.0.0.1:8000
|
|
180
|
+
# OpenAPI Docs: http://127.0.0.1:8000/docs
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
## Python SDK
|
|
186
|
+
|
|
187
|
+
Integrate optical scanning, grading, and psychometrics in 10 lines of typed Python:
|
|
188
|
+
|
|
189
|
+
```python
|
|
190
|
+
from omrkit import AnswerKey, ExamGrader, GradingPolicy, OMRScanner, Template
|
|
191
|
+
|
|
192
|
+
template = Template.from_file("examples/standard_mcq_40q/template.json")
|
|
193
|
+
scanner = OMRScanner(template)
|
|
194
|
+
|
|
195
|
+
batch = scanner.scan_batch("examples/standard_mcq_40q/scans", workers=4)
|
|
196
|
+
|
|
197
|
+
key = AnswerKey.from_file("examples/standard_mcq_40q/answer_key.json")
|
|
198
|
+
report = ExamGrader(key, GradingPolicy.preset("yks_tyt")).grade_batch(batch.sheets)
|
|
199
|
+
|
|
200
|
+
print(f"Graded {report.analytics.student_count} sheets | Mean: {report.analytics.mean_score}")
|
|
201
|
+
print(f"KR-20 Reliability: {report.analytics.kr20_reliability}")
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
## Architecture
|
|
207
|
+
|
|
208
|
+
```mermaid
|
|
209
|
+
flowchart LR
|
|
210
|
+
A["Images / Multi-Page PDF"] --> B["EXIF Auto-Orient + PDFium Loader"]
|
|
211
|
+
B --> C["5-Mode Registration: ArUco / Markers / PageQuad / ORB / Direct"]
|
|
212
|
+
C --> D["Shadow & Illumination Normalization"]
|
|
213
|
+
D --> E["Hybrid Bubble Detector (Fill + Ring Contrast + Ink Stroke)"]
|
|
214
|
+
E --> F{"Confidence & Validator Check"}
|
|
215
|
+
F -- "High Confidence" --> G["ExamGrader + CTT Psychometrics"]
|
|
216
|
+
F -- "Low Conf / Multi-Mark / Bad Checksum" --> H["HITL Review Queue (Web Studio)"]
|
|
217
|
+
H --> G
|
|
218
|
+
G --> I["CSV / JSON / Multi-Sheet Excel / PDF Scorecards / Overlays"]
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
### Key Technical Features
|
|
222
|
+
- **5 Registration Engines:** `aruco` (instant 0/90/180/270° recovery), `markers` (multi-scale concentric markers with template-structure orientation recovery), `page_quad` (borderless page contour), `homography` (ORB + RANSAC), and `none` (flatbed).
|
|
223
|
+
- **Shape-Aware Hybrid Bubble Classifier:** Evaluates inner circular fill ratio, 75th-percentile local ring contrast (immune to printed borders/numbers), and dark ink stroke density so pen checkmarks (`✓`) and crosses (`✗`) read accurately while smudges and multi-marks route to the HITL review queue.
|
|
224
|
+
- **Built-in Field Validators:** Algorithmic **Turkish TC Kimlik No** (11-digit mod-10/11), **Luhn**, `digits`, and `non_empty` validators flag misread IDs automatically.
|
|
225
|
+
- **Classical Test Theory (CTT) Psychometrics:** Mean, median, standard deviation, percentiles, per-item difficulty ($p$), upper/lower 27% discrimination index ($D$), option distractor distribution, and **KR-20** internal consistency reliability.
|
|
226
|
+
- **Grading Policies:** Standard, Turkish **YKS/TYT & KPSS** (4 wrong = -1 correct), **LGS** (3 wrong = -1 correct), multi-booklet (`A/B/C/D`), bonus/cancelled questions, and weighted sections.
|
|
227
|
+
- **Privacy Utility:** `omrkit strip-exif <dir> -o <clean_dir>` permanently bakes EXIF orientation into pixels and removes GPS/device metadata.
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## Reproducible Benchmarks
|
|
232
|
+
|
|
233
|
+
Run `omrkit benchmark --samples 5` on your own machine to reproduce:
|
|
234
|
+
|
|
235
|
+
| Scenario (`standard_mcq_40`, 245 fields/scenario) | Accuracy | Avg Confidence | False HITL Flags | Single-Thread Throughput |
|
|
236
|
+
| :--- | :---: | :---: | :---: | :---: |
|
|
237
|
+
| Clean Flatbed Scan (Solid Fill) | **100.00%** | 99.2% | 0 | **~530 OMR/min** |
|
|
238
|
+
| Mobile Perspective + Uneven Shadow | **100.00%** | 99.2% | 0 | **~310 OMR/min** |
|
|
239
|
+
| Rotated 90° / 180° / 270° + Perspective | **100.00%** | 99.2% | 0 | **~415 OMR/min** |
|
|
240
|
+
| Pen Checkmarks (`✓`) + Shadow | **100.00%** | 99.1% | 0 | **~440 OMR/min** |
|
|
241
|
+
|
|
242
|
+
*(Multi-process batch mode via `--workers N` scales linearly across CPU cores.)*
|
|
243
|
+
|
|
244
|
+
---
|
|
245
|
+
|
|
246
|
+
## Web Studio & REST API
|
|
247
|
+
|
|
248
|
+
OMRKit Studio ships pre-bundled inside the Python package and launches via `omrkit studio` or `docker compose up` (includes a **Try Demo** button in the header for instant 1-click exploration):
|
|
249
|
+
|
|
250
|
+
1. **Scan & Review (HITL):** Drag-and-drop JPG/PNG/PDF batches with explicit template or **QR Auto-Detect**, inspect zoomable color-coded verification overlays, resolve flagged bubbles with 1-click overrides, and export CSV/Excel.
|
|
251
|
+
2. **Live Camera:** Real-time browser webcam / smartphone camera viewfinder (`getUserMedia`) with **Auto-Lock** corner capture, audio confirmation, and QR template recognition.
|
|
252
|
+
3. **Template Designer:** Upload any blank optical form image or PDF, click **Auto-Detect Grids** to find circular bubble blocks automatically, import legacy `OMRChecker` templates (**Migrate v1**), or draw blocks directly on the HTML5 canvas.
|
|
253
|
+
4. **Sheet Generator:** Customize title, question count (5–120), option labels, booklet selector, and ID grids; preview live and download a ready-to-print ZIP bundle (`PDF + template.json + answer_key.json`).
|
|
254
|
+
5. **Grading & Analytics:** Inline answer-key editor, scoring policy selector, score histogram, student scoreboard with per-student **PDF Scorecards**, and full CTT item psychometrics.
|
|
255
|
+
|
|
256
|
+
### REST API Endpoints
|
|
257
|
+
- `GET /api/health` · `GET /api/presets`
|
|
258
|
+
- `POST /api/generate` · `POST /api/generate/bundle`
|
|
259
|
+
- `POST /api/templates/validate` · `POST /api/templates/auto-detect` · `POST /api/templates/migrate` · `POST /api/preview-image`
|
|
260
|
+
- `POST /api/scan` *(supports `template_json="auto"`)* · `POST /api/demo/cohort` · `POST /api/grade`
|
|
261
|
+
- `POST /api/export/csv` · `POST /api/export/xlsx` · `POST /api/export/scorecard`
|
|
262
|
+
|
|
263
|
+
---
|
|
264
|
+
|
|
265
|
+
## Development
|
|
266
|
+
|
|
267
|
+
```bash
|
|
268
|
+
uv venv .venv
|
|
269
|
+
uv pip install --python .venv/bin/python -e ".[all,dev]"
|
|
270
|
+
|
|
271
|
+
# Python QA
|
|
272
|
+
.venv/bin/ruff check src tests
|
|
273
|
+
.venv/bin/mypy src/omrkit
|
|
274
|
+
.venv/bin/pytest -v --cov=omrkit
|
|
275
|
+
|
|
276
|
+
# Frontend Studio development
|
|
277
|
+
cd studio && npm ci && npm run dev
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
---
|
|
281
|
+
|
|
282
|
+
## License
|
|
283
|
+
|
|
284
|
+
Released under the [MIT License](LICENSE). Copyright © 2026 Duhan Güler & Contributors.
|
omrkit-2.1.0/README.md
ADDED
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# OMRKit v2.1
|
|
4
|
+
|
|
5
|
+
**Zero-calibration Optical Mark Recognition engine with QR auto-template detection, blank-form auto-grid finder, live browser camera scanner, printable ArUco sheet generator, Classical Test Theory psychometrics, FastAPI REST API, and React Web Studio.**
|
|
6
|
+
|
|
7
|
+
[](https://github.com/duhanguler/omr/actions/workflows/ci.yml)
|
|
8
|
+
[](https://github.com/duhanguler/omr/releases)
|
|
9
|
+
[](LICENSE)
|
|
10
|
+
[](pyproject.toml)
|
|
11
|
+
[](https://github.com/duhanguler/omr/pkgs/container/omr)
|
|
12
|
+
|
|
13
|
+
[English](README.md) · [Türkçe](README.tr.md) · [Deployment & PyPI Guide](docs/DEPLOYMENT.md) · [Examples](examples/) · [Contributing](CONTRIBUTING.md)
|
|
14
|
+
|
|
15
|
+
</div>
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Why OMRKit?
|
|
20
|
+
|
|
21
|
+
Traditional open-source OMR scripts force you to hand-edit pixel coordinates in brittle JSON files, break on rotated mobile photos, fail on checkmarks/crosses, and dump raw CSVs without confidence scores or grading analytics. **OMRKit v2.1** solves the entire lifecycle in one clean MIT-licensed toolkit:
|
|
22
|
+
|
|
23
|
+
| Capability | Legacy OMR Scripts | **OMRKit v2.1** |
|
|
24
|
+
| :--- | :---: | :---: |
|
|
25
|
+
| **Printable PDF Sheet Generator + Auto Template** | Manual JSON pixels | **1-Click Vector PDF (ArUco + QR) + Exact `template.json`** |
|
|
26
|
+
| **Zero-Template QR Auto-Scanning** | Must pass template manually | **`omrkit scan sheet.jpg` auto-detects template from QR** |
|
|
27
|
+
| **Auto-Detect Grids on Existing Blank Forms** | Measure pixels by hand | **`omrkit detect-layout blank.jpg` + Studio Canvas Wizard** |
|
|
28
|
+
| **Live Webcam / Mobile Browser Scanner** | Static files only | **Real-time `getUserMedia` Viewfinder with Auto-Lock** |
|
|
29
|
+
| **Multi-Page PDF & EXIF Auto-Orientation** | Single images only | **Native `pypdfium2` + EXIF Auto-Orient** |
|
|
30
|
+
| **0° / 90° / 180° / 270° Auto-Rotation** | Breaks when sideways | **ArUco IDs + Template-Structure Disambiguation** |
|
|
31
|
+
| **Checkmarks (✓), Crosses (✗) & Shadow Tolerance** | Global intensity only | **Illumination Normalization + Hybrid Ink Scorer** |
|
|
32
|
+
| **Confidence Scores & Human-in-the-Loop (HITL)** | Silent errors in CSV | **Calibrated `0–1` Confidence + 1-Click Review Queue** |
|
|
33
|
+
| **Exam Psychometrics & Scorecards** | Basic score sum | **CTT Difficulty ($p$), Discrimination ($D$), KR-20, Excel & PDF Cards** |
|
|
34
|
+
| **Legacy `OMRChecker` Template Migration** | Manual rewrite | **`omrkit migrate-template old.json -o new.json`** |
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## Real-World Detection & Generated Sheets
|
|
39
|
+
|
|
40
|
+
<table>
|
|
41
|
+
<tr>
|
|
42
|
+
<td width="54%" align="center">
|
|
43
|
+
<img src="https://raw.githubusercontent.com/duhanguler/omr/main/docs/assets/scan_overlay_demo.jpg" alt="OMRKit real-world phone scan verification overlay" />
|
|
44
|
+
<br />
|
|
45
|
+
<sub><b>Real mobile photo scan:</b> Emerald = confident (including ✓ & ✗ marks), Crimson = multi-marked, Amber = faint marks queued for 1-click HITL review.</sub>
|
|
46
|
+
</td>
|
|
47
|
+
<td width="46%" align="center">
|
|
48
|
+
<img src="https://raw.githubusercontent.com/duhanguler/omr/main/docs/assets/generated_sheet_preview.jpg" alt="OMRKit generated ArUco + QR optical answer sheet" />
|
|
49
|
+
<br />
|
|
50
|
+
<sub><b>Zero-calibration generated PDF:</b> Vector A4/Letter layout with ArUco corners [0,1,2,3], embedded auto-detect QR badge, and exact companion <code>template.json</code>.</sub>
|
|
51
|
+
</td>
|
|
52
|
+
</tr>
|
|
53
|
+
</table>
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## Quickstart (60 Seconds)
|
|
58
|
+
|
|
59
|
+
### 1. Run Instantly (Docker / One-Click Cloud Demo / Python)
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
# Option A: Prebuilt official Docker image (zero build!)
|
|
63
|
+
docker run -p 8000:8000 ghcr.io/duhanguler/omr:latest
|
|
64
|
+
|
|
65
|
+
# Option B: Install from source (or `pip install "omrkit[all]"` once PyPI publishing is enabled)
|
|
66
|
+
git clone https://github.com/duhanguler/omr.git
|
|
67
|
+
cd omr
|
|
68
|
+
pip install -e ".[all]"
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
**One-Click Free Cloud Live Demo:**
|
|
72
|
+
- **Render Blueprint:** [](https://dashboard.render.com/blueprint/new?repo=https://github.com/duhanguler/omr)
|
|
73
|
+
- **HuggingFace Spaces (Docker + Auto-Sync):** See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for the 2-minute free HTTPS setup (supports browser **Live Camera**!).
|
|
74
|
+
|
|
75
|
+
### 2. Generate a Print-Ready ArUco + QR Sheet
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
omrkit generate --preset standard_mcq_40 -o my_exam
|
|
79
|
+
# Writes: standard_mcq_40_sheet.pdf, template.json, answer_key.json
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Built-in presets (`omrkit generate --list`):
|
|
83
|
+
- `quick_quiz_20` — 20 questions (A–D), 6-digit Student ID
|
|
84
|
+
- `standard_mcq_40` — 40 questions (A–E), 8-digit Student ID, Booklet (A–D)
|
|
85
|
+
- `turkish_exam_50` — 50 questions (A–E), 6-digit Sınav Kodu, 11-digit **TC Kimlik No** (with checksum validation), Booklet
|
|
86
|
+
- `turkish_yks_120` — 120-question YKS / TYT layout (4 columns × 30 rows)
|
|
87
|
+
|
|
88
|
+
### 3. Scan Images or Multi-Page PDFs (Explicit or Zero-Template QR Auto-Scan)
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
# Zero-template QR auto-detection on generated sheets:
|
|
92
|
+
omrkit scan examples/standard_mcq_40q/scans -o outputs/auto_demo
|
|
93
|
+
|
|
94
|
+
# Explicit template + YKS/TYT negative marking + Excel & PDF scorecards:
|
|
95
|
+
omrkit scan examples/standard_mcq_40q/scans \
|
|
96
|
+
-t examples/standard_mcq_40q/template.json \
|
|
97
|
+
-k examples/standard_mcq_40q/answer_key.json \
|
|
98
|
+
--policy yks_tyt \
|
|
99
|
+
--format csv,json,xlsx,scorecards \
|
|
100
|
+
-o outputs/demo
|
|
101
|
+
|
|
102
|
+
# Auto-detect bubble grids from ANY existing blank optical sheet:
|
|
103
|
+
omrkit detect-layout examples/turkish_exam_50q/blank_form.jpg -o auto_template.json
|
|
104
|
+
|
|
105
|
+
# Migrate a legacy OMRChecker v1 template.json in one command:
|
|
106
|
+
omrkit migrate-template old_template.json -o template_v2.json
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Try the real-world hand-marked Turkish 50-question mobile scans too:
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
omrkit scan examples/turkish_exam_50q/scans \
|
|
113
|
+
-t examples/turkish_exam_50q/template.json \
|
|
114
|
+
-o outputs/turkish_demo
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### 4. Launch Visual Web Studio & REST API
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
omrkit studio
|
|
121
|
+
# Web Studio: http://127.0.0.1:8000
|
|
122
|
+
# OpenAPI Docs: http://127.0.0.1:8000/docs
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
## Python SDK
|
|
128
|
+
|
|
129
|
+
Integrate optical scanning, grading, and psychometrics in 10 lines of typed Python:
|
|
130
|
+
|
|
131
|
+
```python
|
|
132
|
+
from omrkit import AnswerKey, ExamGrader, GradingPolicy, OMRScanner, Template
|
|
133
|
+
|
|
134
|
+
template = Template.from_file("examples/standard_mcq_40q/template.json")
|
|
135
|
+
scanner = OMRScanner(template)
|
|
136
|
+
|
|
137
|
+
batch = scanner.scan_batch("examples/standard_mcq_40q/scans", workers=4)
|
|
138
|
+
|
|
139
|
+
key = AnswerKey.from_file("examples/standard_mcq_40q/answer_key.json")
|
|
140
|
+
report = ExamGrader(key, GradingPolicy.preset("yks_tyt")).grade_batch(batch.sheets)
|
|
141
|
+
|
|
142
|
+
print(f"Graded {report.analytics.student_count} sheets | Mean: {report.analytics.mean_score}")
|
|
143
|
+
print(f"KR-20 Reliability: {report.analytics.kr20_reliability}")
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## Architecture
|
|
149
|
+
|
|
150
|
+
```mermaid
|
|
151
|
+
flowchart LR
|
|
152
|
+
A["Images / Multi-Page PDF"] --> B["EXIF Auto-Orient + PDFium Loader"]
|
|
153
|
+
B --> C["5-Mode Registration: ArUco / Markers / PageQuad / ORB / Direct"]
|
|
154
|
+
C --> D["Shadow & Illumination Normalization"]
|
|
155
|
+
D --> E["Hybrid Bubble Detector (Fill + Ring Contrast + Ink Stroke)"]
|
|
156
|
+
E --> F{"Confidence & Validator Check"}
|
|
157
|
+
F -- "High Confidence" --> G["ExamGrader + CTT Psychometrics"]
|
|
158
|
+
F -- "Low Conf / Multi-Mark / Bad Checksum" --> H["HITL Review Queue (Web Studio)"]
|
|
159
|
+
H --> G
|
|
160
|
+
G --> I["CSV / JSON / Multi-Sheet Excel / PDF Scorecards / Overlays"]
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
### Key Technical Features
|
|
164
|
+
- **5 Registration Engines:** `aruco` (instant 0/90/180/270° recovery), `markers` (multi-scale concentric markers with template-structure orientation recovery), `page_quad` (borderless page contour), `homography` (ORB + RANSAC), and `none` (flatbed).
|
|
165
|
+
- **Shape-Aware Hybrid Bubble Classifier:** Evaluates inner circular fill ratio, 75th-percentile local ring contrast (immune to printed borders/numbers), and dark ink stroke density so pen checkmarks (`✓`) and crosses (`✗`) read accurately while smudges and multi-marks route to the HITL review queue.
|
|
166
|
+
- **Built-in Field Validators:** Algorithmic **Turkish TC Kimlik No** (11-digit mod-10/11), **Luhn**, `digits`, and `non_empty` validators flag misread IDs automatically.
|
|
167
|
+
- **Classical Test Theory (CTT) Psychometrics:** Mean, median, standard deviation, percentiles, per-item difficulty ($p$), upper/lower 27% discrimination index ($D$), option distractor distribution, and **KR-20** internal consistency reliability.
|
|
168
|
+
- **Grading Policies:** Standard, Turkish **YKS/TYT & KPSS** (4 wrong = -1 correct), **LGS** (3 wrong = -1 correct), multi-booklet (`A/B/C/D`), bonus/cancelled questions, and weighted sections.
|
|
169
|
+
- **Privacy Utility:** `omrkit strip-exif <dir> -o <clean_dir>` permanently bakes EXIF orientation into pixels and removes GPS/device metadata.
|
|
170
|
+
|
|
171
|
+
---
|
|
172
|
+
|
|
173
|
+
## Reproducible Benchmarks
|
|
174
|
+
|
|
175
|
+
Run `omrkit benchmark --samples 5` on your own machine to reproduce:
|
|
176
|
+
|
|
177
|
+
| Scenario (`standard_mcq_40`, 245 fields/scenario) | Accuracy | Avg Confidence | False HITL Flags | Single-Thread Throughput |
|
|
178
|
+
| :--- | :---: | :---: | :---: | :---: |
|
|
179
|
+
| Clean Flatbed Scan (Solid Fill) | **100.00%** | 99.2% | 0 | **~530 OMR/min** |
|
|
180
|
+
| Mobile Perspective + Uneven Shadow | **100.00%** | 99.2% | 0 | **~310 OMR/min** |
|
|
181
|
+
| Rotated 90° / 180° / 270° + Perspective | **100.00%** | 99.2% | 0 | **~415 OMR/min** |
|
|
182
|
+
| Pen Checkmarks (`✓`) + Shadow | **100.00%** | 99.1% | 0 | **~440 OMR/min** |
|
|
183
|
+
|
|
184
|
+
*(Multi-process batch mode via `--workers N` scales linearly across CPU cores.)*
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## Web Studio & REST API
|
|
189
|
+
|
|
190
|
+
OMRKit Studio ships pre-bundled inside the Python package and launches via `omrkit studio` or `docker compose up` (includes a **Try Demo** button in the header for instant 1-click exploration):
|
|
191
|
+
|
|
192
|
+
1. **Scan & Review (HITL):** Drag-and-drop JPG/PNG/PDF batches with explicit template or **QR Auto-Detect**, inspect zoomable color-coded verification overlays, resolve flagged bubbles with 1-click overrides, and export CSV/Excel.
|
|
193
|
+
2. **Live Camera:** Real-time browser webcam / smartphone camera viewfinder (`getUserMedia`) with **Auto-Lock** corner capture, audio confirmation, and QR template recognition.
|
|
194
|
+
3. **Template Designer:** Upload any blank optical form image or PDF, click **Auto-Detect Grids** to find circular bubble blocks automatically, import legacy `OMRChecker` templates (**Migrate v1**), or draw blocks directly on the HTML5 canvas.
|
|
195
|
+
4. **Sheet Generator:** Customize title, question count (5–120), option labels, booklet selector, and ID grids; preview live and download a ready-to-print ZIP bundle (`PDF + template.json + answer_key.json`).
|
|
196
|
+
5. **Grading & Analytics:** Inline answer-key editor, scoring policy selector, score histogram, student scoreboard with per-student **PDF Scorecards**, and full CTT item psychometrics.
|
|
197
|
+
|
|
198
|
+
### REST API Endpoints
|
|
199
|
+
- `GET /api/health` · `GET /api/presets`
|
|
200
|
+
- `POST /api/generate` · `POST /api/generate/bundle`
|
|
201
|
+
- `POST /api/templates/validate` · `POST /api/templates/auto-detect` · `POST /api/templates/migrate` · `POST /api/preview-image`
|
|
202
|
+
- `POST /api/scan` *(supports `template_json="auto"`)* · `POST /api/demo/cohort` · `POST /api/grade`
|
|
203
|
+
- `POST /api/export/csv` · `POST /api/export/xlsx` · `POST /api/export/scorecard`
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## Development
|
|
208
|
+
|
|
209
|
+
```bash
|
|
210
|
+
uv venv .venv
|
|
211
|
+
uv pip install --python .venv/bin/python -e ".[all,dev]"
|
|
212
|
+
|
|
213
|
+
# Python QA
|
|
214
|
+
.venv/bin/ruff check src tests
|
|
215
|
+
.venv/bin/mypy src/omrkit
|
|
216
|
+
.venv/bin/pytest -v --cov=omrkit
|
|
217
|
+
|
|
218
|
+
# Frontend Studio development
|
|
219
|
+
cd studio && npm ci && npm run dev
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
## License
|
|
225
|
+
|
|
226
|
+
Released under the [MIT License](LICENSE). Copyright © 2026 Duhan Güler & Contributors.
|