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