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,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}.")