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.
@@ -0,0 +1,132 @@
1
+ """Zero-template automatic scanning via embedded QR template discovery."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from functools import lru_cache
6
+ from pathlib import Path
7
+
8
+ import numpy as np
9
+
10
+ from omrkit.core.scanner import OMRScanner
11
+ from omrkit.generator.pdf_sheet import SheetGenerator
12
+ from omrkit.generator.presets import get_sheet_presets
13
+ from omrkit.io.loader import LoadedPage, load_bytes, load_document
14
+ from omrkit.models.scan import SheetResult
15
+ from omrkit.models.template import Template
16
+ from omrkit.vision.qr import detect_sheet_qr
17
+ from omrkit.vision.registration import RegistrationError, register_sheet
18
+
19
+
20
+ @lru_cache(maxsize=1)
21
+ def _builtin_preset_templates() -> dict[str, Template]:
22
+ gen = SheetGenerator()
23
+ return {pid: gen.generate(spec).template for pid, spec in get_sheet_presets().items()}
24
+
25
+
26
+ def resolve_template_for_image(
27
+ image_bgr: np.ndarray,
28
+ extra_templates: dict[str, Template] | None = None,
29
+ ) -> tuple[Template, str] | None:
30
+ """Detect an OMRKit sheet's embedded QR template ID and resolve its matching Template.
31
+
32
+ Falls back to ArUco perspective rectification first if severe skew/rotation prevents
33
+ direct QR reading on the raw photo.
34
+ """
35
+ registry: dict[str, Template] = dict(_builtin_preset_templates())
36
+ if extra_templates:
37
+ registry.update(extra_templates)
38
+
39
+ preset_id = detect_sheet_qr(image_bgr)
40
+ if preset_id and preset_id in registry:
41
+ return registry[preset_id], preset_id
42
+
43
+ # Fallback: use standard A4 ArUco corner rectification to flatten perspective, then read QR
44
+ fallback_template = registry.get("standard_mcq_40")
45
+ if fallback_template is not None:
46
+ try:
47
+ reg = register_sheet(image_bgr, fallback_template)
48
+ wh, ww = reg.warped_bgr.shape[:2]
49
+ # Try upper-right header ROI first (fast & zoomed) then full rectified image
50
+ qr_roi = reg.warped_bgr[0 : round(wh * 0.22), round(ww * 0.65) : ww]
51
+ for view in (qr_roi, reg.warped_bgr):
52
+ preset_id = detect_sheet_qr(view)
53
+ if preset_id and preset_id in registry:
54
+ return registry[preset_id], preset_id
55
+ except RegistrationError:
56
+ pass
57
+
58
+ return None
59
+
60
+
61
+ def scan_page_auto(
62
+ page: LoadedPage,
63
+ extra_templates: dict[str, Template] | None = None,
64
+ save_overlay_dir: str | Path | None = None,
65
+ ) -> tuple[SheetResult, np.ndarray | None]:
66
+ """Automatically identify a page's template via QR code and scan it."""
67
+ resolved = resolve_template_for_image(page.image_bgr, extra_templates=extra_templates)
68
+ if resolved is None:
69
+ stem = Path(page.source_name).stem
70
+ sheet_id = f"{stem}_p{page.page_index + 1}" if page.page_index > 0 else stem
71
+ return (
72
+ SheetResult(
73
+ sheet_id=sheet_id,
74
+ source_file=page.source_name,
75
+ page_index=page.page_index,
76
+ template_name="auto",
77
+ overall_confidence=0.0,
78
+ registration_method="qr_auto",
79
+ registration_score=0.0,
80
+ error=(
81
+ "Auto-template detection failed: no recognized OMRKit QR code found. "
82
+ "Provide an explicit template.json for custom sheets."
83
+ ),
84
+ ),
85
+ None,
86
+ )
87
+
88
+ template, _ = resolved
89
+ return OMRScanner(template).scan_page(page, save_overlay_dir=save_overlay_dir)
90
+
91
+
92
+ def scan_image_auto(
93
+ image_bgr: np.ndarray,
94
+ source_name: str = "image.png",
95
+ extra_templates: dict[str, Template] | None = None,
96
+ ) -> tuple[SheetResult, np.ndarray | None]:
97
+ """Auto-detect template via QR code and scan an in-memory BGR image."""
98
+ h, w = image_bgr.shape[:2]
99
+ page = LoadedPage(
100
+ source_name=source_name,
101
+ page_index=0,
102
+ image_bgr=image_bgr,
103
+ original_width=w,
104
+ original_height=h,
105
+ )
106
+ return scan_page_auto(page, extra_templates=extra_templates)
107
+
108
+
109
+ def scan_bytes_auto(
110
+ data: bytes,
111
+ filename: str,
112
+ dpi: int = 200,
113
+ extra_templates: dict[str, Template] | None = None,
114
+ max_pages: int | None = None,
115
+ ) -> list[tuple[SheetResult, np.ndarray | None]]:
116
+ """Auto-detect template per page and scan uploaded image or multi-page PDF bytes."""
117
+ pages = load_bytes(data, filename=filename, dpi=dpi, max_pages=max_pages)
118
+ return [scan_page_auto(p, extra_templates=extra_templates) for p in pages]
119
+
120
+
121
+ def scan_file_auto(
122
+ path: str | Path,
123
+ dpi: int = 200,
124
+ extra_templates: dict[str, Template] | None = None,
125
+ save_overlay_dir: str | Path | None = None,
126
+ ) -> list[SheetResult]:
127
+ """Auto-detect template per page and scan an image or multi-page PDF on disk."""
128
+ pages = load_document(path, dpi=dpi)
129
+ return [
130
+ scan_page_auto(p, extra_templates=extra_templates, save_overlay_dir=save_overlay_dir)[0]
131
+ for p in pages
132
+ ]
@@ -0,0 +1,204 @@
1
+ """Synthetic distortion benchmark harness for measuring OMR accuracy and throughput."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import random
6
+ from dataclasses import dataclass
7
+ from time import perf_counter
8
+
9
+ import cv2
10
+ import numpy as np
11
+
12
+ from omrkit.core.scanner import OMRScanner
13
+ from omrkit.generator.pdf_sheet import SheetGenerator
14
+ from omrkit.generator.presets import get_sheet_preset
15
+ from omrkit.io.loader import load_bytes
16
+ from omrkit.models.template import Template
17
+ from omrkit.vision.preprocess import rotate_image
18
+
19
+
20
+ @dataclass(slots=True)
21
+ class BenchmarkScenarioResult:
22
+ """Accuracy and throughput metrics for one camera/marking distortion scenario."""
23
+
24
+ scenario: str
25
+ sheets: int
26
+ total_fields: int
27
+ correct_fields: int
28
+ accuracy_pct: float
29
+ avg_confidence: float
30
+ flagged_fields: int
31
+ sheets_per_minute: float
32
+
33
+
34
+ def render_synthetic_filled_sheet(
35
+ blank_bgr: np.ndarray,
36
+ template: Template,
37
+ answers: dict[str, str],
38
+ mark_style: str = "solid",
39
+ seed: int = 42,
40
+ ) -> np.ndarray:
41
+ """Programmatically mark known answers onto a rendered blank optical sheet."""
42
+ rng = random.Random(seed)
43
+ img = blank_bgr.copy()
44
+
45
+ for block in template.blocks:
46
+ for field_id, coords in block.iter_field_bubbles():
47
+ expected = answers.get(field_id, "")
48
+ if not expected:
49
+ continue
50
+ for coord in coords:
51
+ if coord.option not in expected:
52
+ continue
53
+ cx = round(coord.cx + rng.uniform(-1.0, 1.0))
54
+ cy = round(coord.cy + rng.uniform(-1.0, 1.0))
55
+ r = max(4, round(coord.radius))
56
+ ink_tone = rng.randint(25, 58)
57
+ color = (ink_tone, ink_tone, ink_tone)
58
+
59
+ if mark_style == "solid":
60
+ cv2.circle(img, (cx, cy), int(r * 0.80), color, -1, cv2.LINE_AA)
61
+ elif mark_style == "checkmark":
62
+ p1 = (cx - int(r * 0.55), cy)
63
+ p2 = (cx - int(r * 0.10), cy + int(r * 0.50))
64
+ p3 = (cx + int(r * 0.65), cy - int(r * 0.55))
65
+ thickness = max(3, int(r * 0.28))
66
+ cv2.line(img, p1, p2, color, thickness, cv2.LINE_AA)
67
+ cv2.line(img, p2, p3, color, thickness, cv2.LINE_AA)
68
+ elif mark_style == "cross":
69
+ d = int(r * 0.55)
70
+ thickness = max(3, int(r * 0.26))
71
+ cv2.line(img, (cx - d, cy - d), (cx + d, cy + d), color, thickness, cv2.LINE_AA)
72
+ cv2.line(img, (cx - d, cy + d), (cx + d, cy - d), color, thickness, cv2.LINE_AA)
73
+ result_img: np.ndarray = img
74
+ return result_img
75
+
76
+
77
+ def apply_camera_distortion(
78
+ img_bgr: np.ndarray,
79
+ rotation_deg: int = 0,
80
+ perspective_strength: float = 0.0,
81
+ shadow_strength: float = 0.0,
82
+ blur_sigma: float = 0.0,
83
+ seed: int = 42,
84
+ ) -> np.ndarray:
85
+ """Simulate mobile camera perspective skew, shadows, rotation, and lens blur."""
86
+ rng = random.Random(seed)
87
+ out: np.ndarray = img_bgr.copy()
88
+
89
+ if shadow_strength > 0:
90
+ h, w = out.shape[:2]
91
+ grad_x = np.linspace(1.0 - shadow_strength, 1.0, w, dtype=np.float32)
92
+ grad_y = np.linspace(1.0, 1.0 - shadow_strength * 0.6, h, dtype=np.float32)
93
+ mask = np.outer(grad_y, grad_x)[:, :, None]
94
+ out = np.clip(out.astype(np.float32) * mask, 0, 255).astype(np.uint8)
95
+
96
+ if perspective_strength > 0:
97
+ h, w = out.shape[:2]
98
+ pad = int(min(h, w) * 0.08)
99
+ bordered = cv2.copyMakeBorder(
100
+ out, pad, pad, pad, pad, cv2.BORDER_CONSTANT, value=(210, 205, 198)
101
+ )
102
+ bh, bw = bordered.shape[:2]
103
+ jitter = min(bh, bw) * perspective_strength
104
+ src = np.asarray([[0, 0], [bw - 1, 0], [bw - 1, bh - 1], [0, bh - 1]], dtype=np.float32)
105
+ dst = np.asarray(
106
+ [
107
+ [rng.uniform(0, jitter), rng.uniform(0, jitter)],
108
+ [bw - 1 - rng.uniform(0, jitter), rng.uniform(0, jitter)],
109
+ [bw - 1 - rng.uniform(0, jitter), bh - 1 - rng.uniform(0, jitter)],
110
+ [rng.uniform(0, jitter), bh - 1 - rng.uniform(0, jitter)],
111
+ ],
112
+ dtype=np.float32,
113
+ )
114
+ mat = cv2.getPerspectiveTransform(src, dst)
115
+ out = cv2.warpPerspective(
116
+ bordered, mat, (bw, bh), borderMode=cv2.BORDER_CONSTANT, borderValue=(195, 190, 185)
117
+ )
118
+
119
+ if rotation_deg % 360 != 0:
120
+ out = rotate_image(out, rotation_deg)
121
+
122
+ if blur_sigma > 0:
123
+ out = cv2.GaussianBlur(out, (0, 0), sigmaX=blur_sigma)
124
+
125
+ return out
126
+
127
+
128
+ def run_benchmark(
129
+ preset_id: str = "standard_mcq_40",
130
+ samples_per_scenario: int = 5,
131
+ ) -> list[BenchmarkScenarioResult]:
132
+ """Run an end-to-end accuracy and speed benchmark across realistic scan scenarios."""
133
+ spec = get_sheet_preset(preset_id)
134
+ generated = SheetGenerator().generate(spec)
135
+ blank_page = load_bytes(generated.pdf_bytes, f"{preset_id}.pdf", dpi=spec.dpi)[0]
136
+ template = generated.template
137
+ scanner = OMRScanner(template)
138
+
139
+ scenarios = [
140
+ ("Clean Flatbed Scan (Solid Fill)", "solid", 0, 0.0, 0.0, 0.0),
141
+ ("Mobile Perspective + Shadow", "solid", 0, 0.055, 0.35, 0.7),
142
+ ("Rotated 90/180/270 + Perspective", "solid", -1, 0.045, 0.25, 0.5),
143
+ ("Pen Checkmarks (✓) + Shadow", "checkmark", 0, 0.03, 0.25, 0.4),
144
+ ]
145
+
146
+ results: list[BenchmarkScenarioResult] = []
147
+ for s_idx, (name, style, rot_mode, persp, shadow, blur) in enumerate(scenarios):
148
+ total_fields = 0
149
+ correct_fields = 0
150
+ flagged_fields = 0
151
+ confs: list[float] = []
152
+ t0 = perf_counter()
153
+
154
+ for i in range(samples_per_scenario):
155
+ seed = 1000 + s_idx * 100 + i
156
+ rng = random.Random(seed)
157
+ ground_truth: dict[str, str] = {}
158
+ for block in template.blocks:
159
+ for field_id in block.expanded_labels():
160
+ # Leave ~10% MCQ questions intentionally blank
161
+ if block.field_type == "mcq" and rng.random() < 0.10:
162
+ ground_truth[field_id] = ""
163
+ else:
164
+ ground_truth[field_id] = rng.choice(block.options)
165
+
166
+ marked = render_synthetic_filled_sheet(
167
+ blank_page.image_bgr, template, ground_truth, mark_style=style, seed=seed
168
+ )
169
+ rot = [90, 180, 270][i % 3] if rot_mode == -1 else rot_mode
170
+ distorted = apply_camera_distortion(
171
+ marked,
172
+ rotation_deg=rot,
173
+ perspective_strength=persp,
174
+ shadow_strength=shadow,
175
+ blur_sigma=blur,
176
+ seed=seed,
177
+ )
178
+
179
+ scan_res, _ = scanner.scan_image(distorted, source_name=f"bench_{s_idx}_{i}.png")
180
+ confs.append(scan_res.overall_confidence)
181
+ flagged_fields += len(scan_res.review_items)
182
+
183
+ for field_id, expected in ground_truth.items():
184
+ total_fields += 1
185
+ got = scan_res.fields[field_id].value if field_id in scan_res.fields else "__ERR__"
186
+ if got == expected:
187
+ correct_fields += 1
188
+
189
+ elapsed_min = max(1e-6, (perf_counter() - t0) / 60.0)
190
+ acc = (correct_fields / float(total_fields) * 100.0) if total_fields else 0.0
191
+ results.append(
192
+ BenchmarkScenarioResult(
193
+ scenario=name,
194
+ sheets=samples_per_scenario,
195
+ total_fields=total_fields,
196
+ correct_fields=correct_fields,
197
+ accuracy_pct=round(acc, 2),
198
+ avg_confidence=round(float(np.mean(confs)) if confs else 0.0, 4),
199
+ flagged_fields=flagged_fields,
200
+ sheets_per_minute=round(samples_per_scenario / elapsed_min, 1),
201
+ )
202
+ )
203
+
204
+ return results
@@ -0,0 +1,149 @@
1
+ """One-command migrator converting legacy OMRChecker v1 template.json files to OMRKit v2.0."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from pathlib import Path
7
+ from typing import Any
8
+
9
+ from omrkit.models.template import (
10
+ BlockDirection,
11
+ DetectionConfig,
12
+ FieldBlock,
13
+ FieldType,
14
+ RegistrationConfig,
15
+ Template,
16
+ )
17
+
18
+ _LEGACY_FIELD_TYPES: dict[str, tuple[list[str], BlockDirection, FieldType]] = {
19
+ "QTYPE_INT": ([str(i) for i in range(10)], "vertical", "grid_digits"),
20
+ "QTYPE_INT_FROM_1": ([str(i) for i in range(1, 10)] + ["0"], "vertical", "grid_digits"),
21
+ "QTYPE_MCQ4": (["A", "B", "C", "D"], "horizontal", "mcq"),
22
+ "QTYPE_MCQ5": (["A", "B", "C", "D", "E"], "horizontal", "mcq"),
23
+ }
24
+
25
+
26
+ def migrate_legacy_template_dict(
27
+ legacy: dict[str, Any],
28
+ name: str = "migrated_template",
29
+ ) -> Template:
30
+ """Convert an OMRChecker-format template dictionary into a validated OMRKit v2.0 Template."""
31
+ page_dims = legacy.get("pageDimensions")
32
+ bubble_dims = legacy.get("bubbleDimensions", [24, 24])
33
+ if not isinstance(page_dims, list) or len(page_dims) != 2:
34
+ raise ValueError("Legacy template must define 'pageDimensions': [width, height].")
35
+
36
+ page_w, page_h = int(page_dims[0]), int(page_dims[1])
37
+ default_radius = max(4.0, round(min(float(bubble_dims[0]), float(bubble_dims[1])) / 2.0, 2))
38
+ global_empty = str(legacy.get("emptyValue", ""))
39
+
40
+ # Translate preProcessors -> RegistrationConfig
41
+ registration = RegistrationConfig(mode="none")
42
+ for pp in legacy.get("preProcessors", []):
43
+ pp_name = pp.get("name")
44
+ opts = pp.get("options", {})
45
+ if pp_name == "CropOnMarkers":
46
+ registration = RegistrationConfig(
47
+ mode="markers",
48
+ marker_path=opts.get("relativePath"),
49
+ sheet_to_marker_width_ratio=float(opts.get("sheetToMarkerWidthRatio", 17.0)),
50
+ min_match_score=float(opts.get("min_matching_threshold", 0.30)),
51
+ max_match_variation=float(opts.get("max_matching_variation", 0.45)),
52
+ erode_subtract=bool(opts.get("apply_erode_subtract", True)),
53
+ auto_rotate=True,
54
+ )
55
+ break
56
+ if pp_name == "CropPage":
57
+ mk = opts.get("morphKernel", [10, 10])
58
+ registration = RegistrationConfig(
59
+ mode="page_quad",
60
+ morph_kernel=(int(mk[0]), int(mk[1])),
61
+ )
62
+ break
63
+ if pp_name == "FeatureBasedAlignment":
64
+ registration = RegistrationConfig(
65
+ mode="homography",
66
+ reference_path=opts.get("reference"),
67
+ max_features=int(opts.get("maxFeatures", 1500)),
68
+ good_match_ratio=float(opts.get("goodMatchPercent", 0.20)),
69
+ )
70
+ break
71
+
72
+ # Build lookup from exact field label list -> customLabel group name
73
+ custom_groups: dict[tuple[str, ...], str] = {}
74
+ for group_name, label_list in legacy.get("customLabels", {}).items():
75
+ if isinstance(label_list, list):
76
+ custom_groups[tuple(str(x) for x in label_list)] = str(group_name)
77
+
78
+ blocks: list[FieldBlock] = []
79
+ field_blocks = legacy.get("fieldBlocks", {})
80
+ if not isinstance(field_blocks, dict) or not field_blocks:
81
+ raise ValueError("Legacy template must define a non-empty 'fieldBlocks' mapping.")
82
+
83
+ for block_name, cfg in field_blocks.items():
84
+ legacy_ft = cfg.get("fieldType")
85
+ if legacy_ft in _LEGACY_FIELD_TYPES:
86
+ options, direction, ftype = _LEGACY_FIELD_TYPES[legacy_ft]
87
+ else:
88
+ options = [str(v) for v in cfg.get("bubbleValues", ["A", "B", "C", "D"])]
89
+ raw_dir = str(cfg.get("direction", "vertical"))
90
+ direction = "horizontal" if raw_dir == "horizontal" else "vertical"
91
+ ftype = "custom"
92
+
93
+ if "direction" in cfg:
94
+ direction = "horizontal" if cfg["direction"] == "horizontal" else "vertical"
95
+ if "bubbleValues" in cfg:
96
+ options = [str(v) for v in cfg["bubbleValues"]]
97
+
98
+ blk_dims = cfg.get("bubbleDimensions")
99
+ radius = (
100
+ max(4.0, round(min(float(blk_dims[0]), float(blk_dims[1])) / 2.0, 2))
101
+ if isinstance(blk_dims, list) and len(blk_dims) == 2
102
+ else default_radius
103
+ )
104
+
105
+ labels = [str(x) for x in cfg["fieldLabels"]]
106
+ group_as = custom_groups.get(tuple(labels))
107
+ origin_raw = cfg["origin"]
108
+
109
+ blocks.append(
110
+ FieldBlock(
111
+ name=str(block_name),
112
+ field_type=ftype,
113
+ direction=direction,
114
+ origin=(float(origin_raw[0]), float(origin_raw[1])),
115
+ origin_mode="top_left",
116
+ bubble_radius=radius,
117
+ bubbles_gap=float(cfg["bubblesGap"]),
118
+ labels_gap=float(cfg["labelsGap"]),
119
+ options=options,
120
+ labels=labels,
121
+ empty_value=str(cfg.get("emptyValue", global_empty)),
122
+ group_as=group_as,
123
+ )
124
+ )
125
+
126
+ return Template(
127
+ version="2.0",
128
+ name=name,
129
+ description="Migrated from legacy OMRChecker template format.",
130
+ page_width=page_w,
131
+ page_height=page_h,
132
+ registration=registration,
133
+ detection=DetectionConfig(),
134
+ blocks=blocks,
135
+ metadata={"migrated_from": "omrchecker_v1"},
136
+ )
137
+
138
+
139
+ def migrate_legacy_template_file(
140
+ src_path: str | Path,
141
+ dst_path: str | Path | None = None,
142
+ ) -> Template:
143
+ """Load a legacy OMRChecker template JSON file, migrate to v2.0, and optionally save."""
144
+ src = Path(src_path)
145
+ raw = json.loads(src.read_text(encoding="utf-8"))
146
+ template = migrate_legacy_template_dict(raw, name=src.stem)
147
+ if dst_path is not None:
148
+ template.to_file(dst_path)
149
+ return template