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.
Files changed (48) hide show
  1. {omrkit-2.1.1 → omrkit-2.2.0}/PKG-INFO +51 -46
  2. omrkit-2.2.0/README.md +233 -0
  3. {omrkit-2.1.1 → omrkit-2.2.0}/pyproject.toml +1 -1
  4. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/_version.py +1 -1
  5. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/api/routes.py +48 -2
  6. omrkit-2.2.0/src/omrkit/api/static/assets/index-DPM1YTLN.js +249 -0
  7. omrkit-2.2.0/src/omrkit/api/static/assets/index-fkgIgDbH.css +1 -0
  8. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/api/static/index.html +4 -4
  9. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/core/scanner.py +4 -0
  10. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/generator/pdf_sheet.py +26 -21
  11. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/generator/presets.py +11 -6
  12. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/io/exporters.py +22 -19
  13. omrkit-2.2.0/src/omrkit/io/pdf_fonts.py +89 -0
  14. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/models/template.py +3 -0
  15. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/vision/detector.py +115 -10
  16. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/vision/grid_finder.py +49 -1
  17. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/vision/registration.py +90 -22
  18. omrkit-2.1.1/README.md +0 -228
  19. omrkit-2.1.1/src/omrkit/api/static/assets/index-DJfyticU.js +0 -224
  20. omrkit-2.1.1/src/omrkit/api/static/assets/index-qnvuF9WA.css +0 -1
  21. {omrkit-2.1.1 → omrkit-2.2.0}/.gitignore +0 -0
  22. {omrkit-2.1.1 → omrkit-2.2.0}/LICENSE +0 -0
  23. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/__init__.py +0 -0
  24. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/__main__.py +0 -0
  25. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/api/__init__.py +0 -0
  26. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/api/app.py +0 -0
  27. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/api/settings.py +0 -0
  28. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/cli/__init__.py +0 -0
  29. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/cli/app.py +0 -0
  30. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/core/__init__.py +0 -0
  31. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/core/auto_scanner.py +0 -0
  32. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/core/benchmark.py +0 -0
  33. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/core/migrator.py +0 -0
  34. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/core/validators.py +0 -0
  35. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/generator/__init__.py +0 -0
  36. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/grading/__init__.py +0 -0
  37. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/grading/analytics.py +0 -0
  38. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/grading/grader.py +0 -0
  39. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/io/__init__.py +0 -0
  40. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/io/loader.py +0 -0
  41. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/models/__init__.py +0 -0
  42. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/models/grading.py +0 -0
  43. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/models/scan.py +0 -0
  44. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/py.typed +0 -0
  45. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/vision/__init__.py +0 -0
  46. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/vision/preprocess.py +0 -0
  47. {omrkit-2.1.1 → omrkit-2.2.0}/src/omrkit/vision/qr.py +0 -0
  48. {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.1.1
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.1
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 React Web Studio.**
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
  [![CI](https://github.com/duhanguler/omr/actions/workflows/ci.yml/badge.svg)](https://github.com/duhanguler/omr/actions/workflows/ci.yml)
67
- [![PyPI](https://img.shields.io/pypi/v/omrkit?style=flat-square&color=0F8A5F&logo=pypi&logoColor=white)](https://pypi.org/project/omrkit/)
68
- [![Live Demo](https://img.shields.io/badge/Live_Demo-OMRKit_Studio-1D4ED8?style=flat-square&logo=render&logoColor=white)](https://omrkit-studio.onrender.com/)
69
- [![Release](https://img.shields.io/github/v/release/duhanguler/omr?style=flat-square&color=14181F)](https://github.com/duhanguler/omr/releases)
70
- [![License: MIT](https://img.shields.io/badge/License-MIT-0F8A5F.svg?style=flat-square)](LICENSE)
71
- [![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-14181F.svg?style=flat-square)](pyproject.toml)
67
+ [![PyPI](https://img.shields.io/pypi/v/omrkit?style=flat-square&color=0D7A52&logo=pypi&logoColor=white)](https://pypi.org/project/omrkit/)
68
+ [![Live Demo](https://img.shields.io/badge/Live_Demo-OMRKit_Studio-1849C6?style=flat-square&logo=render&logoColor=white)](https://omrkit-studio.onrender.com/)
69
+ [![Release](https://img.shields.io/github/v/release/duhanguler/omr?style=flat-square&color=111317)](https://github.com/duhanguler/omr/releases)
70
+ [![License: MIT](https://img.shields.io/badge/License-MIT-0D7A52.svg?style=flat-square)](LICENSE)
71
+ [![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-111317.svg?style=flat-square)](pyproject.toml)
72
72
  [![Docker GHCR](https://img.shields.io/badge/Docker-ghcr.io%2Fduhanguler%2Fomr-2496ED.svg?style=flat-square)](https://github.com/duhanguler/omr/pkgs/container/omr)
73
73
 
74
- [**Try Live Demo**](https://omrkit-studio.onrender.com/) · [**PyPI**](https://pypi.org/project/omrkit/) · [English](README.md) · [Türkçe](README.tr.md) · [Deployment Guide](docs/DEPLOYMENT.md) · [Examples](examples/) · [Contributing](CONTRIBUTING.md)
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 Demo:** Try OMRKit directly in your browser at **[omrkit-studio.onrender.com](https://omrkit-studio.onrender.com/)** — click **Try Demo** in the top bar to scan & grade a 5-student exam cohort, test **Live Camera**, or generate printable ArUco + QR sheets. *(Hosted on Render's free tier; first load after inactivity may take ~20–30s to wake up.)*
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 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:
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.1** |
88
+ | Capability | Legacy OMR Scripts | **OMRKit v2.2** |
87
89
  | :--- | :---: | :---: |
88
- | **Printable PDF Sheet Generator + Auto Template** | Manual JSON pixels | **1-Click Vector PDF (ArUco + QR) + Exact `template.json`** |
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 Existing Blank Forms** | Measure pixels by hand | **`omrkit detect-layout blank.jpg` + Studio Canvas Wizard** |
91
- | **Live Webcam / Mobile Browser Scanner** | Static files only | **Real-time `getUserMedia` Viewfinder with Auto-Lock** |
92
- | **Multi-Page PDF & EXIF Auto-Orientation** | Single images only | **Native `pypdfium2` + EXIF Auto-Orient** |
93
- | **0° / 90° / 180° / 270° Auto-Rotation** | Breaks when sideways | **ArUco IDs + Template-Structure Disambiguation** |
94
- | **Checkmarks (✓), Crosses (✗) & Shadow Tolerance** | Global intensity only | **Illumination Normalization + Hybrid Ink Scorer** |
95
- | **Confidence Scores & Human-in-the-Loop (HITL)** | Silent errors in CSV | **Calibrated `0–1` Confidence + 1-Click Review Queue** |
96
- | **Exam Psychometrics & Scorecards** | Basic score sum | **CTT Difficulty ($p$), Discrimination ($D$), KR-20, Excel & PDF Cards** |
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 1-click HITL review.</sub>
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], embedded auto-detect QR badge, and exact companion <code>template.json</code>.</sub>
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 Your Own Copy (1-Click Free Render Blueprint):** [![Deploy to Render](https://img.shields.io/badge/Deploy_to-Render-14181F?style=flat-square&logo=render)](https://dashboard.render.com/blueprint/new?repo=https://github.com/duhanguler/omr) · See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for GHCR, Render & HuggingFace PRO options.
137
+ - **Self-Host (1-Click Render Blueprint):** [![Deploy to Render](https://img.shields.io/badge/Deploy_to-Render-111317?style=flat-square&logo=render)](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** (with checksum validation), Booklet
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 existing blank optical sheet:
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 too:
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 / PageQuad / ORB / Direct"]
215
- C --> D["Shadow & Illumination Normalization"]
216
- D --> E["Hybrid Bubble Detector (Fill + Ring Contrast + Ink Stroke)"]
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 (Web Studio)"]
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 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).
226
- - **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.
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, per-item difficulty ($p$), upper/lower 27% discrimination index ($D$), option distractor distribution, and **KR-20** internal consistency reliability.
229
- - **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.
230
- - **Privacy Utility:** `omrkit strip-exif <dir> -o <clean_dir>` permanently bakes EXIF orientation into pixels and removes GPS/device metadata.
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 and launches via `omrkit studio` or `docker compose up` (includes a **Try Demo** button in the header for instant 1-click exploration):
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):** 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.
254
- 2. **Live Camera:** Real-time browser webcam / smartphone camera viewfinder (`getUserMedia`) with **Auto-Lock** corner capture, audio confirmation, and QR template recognition.
255
- 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.
256
- 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`).
257
- 5. **Grading & Analytics:** Inline answer-key editor, scoring policy selector, score histogram, student scoreboard with per-student **PDF Scorecards**, and full CTT item psychometrics.
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
+ [![CI](https://github.com/duhanguler/omr/actions/workflows/ci.yml/badge.svg)](https://github.com/duhanguler/omr/actions/workflows/ci.yml)
8
+ [![PyPI](https://img.shields.io/pypi/v/omrkit?style=flat-square&color=0D7A52&logo=pypi&logoColor=white)](https://pypi.org/project/omrkit/)
9
+ [![Live Demo](https://img.shields.io/badge/Live_Demo-OMRKit_Studio-1849C6?style=flat-square&logo=render&logoColor=white)](https://omrkit-studio.onrender.com/)
10
+ [![Release](https://img.shields.io/github/v/release/duhanguler/omr?style=flat-square&color=111317)](https://github.com/duhanguler/omr/releases)
11
+ [![License: MIT](https://img.shields.io/badge/License-MIT-0D7A52.svg?style=flat-square)](LICENSE)
12
+ [![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-111317.svg?style=flat-square)](pyproject.toml)
13
+ [![Docker GHCR](https://img.shields.io/badge/Docker-ghcr.io%2Fduhanguler%2Fomr-2496ED.svg?style=flat-square)](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):** [![Deploy to Render](https://img.shields.io/badge/Deploy_to-Render-111317?style=flat-square&logo=render)](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.1.1"
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" }
@@ -1,3 +1,3 @@
1
1
  """Single source of truth for the OMRKit package version."""
2
2
 
3
- __version__ = "2.1.1"
3
+ __version__ = "2.2.0"
@@ -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 include_overlay and warped_bgr is not None:
425
- overlays[result.sheet_id] = _encode_overlay(warped_bgr, result)
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
  }