omrkit 2.1.0__py3-none-any.whl
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/__init__.py +76 -0
- omrkit/__main__.py +6 -0
- omrkit/api/__init__.py +5 -0
- omrkit/api/app.py +75 -0
- omrkit/api/routes.py +490 -0
- omrkit/api/settings.py +55 -0
- omrkit/api/static/assets/index-BFfdzDls.js +224 -0
- omrkit/api/static/assets/index-DRPOjlrM.css +1 -0
- omrkit/api/static/index.html +23 -0
- omrkit/cli/__init__.py +5 -0
- omrkit/cli/app.py +440 -0
- omrkit/core/__init__.py +44 -0
- omrkit/core/auto_scanner.py +132 -0
- omrkit/core/benchmark.py +204 -0
- omrkit/core/migrator.py +149 -0
- omrkit/core/scanner.py +281 -0
- omrkit/core/validators.py +62 -0
- omrkit/generator/__init__.py +13 -0
- omrkit/generator/pdf_sheet.py +508 -0
- omrkit/generator/presets.py +109 -0
- omrkit/grading/__init__.py +6 -0
- omrkit/grading/analytics.py +177 -0
- omrkit/grading/grader.py +191 -0
- omrkit/io/__init__.py +37 -0
- omrkit/io/exporters.py +355 -0
- omrkit/io/loader.py +207 -0
- omrkit/models/__init__.py +65 -0
- omrkit/models/grading.py +222 -0
- omrkit/models/scan.py +100 -0
- omrkit/models/template.py +285 -0
- omrkit/py.typed +0 -0
- omrkit/vision/__init__.py +30 -0
- omrkit/vision/detector.py +313 -0
- omrkit/vision/grid_finder.py +280 -0
- omrkit/vision/preprocess.py +57 -0
- omrkit/vision/qr.py +83 -0
- omrkit/vision/registration.py +486 -0
- omrkit/vision/visualizer.py +99 -0
- omrkit-2.1.0.dist-info/METADATA +284 -0
- omrkit-2.1.0.dist-info/RECORD +43 -0
- omrkit-2.1.0.dist-info/WHEEL +4 -0
- omrkit-2.1.0.dist-info/entry_points.txt +2 -0
- omrkit-2.1.0.dist-info/licenses/LICENSE +21 -0
omrkit/core/scanner.py
ADDED
|
@@ -0,0 +1,281 @@
|
|
|
1
|
+
"""High-level single-sheet and parallel batch OMR scanning engine."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import os
|
|
6
|
+
from collections.abc import Callable
|
|
7
|
+
from concurrent.futures import ProcessPoolExecutor, as_completed
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
from time import perf_counter
|
|
10
|
+
|
|
11
|
+
import cv2
|
|
12
|
+
import numpy as np
|
|
13
|
+
|
|
14
|
+
from omrkit.core.validators import run_validator
|
|
15
|
+
from omrkit.io.loader import (
|
|
16
|
+
DocumentLoadError,
|
|
17
|
+
LoadedPage,
|
|
18
|
+
discover_documents,
|
|
19
|
+
load_bytes,
|
|
20
|
+
load_document,
|
|
21
|
+
)
|
|
22
|
+
from omrkit.models.scan import BatchResult, ReviewItem, SheetResult
|
|
23
|
+
from omrkit.models.template import Template
|
|
24
|
+
from omrkit.vision.detector import HybridBubbleDetector
|
|
25
|
+
from omrkit.vision.registration import RegistrationError, register_sheet
|
|
26
|
+
from omrkit.vision.visualizer import render_annotated_sheet
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def _scan_single_file_worker(
|
|
30
|
+
args: tuple[str, dict[str, object], int, str | None],
|
|
31
|
+
) -> list[dict[str, object]]:
|
|
32
|
+
"""Top-level picklable worker function for ProcessPoolExecutor batch scanning."""
|
|
33
|
+
file_path_str, template_dict, dpi, overlay_dir_str = args
|
|
34
|
+
template = Template.model_validate(template_dict)
|
|
35
|
+
scanner = OMRScanner(template=template, dpi=dpi)
|
|
36
|
+
overlay_dir = Path(overlay_dir_str) if overlay_dir_str else None
|
|
37
|
+
results = scanner.scan_file(file_path_str, save_overlay_dir=overlay_dir)
|
|
38
|
+
return [r.model_dump(mode="json") for r in results]
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class OMRScanner:
|
|
42
|
+
"""Scans single images, multi-page PDFs, or folders against an OMRKit Template."""
|
|
43
|
+
|
|
44
|
+
def __init__(
|
|
45
|
+
self,
|
|
46
|
+
template: Template,
|
|
47
|
+
detector: HybridBubbleDetector | None = None,
|
|
48
|
+
dpi: int = 200,
|
|
49
|
+
) -> None:
|
|
50
|
+
self.template = template
|
|
51
|
+
self.detector = detector or HybridBubbleDetector(template.detection)
|
|
52
|
+
self.dpi = dpi
|
|
53
|
+
|
|
54
|
+
def scan_page(
|
|
55
|
+
self,
|
|
56
|
+
page: LoadedPage,
|
|
57
|
+
save_overlay_dir: str | Path | None = None,
|
|
58
|
+
) -> tuple[SheetResult, np.ndarray | None]:
|
|
59
|
+
"""Scan one decoded page and return (SheetResult, aligned_warped_bgr)."""
|
|
60
|
+
t0 = perf_counter()
|
|
61
|
+
stem = Path(page.source_name).stem
|
|
62
|
+
sheet_id = f"{stem}_p{page.page_index + 1}" if page.page_index > 0 else stem
|
|
63
|
+
|
|
64
|
+
try:
|
|
65
|
+
reg = register_sheet(page.image_bgr, self.template)
|
|
66
|
+
except RegistrationError as exc:
|
|
67
|
+
elapsed = (perf_counter() - t0) * 1000.0
|
|
68
|
+
return (
|
|
69
|
+
SheetResult(
|
|
70
|
+
sheet_id=sheet_id,
|
|
71
|
+
source_file=page.source_name,
|
|
72
|
+
page_index=page.page_index,
|
|
73
|
+
template_name=self.template.name,
|
|
74
|
+
overall_confidence=0.0,
|
|
75
|
+
registration_method=self.template.registration.mode,
|
|
76
|
+
registration_score=0.0,
|
|
77
|
+
elapsed_ms=round(elapsed, 2),
|
|
78
|
+
error=str(exc),
|
|
79
|
+
),
|
|
80
|
+
None,
|
|
81
|
+
)
|
|
82
|
+
|
|
83
|
+
fields, review_items = self.detector.detect_sheet(reg.warped_bgr, self.template)
|
|
84
|
+
|
|
85
|
+
# Assemble grouped values (e.g., multi-column Student ID / TC Kimlik No)
|
|
86
|
+
grouped_values: dict[str, str] = {}
|
|
87
|
+
warnings: list[str] = []
|
|
88
|
+
|
|
89
|
+
for block in self.template.blocks:
|
|
90
|
+
labels = block.expanded_labels()
|
|
91
|
+
if block.group_as:
|
|
92
|
+
joined = "".join(fields[lbl].value for lbl in labels)
|
|
93
|
+
grouped_values[block.group_as] = joined
|
|
94
|
+
if block.validator is not None:
|
|
95
|
+
valid, msg = run_validator(block.validator, joined)
|
|
96
|
+
if not valid:
|
|
97
|
+
warnings.append(msg)
|
|
98
|
+
all_bubbles = [b for lbl in labels for b in fields[lbl].bubbles]
|
|
99
|
+
xs = [b.cx for b in all_bubbles]
|
|
100
|
+
ys = [b.cy for b in all_bubbles]
|
|
101
|
+
pad = max(20.0, block.bubble_radius * 2.0)
|
|
102
|
+
bbox = (
|
|
103
|
+
max(0, int(min(xs) - pad)),
|
|
104
|
+
max(0, int(min(ys) - pad)),
|
|
105
|
+
int(max(xs) + pad),
|
|
106
|
+
int(max(ys) + pad),
|
|
107
|
+
)
|
|
108
|
+
review_items.append(
|
|
109
|
+
ReviewItem(
|
|
110
|
+
field_id=block.group_as,
|
|
111
|
+
block_name=block.name,
|
|
112
|
+
reason="invalid_checksum",
|
|
113
|
+
suggested_value=joined,
|
|
114
|
+
confidence=0.4,
|
|
115
|
+
candidate_options=[],
|
|
116
|
+
bbox=bbox,
|
|
117
|
+
message=msg,
|
|
118
|
+
)
|
|
119
|
+
)
|
|
120
|
+
elif block.validator is not None:
|
|
121
|
+
for lbl in labels:
|
|
122
|
+
val = fields[lbl].value
|
|
123
|
+
valid, msg = run_validator(block.validator, val)
|
|
124
|
+
if not valid:
|
|
125
|
+
fields[lbl].status = "invalid_checksum"
|
|
126
|
+
warnings.append(f"{lbl}: {msg}")
|
|
127
|
+
|
|
128
|
+
confidences = [f.confidence for f in fields.values()]
|
|
129
|
+
overall_conf = round(float(np.mean(confidences)) if confidences else 0.0, 4)
|
|
130
|
+
elapsed = (perf_counter() - t0) * 1000.0
|
|
131
|
+
|
|
132
|
+
result = SheetResult(
|
|
133
|
+
sheet_id=sheet_id,
|
|
134
|
+
source_file=page.source_name,
|
|
135
|
+
page_index=page.page_index,
|
|
136
|
+
template_name=self.template.name,
|
|
137
|
+
fields=fields,
|
|
138
|
+
grouped_values=grouped_values,
|
|
139
|
+
review_items=review_items,
|
|
140
|
+
overall_confidence=overall_conf,
|
|
141
|
+
registration_method=reg.method,
|
|
142
|
+
registration_score=reg.score,
|
|
143
|
+
rotation_applied=reg.rotation_deg,
|
|
144
|
+
elapsed_ms=round(elapsed, 2),
|
|
145
|
+
warnings=warnings,
|
|
146
|
+
)
|
|
147
|
+
|
|
148
|
+
if save_overlay_dir is not None:
|
|
149
|
+
out_dir = Path(save_overlay_dir)
|
|
150
|
+
out_dir.mkdir(parents=True, exist_ok=True)
|
|
151
|
+
overlay = render_annotated_sheet(reg.warped_bgr, result)
|
|
152
|
+
cv2.imwrite(str(out_dir / f"{sheet_id}_overlay.png"), overlay)
|
|
153
|
+
|
|
154
|
+
return result, reg.warped_bgr
|
|
155
|
+
|
|
156
|
+
def scan_image(
|
|
157
|
+
self,
|
|
158
|
+
image_bgr: np.ndarray,
|
|
159
|
+
source_name: str = "image.png",
|
|
160
|
+
page_index: int = 0,
|
|
161
|
+
) -> tuple[SheetResult, np.ndarray | None]:
|
|
162
|
+
"""Scan an in-memory OpenCV BGR array."""
|
|
163
|
+
h, w = image_bgr.shape[:2]
|
|
164
|
+
page = LoadedPage(
|
|
165
|
+
source_name=source_name,
|
|
166
|
+
page_index=page_index,
|
|
167
|
+
image_bgr=image_bgr,
|
|
168
|
+
original_width=w,
|
|
169
|
+
original_height=h,
|
|
170
|
+
)
|
|
171
|
+
return self.scan_page(page)
|
|
172
|
+
|
|
173
|
+
def scan_bytes(
|
|
174
|
+
self,
|
|
175
|
+
data: bytes,
|
|
176
|
+
filename: str,
|
|
177
|
+
max_pages: int | None = None,
|
|
178
|
+
) -> list[tuple[SheetResult, np.ndarray | None]]:
|
|
179
|
+
"""Scan an uploaded image or multi-page PDF byte buffer."""
|
|
180
|
+
pages = load_bytes(data, filename=filename, dpi=self.dpi, max_pages=max_pages)
|
|
181
|
+
return [self.scan_page(page) for page in pages]
|
|
182
|
+
|
|
183
|
+
def scan_file(
|
|
184
|
+
self,
|
|
185
|
+
path: str | Path,
|
|
186
|
+
save_overlay_dir: str | Path | None = None,
|
|
187
|
+
) -> list[SheetResult]:
|
|
188
|
+
"""Scan all pages of an image or PDF file on disk."""
|
|
189
|
+
file_path = Path(path)
|
|
190
|
+
try:
|
|
191
|
+
pages = load_document(file_path, dpi=self.dpi)
|
|
192
|
+
except DocumentLoadError as exc:
|
|
193
|
+
return [
|
|
194
|
+
SheetResult(
|
|
195
|
+
sheet_id=file_path.stem,
|
|
196
|
+
source_file=file_path.name,
|
|
197
|
+
page_index=0,
|
|
198
|
+
template_name=self.template.name,
|
|
199
|
+
overall_confidence=0.0,
|
|
200
|
+
registration_method=self.template.registration.mode,
|
|
201
|
+
registration_score=0.0,
|
|
202
|
+
error=str(exc),
|
|
203
|
+
)
|
|
204
|
+
]
|
|
205
|
+
return [self.scan_page(p, save_overlay_dir=save_overlay_dir)[0] for p in pages]
|
|
206
|
+
|
|
207
|
+
def scan_batch(
|
|
208
|
+
self,
|
|
209
|
+
input_path: str | Path | list[Path],
|
|
210
|
+
workers: int | None = None,
|
|
211
|
+
recursive: bool = False,
|
|
212
|
+
save_overlay_dir: str | Path | None = None,
|
|
213
|
+
progress_cb: Callable[[int, int, str], None] | None = None,
|
|
214
|
+
) -> BatchResult:
|
|
215
|
+
"""Scan a folder or list of files sequentially or with ProcessPoolExecutor."""
|
|
216
|
+
files = (
|
|
217
|
+
input_path
|
|
218
|
+
if isinstance(input_path, list)
|
|
219
|
+
else discover_documents(input_path, recursive=recursive)
|
|
220
|
+
)
|
|
221
|
+
|
|
222
|
+
# Exclude marker or reference assets referenced by the template itself
|
|
223
|
+
excluded: set[Path] = set()
|
|
224
|
+
if self.template.registration.marker_path:
|
|
225
|
+
excluded.add(Path(self.template.registration.marker_path).resolve())
|
|
226
|
+
if self.template.registration.reference_path:
|
|
227
|
+
excluded.add(Path(self.template.registration.reference_path).resolve())
|
|
228
|
+
files = [f for f in files if f.resolve() not in excluded]
|
|
229
|
+
|
|
230
|
+
t0 = perf_counter()
|
|
231
|
+
all_results: list[SheetResult] = []
|
|
232
|
+
total_files = len(files)
|
|
233
|
+
|
|
234
|
+
max_workers = workers if workers is not None else min(4, os.cpu_count() or 1)
|
|
235
|
+
use_parallel = max_workers > 1 and total_files >= 4
|
|
236
|
+
|
|
237
|
+
if use_parallel:
|
|
238
|
+
template_dict = self.template.model_dump(mode="json")
|
|
239
|
+
overlay_str = str(save_overlay_dir) if save_overlay_dir else None
|
|
240
|
+
tasks = [(str(f), template_dict, self.dpi, overlay_str) for f in files]
|
|
241
|
+
ordered: dict[int, list[SheetResult]] = {}
|
|
242
|
+
|
|
243
|
+
with ProcessPoolExecutor(max_workers=max_workers) as pool:
|
|
244
|
+
future_map = {
|
|
245
|
+
pool.submit(_scan_single_file_worker, task): idx
|
|
246
|
+
for idx, task in enumerate(tasks)
|
|
247
|
+
}
|
|
248
|
+
for completed, future in enumerate(as_completed(future_map), start=1):
|
|
249
|
+
idx = future_map[future]
|
|
250
|
+
raw_list = future.result()
|
|
251
|
+
ordered[idx] = [SheetResult.model_validate(item) for item in raw_list]
|
|
252
|
+
if progress_cb:
|
|
253
|
+
progress_cb(completed, total_files, files[idx].name)
|
|
254
|
+
|
|
255
|
+
for idx in range(total_files):
|
|
256
|
+
all_results.extend(ordered.get(idx, []))
|
|
257
|
+
else:
|
|
258
|
+
for idx, file_path in enumerate(files, start=1):
|
|
259
|
+
results = self.scan_file(file_path, save_overlay_dir=save_overlay_dir)
|
|
260
|
+
all_results.extend(results)
|
|
261
|
+
if progress_cb:
|
|
262
|
+
progress_cb(idx, total_files, file_path.name)
|
|
263
|
+
|
|
264
|
+
elapsed_ms = (perf_counter() - t0) * 1000.0
|
|
265
|
+
succeeded = sum(1 for r in all_results if r.error is None)
|
|
266
|
+
failed = sum(1 for r in all_results if r.error is not None)
|
|
267
|
+
flagged = sum(1 for r in all_results if r.error is None and len(r.review_items) > 0)
|
|
268
|
+
sheets_per_min = (
|
|
269
|
+
(len(all_results) / (elapsed_ms / 60000.0)) if elapsed_ms > 0 and all_results else 0.0
|
|
270
|
+
)
|
|
271
|
+
|
|
272
|
+
return BatchResult(
|
|
273
|
+
template_name=self.template.name,
|
|
274
|
+
sheets=all_results,
|
|
275
|
+
total_sheets=len(all_results),
|
|
276
|
+
succeeded=succeeded,
|
|
277
|
+
flagged_sheets=flagged,
|
|
278
|
+
failed_sheets=failed,
|
|
279
|
+
total_elapsed_ms=round(elapsed_ms, 2),
|
|
280
|
+
sheets_per_minute=round(sheets_per_min, 1),
|
|
281
|
+
)
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
"""Built-in field and identity checksum validators (including Turkish TC Kimlik No)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from omrkit.models.template import ValidatorType
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
def validate_tr_tckn(value: str) -> bool:
|
|
9
|
+
"""Validate an 11-digit Turkish Republic Identity Number (TC Kimlik No)."""
|
|
10
|
+
digits = value.strip()
|
|
11
|
+
if len(digits) != 11 or not digits.isdigit() or digits[0] == "0":
|
|
12
|
+
return False
|
|
13
|
+
nums = [int(ch) for ch in digits]
|
|
14
|
+
odd_sum = sum(nums[0:9:2]) # 1st, 3rd, 5th, 7th, 9th
|
|
15
|
+
even_sum = sum(nums[1:8:2]) # 2nd, 4th, 6th, 8th
|
|
16
|
+
d10 = ((odd_sum * 7) - even_sum) % 10
|
|
17
|
+
d11 = sum(nums[0:10]) % 10
|
|
18
|
+
return nums[9] == d10 and nums[10] == d11
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def validate_luhn(value: str) -> bool:
|
|
22
|
+
"""Validate a numeric identifier using the standard Luhn mod-10 checksum."""
|
|
23
|
+
digits = value.strip()
|
|
24
|
+
if len(digits) < 2 or not digits.isdigit():
|
|
25
|
+
return False
|
|
26
|
+
total = 0
|
|
27
|
+
for idx, ch in enumerate(reversed(digits)):
|
|
28
|
+
n = int(ch)
|
|
29
|
+
if idx % 2 == 1:
|
|
30
|
+
n *= 2
|
|
31
|
+
if n > 9:
|
|
32
|
+
n -= 9
|
|
33
|
+
total += n
|
|
34
|
+
return total % 10 == 0
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def validate_digits(value: str) -> bool:
|
|
38
|
+
"""Verify the value consists solely of ASCII digits and is non-empty."""
|
|
39
|
+
stripped = value.strip()
|
|
40
|
+
return bool(stripped) and stripped.isdigit()
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def validate_non_empty(value: str) -> bool:
|
|
44
|
+
"""Verify the value is non-empty."""
|
|
45
|
+
return bool(value.strip())
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def run_validator(validator_type: ValidatorType, value: str) -> tuple[bool, str]:
|
|
49
|
+
"""Run a named field validator and return (is_valid, reason_message)."""
|
|
50
|
+
if validator_type == "tr_tckn":
|
|
51
|
+
ok = validate_tr_tckn(value)
|
|
52
|
+
return ok, "" if ok else f"Invalid Turkish TC Kimlik No checksum: '{value}'."
|
|
53
|
+
if validator_type == "luhn":
|
|
54
|
+
ok = validate_luhn(value)
|
|
55
|
+
return ok, "" if ok else f"Invalid Luhn checksum: '{value}'."
|
|
56
|
+
if validator_type == "digits":
|
|
57
|
+
ok = validate_digits(value)
|
|
58
|
+
return ok, "" if ok else f"Expected numeric digits only, got '{value}'."
|
|
59
|
+
if validator_type == "non_empty":
|
|
60
|
+
ok = validate_non_empty(value)
|
|
61
|
+
return ok, "" if ok else "Required field was left blank."
|
|
62
|
+
return True, ""
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
"""Printable optical sheet generator and built-in exam presets."""
|
|
2
|
+
|
|
3
|
+
from omrkit.generator.pdf_sheet import GeneratedSheet, SheetGenerator
|
|
4
|
+
from omrkit.generator.presets import IdGridSpec, SheetSpec, get_sheet_preset, get_sheet_presets
|
|
5
|
+
|
|
6
|
+
__all__ = [
|
|
7
|
+
"GeneratedSheet",
|
|
8
|
+
"IdGridSpec",
|
|
9
|
+
"SheetGenerator",
|
|
10
|
+
"SheetSpec",
|
|
11
|
+
"get_sheet_preset",
|
|
12
|
+
"get_sheet_presets",
|
|
13
|
+
]
|