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/vision/qr.py ADDED
@@ -0,0 +1,83 @@
1
+ """Embedded QR code encoding and automatic template discovery for OMRKit sheets."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import cv2
6
+ import numpy as np
7
+
8
+ from omrkit.vision.preprocess import ensure_grayscale
9
+
10
+ QR_PREFIX = "OMRKIT:v2:"
11
+
12
+
13
+ def encode_sheet_qr_payload(preset_id: str) -> str:
14
+ """Build a compact canonical QR payload identifying an OMRKit sheet layout."""
15
+ return f"{QR_PREFIX}{preset_id.strip()}"
16
+
17
+
18
+ def parse_sheet_qr_payload(raw_text: str) -> str | None:
19
+ """Extract the preset/template ID from a decoded QR payload, or None if unrecognized."""
20
+ cleaned = raw_text.strip()
21
+ if not cleaned.startswith(QR_PREFIX):
22
+ return None
23
+ preset_id = cleaned[len(QR_PREFIX) :].strip()
24
+ return preset_id or None
25
+
26
+
27
+ def render_qr_matrix(payload: str, pixel_size: int = 220) -> np.ndarray:
28
+ """Generate a crisp binary QR code image with a white quiet zone using OpenCV."""
29
+ encoder = cv2.QRCodeEncoder_create() # type: ignore[attr-defined]
30
+ matrix = encoder.encode(payload)
31
+ scaled = cv2.resize(matrix, (pixel_size, pixel_size), interpolation=cv2.INTER_NEAREST)
32
+ pad = max(12, pixel_size // 10)
33
+ bordered: np.ndarray = cv2.copyMakeBorder(
34
+ scaled, pad, pad, pad, pad, cv2.BORDER_CONSTANT, value=255
35
+ )
36
+ return bordered
37
+
38
+
39
+ def detect_sheet_qr(image_bgr: np.ndarray) -> str | None:
40
+ """Detect and decode an OMRKit template ID QR code from an image (any orientation)."""
41
+ detector = cv2.QRCodeDetector()
42
+ gray = ensure_grayscale(image_bgr)
43
+
44
+ candidates: list[np.ndarray] = [gray]
45
+ # Add CLAHE contrast-boosted version for shadowed phone captures
46
+ clahe = cv2.createCLAHE(clipLimit=2.2, tileGridSize=(8, 8))
47
+ candidates.append(clahe.apply(gray))
48
+
49
+ # Downscaled variant helps when QR modules have subtle camera noise at huge resolutions
50
+ h, w = gray.shape[:2]
51
+ if max(h, w) > 1800:
52
+ scale = 1400.0 / float(max(h, w))
53
+ candidates.append(
54
+ cv2.resize(gray, (round(w * scale), round(h * scale)), interpolation=cv2.INTER_AREA)
55
+ )
56
+
57
+ for img in candidates:
58
+ text, _, _ = detector.detectAndDecode(img)
59
+ if text:
60
+ parsed = parse_sheet_qr_payload(text)
61
+ if parsed is not None:
62
+ return parsed
63
+
64
+ # Fallback: decodeMulti handles sheets where corner markers confuse single-QR finder
65
+ ok, decoded_list, _, _ = detector.detectAndDecodeMulti(img)
66
+ if ok and decoded_list:
67
+ for item in decoded_list:
68
+ parsed = parse_sheet_qr_payload(item)
69
+ if parsed is not None:
70
+ return parsed
71
+
72
+ # Focused high-contrast upscaled pass on small crops (e.g., rectified QR badge)
73
+ if max(h, w) <= 600:
74
+ up = cv2.resize(gray, (w * 2, h * 2), interpolation=cv2.INTER_CUBIC)
75
+ _, otsu = cv2.threshold(up, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
76
+ for img in (up, otsu):
77
+ text, _, _ = detector.detectAndDecode(img)
78
+ if text:
79
+ parsed = parse_sheet_qr_payload(text)
80
+ if parsed is not None:
81
+ return parsed
82
+
83
+ return None
@@ -0,0 +1,486 @@
1
+ """Multi-strategy sheet registration and perspective rectification."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import math
6
+ from dataclasses import dataclass
7
+ from pathlib import Path
8
+
9
+ import cv2
10
+ import numpy as np
11
+
12
+ from omrkit.models.template import RegistrationConfig, Template
13
+ from omrkit.vision.preprocess import ensure_grayscale, rotate_image
14
+
15
+
16
+ class RegistrationError(RuntimeError):
17
+ """Raised when an optical sheet cannot be aligned to its template."""
18
+
19
+
20
+ @dataclass(slots=True)
21
+ class RegistrationResult:
22
+ """Warped canonical sheet image and diagnostic alignment metadata."""
23
+
24
+ warped_bgr: np.ndarray
25
+ method: str
26
+ score: float
27
+ rotation_deg: int
28
+ source_corners: list[tuple[float, float]] | None = None
29
+
30
+
31
+ def order_quad_points(pts: np.ndarray) -> np.ndarray:
32
+ """Order 4 2D points consistently as [top-left, top-right, bottom-right, bottom-left]."""
33
+ arr = np.asarray(pts, dtype=np.float32).reshape(4, 2)
34
+ ordered = np.zeros((4, 2), dtype=np.float32)
35
+ s = arr.sum(axis=1)
36
+ diff = np.diff(arr, axis=1).reshape(-1)
37
+ ordered[0] = arr[int(np.argmin(s))] # TL
38
+ ordered[2] = arr[int(np.argmax(s))] # BR
39
+ ordered[1] = arr[int(np.argmin(diff))] # TR
40
+ ordered[3] = arr[int(np.argmax(diff))] # BL
41
+ return ordered
42
+
43
+
44
+ def _default_target_corners(template: Template) -> np.ndarray:
45
+ if template.registration.target_corners is not None:
46
+ return np.asarray(template.registration.target_corners, dtype=np.float32)
47
+ w = float(template.page_width - 1)
48
+ h = float(template.page_height - 1)
49
+ return np.asarray([[0.0, 0.0], [w, 0.0], [w, h], [0.0, h]], dtype=np.float32)
50
+
51
+
52
+ def _infer_rotation_from_top_edge(tl: np.ndarray, tr: np.ndarray) -> int:
53
+ """Infer nearest 90-degree clockwise rotation applied to bring TL->TR horizontal."""
54
+ dx = float(tr[0] - tl[0])
55
+ dy = float(tr[1] - tl[1])
56
+ angle = math.degrees(math.atan2(dy, dx))
57
+ # Snap to nearest quadrant: 0=upright, 90=rotated CW (needs 270), etc.
58
+ snapped = (round(-angle / 90.0) * 90) % 360
59
+ return int(snapped)
60
+
61
+
62
+ def _warp_from_corners(
63
+ image_bgr: np.ndarray,
64
+ src_corners: np.ndarray,
65
+ dst_corners: np.ndarray,
66
+ page_width: int,
67
+ page_height: int,
68
+ ) -> np.ndarray:
69
+ matrix = cv2.getPerspectiveTransform(
70
+ src_corners.astype(np.float32),
71
+ dst_corners.astype(np.float32),
72
+ )
73
+ return cv2.warpPerspective(
74
+ image_bgr,
75
+ matrix,
76
+ (page_width, page_height),
77
+ flags=cv2.INTER_LINEAR,
78
+ borderMode=cv2.BORDER_CONSTANT,
79
+ borderValue=(255, 255, 255),
80
+ )
81
+
82
+
83
+ def _get_aruco_dictionary(dict_name: str) -> cv2.aruco.Dictionary:
84
+ if not hasattr(cv2.aruco, dict_name):
85
+ raise RegistrationError(f"Unknown ArUco dictionary '{dict_name}'.")
86
+ dict_id = getattr(cv2.aruco, dict_name)
87
+ return cv2.aruco.getPredefinedDictionary(dict_id)
88
+
89
+
90
+ def _register_aruco(image_bgr: np.ndarray, template: Template) -> RegistrationResult:
91
+ cfg = template.registration
92
+ aruco_dict = _get_aruco_dictionary(cfg.aruco_dict)
93
+ params = cv2.aruco.DetectorParameters()
94
+ params.cornerRefinementMethod = cv2.aruco.CORNER_REFINE_SUBPIX
95
+ detector = cv2.aruco.ArucoDetector(aruco_dict, params)
96
+
97
+ gray = ensure_grayscale(image_bgr)
98
+ required_ids = list(cfg.aruco_ids)
99
+
100
+ def _detect_centers(img: np.ndarray, inv_scale: float = 1.0) -> dict[int, np.ndarray]:
101
+ corners, ids, _ = detector.detectMarkers(img)
102
+ found: dict[int, np.ndarray] = {}
103
+ if ids is None:
104
+ return found
105
+ for marker_corners, marker_id_val in zip(corners, np.asarray(ids).ravel(), strict=False):
106
+ mid = int(marker_id_val)
107
+ if mid in required_ids:
108
+ center = np.asarray(marker_corners, dtype=np.float32).reshape(-1, 2).mean(axis=0)
109
+ found[mid] = center * inv_scale
110
+ return found
111
+
112
+ # Attempt 1: Native resolution grayscale
113
+ found = _detect_centers(gray, 1.0)
114
+
115
+ # Attempt 2: CLAHE contrast-enhanced grayscale (helps shadowed phone photos)
116
+ if len(found) < 4:
117
+ clahe = cv2.createCLAHE(clipLimit=2.5, tileGridSize=(8, 8))
118
+ found_clahe = _detect_centers(clahe.apply(gray), 1.0)
119
+ if len(found_clahe) > len(found):
120
+ found = found_clahe
121
+
122
+ # Attempt 3: Downscaled pass for very high-res noisy camera captures
123
+ if len(found) < 4 and max(gray.shape[:2]) > 2000:
124
+ scale = 1600.0 / float(max(gray.shape[:2]))
125
+ small = cv2.resize(
126
+ gray,
127
+ (int(gray.shape[1] * scale), int(gray.shape[0] * scale)),
128
+ interpolation=cv2.INTER_AREA,
129
+ )
130
+ found_small = _detect_centers(small, 1.0 / scale)
131
+ if len(found_small) > len(found):
132
+ found = found_small
133
+
134
+ if len(found) < 4:
135
+ missing = [mid for mid in required_ids if mid not in found]
136
+ raise RegistrationError(
137
+ f"ArUco registration failed: detected {len(found)}/4 markers (missing IDs: {missing})."
138
+ )
139
+
140
+ src_pts = np.asarray([found[mid] for mid in required_ids], dtype=np.float32)
141
+ dst_pts = _default_target_corners(template)
142
+ rotation = _infer_rotation_from_top_edge(src_pts[0], src_pts[1])
143
+ warped = _warp_from_corners(
144
+ image_bgr, src_pts, dst_pts, template.page_width, template.page_height
145
+ )
146
+ return RegistrationResult(
147
+ warped_bgr=warped,
148
+ method="aruco",
149
+ score=1.0,
150
+ rotation_deg=rotation,
151
+ source_corners=[(float(p[0]), float(p[1])) for p in src_pts],
152
+ )
153
+
154
+
155
+ def _prepare_marker_image(
156
+ marker_gray: np.ndarray, target_w: int, erode_subtract: bool
157
+ ) -> np.ndarray:
158
+ h, w = marker_gray.shape[:2]
159
+ target_h = max(8, round(h * (target_w / float(w))))
160
+ resized = cv2.resize(marker_gray, (max(8, target_w), target_h), interpolation=cv2.INTER_AREA)
161
+ blurred = cv2.GaussianBlur(resized, (5, 5), 0)
162
+ normed = cv2.normalize(blurred, None, 0, 255, cv2.NORM_MINMAX)
163
+ if erode_subtract:
164
+ kernel = np.ones((5, 5), dtype=np.uint8)
165
+ normed = cv2.subtract(normed, cv2.erode(normed, kernel, iterations=5))
166
+ return normed
167
+
168
+
169
+ def _match_four_markers(
170
+ image_bgr: np.ndarray,
171
+ marker_gray: np.ndarray,
172
+ cfg: RegistrationConfig,
173
+ ) -> tuple[np.ndarray, float] | None:
174
+ gray = ensure_grayscale(image_bgr)
175
+ orig_h, orig_w = gray.shape[:2]
176
+ work_w = 800
177
+ scale_to_work = work_w / float(orig_w)
178
+ work_h = max(64, round(orig_h * scale_to_work))
179
+ work = cv2.resize(gray, (work_w, work_h), interpolation=cv2.INTER_AREA)
180
+
181
+ if cfg.erode_subtract:
182
+ kernel = np.ones((5, 5), dtype=np.uint8)
183
+ work_proc = cv2.subtract(work, cv2.erode(work, kernel, iterations=5))
184
+ else:
185
+ work_proc = work
186
+ work_proc = cv2.normalize(work_proc, None, 0, 255, cv2.NORM_MINMAX)
187
+
188
+ base_marker_w = max(12, round(work_w / cfg.sheet_to_marker_width_ratio))
189
+ base_marker = _prepare_marker_image(marker_gray, base_marker_w, cfg.erode_subtract)
190
+
191
+ mid_x = round(work_w * cfg.split_ratio_x)
192
+ mid_y = round(work_h * cfg.split_ratio_y)
193
+ quads = [
194
+ (0, 0, work_proc[0:mid_y, 0:mid_x]), # TL
195
+ (mid_x, 0, work_proc[0:mid_y, mid_x:work_w]), # TR
196
+ (mid_x, mid_y, work_proc[mid_y:work_h, mid_x:work_w]), # BR
197
+ (0, mid_y, work_proc[mid_y:work_h, 0:mid_x]), # BL
198
+ ]
199
+
200
+ min_s, max_s = cfg.scale_range
201
+ scales = np.linspace(max_s, min_s, cfg.scale_steps)
202
+ best_scale: float | None = None
203
+ best_global_score = -1.0
204
+
205
+ mh, mw = base_marker.shape[:2]
206
+ for s in scales:
207
+ tw = max(8, round(mw * float(s)))
208
+ th = max(8, round(mh * float(s)))
209
+ if tw >= min(mid_x, work_w - mid_x) or th >= min(mid_y, work_h - mid_y):
210
+ continue
211
+ scaled = cv2.resize(base_marker, (tw, th), interpolation=cv2.INTER_AREA)
212
+ res = cv2.matchTemplate(work_proc, scaled, cv2.TM_CCOEFF_NORMED)
213
+ score = float(np.max(res))
214
+ if score > best_global_score:
215
+ best_global_score = score
216
+ best_scale = float(s)
217
+
218
+ if best_scale is None or best_global_score < cfg.min_match_score:
219
+ return None
220
+
221
+ tw = max(8, round(mw * best_scale))
222
+ th = max(8, round(mh * best_scale))
223
+ optimal_marker = cv2.resize(base_marker, (tw, th), interpolation=cv2.INTER_AREA)
224
+
225
+ centers: list[tuple[float, float]] = []
226
+ quad_scores: list[float] = []
227
+ for ox, oy, quad in quads:
228
+ if quad.shape[0] <= th or quad.shape[1] <= tw:
229
+ return None
230
+ res = cv2.matchTemplate(quad, optimal_marker, cv2.TM_CCOEFF_NORMED)
231
+ _, max_val, _, max_loc = cv2.minMaxLoc(res)
232
+ score_val = float(max_val)
233
+ if (
234
+ score_val < cfg.min_match_score
235
+ or abs(best_global_score - score_val) > cfg.max_match_variation
236
+ ):
237
+ return None
238
+ cx_work = ox + max_loc[0] + tw / 2.0
239
+ cy_work = oy + max_loc[1] + th / 2.0
240
+ centers.append((cx_work / scale_to_work, cy_work / scale_to_work))
241
+ quad_scores.append(score_val)
242
+
243
+ # Validate geometry: markers must form a non-degenerate convex quad with sensible area
244
+ pts = np.asarray(centers, dtype=np.float32)
245
+ area = float(cv2.contourArea(pts))
246
+ if area < 0.05 * orig_w * orig_h:
247
+ return None
248
+
249
+ return pts, float(np.mean(quad_scores))
250
+
251
+
252
+ def _template_structure_score(warped_bgr: np.ndarray, template: Template) -> float:
253
+ """Measure ratio of printed edge density inside template blocks vs outside margins."""
254
+ scale = 0.25
255
+ mw = max(32, round(template.page_width * scale))
256
+ mh = max(32, round(template.page_height * scale))
257
+ mask = np.zeros((mh, mw), dtype=bool)
258
+ for blk in template.blocks:
259
+ xs: list[float] = []
260
+ ys: list[float] = []
261
+ for _, coords in blk.iter_field_bubbles():
262
+ for c in coords:
263
+ xs.append(c.cx)
264
+ ys.append(c.cy)
265
+ if not xs:
266
+ continue
267
+ r = blk.bubble_radius
268
+ x1 = max(0, round((min(xs) - r) * scale))
269
+ x2 = min(mw, round((max(xs) + r) * scale))
270
+ y1 = max(0, round((min(ys) - r) * scale))
271
+ y2 = min(mh, round((max(ys) + r) * scale))
272
+ mask[y1:y2, x1:x2] = True
273
+
274
+ if not mask.any() or mask.all():
275
+ return 1.0
276
+ gray = cv2.resize(ensure_grayscale(warped_bgr), (mw, mh), interpolation=cv2.INTER_AREA)
277
+ edges = cv2.Canny(gray, 40, 120) > 0
278
+ in_density = float(np.mean(edges[mask]))
279
+ out_density = float(np.mean(edges[~mask]))
280
+ return in_density / (out_density + 0.005)
281
+
282
+
283
+ def _register_markers(image_bgr: np.ndarray, template: Template) -> RegistrationResult:
284
+ cfg = template.registration
285
+ if not cfg.marker_path:
286
+ raise RegistrationError("Marker registration requires 'registration.marker_path'.")
287
+
288
+ marker_path = Path(cfg.marker_path)
289
+ if not marker_path.exists():
290
+ raise RegistrationError(f"Marker image not found: '{marker_path}'")
291
+
292
+ marker_gray = cv2.imread(str(marker_path), cv2.IMREAD_GRAYSCALE)
293
+ if marker_gray is None:
294
+ raise RegistrationError(f"Could not decode marker image: '{marker_path}'")
295
+
296
+ candidate_rotations = [0, 90, 270, 180] if cfg.auto_rotate else [0]
297
+ expected_aspect = template.page_width / float(template.page_height)
298
+ dst_pts = _default_target_corners(template)
299
+ best_match: tuple[int, np.ndarray, np.ndarray, float, float] | None = None
300
+
301
+ for deg in candidate_rotations:
302
+ rotated = rotate_image(image_bgr, deg)
303
+ result = _match_four_markers(rotated, marker_gray, cfg)
304
+ if result is None:
305
+ continue
306
+ pts, match_score = result
307
+ warped = _warp_from_corners(
308
+ rotated, pts, dst_pts, template.page_width, template.page_height
309
+ )
310
+
311
+ quad_w = 0.5 * (
312
+ float(np.linalg.norm(pts[1] - pts[0])) + float(np.linalg.norm(pts[2] - pts[3]))
313
+ )
314
+ quad_h = 0.5 * (
315
+ float(np.linalg.norm(pts[3] - pts[0])) + float(np.linalg.norm(pts[2] - pts[1]))
316
+ )
317
+ quad_aspect = quad_w / max(quad_h, 1.0)
318
+ aspect_err = abs(math.log(max(quad_aspect, 1e-3) / expected_aspect))
319
+ structure_ratio = _template_structure_score(warped, template)
320
+
321
+ combined_rank = match_score + 0.45 * min(structure_ratio, 3.0) - 1.2 * aspect_err
322
+ if best_match is None or combined_rank > best_match[4]:
323
+ best_match = (deg, warped, pts, match_score, combined_rank)
324
+
325
+ if best_match is None:
326
+ raise RegistrationError(
327
+ "Marker registration failed: could not locate all 4 corner markers."
328
+ )
329
+
330
+ deg, warped, src_pts, score, _ = best_match
331
+ return RegistrationResult(
332
+ warped_bgr=warped,
333
+ method="markers",
334
+ score=round(score, 4),
335
+ rotation_deg=deg,
336
+ source_corners=[(float(p[0]), float(p[1])) for p in src_pts],
337
+ )
338
+
339
+
340
+ def _check_quad_angles(pts: np.ndarray, max_cosine: float = 0.38) -> bool:
341
+ for i in range(4):
342
+ p0 = pts[i]
343
+ p1 = pts[(i - 1) % 4]
344
+ p2 = pts[(i + 1) % 4]
345
+ v1 = p1 - p0
346
+ v2 = p2 - p0
347
+ denom = float(np.linalg.norm(v1) * np.linalg.norm(v2)) + 1e-9
348
+ cos_val = abs(float(np.dot(v1, v2)) / denom)
349
+ if cos_val >= max_cosine:
350
+ return False
351
+ return True
352
+
353
+
354
+ def _register_page_quad(image_bgr: np.ndarray, template: Template) -> RegistrationResult:
355
+ cfg = template.registration
356
+ gray = ensure_grayscale(image_bgr)
357
+ h, w = gray.shape[:2]
358
+ min_area = cfg.min_area_ratio * float(h * w)
359
+
360
+ blurred = cv2.GaussianBlur(gray, (5, 5), 0)
361
+ normed = cv2.normalize(blurred, None, 0, 255, cv2.NORM_MINMAX)
362
+ _, trunc = cv2.threshold(normed, 200, 255, cv2.THRESH_TRUNC)
363
+ normed = cv2.normalize(trunc, None, 0, 255, cv2.NORM_MINMAX)
364
+
365
+ kernel = cv2.getStructuringElement(cv2.MORPH_RECT, cfg.morph_kernel)
366
+ closed = cv2.morphologyEx(normed, cv2.MORPH_CLOSE, kernel)
367
+ edges = cv2.Canny(closed, 60, 180)
368
+ contours, _ = cv2.findContours(edges, cv2.RETR_LIST, cv2.CHAIN_APPROX_SIMPLE)
369
+
370
+ hulls = [cv2.convexHull(c) for c in contours]
371
+ hulls = sorted(hulls, key=cv2.contourArea, reverse=True)[:8]
372
+
373
+ for hull in hulls:
374
+ area = float(cv2.contourArea(hull))
375
+ if area < min_area:
376
+ continue
377
+ peri = cv2.arcLength(hull, True)
378
+ approx = cv2.approxPolyDP(hull, 0.025 * peri, True)
379
+ if len(approx) == 4:
380
+ pts = order_quad_points(approx.reshape(4, 2))
381
+ if _check_quad_angles(pts):
382
+ dst_pts = _default_target_corners(template)
383
+ warped = _warp_from_corners(
384
+ image_bgr, pts, dst_pts, template.page_width, template.page_height
385
+ )
386
+ coverage = min(1.0, area / float(h * w))
387
+ return RegistrationResult(
388
+ warped_bgr=warped,
389
+ method="page_quad",
390
+ score=round(max(0.5, coverage), 4),
391
+ rotation_deg=0,
392
+ source_corners=[(float(p[0]), float(p[1])) for p in pts],
393
+ )
394
+
395
+ raise RegistrationError("Page boundary quadrilateral not found in image.")
396
+
397
+
398
+ def _register_homography(image_bgr: np.ndarray, template: Template) -> RegistrationResult:
399
+ cfg = template.registration
400
+ if not cfg.reference_path:
401
+ raise RegistrationError("Homography registration requires 'registration.reference_path'.")
402
+
403
+ ref_path = Path(cfg.reference_path)
404
+ if not ref_path.exists():
405
+ raise RegistrationError(f"Reference image not found: '{ref_path}'")
406
+
407
+ ref_gray = cv2.imread(str(ref_path), cv2.IMREAD_GRAYSCALE)
408
+ if ref_gray is None:
409
+ raise RegistrationError(f"Could not decode reference image: '{ref_path}'")
410
+ ref_gray = cv2.resize(
411
+ ref_gray, (template.page_width, template.page_height), interpolation=cv2.INTER_AREA
412
+ )
413
+
414
+ src_gray = cv2.normalize(ensure_grayscale(image_bgr), None, 0, 255, cv2.NORM_MINMAX)
415
+ ref_norm = cv2.normalize(ref_gray, None, 0, 255, cv2.NORM_MINMAX)
416
+
417
+ orb = cv2.ORB_create(cfg.max_features) # type: ignore[attr-defined]
418
+ kp_src, des_src = orb.detectAndCompute(src_gray, None)
419
+ kp_ref, des_ref = orb.detectAndCompute(ref_norm, None)
420
+
421
+ if des_src is None or des_ref is None or len(kp_src) < 8 or len(kp_ref) < 8:
422
+ raise RegistrationError("Insufficient ORB keypoints for homography alignment.")
423
+
424
+ matcher = cv2.BFMatcher(cv2.NORM_HAMMING, crossCheck=True)
425
+ matches = sorted(matcher.match(des_src, des_ref), key=lambda m: m.distance)
426
+ keep = max(8, int(len(matches) * cfg.good_match_ratio))
427
+ good_matches = matches[:keep]
428
+
429
+ if len(good_matches) < 8:
430
+ raise RegistrationError(f"Only {len(good_matches)} feature matches found (need >= 8).")
431
+
432
+ pts_src = np.asarray([kp_src[m.queryIdx].pt for m in good_matches], dtype=np.float32).reshape(
433
+ -1, 1, 2
434
+ )
435
+ pts_ref = np.asarray([kp_ref[m.trainIdx].pt for m in good_matches], dtype=np.float32).reshape(
436
+ -1, 1, 2
437
+ )
438
+
439
+ matrix, mask = cv2.findHomography(pts_src, pts_ref, cv2.RANSAC, 5.0)
440
+ if matrix is None:
441
+ raise RegistrationError("RANSAC homography estimation failed.")
442
+
443
+ inlier_ratio = (
444
+ float(np.mean(np.asarray(mask, dtype=np.float32)))
445
+ if mask is not None and mask.size > 0
446
+ else 0.5
447
+ )
448
+ warped = cv2.warpPerspective(
449
+ image_bgr,
450
+ matrix,
451
+ (template.page_width, template.page_height),
452
+ flags=cv2.INTER_LINEAR,
453
+ borderMode=cv2.BORDER_CONSTANT,
454
+ borderValue=(255, 255, 255),
455
+ )
456
+ return RegistrationResult(
457
+ warped_bgr=warped,
458
+ method="homography",
459
+ score=round(inlier_ratio, 4),
460
+ rotation_deg=0,
461
+ )
462
+
463
+
464
+ def register_sheet(image_bgr: np.ndarray, template: Template) -> RegistrationResult:
465
+ """Align and perspective-warp an input sheet image to canonical template coordinates."""
466
+ mode = template.registration.mode
467
+ if mode == "aruco":
468
+ return _register_aruco(image_bgr, template)
469
+ if mode == "markers":
470
+ return _register_markers(image_bgr, template)
471
+ if mode == "page_quad":
472
+ return _register_page_quad(image_bgr, template)
473
+ if mode == "homography":
474
+ return _register_homography(image_bgr, template)
475
+
476
+ resized = cv2.resize(
477
+ image_bgr,
478
+ (template.page_width, template.page_height),
479
+ interpolation=cv2.INTER_AREA,
480
+ )
481
+ return RegistrationResult(
482
+ warped_bgr=resized,
483
+ method="none",
484
+ score=1.0,
485
+ rotation_deg=0,
486
+ )
@@ -0,0 +1,99 @@
1
+ """Annotated visual overlays for scan verification and graded sheet review."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import cv2
6
+ import numpy as np
7
+
8
+ from omrkit.models.grading import StudentGrade
9
+ from omrkit.models.scan import SheetResult
10
+
11
+ # BGR color constants
12
+ _CLR_OK = (95, 138, 15) # Emerald green
13
+ _CLR_WARN = (6, 119, 217) # Amber
14
+ _CLR_ERR = (38, 38, 220) # Crimson red
15
+ _CLR_BLANK = (165, 165, 165) # Neutral gray
16
+ _CLR_EXPECTED = (205, 115, 25) # Steel blue
17
+ _CLR_INK = (31, 24, 20)
18
+
19
+
20
+ def render_annotated_sheet(
21
+ warped_bgr: np.ndarray,
22
+ result: SheetResult,
23
+ grade: StudentGrade | None = None,
24
+ ) -> np.ndarray:
25
+ """Draw color-coded optical readings, confidence signals, and optional grading feedback."""
26
+ canvas = warped_bgr.copy()
27
+ verdict_map = {v.question_id: v for v in grade.verdicts} if grade is not None else {}
28
+
29
+ for field_id, reading in result.fields.items():
30
+ verdict = verdict_map.get(field_id)
31
+
32
+ for bubble in reading.bubbles:
33
+ cx, cy = round(bubble.cx), round(bubble.cy)
34
+ r = max(4, round(bubble.radius))
35
+
36
+ if verdict is not None:
37
+ is_expected = bubble.option in verdict.expected
38
+ if bubble.selected and verdict.verdict in {"correct", "bonus"}:
39
+ cv2.circle(canvas, (cx, cy), r + 2, _CLR_OK, 3, cv2.LINE_AA)
40
+ elif bubble.selected and verdict.verdict == "incorrect":
41
+ cv2.circle(canvas, (cx, cy), r + 2, _CLR_ERR, 3, cv2.LINE_AA)
42
+ elif is_expected and verdict.verdict in {"incorrect", "blank"}:
43
+ cv2.circle(canvas, (cx, cy), r + 2, _CLR_EXPECTED, 2, cv2.LINE_AA)
44
+ else:
45
+ cv2.circle(canvas, (cx, cy), r, _CLR_BLANK, 1, cv2.LINE_AA)
46
+ continue
47
+
48
+ if bubble.selected:
49
+ if reading.status == "multi_marked":
50
+ color = _CLR_ERR
51
+ elif reading.status == "low_confidence":
52
+ color = _CLR_WARN
53
+ else:
54
+ color = _CLR_OK
55
+ cv2.circle(canvas, (cx, cy), r + 2, color, 3, cv2.LINE_AA)
56
+ cv2.putText(
57
+ canvas,
58
+ bubble.option,
59
+ (cx - r // 2, cy - r - 4),
60
+ cv2.FONT_HERSHEY_SIMPLEX,
61
+ 0.45,
62
+ color,
63
+ 1,
64
+ cv2.LINE_AA,
65
+ )
66
+ else:
67
+ border_color = _CLR_WARN if reading.status == "low_confidence" else _CLR_BLANK
68
+ cv2.circle(canvas, (cx, cy), r, border_color, 1, cv2.LINE_AA)
69
+
70
+ # Compact status header banner
71
+ banner_h = 44
72
+ overlay = canvas.copy()
73
+ cv2.rectangle(overlay, (0, 0), (canvas.shape[1], banner_h), (246, 249, 250), -1)
74
+ cv2.addWeighted(overlay, 0.88, canvas, 0.12, 0, canvas)
75
+ cv2.line(canvas, (0, banner_h), (canvas.shape[1], banner_h), (210, 215, 220), 1)
76
+
77
+ if grade is not None:
78
+ header = (
79
+ f"OMRKit | {result.source_file} | Score: {grade.raw_score:.2f}/{grade.max_score:.2f} "
80
+ f"({grade.percentage:.1f}%) | +{grade.correct} -{grade.incorrect} o{grade.blank}"
81
+ )
82
+ else:
83
+ header = (
84
+ f"OMRKit | {result.source_file} | Conf: {result.overall_confidence * 100:.1f}% "
85
+ f"| Review Flags: {len(result.review_items)} | Reg: {result.registration_method}"
86
+ )
87
+
88
+ cv2.putText(
89
+ canvas,
90
+ header,
91
+ (16, 28),
92
+ cv2.FONT_HERSHEY_SIMPLEX,
93
+ 0.58,
94
+ _CLR_INK,
95
+ 1,
96
+ cv2.LINE_AA,
97
+ )
98
+ result_img: np.ndarray = canvas
99
+ return result_img