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
|
@@ -0,0 +1,313 @@
|
|
|
1
|
+
"""Shape-aware hybrid bubble detector with calibrated HITL confidence scoring."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import math
|
|
6
|
+
from functools import lru_cache
|
|
7
|
+
|
|
8
|
+
import numpy as np
|
|
9
|
+
|
|
10
|
+
from omrkit.models.scan import BubbleReading, FieldReading, FieldStatus, ReviewItem
|
|
11
|
+
from omrkit.models.template import BubbleCoord, DetectionConfig, FieldBlock, Template
|
|
12
|
+
from omrkit.vision.preprocess import ensure_grayscale, normalize_illumination
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@lru_cache(maxsize=64)
|
|
16
|
+
def _radial_masks(
|
|
17
|
+
half_size: int,
|
|
18
|
+
radius: float,
|
|
19
|
+
inner_ratio: float,
|
|
20
|
+
ring_inner_ratio: float,
|
|
21
|
+
ring_outer_ratio: float,
|
|
22
|
+
) -> tuple[np.ndarray, np.ndarray]:
|
|
23
|
+
"""Build cached circular inner-core and local-background-ring boolean masks."""
|
|
24
|
+
size = 2 * half_size + 1
|
|
25
|
+
yy, xx = np.ogrid[:size, :size]
|
|
26
|
+
dist_sq = (xx - half_size) ** 2 + (yy - half_size) ** 2
|
|
27
|
+
inner_r = max(1.5, radius * inner_ratio)
|
|
28
|
+
ring_in = radius * ring_inner_ratio
|
|
29
|
+
ring_out = radius * ring_outer_ratio
|
|
30
|
+
inner_mask = dist_sq <= inner_r**2
|
|
31
|
+
ring_mask = (dist_sq >= ring_in**2) & (dist_sq <= ring_out**2)
|
|
32
|
+
return inner_mask, ring_mask
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class HybridBubbleDetector:
|
|
36
|
+
"""Evaluates bubble markings using fill ratio, ring contrast, and ink stroke density.
|
|
37
|
+
|
|
38
|
+
Handles solid fills, partial fills, pen checkmarks/crosses, printed letters inside
|
|
39
|
+
bubbles, and uneven shadows while emitting calibrated per-field confidence scores
|
|
40
|
+
and Human-in-the-Loop (HITL) review flags.
|
|
41
|
+
"""
|
|
42
|
+
|
|
43
|
+
def __init__(self, config: DetectionConfig | None = None) -> None:
|
|
44
|
+
self.config = config or DetectionConfig()
|
|
45
|
+
|
|
46
|
+
def measure_bubble(self, gray: np.ndarray, coord: BubbleCoord) -> BubbleReading:
|
|
47
|
+
"""Compute multi-feature optical scores for a single bubble coordinate."""
|
|
48
|
+
cfg = self.config
|
|
49
|
+
h, w = gray.shape[:2]
|
|
50
|
+
cx = round(coord.cx)
|
|
51
|
+
cy = round(coord.cy)
|
|
52
|
+
half = max(4, math.ceil(coord.radius * cfg.ring_outer_ratio) + 1)
|
|
53
|
+
|
|
54
|
+
# Pad ROI safely if bubble sits near the page edge
|
|
55
|
+
x1, y1 = cx - half, cy - half
|
|
56
|
+
x2, y2 = cx + half + 1, cy + half + 1
|
|
57
|
+
pad_l = max(0, -x1)
|
|
58
|
+
pad_t = max(0, -y1)
|
|
59
|
+
pad_r = max(0, x2 - w)
|
|
60
|
+
pad_b = max(0, y2 - h)
|
|
61
|
+
|
|
62
|
+
patch = gray[max(0, y1) : min(h, y2), max(0, x1) : min(w, x2)]
|
|
63
|
+
if pad_l or pad_t or pad_r or pad_b:
|
|
64
|
+
patch = np.pad(
|
|
65
|
+
patch,
|
|
66
|
+
((pad_t, pad_b), (pad_l, pad_r)),
|
|
67
|
+
mode="edge",
|
|
68
|
+
)
|
|
69
|
+
|
|
70
|
+
inner_mask, ring_mask = _radial_masks(
|
|
71
|
+
half,
|
|
72
|
+
round(coord.radius, 1),
|
|
73
|
+
cfg.inner_radius_ratio,
|
|
74
|
+
cfg.ring_inner_ratio,
|
|
75
|
+
cfg.ring_outer_ratio,
|
|
76
|
+
)
|
|
77
|
+
|
|
78
|
+
inner_px = patch[inner_mask].astype(np.float32)
|
|
79
|
+
ring_px = patch[ring_mask].astype(np.float32)
|
|
80
|
+
|
|
81
|
+
if inner_px.size == 0 or ring_px.size == 0:
|
|
82
|
+
return BubbleReading(
|
|
83
|
+
option=coord.option,
|
|
84
|
+
cx=coord.cx,
|
|
85
|
+
cy=coord.cy,
|
|
86
|
+
radius=coord.radius,
|
|
87
|
+
fill_ratio=0.0,
|
|
88
|
+
darkness=0.0,
|
|
89
|
+
ink_score=0.0,
|
|
90
|
+
combined_score=0.0,
|
|
91
|
+
selected=False,
|
|
92
|
+
)
|
|
93
|
+
|
|
94
|
+
# 75th percentile of outer ring ignores adjacent printed numbers/lines
|
|
95
|
+
ring_bg = float(np.percentile(ring_px, 75))
|
|
96
|
+
fill_ratio = float(np.mean(inner_px < (ring_bg - cfg.fill_delta)))
|
|
97
|
+
darkness = float(
|
|
98
|
+
np.clip((ring_bg - float(np.mean(inner_px))) / max(ring_bg, 1.0), 0.0, 1.0)
|
|
99
|
+
)
|
|
100
|
+
ink_score = float(np.mean(inner_px < (ring_bg - cfg.ink_delta)))
|
|
101
|
+
|
|
102
|
+
combined = float(
|
|
103
|
+
np.clip(
|
|
104
|
+
0.48 * fill_ratio + 0.32 * darkness + 0.20 * min(1.0, ink_score * 2.2),
|
|
105
|
+
0.0,
|
|
106
|
+
1.0,
|
|
107
|
+
)
|
|
108
|
+
)
|
|
109
|
+
|
|
110
|
+
return BubbleReading(
|
|
111
|
+
option=coord.option,
|
|
112
|
+
cx=coord.cx,
|
|
113
|
+
cy=coord.cy,
|
|
114
|
+
radius=coord.radius,
|
|
115
|
+
fill_ratio=round(fill_ratio, 4),
|
|
116
|
+
darkness=round(darkness, 4),
|
|
117
|
+
ink_score=round(ink_score, 4),
|
|
118
|
+
combined_score=round(combined, 4),
|
|
119
|
+
selected=False,
|
|
120
|
+
)
|
|
121
|
+
|
|
122
|
+
def detect_sheet(
|
|
123
|
+
self,
|
|
124
|
+
warped_bgr: np.ndarray,
|
|
125
|
+
template: Template,
|
|
126
|
+
) -> tuple[dict[str, FieldReading], list[ReviewItem]]:
|
|
127
|
+
"""Measure and classify every field block on an aligned sheet image."""
|
|
128
|
+
cfg = template.detection
|
|
129
|
+
# Use template-level detection config for this sheet
|
|
130
|
+
self.config = cfg
|
|
131
|
+
|
|
132
|
+
gray = ensure_grayscale(warped_bgr)
|
|
133
|
+
proc = normalize_illumination(gray) if cfg.normalize_illumination else gray
|
|
134
|
+
|
|
135
|
+
# First pass: measure all raw bubble features across the sheet
|
|
136
|
+
measured_blocks: list[tuple[FieldBlock, list[tuple[str, list[BubbleReading]]]]] = []
|
|
137
|
+
all_scores: list[float] = []
|
|
138
|
+
|
|
139
|
+
for block in template.blocks:
|
|
140
|
+
block_fields: list[tuple[str, list[BubbleReading]]] = []
|
|
141
|
+
for field_id, coords in block.iter_field_bubbles():
|
|
142
|
+
readings = [self.measure_bubble(proc, c) for c in coords]
|
|
143
|
+
all_scores.extend(r.combined_score for r in readings)
|
|
144
|
+
block_fields.append((field_id, readings))
|
|
145
|
+
measured_blocks.append((block, block_fields))
|
|
146
|
+
|
|
147
|
+
# Global baseline captures faint printed letters/borders inside unmarked bubbles
|
|
148
|
+
global_baseline = float(np.percentile(all_scores, 35)) if len(all_scores) >= 10 else 0.05
|
|
149
|
+
global_baseline = min(global_baseline, cfg.blank_floor * 0.9)
|
|
150
|
+
|
|
151
|
+
fields_out: dict[str, FieldReading] = {}
|
|
152
|
+
review_items: list[ReviewItem] = []
|
|
153
|
+
|
|
154
|
+
for block, block_fields in measured_blocks:
|
|
155
|
+
for field_id, readings in block_fields:
|
|
156
|
+
field_reading, review = self._classify_field(
|
|
157
|
+
block=block,
|
|
158
|
+
field_id=field_id,
|
|
159
|
+
readings=readings,
|
|
160
|
+
global_baseline=global_baseline,
|
|
161
|
+
cfg=cfg,
|
|
162
|
+
)
|
|
163
|
+
fields_out[field_id] = field_reading
|
|
164
|
+
if review is not None:
|
|
165
|
+
review_items.append(review)
|
|
166
|
+
|
|
167
|
+
return fields_out, review_items
|
|
168
|
+
|
|
169
|
+
def _classify_field(
|
|
170
|
+
self,
|
|
171
|
+
block: FieldBlock,
|
|
172
|
+
field_id: str,
|
|
173
|
+
readings: list[BubbleReading],
|
|
174
|
+
global_baseline: float,
|
|
175
|
+
cfg: DetectionConfig,
|
|
176
|
+
) -> tuple[FieldReading, ReviewItem | None]:
|
|
177
|
+
scores = [r.combined_score for r in readings]
|
|
178
|
+
ranked_indices = sorted(range(len(scores)), key=lambda i: scores[i], reverse=True)
|
|
179
|
+
|
|
180
|
+
# Estimate local unmarked baseline (captures printed letters inside blank bubbles)
|
|
181
|
+
if len(scores) >= 3:
|
|
182
|
+
non_top = [scores[i] for i in ranked_indices[1:]]
|
|
183
|
+
local_baseline = min(float(np.median(non_top)), cfg.fill_threshold * 0.95)
|
|
184
|
+
else:
|
|
185
|
+
local_baseline = min(global_baseline, cfg.fill_threshold * 0.95)
|
|
186
|
+
|
|
187
|
+
effective_scores = [max(0.0, s - local_baseline) for s in scores]
|
|
188
|
+
top_idx = ranked_indices[0]
|
|
189
|
+
top_raw = scores[top_idx]
|
|
190
|
+
top_eff = effective_scores[top_idx]
|
|
191
|
+
second_idx = ranked_indices[1] if len(ranked_indices) > 1 else None
|
|
192
|
+
second_raw = scores[second_idx] if second_idx is not None else 0.0
|
|
193
|
+
second_eff = effective_scores[second_idx] if second_idx is not None else 0.0
|
|
194
|
+
gap = top_eff - second_eff
|
|
195
|
+
|
|
196
|
+
mark_delta_thresh = max(0.16, cfg.fill_threshold - 0.06)
|
|
197
|
+
blank_delta_floor = max(0.08, cfg.blank_floor - 0.04)
|
|
198
|
+
|
|
199
|
+
selected_indices: list[int] = []
|
|
200
|
+
status: FieldStatus = "ok"
|
|
201
|
+
confidence = 1.0
|
|
202
|
+
review_msg = ""
|
|
203
|
+
|
|
204
|
+
# Case 1: Clearly blank field
|
|
205
|
+
if top_eff < blank_delta_floor and top_raw < (local_baseline + mark_delta_thresh):
|
|
206
|
+
status = "blank"
|
|
207
|
+
margin_below = max(0.0, (mark_delta_thresh - top_eff) / max(mark_delta_thresh, 1e-6))
|
|
208
|
+
confidence = round(float(np.clip(0.84 + 0.15 * margin_below, 0.84, 0.99)), 4)
|
|
209
|
+
|
|
210
|
+
# Case 2: Borderline faint mark or smudge
|
|
211
|
+
elif top_eff < mark_delta_thresh:
|
|
212
|
+
if gap >= cfg.min_separation and readings[top_idx].ink_score >= 0.14:
|
|
213
|
+
selected_indices = [top_idx]
|
|
214
|
+
status = "low_confidence"
|
|
215
|
+
confidence = round(
|
|
216
|
+
float(np.clip(0.55 + (top_eff / mark_delta_thresh) * 0.16, 0.45, 0.71)),
|
|
217
|
+
4,
|
|
218
|
+
)
|
|
219
|
+
review_msg = (
|
|
220
|
+
f"Faint or partial mark detected on '{readings[top_idx].option}' "
|
|
221
|
+
f"(delta={top_eff:.2f}, gap={gap:.2f})."
|
|
222
|
+
)
|
|
223
|
+
else:
|
|
224
|
+
status = "low_confidence"
|
|
225
|
+
confidence = round(
|
|
226
|
+
float(
|
|
227
|
+
np.clip(0.68 - (top_eff / max(mark_delta_thresh, 1e-6)) * 0.20, 0.40, 0.70)
|
|
228
|
+
),
|
|
229
|
+
4,
|
|
230
|
+
)
|
|
231
|
+
review_msg = (
|
|
232
|
+
f"Ambiguous faint smudge near '{readings[top_idx].option}' "
|
|
233
|
+
f"(delta={top_eff:.2f}); verify blank vs marked."
|
|
234
|
+
)
|
|
235
|
+
|
|
236
|
+
# Case 3: At least one bubble clearly stands out above unmarked baseline
|
|
237
|
+
else:
|
|
238
|
+
marked = [
|
|
239
|
+
i
|
|
240
|
+
for i in ranked_indices
|
|
241
|
+
if effective_scores[i] >= mark_delta_thresh
|
|
242
|
+
and effective_scores[i] >= top_eff * cfg.multi_mark_ratio
|
|
243
|
+
]
|
|
244
|
+
if not marked:
|
|
245
|
+
marked = [top_idx]
|
|
246
|
+
|
|
247
|
+
if len(marked) > 1:
|
|
248
|
+
selected_indices = sorted(marked)
|
|
249
|
+
if block.allow_multiple:
|
|
250
|
+
status = "ok"
|
|
251
|
+
confidence = round(float(np.clip(0.82 + 0.16 * top_eff, 0.82, 0.98)), 4)
|
|
252
|
+
else:
|
|
253
|
+
status = "multi_marked"
|
|
254
|
+
confidence = round(float(np.clip(0.35 + 0.25 * gap, 0.25, 0.60)), 4)
|
|
255
|
+
opts = ", ".join(readings[i].option for i in selected_indices)
|
|
256
|
+
review_msg = f"Multiple bubbles marked ({opts}) in single-choice field."
|
|
257
|
+
else:
|
|
258
|
+
selected_indices = [top_idx]
|
|
259
|
+
strength = min(1.0, top_eff / max(mark_delta_thresh * 1.5, 1e-6))
|
|
260
|
+
sep_score = min(1.0, gap / max(cfg.min_separation * 1.5, 1e-6))
|
|
261
|
+
confidence = round(
|
|
262
|
+
float(np.clip(0.45 + 0.30 * strength + 0.25 * sep_score, 0.45, 0.995)),
|
|
263
|
+
4,
|
|
264
|
+
)
|
|
265
|
+
if gap < cfg.min_separation or confidence < cfg.review_confidence_threshold:
|
|
266
|
+
status = "low_confidence"
|
|
267
|
+
runner_up = readings[second_idx].option if second_idx is not None else "-"
|
|
268
|
+
review_msg = (
|
|
269
|
+
f"Low separation between '{readings[top_idx].option}' ({top_raw:.2f}) "
|
|
270
|
+
f"and '{runner_up}' ({second_raw:.2f})."
|
|
271
|
+
)
|
|
272
|
+
else:
|
|
273
|
+
status = "ok"
|
|
274
|
+
|
|
275
|
+
for idx in selected_indices:
|
|
276
|
+
readings[idx].selected = True
|
|
277
|
+
|
|
278
|
+
selected_options = [readings[i].option for i in selected_indices]
|
|
279
|
+
value = "".join(selected_options) if selected_options else block.empty_value
|
|
280
|
+
|
|
281
|
+
field_reading = FieldReading(
|
|
282
|
+
field_id=field_id,
|
|
283
|
+
block_name=block.name,
|
|
284
|
+
value=value,
|
|
285
|
+
selected_options=selected_options,
|
|
286
|
+
confidence=confidence,
|
|
287
|
+
status=status,
|
|
288
|
+
bubbles=readings,
|
|
289
|
+
)
|
|
290
|
+
|
|
291
|
+
review_item: ReviewItem | None = None
|
|
292
|
+
if status in {"low_confidence", "multi_marked"}:
|
|
293
|
+
xs = [r.cx for r in readings]
|
|
294
|
+
ys = [r.cy for r in readings]
|
|
295
|
+
pad = max(18.0, block.bubble_radius * 2.2)
|
|
296
|
+
bbox = (
|
|
297
|
+
max(0, int(min(xs) - pad)),
|
|
298
|
+
max(0, int(min(ys) - pad)),
|
|
299
|
+
int(max(xs) + pad),
|
|
300
|
+
int(max(ys) + pad),
|
|
301
|
+
)
|
|
302
|
+
review_item = ReviewItem(
|
|
303
|
+
field_id=field_id,
|
|
304
|
+
block_name=block.name,
|
|
305
|
+
reason=status,
|
|
306
|
+
suggested_value=value,
|
|
307
|
+
confidence=confidence,
|
|
308
|
+
candidate_options=[r.option for r in readings],
|
|
309
|
+
bbox=bbox,
|
|
310
|
+
message=review_msg,
|
|
311
|
+
)
|
|
312
|
+
|
|
313
|
+
return field_reading, review_item
|
|
@@ -0,0 +1,280 @@
|
|
|
1
|
+
"""Automatic blank-form bubble grid finder for zero-friction custom template bootstrapping."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import itertools
|
|
6
|
+
import math
|
|
7
|
+
from dataclasses import dataclass
|
|
8
|
+
|
|
9
|
+
import cv2
|
|
10
|
+
import numpy as np
|
|
11
|
+
|
|
12
|
+
from omrkit.models.template import (
|
|
13
|
+
DetectionConfig,
|
|
14
|
+
FieldBlock,
|
|
15
|
+
RegistrationConfig,
|
|
16
|
+
Template,
|
|
17
|
+
)
|
|
18
|
+
from omrkit.vision.preprocess import ensure_grayscale, normalize_illumination
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
@dataclass(slots=True)
|
|
22
|
+
class DetectedCircle:
|
|
23
|
+
"""A candidate optical bubble contour found on a blank form."""
|
|
24
|
+
|
|
25
|
+
cx: float
|
|
26
|
+
cy: float
|
|
27
|
+
radius: float
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def _find_candidate_bubbles(image_bgr: np.ndarray) -> list[DetectedCircle]:
|
|
31
|
+
"""Detect printed hollow circular bubbles via adaptive threshold and circularity filtering."""
|
|
32
|
+
gray = normalize_illumination(ensure_grayscale(image_bgr))
|
|
33
|
+
h, w = gray.shape[:2]
|
|
34
|
+
min_dim = min(h, w)
|
|
35
|
+
|
|
36
|
+
# Reasonable bubble radius bounds relative to page width (e.g., 0.5% to 2.8% of min_dim)
|
|
37
|
+
min_r = max(5.0, min_dim * 0.0065)
|
|
38
|
+
max_r = max(24.0, min_dim * 0.026)
|
|
39
|
+
|
|
40
|
+
blurred = cv2.GaussianBlur(gray, (3, 3), 0)
|
|
41
|
+
block_size = max(15, (round(min_dim * 0.025) | 1))
|
|
42
|
+
binary = cv2.adaptiveThreshold(
|
|
43
|
+
blurred,
|
|
44
|
+
255,
|
|
45
|
+
cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
|
|
46
|
+
cv2.THRESH_BINARY_INV,
|
|
47
|
+
block_size,
|
|
48
|
+
8,
|
|
49
|
+
)
|
|
50
|
+
close_k = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3))
|
|
51
|
+
binary = cv2.morphologyEx(binary, cv2.MORPH_CLOSE, close_k)
|
|
52
|
+
|
|
53
|
+
contours, _ = cv2.findContours(binary, cv2.RETR_LIST, cv2.CHAIN_APPROX_SIMPLE)
|
|
54
|
+
raw: list[DetectedCircle] = []
|
|
55
|
+
|
|
56
|
+
for cnt in contours:
|
|
57
|
+
area = float(cv2.contourArea(cnt))
|
|
58
|
+
if area < math.pi * (min_r * 0.72) ** 2 or area > math.pi * (max_r * 1.25) ** 2:
|
|
59
|
+
continue
|
|
60
|
+
peri = float(cv2.arcLength(cnt, True))
|
|
61
|
+
if peri <= 1e-6:
|
|
62
|
+
continue
|
|
63
|
+
circularity = (4.0 * math.pi * area) / (peri * peri)
|
|
64
|
+
if circularity < 0.58:
|
|
65
|
+
continue
|
|
66
|
+
|
|
67
|
+
_x, _y, bw, bh = cv2.boundingRect(cnt)
|
|
68
|
+
aspect = bw / max(float(bh), 1.0)
|
|
69
|
+
if aspect < 0.72 or aspect > 1.38:
|
|
70
|
+
continue
|
|
71
|
+
|
|
72
|
+
(cx, cy), radius = cv2.minEnclosingCircle(cnt)
|
|
73
|
+
if min_r <= radius <= max_r:
|
|
74
|
+
raw.append(DetectedCircle(cx=float(cx), cy=float(cy), radius=float(radius)))
|
|
75
|
+
|
|
76
|
+
if not raw:
|
|
77
|
+
return []
|
|
78
|
+
|
|
79
|
+
# Filter to dominant bubble radius cluster (eliminates tiny dots or huge logos/markers)
|
|
80
|
+
radii = np.asarray([c.radius for c in raw], dtype=np.float32)
|
|
81
|
+
median_r = float(np.median(radii))
|
|
82
|
+
consistent = [c for c in raw if 0.72 * median_r <= c.radius <= 1.32 * median_r]
|
|
83
|
+
|
|
84
|
+
# Non-maximum deduplication (inner/outer contour of the same circle outline)
|
|
85
|
+
consistent.sort(key=lambda c: c.radius, reverse=True)
|
|
86
|
+
deduped: list[DetectedCircle] = []
|
|
87
|
+
min_dist_sq = (median_r * 1.15) ** 2
|
|
88
|
+
for cand in consistent:
|
|
89
|
+
if all(
|
|
90
|
+
(cand.cx - kept.cx) ** 2 + (cand.cy - kept.cy) ** 2 > min_dist_sq for kept in deduped
|
|
91
|
+
):
|
|
92
|
+
deduped.append(cand)
|
|
93
|
+
|
|
94
|
+
return deduped
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def _cluster_rows(circles: list[DetectedCircle], y_tol: float) -> list[list[DetectedCircle]]:
|
|
98
|
+
"""Group circles sharing roughly the same Y coordinate into horizontal strips."""
|
|
99
|
+
sorted_c = sorted(circles, key=lambda c: c.cy)
|
|
100
|
+
rows: list[list[DetectedCircle]] = []
|
|
101
|
+
for c in sorted_c:
|
|
102
|
+
if not rows or abs(c.cy - float(np.mean([p.cy for p in rows[-1]]))) > y_tol:
|
|
103
|
+
rows.append([c])
|
|
104
|
+
else:
|
|
105
|
+
rows[-1].append(c)
|
|
106
|
+
for row in rows:
|
|
107
|
+
row.sort(key=lambda c: c.cx)
|
|
108
|
+
return rows
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
def _split_row_segments(row: list[DetectedCircle], max_gap: float) -> list[list[DetectedCircle]]:
|
|
112
|
+
"""Split a horizontal row of bubbles into contiguous option groups separated by large X gaps."""
|
|
113
|
+
if not row:
|
|
114
|
+
return []
|
|
115
|
+
segments: list[list[DetectedCircle]] = [[row[0]]]
|
|
116
|
+
for c in row[1:]:
|
|
117
|
+
if c.cx - segments[-1][-1].cx <= max_gap:
|
|
118
|
+
segments[-1].append(c)
|
|
119
|
+
else:
|
|
120
|
+
segments.append([c])
|
|
121
|
+
return [seg for seg in segments if len(seg) >= 3]
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def detect_layout_from_blank(
|
|
125
|
+
image_bgr: np.ndarray,
|
|
126
|
+
template_name: str = "auto_detected_template",
|
|
127
|
+
) -> tuple[Template, int]:
|
|
128
|
+
"""Automatically infer OMRKit FieldBlocks from a blank optical form image.
|
|
129
|
+
|
|
130
|
+
Returns (Template, total_bubbles_detected).
|
|
131
|
+
"""
|
|
132
|
+
h, w = image_bgr.shape[:2]
|
|
133
|
+
circles = _find_candidate_bubbles(image_bgr)
|
|
134
|
+
if len(circles) < 4:
|
|
135
|
+
raise ValueError(
|
|
136
|
+
f"Could not detect enough circular bubbles ({len(circles)} found). "
|
|
137
|
+
"Upload a clean blank sheet image or draw blocks manually."
|
|
138
|
+
)
|
|
139
|
+
|
|
140
|
+
median_r = float(np.median([c.radius for c in circles]))
|
|
141
|
+
rows = _cluster_rows(circles, y_tol=median_r * 0.9)
|
|
142
|
+
|
|
143
|
+
# Estimate typical intra-group spacing from nearest horizontal neighbor distances
|
|
144
|
+
horiz_diffs: list[float] = []
|
|
145
|
+
for row in rows:
|
|
146
|
+
for a, b in itertools.pairwise(row):
|
|
147
|
+
dx = b.cx - a.cx
|
|
148
|
+
if median_r * 1.6 <= dx <= median_r * 7.5:
|
|
149
|
+
horiz_diffs.append(dx)
|
|
150
|
+
base_gap = float(np.median(horiz_diffs)) if horiz_diffs else median_r * 3.0
|
|
151
|
+
max_intra_gap = base_gap * 1.65
|
|
152
|
+
|
|
153
|
+
# Extract horizontal bubble segments across all rows
|
|
154
|
+
all_segments: list[tuple[float, float, int, list[DetectedCircle]]] = []
|
|
155
|
+
for row in rows:
|
|
156
|
+
for seg in _split_row_segments(row, max_gap=max_intra_gap):
|
|
157
|
+
x_start = seg[0].cx
|
|
158
|
+
y_mean = float(np.mean([p.cy for p in seg]))
|
|
159
|
+
all_segments.append((x_start, y_mean, len(seg), seg))
|
|
160
|
+
|
|
161
|
+
# Stack aligned segments top-to-bottom within each horizontal column band
|
|
162
|
+
band_w = max(12.0, median_r * 3.0)
|
|
163
|
+
all_segments.sort(key=lambda item: (round(item[0] / band_w), item[1]))
|
|
164
|
+
used = [False] * len(all_segments)
|
|
165
|
+
raw_groups: list[list[list[DetectedCircle]]] = []
|
|
166
|
+
|
|
167
|
+
for i, (x0, y0, n_opts, seg0) in enumerate(all_segments):
|
|
168
|
+
if used[i]:
|
|
169
|
+
continue
|
|
170
|
+
used[i] = True
|
|
171
|
+
stack: list[list[DetectedCircle]] = [seg0]
|
|
172
|
+
last_y = y0
|
|
173
|
+
|
|
174
|
+
candidates = sorted(
|
|
175
|
+
(
|
|
176
|
+
(all_segments[j][1], j)
|
|
177
|
+
for j in range(len(all_segments))
|
|
178
|
+
if not used[j]
|
|
179
|
+
and all_segments[j][2] == n_opts
|
|
180
|
+
and abs(all_segments[j][0] - x0) <= median_r * 1.3
|
|
181
|
+
and all_segments[j][1] > last_y
|
|
182
|
+
),
|
|
183
|
+
key=lambda pair: pair[0],
|
|
184
|
+
)
|
|
185
|
+
max_step_y = max(median_r * 8.0, base_gap * 3.1)
|
|
186
|
+
for cand_y, j in candidates:
|
|
187
|
+
if cand_y - last_y <= max_step_y:
|
|
188
|
+
used[j] = True
|
|
189
|
+
stack.append(all_segments[j][3])
|
|
190
|
+
last_y = cand_y
|
|
191
|
+
|
|
192
|
+
if len(stack) >= 2:
|
|
193
|
+
raw_groups.append(stack)
|
|
194
|
+
|
|
195
|
+
# Sort detected blocks left-to-right, then top-to-bottom
|
|
196
|
+
raw_groups.sort(key=lambda g: (round(g[0][0].cx / 80.0), g[0][0].cy))
|
|
197
|
+
|
|
198
|
+
blocks: list[FieldBlock] = []
|
|
199
|
+
q_counter = 1
|
|
200
|
+
id_counter = 1
|
|
201
|
+
|
|
202
|
+
for stack in raw_groups:
|
|
203
|
+
n_cols = len(stack[0])
|
|
204
|
+
xs_start = [row[0].cx for row in stack]
|
|
205
|
+
ys_rows = [float(np.mean([p.cy for p in row])) for row in stack]
|
|
206
|
+
|
|
207
|
+
origin_x = round(float(np.median(xs_start)), 1)
|
|
208
|
+
origin_y = round(ys_rows[0], 1)
|
|
209
|
+
|
|
210
|
+
col_gaps = [
|
|
211
|
+
(row[-1].cx - row[0].cx) / float(max(1, n_cols - 1)) for row in stack if n_cols > 1
|
|
212
|
+
]
|
|
213
|
+
raw_row_gaps = [ys_rows[k + 1] - ys_rows[k] for k in range(len(ys_rows) - 1)]
|
|
214
|
+
# Use lower-half median of row gaps to ignore occasional skipped rows
|
|
215
|
+
unit_gaps = [g for g in raw_row_gaps if g <= float(np.min(raw_row_gaps)) * 1.45]
|
|
216
|
+
dy_val = float(np.median(unit_gaps)) if unit_gaps else base_gap
|
|
217
|
+
# Reconstruct exact row count spanning first to last detected row
|
|
218
|
+
n_rows = max(len(stack), round((ys_rows[-1] - ys_rows[0]) / max(dy_val, 1.0)) + 1)
|
|
219
|
+
|
|
220
|
+
dx = round(float(np.median(col_gaps)) if col_gaps else base_gap, 2)
|
|
221
|
+
dy = round((ys_rows[-1] - ys_rows[0]) / float(max(1, n_rows - 1)), 2)
|
|
222
|
+
radius = round(median_r, 1)
|
|
223
|
+
|
|
224
|
+
# Heuristic: 10-row grid is almost always a vertical 0-9 digit ID block
|
|
225
|
+
if n_rows == 10 and n_cols >= 4:
|
|
226
|
+
gid = f"ID_GRID_{id_counter}"
|
|
227
|
+
prefix_letter = chr(ord("a") + (id_counter - 1) % 26)
|
|
228
|
+
id_counter += 1
|
|
229
|
+
blocks.append(
|
|
230
|
+
FieldBlock(
|
|
231
|
+
name=gid,
|
|
232
|
+
field_type="grid_digits",
|
|
233
|
+
direction="vertical",
|
|
234
|
+
origin=(origin_x, origin_y),
|
|
235
|
+
origin_mode="center",
|
|
236
|
+
bubble_radius=radius,
|
|
237
|
+
bubbles_gap=dy,
|
|
238
|
+
labels_gap=dx,
|
|
239
|
+
options=[str(d) for d in range(10)],
|
|
240
|
+
labels=[f"id{prefix_letter}_1..{n_cols}"],
|
|
241
|
+
group_as=gid,
|
|
242
|
+
validator="digits",
|
|
243
|
+
)
|
|
244
|
+
)
|
|
245
|
+
else:
|
|
246
|
+
opt_labels = [chr(ord("A") + idx) for idx in range(n_cols)]
|
|
247
|
+
end_q = q_counter + n_rows - 1
|
|
248
|
+
blocks.append(
|
|
249
|
+
FieldBlock(
|
|
250
|
+
name=f"MCQ_BLOCK_{len(blocks) + 1}",
|
|
251
|
+
field_type="mcq",
|
|
252
|
+
direction="horizontal",
|
|
253
|
+
origin=(origin_x, origin_y),
|
|
254
|
+
origin_mode="center",
|
|
255
|
+
bubble_radius=radius,
|
|
256
|
+
bubbles_gap=dx,
|
|
257
|
+
labels_gap=dy,
|
|
258
|
+
options=opt_labels,
|
|
259
|
+
labels=[f"q{q_counter}..{end_q}"],
|
|
260
|
+
)
|
|
261
|
+
)
|
|
262
|
+
q_counter = end_q + 1
|
|
263
|
+
|
|
264
|
+
if not blocks:
|
|
265
|
+
raise ValueError(
|
|
266
|
+
f"Detected {len(circles)} bubbles but could not cluster them into regular grids."
|
|
267
|
+
)
|
|
268
|
+
|
|
269
|
+
template = Template(
|
|
270
|
+
version="2.0",
|
|
271
|
+
name=template_name,
|
|
272
|
+
description=f"Auto-detected layout ({len(blocks)} blocks, {len(circles)} candidate bubbles)",
|
|
273
|
+
page_width=w,
|
|
274
|
+
page_height=h,
|
|
275
|
+
registration=RegistrationConfig(mode="none"),
|
|
276
|
+
detection=DetectionConfig(),
|
|
277
|
+
blocks=blocks,
|
|
278
|
+
metadata={"auto_detected_bubbles": len(circles)},
|
|
279
|
+
)
|
|
280
|
+
return template, len(circles)
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
"""Image preprocessing utilities for shadow-invariant optical mark reading."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import cv2
|
|
6
|
+
import numpy as np
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def ensure_grayscale(image: np.ndarray) -> np.ndarray:
|
|
10
|
+
"""Convert a BGR/BGRA or single-channel image to 8-bit grayscale."""
|
|
11
|
+
if image.ndim == 2:
|
|
12
|
+
return image.astype(np.uint8, copy=False)
|
|
13
|
+
if image.shape[2] == 4:
|
|
14
|
+
return cv2.cvtColor(image, cv2.COLOR_BGRA2GRAY)
|
|
15
|
+
return cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def normalize_illumination(gray: np.ndarray, blur_ratio: float = 0.045) -> np.ndarray:
|
|
19
|
+
"""Remove uneven lighting and camera shadows via smooth background division.
|
|
20
|
+
|
|
21
|
+
Estimates the slowly varying paper illumination field on a downscaled copy for
|
|
22
|
+
speed, then divides pixel intensity by that field so marks retain high contrast
|
|
23
|
+
even under harsh shadows or warm indoor lighting.
|
|
24
|
+
"""
|
|
25
|
+
h, w = gray.shape[:2]
|
|
26
|
+
scale = 4 if min(h, w) >= 600 else 2
|
|
27
|
+
small_w = max(32, w // scale)
|
|
28
|
+
small_h = max(32, h // scale)
|
|
29
|
+
small = cv2.resize(gray, (small_w, small_h), interpolation=cv2.INTER_AREA)
|
|
30
|
+
|
|
31
|
+
# Morphological closing removes dark ink/bubbles from the background estimate
|
|
32
|
+
close_k = max(5, int(min(small_w, small_h) * 0.025) | 1)
|
|
33
|
+
close_kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (close_k, close_k))
|
|
34
|
+
bg_small = cv2.morphologyEx(small, cv2.MORPH_CLOSE, close_kernel)
|
|
35
|
+
|
|
36
|
+
blur_k = max(7, int(min(small_w, small_h) * blur_ratio) | 1)
|
|
37
|
+
bg_small = cv2.GaussianBlur(bg_small, (blur_k, blur_k), 0)
|
|
38
|
+
bg = cv2.resize(bg_small, (w, h), interpolation=cv2.INTER_LINEAR)
|
|
39
|
+
|
|
40
|
+
# Divide gray by background illumination to flatten lighting gradients
|
|
41
|
+
ratio = (gray.astype(np.float32) + 1.0) / (bg.astype(np.float32) + 1.0)
|
|
42
|
+
normalized = np.clip(ratio * 245.0, 0.0, 255.0).astype(np.uint8)
|
|
43
|
+
return normalized
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def rotate_image(image: np.ndarray, degrees: int) -> np.ndarray:
|
|
47
|
+
"""Rotate an image clockwise by a multiple of 90 degrees."""
|
|
48
|
+
normalized_deg = degrees % 360
|
|
49
|
+
if normalized_deg == 0:
|
|
50
|
+
return image
|
|
51
|
+
if normalized_deg == 90:
|
|
52
|
+
return cv2.rotate(image, cv2.ROTATE_90_CLOCKWISE)
|
|
53
|
+
if normalized_deg == 180:
|
|
54
|
+
return cv2.rotate(image, cv2.ROTATE_180)
|
|
55
|
+
if normalized_deg == 270:
|
|
56
|
+
return cv2.rotate(image, cv2.ROTATE_90_COUNTERCLOCKWISE)
|
|
57
|
+
raise ValueError(f"Expected a multiple of 90 degrees, got {degrees}.")
|