omrkit 2.1.1__tar.gz → 2.2.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.1 → omrkit-2.2.0}/PKG-INFO +51 -46
- omrkit-2.2.0/README.md +233 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/pyproject.toml +1 -1
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/_version.py +1 -1
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/api/routes.py +48 -2
- omrkit-2.2.0/src/omrkit/api/static/assets/index-DPM1YTLN.js +249 -0
- omrkit-2.2.0/src/omrkit/api/static/assets/index-fkgIgDbH.css +1 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/api/static/index.html +4 -4
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/core/scanner.py +4 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/generator/pdf_sheet.py +26 -21
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/generator/presets.py +11 -6
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/io/exporters.py +22 -19
- omrkit-2.2.0/src/omrkit/io/pdf_fonts.py +89 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/models/template.py +3 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/vision/detector.py +115 -10
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/vision/grid_finder.py +49 -1
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/vision/registration.py +90 -22
- omrkit-2.1.1/README.md +0 -228
- omrkit-2.1.1/src/omrkit/api/static/assets/index-DJfyticU.js +0 -224
- omrkit-2.1.1/src/omrkit/api/static/assets/index-qnvuF9WA.css +0 -1
- {omrkit-2.1.1 → omrkit-2.2.0}/.gitignore +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/LICENSE +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/__init__.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/__main__.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/api/__init__.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/api/app.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/api/settings.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/cli/__init__.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/cli/app.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/core/__init__.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/core/auto_scanner.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/core/benchmark.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/core/migrator.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/core/validators.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/generator/__init__.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/grading/__init__.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/grading/analytics.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/grading/grader.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/io/__init__.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/io/loader.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/models/__init__.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/models/grading.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/models/scan.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/py.typed +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/vision/__init__.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/vision/preprocess.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/vision/qr.py +0 -0
- {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/vision/visualizer.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: omrkit
|
|
3
|
-
Version: 2.
|
|
3
|
+
Version: 2.2.0
|
|
4
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
5
|
Project-URL: Homepage, https://github.com/duhanguler/omr
|
|
6
6
|
Project-URL: Live Demo, https://omrkit-studio.onrender.com/
|
|
@@ -59,42 +59,45 @@ Description-Content-Type: text/markdown
|
|
|
59
59
|
|
|
60
60
|
<div align="center">
|
|
61
61
|
|
|
62
|
-
# OMRKit v2.
|
|
62
|
+
# OMRKit v2.2
|
|
63
63
|
|
|
64
|
-
**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
|
|
64
|
+
**Zero-calibration Optical Mark Recognition engine with 3-of-4 occluded ArUco recovery, erased-smudge resilience, photocopy drift micro-alignment, QR auto-template detection, blank-form auto-grid finder, live browser camera scanner, printable Unicode ArUco sheet generator, Classical Test Theory psychometrics, FastAPI REST API, and 6-language Web Studio.**
|
|
65
65
|
|
|
66
66
|
[](https://github.com/duhanguler/omr/actions/workflows/ci.yml)
|
|
67
|
-
[](https://pypi.org/project/omrkit/)
|
|
68
|
+
[](https://omrkit-studio.onrender.com/)
|
|
69
|
+
[](https://github.com/duhanguler/omr/releases)
|
|
70
|
+
[](LICENSE)
|
|
71
|
+
[](pyproject.toml)
|
|
72
72
|
[](https://github.com/duhanguler/omr/pkgs/container/omr)
|
|
73
73
|
|
|
74
|
-
[**
|
|
74
|
+
[**Live Demo**](https://omrkit-studio.onrender.com/) · [**PyPI**](https://pypi.org/project/omrkit/) · [Deployment Guide](docs/DEPLOYMENT.md) · [Examples](examples/) · [Contributing](CONTRIBUTING.md)
|
|
75
|
+
|
|
76
|
+
**English** · [Türkçe](README.tr.md) · [简体中文](README.zh.md) · [Deutsch](README.de.md) · [Русский](README.ru.md) · [Español](README.es.md)
|
|
75
77
|
|
|
76
78
|
</div>
|
|
77
79
|
|
|
78
|
-
> **Live Web Studio
|
|
80
|
+
> **Live Web Studio:** Open **[omrkit-studio.onrender.com](https://omrkit-studio.onrender.com/)** directly in your browser (supports **EN · TR · ZH · DE · RU · ES**) — click **Sample Cohort** in the top bar to scan & grade 5 optical sheets, triage flagged bubbles with keyboard shortcuts (`A–E`, `Backspace`, `↑↓`), test **Live Camera**, or generate printable ArUco + QR sheets. *(Hosted on Render's free tier; cold start takes ~20–30s.)*
|
|
79
81
|
|
|
80
82
|
---
|
|
81
83
|
|
|
82
84
|
## Why OMRKit?
|
|
83
85
|
|
|
84
|
-
Traditional open-source OMR scripts
|
|
86
|
+
Traditional open-source OMR scripts require manual pixel-editing in brittle JSON files, break on rotated photos, fail when a thumb covers a corner fiducial or an eraser leaves a faint smudge, and output unverified CSV dumps. **OMRKit v2.2** handles the full optical grading pipeline in one MIT-licensed toolkit:
|
|
85
87
|
|
|
86
|
-
| Capability | Legacy OMR Scripts | **OMRKit v2.
|
|
88
|
+
| Capability | Legacy OMR Scripts | **OMRKit v2.2** |
|
|
87
89
|
| :--- | :---: | :---: |
|
|
88
|
-
| **Printable PDF
|
|
90
|
+
| **Printable PDF Generator + Exact Template** | Manual JSON pixels | **1-Click Unicode Vector PDF (ArUco + QR) + Exact `template.json`** |
|
|
91
|
+
| **Occluded Corner & Photocopy Drift** | Fails if 1 corner hidden or shifted | **3-of-4 ArUco 12-Point Recovery + ±6px Block Micro-Alignment** |
|
|
92
|
+
| **Erased Pencil Smudges vs. Double Marks** | False multi-mark flags | **Darkness-Dominance Filter (Rejects Smudges, Catches Double Marks)** |
|
|
89
93
|
| **Zero-Template QR Auto-Scanning** | Must pass template manually | **`omrkit scan sheet.jpg` auto-detects template from QR** |
|
|
90
|
-
| **Auto-Detect Grids on
|
|
91
|
-
| **Live Webcam / Mobile Browser Scanner** | Static files only | **Real-
|
|
92
|
-
| **Multi-Page PDF & EXIF
|
|
93
|
-
| **
|
|
94
|
-
| **
|
|
95
|
-
| **
|
|
96
|
-
| **
|
|
97
|
-
| **Legacy `OMRChecker` Template Migration** | Manual rewrite | **`omrkit migrate-template old.json -o new.json`** |
|
|
94
|
+
| **Auto-Detect Grids on Blank Forms** | Measure pixels by hand | **Auto-Deskew (±12°) `omrkit detect-layout` + Interactive Canvas** |
|
|
95
|
+
| **Live Webcam / Mobile Browser Scanner** | Static files only | **Real-Time `getUserMedia` Viewfinder with Auto-Lock** |
|
|
96
|
+
| **Multi-Page PDF & EXIF Orientation** | Single images only | **Native `pypdfium2` + EXIF Auto-Orient** |
|
|
97
|
+
| **Checkmarks (✓), Crosses (✗) & Shadows** | Global intensity only | **Illumination Normalization + Hybrid Fill/Ring/Ink Classifier** |
|
|
98
|
+
| **Confidence & Keyboard HITL Review** | Silent errors in CSV | **Calibrated `0–1` Confidence + Zoomed Bubble Crops + `A–E` Triage** |
|
|
99
|
+
| **Exam Psychometrics & Scorecards** | Basic score sum | **CTT Difficulty ($p$), Discrimination ($D$), KR-20, Excel & Unicode PDF Cards** |
|
|
100
|
+
| **Legacy `OMRChecker` v1 Migration** | Manual rewrite | **`omrkit migrate-template old.json -o new.json`** |
|
|
98
101
|
|
|
99
102
|
---
|
|
100
103
|
|
|
@@ -105,12 +108,12 @@ Traditional open-source OMR scripts force you to hand-edit pixel coordinates in
|
|
|
105
108
|
<td width="54%" align="center">
|
|
106
109
|
<img src="https://raw.githubusercontent.com/duhanguler/omr/main/docs/assets/scan_overlay_demo.jpg" alt="OMRKit real-world phone scan verification overlay" />
|
|
107
110
|
<br />
|
|
108
|
-
<sub><b>Real mobile photo scan:</b> Emerald = confident (including ✓ & ✗ marks), Crimson = multi-marked, Amber = faint marks queued for
|
|
111
|
+
<sub><b>Real mobile photo scan:</b> Emerald = confident (including ✓ & ✗ marks), Crimson = multi-marked, Amber = faint marks queued for zoomed HITL keyboard review.</sub>
|
|
109
112
|
</td>
|
|
110
113
|
<td width="46%" align="center">
|
|
111
114
|
<img src="https://raw.githubusercontent.com/duhanguler/omr/main/docs/assets/generated_sheet_preview.jpg" alt="OMRKit generated ArUco + QR optical answer sheet" />
|
|
112
115
|
<br />
|
|
113
|
-
<sub><b>Zero-calibration generated PDF:</b> Vector A4/Letter layout with ArUco corners [0,1,2,3],
|
|
116
|
+
<sub><b>Zero-calibration generated PDF:</b> Vector A4/Letter layout with native Unicode typography, ArUco corners [0,1,2,3], QR badge, and companion <code>template.json</code>.</sub>
|
|
114
117
|
</td>
|
|
115
118
|
</tr>
|
|
116
119
|
</table>
|
|
@@ -124,14 +127,14 @@ Traditional open-source OMR scripts force you to hand-edit pixel coordinates in
|
|
|
124
127
|
```bash
|
|
125
128
|
# Option A: Install from PyPI (recommended)
|
|
126
129
|
pip install omrkit # Core CV engine + PDF + ArUco/QR + Sheet Generator + CLI
|
|
127
|
-
pip install "omrkit[all]" # Full platform: adds Web Studio, FastAPI REST API & Excel
|
|
130
|
+
pip install "omrkit[all]" # Full platform: adds 6-language Web Studio, FastAPI REST API & Excel
|
|
128
131
|
|
|
129
|
-
# Option B: Prebuilt official Docker image (zero build
|
|
132
|
+
# Option B: Prebuilt official Docker image (zero build)
|
|
130
133
|
docker run -p 8000:8000 ghcr.io/duhanguler/omr:latest
|
|
131
134
|
```
|
|
132
135
|
|
|
133
136
|
- **Live Public Demo:** [https://omrkit-studio.onrender.com/](https://omrkit-studio.onrender.com/) (OpenAPI docs at [`/docs`](https://omrkit-studio.onrender.com/docs))
|
|
134
|
-
- **Self-Host
|
|
137
|
+
- **Self-Host (1-Click Render Blueprint):** [](https://dashboard.render.com/blueprint/new?repo=https://github.com/duhanguler/omr) · See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for GHCR & cloud deployment details.
|
|
135
138
|
|
|
136
139
|
### 2. Generate a Print-Ready ArUco + QR Sheet
|
|
137
140
|
|
|
@@ -143,7 +146,7 @@ omrkit generate --preset standard_mcq_40 -o my_exam
|
|
|
143
146
|
Built-in presets (`omrkit generate --list`):
|
|
144
147
|
- `quick_quiz_20` — 20 questions (A–D), 6-digit Student ID
|
|
145
148
|
- `standard_mcq_40` — 40 questions (A–E), 8-digit Student ID, Booklet (A–D)
|
|
146
|
-
- `turkish_exam_50` — 50 questions (A–E), 6-digit Sınav Kodu, 11-digit **TC Kimlik No** (
|
|
149
|
+
- `turkish_exam_50` — 50 questions (A–E), native Turkish Unicode headings, 6-digit Sınav Kodu, 11-digit **TC Kimlik No** (checksum validated), Booklet
|
|
147
150
|
- `turkish_yks_120` — 120-question YKS / TYT layout (4 columns × 30 rows)
|
|
148
151
|
|
|
149
152
|
### 3. Scan Images or Multi-Page PDFs (Explicit or Zero-Template QR Auto-Scan)
|
|
@@ -160,14 +163,14 @@ omrkit scan examples/standard_mcq_40q/scans \
|
|
|
160
163
|
--format csv,json,xlsx,scorecards \
|
|
161
164
|
-o outputs/demo
|
|
162
165
|
|
|
163
|
-
# Auto-detect bubble grids from ANY
|
|
166
|
+
# Auto-detect bubble grids from ANY blank form (with automatic ±12° deskew):
|
|
164
167
|
omrkit detect-layout examples/turkish_exam_50q/blank_form.jpg -o auto_template.json
|
|
165
168
|
|
|
166
169
|
# Migrate a legacy OMRChecker v1 template.json in one command:
|
|
167
170
|
omrkit migrate-template old_template.json -o template_v2.json
|
|
168
171
|
```
|
|
169
172
|
|
|
170
|
-
Try the real-world hand-marked Turkish 50-question mobile scans
|
|
173
|
+
Try the real-world hand-marked Turkish 50-question mobile scans:
|
|
171
174
|
|
|
172
175
|
```bash
|
|
173
176
|
omrkit scan examples/turkish_exam_50q/scans \
|
|
@@ -211,23 +214,23 @@ print(f"KR-20 Reliability: {report.analytics.kr20_reliability}")
|
|
|
211
214
|
```mermaid
|
|
212
215
|
flowchart LR
|
|
213
216
|
A["Images / Multi-Page PDF"] --> B["EXIF Auto-Orient + PDFium Loader"]
|
|
214
|
-
B --> C["5-Mode Registration: ArUco / Markers /
|
|
215
|
-
C --> D["Shadow
|
|
216
|
-
D --> E["Hybrid Bubble Detector (Fill + Ring
|
|
217
|
+
B --> C["5-Mode Registration: ArUco (4pt / 3pt Recovery) / Markers / Quad / ORB / Direct"]
|
|
218
|
+
C --> D["Shadow Normalization + Block Micro-Alignment (±6px)"]
|
|
219
|
+
D --> E["Hybrid Bubble Detector (Fill + Ring + Ink + Smudge Filter)"]
|
|
217
220
|
E --> F{"Confidence & Validator Check"}
|
|
218
221
|
F -- "High Confidence" --> G["ExamGrader + CTT Psychometrics"]
|
|
219
|
-
F -- "Low Conf / Multi-Mark / Bad Checksum" --> H["HITL Review Queue (
|
|
222
|
+
F -- "Low Conf / Multi-Mark / Bad Checksum" --> H["HITL Review Queue (Zoomed Crops + Keyboard Triage)"]
|
|
220
223
|
H --> G
|
|
221
|
-
G --> I["CSV / JSON / Multi-Sheet Excel / PDF Scorecards / Overlays"]
|
|
224
|
+
G --> I["CSV / JSON / Multi-Sheet Excel / Unicode PDF Scorecards / Overlays"]
|
|
222
225
|
```
|
|
223
226
|
|
|
224
227
|
### Key Technical Features
|
|
225
|
-
- **5 Registration
|
|
226
|
-
- **
|
|
228
|
+
- **Resilient 5-Mode Registration:** `aruco` with 0°/90°/180°/270° recovery **plus 3-of-4 occluded corner 12-point homography (`aruco_3pt`)**, `markers` (multi-scale concentric markers), `page_quad` (borderless contour with polar corner ordering), `homography` (ORB + RANSAC), and `none` (flatbed).
|
|
229
|
+
- **Photocopy Micro-Alignment & Smudge-Safe Detector:** Per-block Sobel rim correlation snaps misaligned photocopies (`±6px`) back onto exact bubble centers. Hybrid inner fill + 75th-percentile ring contrast + ink stroke scoring + darkness-dominance smudge rejection reads checkmarks (`✓`), crosses (`✗`), and light pencil marks cleanly while flagging true double marks.
|
|
227
230
|
- **Built-in Field Validators:** Algorithmic **Turkish TC Kimlik No** (11-digit mod-10/11), **Luhn**, `digits`, and `non_empty` validators flag misread IDs automatically.
|
|
228
|
-
- **Classical Test Theory (CTT) Psychometrics:** Mean, median, standard deviation, percentiles,
|
|
229
|
-
- **Grading Policies:** Standard,
|
|
230
|
-
- **Privacy Utility:** `omrkit strip-exif <dir> -o <clean_dir>`
|
|
231
|
+
- **Classical Test Theory (CTT) Psychometrics:** Mean, median, standard deviation, percentiles, item difficulty ($p$), upper/lower 27% discrimination index ($D$), distractor distribution, and **KR-20** reliability.
|
|
232
|
+
- **Grading Policies & Native Unicode PDFs:** Standard, **YKS/TYT & KPSS** (4 wrong = -1 correct), **LGS** (3 wrong = -1 correct), multi-booklet (`A/B/C/D`), bonus/cancelled items, weighted sections, and automatic TrueType Unicode font discovery (`LiberationSans` / `DejaVuSans`) for generated sheets and student scorecards.
|
|
233
|
+
- **Privacy Utility:** `omrkit strip-exif <dir> -o <clean_dir>` bakes EXIF orientation into pixels and strips GPS/device metadata.
|
|
231
234
|
|
|
232
235
|
---
|
|
233
236
|
|
|
@@ -241,6 +244,8 @@ Run `omrkit benchmark --samples 5` on your own machine to reproduce:
|
|
|
241
244
|
| Mobile Perspective + Uneven Shadow | **100.00%** | 99.2% | 0 | **~310 OMR/min** |
|
|
242
245
|
| Rotated 90° / 180° / 270° + Perspective | **100.00%** | 99.2% | 0 | **~415 OMR/min** |
|
|
243
246
|
| Pen Checkmarks (`✓`) + Shadow | **100.00%** | 99.1% | 0 | **~440 OMR/min** |
|
|
247
|
+
| **v2.2** Erased Smudge (`tone=170`) + Dark Fill (`tone=45`) | **100.00%** | 98.4% | 0 | **~490 OMR/min** |
|
|
248
|
+
| **v2.2** 1-of-4 Occluded ArUco + 90° Rotation + Skew | **100.00%** | 99.1% | 0 | **~360 OMR/min** |
|
|
244
249
|
|
|
245
250
|
*(Multi-process batch mode via `--workers N` scales linearly across CPU cores.)*
|
|
246
251
|
|
|
@@ -248,19 +253,19 @@ Run `omrkit benchmark --samples 5` on your own machine to reproduce:
|
|
|
248
253
|
|
|
249
254
|
## Web Studio & REST API
|
|
250
255
|
|
|
251
|
-
OMRKit Studio ships pre-bundled inside the Python package
|
|
256
|
+
OMRKit Studio ships pre-bundled inside the Python package in **6 languages (`EN · TR · ZH · DE · RU · ES`)** and launches via `omrkit studio` or `docker run`:
|
|
252
257
|
|
|
253
|
-
1. **Scan & Review (HITL):**
|
|
254
|
-
2. **Live Camera:**
|
|
255
|
-
3. **Template Designer:** Upload any blank optical form image or PDF,
|
|
256
|
-
4. **Sheet Generator:**
|
|
257
|
-
5. **Grading & Analytics:**
|
|
258
|
+
1. **Scan & Review (HITL):** Drop JPG/PNG/PDF batches with explicit template or **QR Auto-Detect**, inspect zoomed color-coded verification overlays with live bounding-box reticles, view magnified bubble-strip crops inside each flagged card, and resolve flags rapidly with keyboard shortcuts (`A–E`, `Backspace`, `↑↓`).
|
|
259
|
+
2. **Live Camera:** Browser webcam / smartphone viewfinder (`getUserMedia`) with **Auto-Lock** corner capture, live resolution readout, audio confirmation, and QR recognition.
|
|
260
|
+
3. **Template Designer:** Upload any blank optical form image or PDF, run **Auto-Detect Grids** (auto-deskewing up to ±12°), migrate legacy `OMRChecker` v1 JSONs, click-drag blocks directly on canvas, micro-nudge with arrow keys (`1px` / `Shift 10px`), and undo/redo cleanly (`Ctrl+Z` / `Ctrl+Shift+Z`).
|
|
261
|
+
4. **Sheet Generator:** Configure title, questions (5–120), option labels, booklet selector, and ID grids; inspect live print-spec telemetry, print directly (**Print PDF**), or download the ZIP bundle (`PDF + template.json + answer_key.json`).
|
|
262
|
+
5. **Grading & Analytics:** Multi-booklet inline answer-key editor, scoring policy selector, hover-interactive score histogram, sortable student scoreboard with Unicode **PDF Scorecards**, and filterable CTT psychometrics with inline option-distribution micro-bars.
|
|
258
263
|
|
|
259
264
|
### REST API Endpoints
|
|
260
265
|
- `GET /api/health` · `GET /api/presets`
|
|
261
266
|
- `POST /api/generate` · `POST /api/generate/bundle`
|
|
262
267
|
- `POST /api/templates/validate` · `POST /api/templates/auto-detect` · `POST /api/templates/migrate` · `POST /api/preview-image`
|
|
263
|
-
- `POST /api/scan` *(supports `template_json="auto"`)* · `POST /api/demo/cohort` · `POST /api/grade`
|
|
268
|
+
- `POST /api/scan` *(supports `template_json="auto"`, returns `overlays`, `review_crops`, `sheet_dimensions`)* · `POST /api/demo/cohort` · `POST /api/grade`
|
|
264
269
|
- `POST /api/export/csv` · `POST /api/export/xlsx` · `POST /api/export/scorecard`
|
|
265
270
|
|
|
266
271
|
---
|
omrkit-2.2.0/README.md
ADDED
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# OMRKit v2.2
|
|
4
|
+
|
|
5
|
+
**Zero-calibration Optical Mark Recognition engine with 3-of-4 occluded ArUco recovery, erased-smudge resilience, photocopy drift micro-alignment, QR auto-template detection, blank-form auto-grid finder, live browser camera scanner, printable Unicode ArUco sheet generator, Classical Test Theory psychometrics, FastAPI REST API, and 6-language Web Studio.**
|
|
6
|
+
|
|
7
|
+
[](https://github.com/duhanguler/omr/actions/workflows/ci.yml)
|
|
8
|
+
[](https://pypi.org/project/omrkit/)
|
|
9
|
+
[](https://omrkit-studio.onrender.com/)
|
|
10
|
+
[](https://github.com/duhanguler/omr/releases)
|
|
11
|
+
[](LICENSE)
|
|
12
|
+
[](pyproject.toml)
|
|
13
|
+
[](https://github.com/duhanguler/omr/pkgs/container/omr)
|
|
14
|
+
|
|
15
|
+
[**Live Demo**](https://omrkit-studio.onrender.com/) · [**PyPI**](https://pypi.org/project/omrkit/) · [Deployment Guide](docs/DEPLOYMENT.md) · [Examples](examples/) · [Contributing](CONTRIBUTING.md)
|
|
16
|
+
|
|
17
|
+
**English** · [Türkçe](README.tr.md) · [简体中文](README.zh.md) · [Deutsch](README.de.md) · [Русский](README.ru.md) · [Español](README.es.md)
|
|
18
|
+
|
|
19
|
+
</div>
|
|
20
|
+
|
|
21
|
+
> **Live Web Studio:** Open **[omrkit-studio.onrender.com](https://omrkit-studio.onrender.com/)** directly in your browser (supports **EN · TR · ZH · DE · RU · ES**) — click **Sample Cohort** in the top bar to scan & grade 5 optical sheets, triage flagged bubbles with keyboard shortcuts (`A–E`, `Backspace`, `↑↓`), test **Live Camera**, or generate printable ArUco + QR sheets. *(Hosted on Render's free tier; cold start takes ~20–30s.)*
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## Why OMRKit?
|
|
26
|
+
|
|
27
|
+
Traditional open-source OMR scripts require manual pixel-editing in brittle JSON files, break on rotated photos, fail when a thumb covers a corner fiducial or an eraser leaves a faint smudge, and output unverified CSV dumps. **OMRKit v2.2** handles the full optical grading pipeline in one MIT-licensed toolkit:
|
|
28
|
+
|
|
29
|
+
| Capability | Legacy OMR Scripts | **OMRKit v2.2** |
|
|
30
|
+
| :--- | :---: | :---: |
|
|
31
|
+
| **Printable PDF Generator + Exact Template** | Manual JSON pixels | **1-Click Unicode Vector PDF (ArUco + QR) + Exact `template.json`** |
|
|
32
|
+
| **Occluded Corner & Photocopy Drift** | Fails if 1 corner hidden or shifted | **3-of-4 ArUco 12-Point Recovery + ±6px Block Micro-Alignment** |
|
|
33
|
+
| **Erased Pencil Smudges vs. Double Marks** | False multi-mark flags | **Darkness-Dominance Filter (Rejects Smudges, Catches Double Marks)** |
|
|
34
|
+
| **Zero-Template QR Auto-Scanning** | Must pass template manually | **`omrkit scan sheet.jpg` auto-detects template from QR** |
|
|
35
|
+
| **Auto-Detect Grids on Blank Forms** | Measure pixels by hand | **Auto-Deskew (±12°) `omrkit detect-layout` + Interactive Canvas** |
|
|
36
|
+
| **Live Webcam / Mobile Browser Scanner** | Static files only | **Real-Time `getUserMedia` Viewfinder with Auto-Lock** |
|
|
37
|
+
| **Multi-Page PDF & EXIF Orientation** | Single images only | **Native `pypdfium2` + EXIF Auto-Orient** |
|
|
38
|
+
| **Checkmarks (✓), Crosses (✗) & Shadows** | Global intensity only | **Illumination Normalization + Hybrid Fill/Ring/Ink Classifier** |
|
|
39
|
+
| **Confidence & Keyboard HITL Review** | Silent errors in CSV | **Calibrated `0–1` Confidence + Zoomed Bubble Crops + `A–E` Triage** |
|
|
40
|
+
| **Exam Psychometrics & Scorecards** | Basic score sum | **CTT Difficulty ($p$), Discrimination ($D$), KR-20, Excel & Unicode PDF Cards** |
|
|
41
|
+
| **Legacy `OMRChecker` v1 Migration** | Manual rewrite | **`omrkit migrate-template old.json -o new.json`** |
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## Real-World Detection & Generated Sheets
|
|
46
|
+
|
|
47
|
+
<table>
|
|
48
|
+
<tr>
|
|
49
|
+
<td width="54%" align="center">
|
|
50
|
+
<img src="https://raw.githubusercontent.com/duhanguler/omr/main/docs/assets/scan_overlay_demo.jpg" alt="OMRKit real-world phone scan verification overlay" />
|
|
51
|
+
<br />
|
|
52
|
+
<sub><b>Real mobile photo scan:</b> Emerald = confident (including ✓ & ✗ marks), Crimson = multi-marked, Amber = faint marks queued for zoomed HITL keyboard review.</sub>
|
|
53
|
+
</td>
|
|
54
|
+
<td width="46%" align="center">
|
|
55
|
+
<img src="https://raw.githubusercontent.com/duhanguler/omr/main/docs/assets/generated_sheet_preview.jpg" alt="OMRKit generated ArUco + QR optical answer sheet" />
|
|
56
|
+
<br />
|
|
57
|
+
<sub><b>Zero-calibration generated PDF:</b> Vector A4/Letter layout with native Unicode typography, ArUco corners [0,1,2,3], QR badge, and companion <code>template.json</code>.</sub>
|
|
58
|
+
</td>
|
|
59
|
+
</tr>
|
|
60
|
+
</table>
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## Quickstart (60 Seconds)
|
|
65
|
+
|
|
66
|
+
### 1. Install from PyPI, Run via Docker, or Try Online
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
# Option A: Install from PyPI (recommended)
|
|
70
|
+
pip install omrkit # Core CV engine + PDF + ArUco/QR + Sheet Generator + CLI
|
|
71
|
+
pip install "omrkit[all]" # Full platform: adds 6-language Web Studio, FastAPI REST API & Excel
|
|
72
|
+
|
|
73
|
+
# Option B: Prebuilt official Docker image (zero build)
|
|
74
|
+
docker run -p 8000:8000 ghcr.io/duhanguler/omr:latest
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
- **Live Public Demo:** [https://omrkit-studio.onrender.com/](https://omrkit-studio.onrender.com/) (OpenAPI docs at [`/docs`](https://omrkit-studio.onrender.com/docs))
|
|
78
|
+
- **Self-Host (1-Click Render Blueprint):** [](https://dashboard.render.com/blueprint/new?repo=https://github.com/duhanguler/omr) · See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for GHCR & cloud deployment details.
|
|
79
|
+
|
|
80
|
+
### 2. Generate a Print-Ready ArUco + QR Sheet
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
omrkit generate --preset standard_mcq_40 -o my_exam
|
|
84
|
+
# Writes: standard_mcq_40_sheet.pdf, template.json, answer_key.json
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Built-in presets (`omrkit generate --list`):
|
|
88
|
+
- `quick_quiz_20` — 20 questions (A–D), 6-digit Student ID
|
|
89
|
+
- `standard_mcq_40` — 40 questions (A–E), 8-digit Student ID, Booklet (A–D)
|
|
90
|
+
- `turkish_exam_50` — 50 questions (A–E), native Turkish Unicode headings, 6-digit Sınav Kodu, 11-digit **TC Kimlik No** (checksum validated), Booklet
|
|
91
|
+
- `turkish_yks_120` — 120-question YKS / TYT layout (4 columns × 30 rows)
|
|
92
|
+
|
|
93
|
+
### 3. Scan Images or Multi-Page PDFs (Explicit or Zero-Template QR Auto-Scan)
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
# Zero-template QR auto-detection on generated sheets:
|
|
97
|
+
omrkit scan examples/standard_mcq_40q/scans -o outputs/auto_demo
|
|
98
|
+
|
|
99
|
+
# Explicit template + YKS/TYT negative marking + Excel & PDF scorecards:
|
|
100
|
+
omrkit scan examples/standard_mcq_40q/scans \
|
|
101
|
+
-t examples/standard_mcq_40q/template.json \
|
|
102
|
+
-k examples/standard_mcq_40q/answer_key.json \
|
|
103
|
+
--policy yks_tyt \
|
|
104
|
+
--format csv,json,xlsx,scorecards \
|
|
105
|
+
-o outputs/demo
|
|
106
|
+
|
|
107
|
+
# Auto-detect bubble grids from ANY blank form (with automatic ±12° deskew):
|
|
108
|
+
omrkit detect-layout examples/turkish_exam_50q/blank_form.jpg -o auto_template.json
|
|
109
|
+
|
|
110
|
+
# Migrate a legacy OMRChecker v1 template.json in one command:
|
|
111
|
+
omrkit migrate-template old_template.json -o template_v2.json
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Try the real-world hand-marked Turkish 50-question mobile scans:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
omrkit scan examples/turkish_exam_50q/scans \
|
|
118
|
+
-t examples/turkish_exam_50q/template.json \
|
|
119
|
+
-o outputs/turkish_demo
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### 4. Launch Visual Web Studio & REST API
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
omrkit studio
|
|
126
|
+
# Web Studio: http://127.0.0.1:8000
|
|
127
|
+
# OpenAPI Docs: http://127.0.0.1:8000/docs
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## Python SDK
|
|
133
|
+
|
|
134
|
+
Integrate optical scanning, grading, and psychometrics in 10 lines of typed Python:
|
|
135
|
+
|
|
136
|
+
```python
|
|
137
|
+
from omrkit import AnswerKey, ExamGrader, GradingPolicy, OMRScanner, Template
|
|
138
|
+
|
|
139
|
+
template = Template.from_file("examples/standard_mcq_40q/template.json")
|
|
140
|
+
scanner = OMRScanner(template)
|
|
141
|
+
|
|
142
|
+
batch = scanner.scan_batch("examples/standard_mcq_40q/scans", workers=4)
|
|
143
|
+
|
|
144
|
+
key = AnswerKey.from_file("examples/standard_mcq_40q/answer_key.json")
|
|
145
|
+
report = ExamGrader(key, GradingPolicy.preset("yks_tyt")).grade_batch(batch.sheets)
|
|
146
|
+
|
|
147
|
+
print(f"Graded {report.analytics.student_count} sheets | Mean: {report.analytics.mean_score}")
|
|
148
|
+
print(f"KR-20 Reliability: {report.analytics.kr20_reliability}")
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## Architecture
|
|
154
|
+
|
|
155
|
+
```mermaid
|
|
156
|
+
flowchart LR
|
|
157
|
+
A["Images / Multi-Page PDF"] --> B["EXIF Auto-Orient + PDFium Loader"]
|
|
158
|
+
B --> C["5-Mode Registration: ArUco (4pt / 3pt Recovery) / Markers / Quad / ORB / Direct"]
|
|
159
|
+
C --> D["Shadow Normalization + Block Micro-Alignment (±6px)"]
|
|
160
|
+
D --> E["Hybrid Bubble Detector (Fill + Ring + Ink + Smudge Filter)"]
|
|
161
|
+
E --> F{"Confidence & Validator Check"}
|
|
162
|
+
F -- "High Confidence" --> G["ExamGrader + CTT Psychometrics"]
|
|
163
|
+
F -- "Low Conf / Multi-Mark / Bad Checksum" --> H["HITL Review Queue (Zoomed Crops + Keyboard Triage)"]
|
|
164
|
+
H --> G
|
|
165
|
+
G --> I["CSV / JSON / Multi-Sheet Excel / Unicode PDF Scorecards / Overlays"]
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### Key Technical Features
|
|
169
|
+
- **Resilient 5-Mode Registration:** `aruco` with 0°/90°/180°/270° recovery **plus 3-of-4 occluded corner 12-point homography (`aruco_3pt`)**, `markers` (multi-scale concentric markers), `page_quad` (borderless contour with polar corner ordering), `homography` (ORB + RANSAC), and `none` (flatbed).
|
|
170
|
+
- **Photocopy Micro-Alignment & Smudge-Safe Detector:** Per-block Sobel rim correlation snaps misaligned photocopies (`±6px`) back onto exact bubble centers. Hybrid inner fill + 75th-percentile ring contrast + ink stroke scoring + darkness-dominance smudge rejection reads checkmarks (`✓`), crosses (`✗`), and light pencil marks cleanly while flagging true double marks.
|
|
171
|
+
- **Built-in Field Validators:** Algorithmic **Turkish TC Kimlik No** (11-digit mod-10/11), **Luhn**, `digits`, and `non_empty` validators flag misread IDs automatically.
|
|
172
|
+
- **Classical Test Theory (CTT) Psychometrics:** Mean, median, standard deviation, percentiles, item difficulty ($p$), upper/lower 27% discrimination index ($D$), distractor distribution, and **KR-20** reliability.
|
|
173
|
+
- **Grading Policies & Native Unicode PDFs:** Standard, **YKS/TYT & KPSS** (4 wrong = -1 correct), **LGS** (3 wrong = -1 correct), multi-booklet (`A/B/C/D`), bonus/cancelled items, weighted sections, and automatic TrueType Unicode font discovery (`LiberationSans` / `DejaVuSans`) for generated sheets and student scorecards.
|
|
174
|
+
- **Privacy Utility:** `omrkit strip-exif <dir> -o <clean_dir>` bakes EXIF orientation into pixels and strips GPS/device metadata.
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## Reproducible Benchmarks
|
|
179
|
+
|
|
180
|
+
Run `omrkit benchmark --samples 5` on your own machine to reproduce:
|
|
181
|
+
|
|
182
|
+
| Scenario (`standard_mcq_40`, 245 fields/scenario) | Accuracy | Avg Confidence | False HITL Flags | Single-Thread Throughput |
|
|
183
|
+
| :--- | :---: | :---: | :---: | :---: |
|
|
184
|
+
| Clean Flatbed Scan (Solid Fill) | **100.00%** | 99.2% | 0 | **~530 OMR/min** |
|
|
185
|
+
| Mobile Perspective + Uneven Shadow | **100.00%** | 99.2% | 0 | **~310 OMR/min** |
|
|
186
|
+
| Rotated 90° / 180° / 270° + Perspective | **100.00%** | 99.2% | 0 | **~415 OMR/min** |
|
|
187
|
+
| Pen Checkmarks (`✓`) + Shadow | **100.00%** | 99.1% | 0 | **~440 OMR/min** |
|
|
188
|
+
| **v2.2** Erased Smudge (`tone=170`) + Dark Fill (`tone=45`) | **100.00%** | 98.4% | 0 | **~490 OMR/min** |
|
|
189
|
+
| **v2.2** 1-of-4 Occluded ArUco + 90° Rotation + Skew | **100.00%** | 99.1% | 0 | **~360 OMR/min** |
|
|
190
|
+
|
|
191
|
+
*(Multi-process batch mode via `--workers N` scales linearly across CPU cores.)*
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
## Web Studio & REST API
|
|
196
|
+
|
|
197
|
+
OMRKit Studio ships pre-bundled inside the Python package in **6 languages (`EN · TR · ZH · DE · RU · ES`)** and launches via `omrkit studio` or `docker run`:
|
|
198
|
+
|
|
199
|
+
1. **Scan & Review (HITL):** Drop JPG/PNG/PDF batches with explicit template or **QR Auto-Detect**, inspect zoomed color-coded verification overlays with live bounding-box reticles, view magnified bubble-strip crops inside each flagged card, and resolve flags rapidly with keyboard shortcuts (`A–E`, `Backspace`, `↑↓`).
|
|
200
|
+
2. **Live Camera:** Browser webcam / smartphone viewfinder (`getUserMedia`) with **Auto-Lock** corner capture, live resolution readout, audio confirmation, and QR recognition.
|
|
201
|
+
3. **Template Designer:** Upload any blank optical form image or PDF, run **Auto-Detect Grids** (auto-deskewing up to ±12°), migrate legacy `OMRChecker` v1 JSONs, click-drag blocks directly on canvas, micro-nudge with arrow keys (`1px` / `Shift 10px`), and undo/redo cleanly (`Ctrl+Z` / `Ctrl+Shift+Z`).
|
|
202
|
+
4. **Sheet Generator:** Configure title, questions (5–120), option labels, booklet selector, and ID grids; inspect live print-spec telemetry, print directly (**Print PDF**), or download the ZIP bundle (`PDF + template.json + answer_key.json`).
|
|
203
|
+
5. **Grading & Analytics:** Multi-booklet inline answer-key editor, scoring policy selector, hover-interactive score histogram, sortable student scoreboard with Unicode **PDF Scorecards**, and filterable CTT psychometrics with inline option-distribution micro-bars.
|
|
204
|
+
|
|
205
|
+
### REST API Endpoints
|
|
206
|
+
- `GET /api/health` · `GET /api/presets`
|
|
207
|
+
- `POST /api/generate` · `POST /api/generate/bundle`
|
|
208
|
+
- `POST /api/templates/validate` · `POST /api/templates/auto-detect` · `POST /api/templates/migrate` · `POST /api/preview-image`
|
|
209
|
+
- `POST /api/scan` *(supports `template_json="auto"`, returns `overlays`, `review_crops`, `sheet_dimensions`)* · `POST /api/demo/cohort` · `POST /api/grade`
|
|
210
|
+
- `POST /api/export/csv` · `POST /api/export/xlsx` · `POST /api/export/scorecard`
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
214
|
+
## Development
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
uv venv .venv
|
|
218
|
+
uv pip install --python .venv/bin/python -e ".[all,dev]"
|
|
219
|
+
|
|
220
|
+
# Python QA
|
|
221
|
+
.venv/bin/ruff check src tests
|
|
222
|
+
.venv/bin/mypy src/omrkit
|
|
223
|
+
.venv/bin/pytest -v --cov=omrkit
|
|
224
|
+
|
|
225
|
+
# Frontend Studio development
|
|
226
|
+
cd studio && npm ci && npm run dev
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## License
|
|
232
|
+
|
|
233
|
+
Released under the [MIT License](LICENSE). Copyright © 2026 Duhan Güler & Contributors.
|
|
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "omrkit"
|
|
7
|
-
version = "2.
|
|
7
|
+
version = "2.2.0"
|
|
8
8
|
description = "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."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
license = { text = "MIT" }
|
|
@@ -102,6 +102,33 @@ def _encode_overlay(warped_bgr: np.ndarray, result: SheetResult) -> str:
|
|
|
102
102
|
return _encode_image_data_url(annotated, fmt=".jpg", quality=85)
|
|
103
103
|
|
|
104
104
|
|
|
105
|
+
def _extract_review_crops(warped_bgr: np.ndarray, result: SheetResult) -> dict[str, str]:
|
|
106
|
+
"""Extract crisp zoomed JPEG bubble-strip crops for every HITL review item."""
|
|
107
|
+
if not result.review_items:
|
|
108
|
+
return {}
|
|
109
|
+
h, w = warped_bgr.shape[:2]
|
|
110
|
+
crops: dict[str, str] = {}
|
|
111
|
+
for item in result.review_items:
|
|
112
|
+
x1, y1, x2, y2 = item.bbox
|
|
113
|
+
cx1 = max(0, x1 - 10)
|
|
114
|
+
cy1 = max(0, y1 - 8)
|
|
115
|
+
cx2 = min(w, x2 + 10)
|
|
116
|
+
cy2 = min(h, y2 + 8)
|
|
117
|
+
if cx2 - cx1 < 12 or cy2 - cy1 < 12:
|
|
118
|
+
continue
|
|
119
|
+
patch = warped_bgr[cy1:cy2, cx1:cx2]
|
|
120
|
+
ph, pw = patch.shape[:2]
|
|
121
|
+
if max(ph, pw) > 480:
|
|
122
|
+
scale = 480.0 / float(max(ph, pw))
|
|
123
|
+
patch = cv2.resize(
|
|
124
|
+
patch,
|
|
125
|
+
(max(16, round(pw * scale)), max(16, round(ph * scale))),
|
|
126
|
+
interpolation=cv2.INTER_AREA,
|
|
127
|
+
)
|
|
128
|
+
crops[item.field_id] = _encode_image_data_url(patch, fmt=".jpg", quality=88)
|
|
129
|
+
return crops
|
|
130
|
+
|
|
131
|
+
|
|
105
132
|
class GradeRequest(BaseModel):
|
|
106
133
|
"""Request body for grading scanned sheets with an answer key and policy."""
|
|
107
134
|
|
|
@@ -358,6 +385,8 @@ async def scan_uploaded_sheets(
|
|
|
358
385
|
|
|
359
386
|
sheets: list[dict[str, Any]] = []
|
|
360
387
|
overlays: dict[str, str] = {}
|
|
388
|
+
review_crops: dict[str, dict[str, str]] = {}
|
|
389
|
+
sheet_dimensions: dict[str, tuple[int, int]] = {}
|
|
361
390
|
seen_ids: dict[str, int] = {}
|
|
362
391
|
total_elapsed = 0.0
|
|
363
392
|
flagged_count = 0
|
|
@@ -421,8 +450,14 @@ async def scan_uploaded_sheets(
|
|
|
421
450
|
flagged_count += 1
|
|
422
451
|
sheets.append(result.model_dump(mode="json"))
|
|
423
452
|
|
|
424
|
-
if
|
|
425
|
-
|
|
453
|
+
if warped_bgr is not None:
|
|
454
|
+
wh, ww = warped_bgr.shape[:2]
|
|
455
|
+
sheet_dimensions[result.sheet_id] = (ww, wh)
|
|
456
|
+
if include_overlay:
|
|
457
|
+
overlays[result.sheet_id] = _encode_overlay(warped_bgr, result)
|
|
458
|
+
crops = _extract_review_crops(warped_bgr, result)
|
|
459
|
+
if crops:
|
|
460
|
+
review_crops[result.sheet_id] = crops
|
|
426
461
|
|
|
427
462
|
return {
|
|
428
463
|
"template_name": template_name,
|
|
@@ -432,6 +467,8 @@ async def scan_uploaded_sheets(
|
|
|
432
467
|
"total_elapsed_ms": round(total_elapsed, 2),
|
|
433
468
|
"sheets": sheets,
|
|
434
469
|
"overlays": overlays,
|
|
470
|
+
"review_crops": review_crops,
|
|
471
|
+
"sheet_dimensions": sheet_dimensions,
|
|
435
472
|
}
|
|
436
473
|
|
|
437
474
|
|
|
@@ -459,6 +496,8 @@ def run_one_click_demo_cohort(preset_id: str = "quick_quiz_20") -> dict[str, Any
|
|
|
459
496
|
|
|
460
497
|
scanned_sheets: list[SheetResult] = []
|
|
461
498
|
overlays: dict[str, str] = {}
|
|
499
|
+
review_crops: dict[str, dict[str, str]] = {}
|
|
500
|
+
sheet_dimensions: dict[str, tuple[int, int]] = {}
|
|
462
501
|
total_elapsed = 0.0
|
|
463
502
|
|
|
464
503
|
for idx, (sid, skill, rot, persp, shadow, style, inject_hitl) in enumerate(profiles):
|
|
@@ -502,7 +541,12 @@ def run_one_click_demo_cohort(preset_id: str = "quick_quiz_20") -> dict[str, Any
|
|
|
502
541
|
total_elapsed += res.elapsed_ms
|
|
503
542
|
scanned_sheets.append(res)
|
|
504
543
|
if warped is not None:
|
|
544
|
+
wh, ww = warped.shape[:2]
|
|
545
|
+
sheet_dimensions[res.sheet_id] = (ww, wh)
|
|
505
546
|
overlays[res.sheet_id] = _encode_overlay(warped, res)
|
|
547
|
+
crops = _extract_review_crops(warped, res)
|
|
548
|
+
if crops:
|
|
549
|
+
review_crops[res.sheet_id] = crops
|
|
506
550
|
|
|
507
551
|
policy = GradingPolicy.preset("yks_tyt")
|
|
508
552
|
report = ExamGrader(answer_key, policy).grade_batch(scanned_sheets)
|
|
@@ -518,6 +562,8 @@ def run_one_click_demo_cohort(preset_id: str = "quick_quiz_20") -> dict[str, Any
|
|
|
518
562
|
"total_elapsed_ms": round(total_elapsed, 2),
|
|
519
563
|
"sheets": [s.model_dump(mode="json") for s in scanned_sheets],
|
|
520
564
|
"overlays": overlays,
|
|
565
|
+
"review_crops": review_crops,
|
|
566
|
+
"sheet_dimensions": sheet_dimensions,
|
|
521
567
|
},
|
|
522
568
|
"grading_report": report.model_dump(mode="json"),
|
|
523
569
|
}
|