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/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
+ ]