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,508 @@
1
+ """Vector PDF optical sheet generator with ArUco anchors and zero-calibration Template output."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import io
6
+ import math
7
+ from dataclasses import dataclass
8
+ from pathlib import Path
9
+
10
+ import cv2
11
+ from PIL import Image
12
+ from reportlab.lib import colors
13
+ from reportlab.lib.utils import ImageReader
14
+ from reportlab.pdfgen import canvas as rl_canvas
15
+
16
+ from omrkit.generator.presets import SheetSpec
17
+ from omrkit.models.grading import AnswerKey
18
+ from omrkit.models.template import (
19
+ DetectionConfig,
20
+ FieldBlock,
21
+ RegistrationConfig,
22
+ Template,
23
+ )
24
+ from omrkit.vision.qr import encode_sheet_qr_payload, render_qr_matrix
25
+
26
+ _MM_TO_PT = 72.0 / 25.4
27
+ _PAGE_DIMENSIONS_MM: dict[str, tuple[float, float]] = {
28
+ "A4": (210.0, 297.0),
29
+ "LETTER": (215.9, 279.4),
30
+ }
31
+
32
+
33
+ @dataclass(slots=True)
34
+ class GeneratedSheet:
35
+ """Paired printable PDF bytes, pixel-exact Template, and sample AnswerKey."""
36
+
37
+ pdf_bytes: bytes
38
+ template: Template
39
+ sample_answer_key: AnswerKey
40
+
41
+
42
+ def _aruco_image_reader(marker_id: int, pixel_size: int = 240) -> ImageReader:
43
+ dictionary = cv2.aruco.getPredefinedDictionary(cv2.aruco.DICT_4X4_50)
44
+ marker_img = cv2.aruco.generateImageMarker(dictionary, marker_id, pixel_size)
45
+ # Add crisp 1-module white quiet zone around the black border
46
+ pad = pixel_size // 8
47
+ padded = cv2.copyMakeBorder(marker_img, pad, pad, pad, pad, cv2.BORDER_CONSTANT, value=255)
48
+ pil_img = Image.fromarray(padded).convert("L")
49
+ buf = io.BytesIO()
50
+ pil_img.save(buf, format="PNG")
51
+ buf.seek(0)
52
+ return ImageReader(buf)
53
+
54
+
55
+ def _qr_image_reader(preset_id: str, pixel_size: int = 220) -> ImageReader:
56
+ payload = encode_sheet_qr_payload(preset_id)
57
+ qr_img = render_qr_matrix(payload, pixel_size=pixel_size)
58
+ pil_img = Image.fromarray(qr_img).convert("L")
59
+ buf = io.BytesIO()
60
+ pil_img.save(buf, format="PNG")
61
+ buf.seek(0)
62
+ return ImageReader(buf)
63
+
64
+
65
+ def _ascii_safe(text: str) -> str:
66
+ """Transliterate Turkish diacritics cleanly for built-in PDF Helvetica fonts."""
67
+ table = str.maketrans("çğıöşüÇĞİÖŞÜ", "cgiosuCGIOSU")
68
+ return text.translate(table)
69
+
70
+
71
+ class SheetGenerator:
72
+ """Generates print-ready vector PDF OMR sheets alongside mathematically exact Templates."""
73
+
74
+ def generate(self, spec: SheetSpec) -> GeneratedSheet:
75
+ """Render the PDF in memory and construct its zero-calibration Template."""
76
+ page_w_mm, page_h_mm = _PAGE_DIMENSIONS_MM[spec.page_format]
77
+ dpi = spec.dpi
78
+ mm_to_px = dpi / 25.4
79
+ page_w_px = round(page_w_mm * mm_to_px)
80
+ page_h_px = round(page_h_mm * mm_to_px)
81
+ page_w_pt = page_w_mm * _MM_TO_PT
82
+ page_h_pt = page_h_mm * _MM_TO_PT
83
+
84
+ buf = io.BytesIO()
85
+ pdf = rl_canvas.Canvas(buf, pagesize=(page_w_pt, page_h_pt))
86
+ pdf.setTitle(_ascii_safe(spec.title))
87
+ pdf.setAuthor("OMRKit v2.0")
88
+
89
+ def x_pt(x_mm: float) -> float:
90
+ return x_mm * _MM_TO_PT
91
+
92
+ def y_pt(y_mm_top: float) -> float:
93
+ return page_h_pt - (y_mm_top * _MM_TO_PT)
94
+
95
+ # 1. Draw 4 ArUco corner markers (IDs 0=TL, 1=TR, 2=BR, 3=BL)
96
+ marker_draw_mm = 15.0 # includes quiet zone
97
+ margin_mm = 13.5
98
+ corner_centers_mm = [
99
+ (margin_mm, margin_mm), # TL (ID 0)
100
+ (page_w_mm - margin_mm, margin_mm), # TR (ID 1)
101
+ (page_w_mm - margin_mm, page_h_mm - margin_mm), # BR (ID 2)
102
+ (margin_mm, page_h_mm - margin_mm), # BL (ID 3)
103
+ ]
104
+ for marker_id, (mx, my) in enumerate(corner_centers_mm):
105
+ reader = _aruco_image_reader(marker_id)
106
+ half = marker_draw_mm / 2.0
107
+ pdf.drawImage(
108
+ reader,
109
+ x_pt(mx - half),
110
+ y_pt(my + half),
111
+ width=marker_draw_mm * _MM_TO_PT,
112
+ height=marker_draw_mm * _MM_TO_PT,
113
+ preserveAspectRatio=True,
114
+ mask=None,
115
+ )
116
+
117
+ target_corners_px = [
118
+ (round(mx * mm_to_px, 2), round(my * mm_to_px, 2)) for mx, my in corner_centers_mm
119
+ ]
120
+
121
+ # 2. Header band
122
+ ink = colors.HexColor("#18202A")
123
+ muted = colors.HexColor("#5C6773")
124
+ border = colors.HexColor("#CBD3DC")
125
+ header_bg = colors.HexColor("#F4F6F8")
126
+
127
+ pdf.setFillColor(ink)
128
+ pdf.setFont("Helvetica-Bold", 14)
129
+ pdf.drawCentredString(page_w_pt / 2.0, y_pt(13.0), _ascii_safe(spec.title))
130
+ pdf.setFillColor(muted)
131
+ pdf.setFont("Helvetica", 8.5)
132
+ pdf.drawCentredString(page_w_pt / 2.0, y_pt(18.5), _ascii_safe(spec.subtitle))
133
+
134
+ # Name / Date box + embedded auto-detect QR template identifier
135
+ qr_size_mm = 15.0
136
+ qr_left_mm = page_w_mm - 41.0
137
+ qr_top_mm = 20.0
138
+ pdf.drawImage(
139
+ _qr_image_reader(spec.preset_id),
140
+ x_pt(qr_left_mm),
141
+ y_pt(qr_top_mm + qr_size_mm),
142
+ width=qr_size_mm * _MM_TO_PT,
143
+ height=qr_size_mm * _MM_TO_PT,
144
+ preserveAspectRatio=True,
145
+ mask=None,
146
+ )
147
+
148
+ box_left = 26.0
149
+ box_right = qr_left_mm - 3.0
150
+ pdf.setStrokeColor(border)
151
+ pdf.setLineWidth(0.7)
152
+ pdf.roundRect(
153
+ x_pt(box_left),
154
+ y_pt(32.0),
155
+ (box_right - box_left) * _MM_TO_PT,
156
+ 9.5 * _MM_TO_PT,
157
+ 2.0,
158
+ stroke=1,
159
+ fill=0,
160
+ )
161
+ pdf.setFillColor(muted)
162
+ pdf.setFont("Helvetica-Bold", 7.5)
163
+ pdf.drawString(x_pt(box_left + 3.0), y_pt(28.5), "NAME / SURNAME:")
164
+ pdf.drawString(x_pt(box_right - 44.0), y_pt(28.5), "DATE:")
165
+
166
+ blocks: list[FieldBlock] = []
167
+ content_left = 18.0
168
+ content_right = page_w_mm - 18.0
169
+ content_w = content_right - content_left
170
+
171
+ # 3. Optional Top Row: ID Grids + Booklet selector
172
+ id_row_top = 37.5
173
+ id_bubble_r_mm = 2.0
174
+ id_bubbles_gap_mm = 5.4
175
+ id_labels_gap_mm = 5.6
176
+ cursor_x = content_left
177
+ id_section_bottom = id_row_top
178
+
179
+ for grid in spec.id_grids:
180
+ grid_w = (grid.digits - 1) * id_labels_gap_mm + 10.0
181
+ grid_h = 11.0 + (len(grid.options) - 1) * id_bubbles_gap_mm + 6.5
182
+
183
+ # Card container
184
+ pdf.setFillColor(header_bg)
185
+ pdf.setStrokeColor(border)
186
+ pdf.setLineWidth(0.6)
187
+ pdf.rect(
188
+ x_pt(cursor_x),
189
+ y_pt(id_row_top + 6.2),
190
+ grid_w * _MM_TO_PT,
191
+ 6.2 * _MM_TO_PT,
192
+ stroke=1,
193
+ fill=1,
194
+ )
195
+ pdf.setFillColor(ink)
196
+ pdf.setFont("Helvetica-Bold", 7.5)
197
+ pdf.drawCentredString(
198
+ x_pt(cursor_x + grid_w / 2.0),
199
+ y_pt(id_row_top + 4.3),
200
+ _ascii_safe(grid.title.upper()),
201
+ )
202
+
203
+ # Outer grid frame
204
+ pdf.rect(
205
+ x_pt(cursor_x),
206
+ y_pt(id_row_top + grid_h),
207
+ grid_w * _MM_TO_PT,
208
+ (grid_h - 6.2) * _MM_TO_PT,
209
+ stroke=1,
210
+ fill=0,
211
+ )
212
+
213
+ first_cx = cursor_x + 5.0
214
+ first_cy = id_row_top + 11.5
215
+
216
+ # Write digit box row headers
217
+ for d_idx in range(grid.digits):
218
+ cx_mm = first_cx + d_idx * id_labels_gap_mm
219
+ pdf.setStrokeColor(border)
220
+ pdf.rect(
221
+ x_pt(cx_mm - 2.3),
222
+ y_pt(id_row_top + 9.4),
223
+ 4.6 * _MM_TO_PT,
224
+ 3.2 * _MM_TO_PT,
225
+ stroke=1,
226
+ fill=0,
227
+ )
228
+ for opt_idx, opt in enumerate(grid.options):
229
+ cy_mm = first_cy + opt_idx * id_bubbles_gap_mm
230
+ self._draw_bubble(
231
+ pdf, x_pt(cx_mm), y_pt(cy_mm), id_bubble_r_mm * _MM_TO_PT, opt
232
+ )
233
+
234
+ prefix = grid.name.lower()
235
+ blocks.append(
236
+ FieldBlock(
237
+ name=f"ID_{grid.name}",
238
+ field_type="grid_digits",
239
+ direction="vertical",
240
+ origin=(round(first_cx * mm_to_px, 2), round(first_cy * mm_to_px, 2)),
241
+ origin_mode="center",
242
+ bubble_radius=round(id_bubble_r_mm * mm_to_px, 2),
243
+ bubbles_gap=round(id_bubbles_gap_mm * mm_to_px, 2),
244
+ labels_gap=round(id_labels_gap_mm * mm_to_px, 2),
245
+ options=list(grid.options),
246
+ labels=[f"{prefix}_1..{grid.digits}"],
247
+ group_as=grid.name,
248
+ validator=grid.validator,
249
+ )
250
+ )
251
+
252
+ cursor_x += grid_w + 5.0
253
+ id_section_bottom = max(id_section_bottom, id_row_top + grid_h)
254
+
255
+ if spec.include_booklet:
256
+ bk_w = max(32.0, (len(spec.booklet_options) - 1) * 7.5 + 14.0)
257
+ bk_h = 20.0
258
+ # Place booklet card right-aligned in the ID band if space permits
259
+ bk_x = max(cursor_x, content_right - bk_w)
260
+ pdf.setFillColor(header_bg)
261
+ pdf.setStrokeColor(border)
262
+ pdf.setLineWidth(0.6)
263
+ pdf.rect(
264
+ x_pt(bk_x),
265
+ y_pt(id_row_top + 6.2),
266
+ bk_w * _MM_TO_PT,
267
+ 6.2 * _MM_TO_PT,
268
+ stroke=1,
269
+ fill=1,
270
+ )
271
+ pdf.setFillColor(ink)
272
+ pdf.setFont("Helvetica-Bold", 7.5)
273
+ pdf.drawCentredString(x_pt(bk_x + bk_w / 2.0), y_pt(id_row_top + 4.3), "BOOKLET")
274
+ pdf.rect(
275
+ x_pt(bk_x),
276
+ y_pt(id_row_top + bk_h),
277
+ bk_w * _MM_TO_PT,
278
+ (bk_h - 6.2) * _MM_TO_PT,
279
+ stroke=1,
280
+ fill=0,
281
+ )
282
+
283
+ bk_gap = 7.2
284
+ bk_r = 2.2
285
+ bk_first_cx = bk_x + (bk_w - (len(spec.booklet_options) - 1) * bk_gap) / 2.0
286
+ bk_cy = id_row_top + 13.5
287
+ for opt_idx, opt in enumerate(spec.booklet_options):
288
+ self._draw_bubble(
289
+ pdf,
290
+ x_pt(bk_first_cx + opt_idx * bk_gap),
291
+ y_pt(bk_cy),
292
+ bk_r * _MM_TO_PT,
293
+ opt,
294
+ )
295
+
296
+ blocks.append(
297
+ FieldBlock(
298
+ name="BOOKLET_BLOCK",
299
+ field_type="custom",
300
+ direction="horizontal",
301
+ origin=(round(bk_first_cx * mm_to_px, 2), round(bk_cy * mm_to_px, 2)),
302
+ origin_mode="center",
303
+ bubble_radius=round(bk_r * mm_to_px, 2),
304
+ bubbles_gap=round(bk_gap * mm_to_px, 2),
305
+ labels_gap=round(7.0 * mm_to_px, 2),
306
+ options=list(spec.booklet_options),
307
+ labels=["BOOKLET"],
308
+ )
309
+ )
310
+ id_section_bottom = max(id_section_bottom, id_row_top + bk_h)
311
+
312
+ # 4. Multi-column MCQ Answer Grid
313
+ answers_top = id_section_bottom + 7.5
314
+ answers_bottom_limit = page_h_mm - 26.5
315
+ avail_h = answers_bottom_limit - answers_top
316
+
317
+ num_cols = math.ceil(spec.num_questions / spec.questions_per_column)
318
+ col_gap_mm = 4.5
319
+ col_w_mm = (content_w - (num_cols - 1) * col_gap_mm) / num_cols
320
+
321
+ # Dynamically adapt row spacing and bubble sizing to fit cleanly within A4/Letter height
322
+ max_rows = min(spec.questions_per_column, spec.num_questions)
323
+ header_h_mm = 7.0
324
+ row_pitch_mm = min(6.2, max(4.7, (avail_h - header_h_mm - 3.0) / max_rows))
325
+ num_opts = len(spec.options)
326
+ # Space for question number label + options
327
+ q_label_pad_mm = 8.5
328
+ opt_gap_mm = min(6.8, max(4.6, (col_w_mm - q_label_pad_mm - 4.0) / max(1, num_opts - 1)))
329
+ bubble_r_mm = min(2.15, max(1.65, min(row_pitch_mm, opt_gap_mm) * 0.36))
330
+
331
+ sample_answers: dict[str, str | list[str]] = {}
332
+
333
+ for col_idx in range(num_cols):
334
+ q_start = col_idx * spec.questions_per_column + 1
335
+ q_end = min(spec.num_questions, q_start + spec.questions_per_column - 1)
336
+ row_count = q_end - q_start + 1
337
+
338
+ col_x = content_left + col_idx * (col_w_mm + col_gap_mm)
339
+ col_h = header_h_mm + row_count * row_pitch_mm + 2.0
340
+
341
+ # Column header
342
+ pdf.setFillColor(header_bg)
343
+ pdf.setStrokeColor(border)
344
+ pdf.setLineWidth(0.6)
345
+ pdf.rect(
346
+ x_pt(col_x),
347
+ y_pt(answers_top + header_h_mm),
348
+ col_w_mm * _MM_TO_PT,
349
+ header_h_mm * _MM_TO_PT,
350
+ stroke=1,
351
+ fill=1,
352
+ )
353
+ pdf.setFillColor(ink)
354
+ pdf.setFont("Helvetica-Bold", 7.2)
355
+ pdf.drawCentredString(
356
+ x_pt(col_x + col_w_mm / 2.0),
357
+ y_pt(answers_top + 4.7),
358
+ f"QUESTIONS {q_start} - {q_end}",
359
+ )
360
+
361
+ # Column body frame
362
+ pdf.rect(
363
+ x_pt(col_x),
364
+ y_pt(answers_top + col_h),
365
+ col_w_mm * _MM_TO_PT,
366
+ (col_h - header_h_mm) * _MM_TO_PT,
367
+ stroke=1,
368
+ fill=0,
369
+ )
370
+
371
+ first_bubble_x = col_x + q_label_pad_mm + 1.5
372
+ first_bubble_y = answers_top + header_h_mm + row_pitch_mm * 0.65
373
+
374
+ for r_idx in range(row_count):
375
+ q_num = q_start + r_idx
376
+ cy_mm = first_bubble_y + r_idx * row_pitch_mm
377
+
378
+ # Alternating subtle row shading for human readability
379
+ if r_idx % 2 == 1:
380
+ pdf.setFillColor(colors.HexColor("#FAFBFD"))
381
+ pdf.rect(
382
+ x_pt(col_x + 0.4),
383
+ y_pt(cy_mm + row_pitch_mm * 0.48),
384
+ (col_w_mm - 0.8) * _MM_TO_PT,
385
+ (row_pitch_mm * 0.96) * _MM_TO_PT,
386
+ stroke=0,
387
+ fill=1,
388
+ )
389
+
390
+ pdf.setFillColor(ink)
391
+ pdf.setFont("Helvetica-Bold", 7.0)
392
+ pdf.drawRightString(
393
+ x_pt(col_x + q_label_pad_mm - 1.4),
394
+ y_pt(cy_mm + 0.9),
395
+ str(q_num),
396
+ )
397
+
398
+ for opt_idx, opt in enumerate(spec.options):
399
+ cx_mm = first_bubble_x + opt_idx * opt_gap_mm
400
+ self._draw_bubble(pdf, x_pt(cx_mm), y_pt(cy_mm), bubble_r_mm * _MM_TO_PT, opt)
401
+
402
+ sample_answers[f"{spec.question_prefix}{q_num}"] = spec.options[
403
+ (q_num - 1) % len(spec.options)
404
+ ]
405
+
406
+ blocks.append(
407
+ FieldBlock(
408
+ name=f"MCQ_COL_{col_idx + 1}",
409
+ field_type="mcq",
410
+ direction="horizontal",
411
+ origin=(
412
+ round(first_bubble_x * mm_to_px, 2),
413
+ round(first_bubble_y * mm_to_px, 2),
414
+ ),
415
+ origin_mode="center",
416
+ bubble_radius=round(bubble_r_mm * mm_to_px, 2),
417
+ bubbles_gap=round(opt_gap_mm * mm_to_px, 2),
418
+ labels_gap=round(row_pitch_mm * mm_to_px, 2),
419
+ options=list(spec.options),
420
+ labels=[f"{spec.question_prefix}{q_start}..{q_end}"],
421
+ )
422
+ )
423
+
424
+ # Footer note
425
+ pdf.setFillColor(muted)
426
+ pdf.setFont("Helvetica", 7.0)
427
+ pdf.drawCentredString(
428
+ page_w_pt / 2.0,
429
+ y_pt(page_h_mm - 11.5),
430
+ f"OMRKit v2.0 | Preset: {spec.preset_id} | ArUco DICT_4X4_50 [0,1,2,3] | {page_w_px}x{page_h_px}@{dpi}DPI",
431
+ )
432
+
433
+ pdf.showPage()
434
+ pdf.save()
435
+
436
+ template = Template(
437
+ version="2.0",
438
+ name=spec.preset_id,
439
+ description=spec.title,
440
+ page_width=page_w_px,
441
+ page_height=page_h_px,
442
+ registration=RegistrationConfig(
443
+ mode="aruco",
444
+ aruco_dict="DICT_4X4_50",
445
+ aruco_ids=(0, 1, 2, 3),
446
+ target_corners=target_corners_px,
447
+ ),
448
+ detection=DetectionConfig(),
449
+ blocks=blocks,
450
+ metadata={
451
+ "generated_by": "omrkit.SheetGenerator",
452
+ "page_format": spec.page_format,
453
+ "dpi": dpi,
454
+ "num_questions": spec.num_questions,
455
+ },
456
+ )
457
+
458
+ answer_key = AnswerKey(
459
+ exam_name=spec.title,
460
+ booklet_field="BOOKLET" if spec.include_booklet else None,
461
+ default_booklet="A",
462
+ answers=sample_answers,
463
+ )
464
+
465
+ return GeneratedSheet(
466
+ pdf_bytes=buf.getvalue(),
467
+ template=template,
468
+ sample_answer_key=answer_key,
469
+ )
470
+
471
+ @staticmethod
472
+ def _draw_bubble(
473
+ pdf: rl_canvas.Canvas,
474
+ cx_pt: float,
475
+ cy_pt: float,
476
+ radius_pt: float,
477
+ label: str,
478
+ ) -> None:
479
+ """Draw a clean light-outlined circular bubble with a soft interior letter."""
480
+ pdf.setStrokeColor(colors.HexColor("#7B8794"))
481
+ pdf.setLineWidth(0.65)
482
+ pdf.setFillColor(colors.white)
483
+ pdf.circle(cx_pt, cy_pt, radius_pt, stroke=1, fill=1)
484
+
485
+ pdf.setFillColor(colors.HexColor("#B8C2CC"))
486
+ font_size = max(4.8, radius_pt * 1.05)
487
+ pdf.setFont("Helvetica", font_size)
488
+ pdf.drawCentredString(cx_pt, cy_pt - font_size * 0.34, label)
489
+
490
+ def generate_to_dir(self, spec: SheetSpec, output_dir: str | Path) -> dict[str, Path]:
491
+ """Write sheet.pdf, template.json, and sample_answer_key.json into output_dir."""
492
+ out = Path(output_dir)
493
+ out.mkdir(parents=True, exist_ok=True)
494
+ generated = self.generate(spec)
495
+
496
+ pdf_path = out / f"{spec.preset_id}_sheet.pdf"
497
+ template_path = out / "template.json"
498
+ key_path = out / "answer_key.json"
499
+
500
+ pdf_path.write_bytes(generated.pdf_bytes)
501
+ generated.template.to_file(template_path)
502
+ generated.sample_answer_key.to_file(key_path)
503
+
504
+ return {
505
+ "pdf": pdf_path,
506
+ "template": template_path,
507
+ "answer_key": key_path,
508
+ }
@@ -0,0 +1,109 @@
1
+ """Built-in printable optical sheet presets (international & Turkish exam layouts)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Literal
6
+
7
+ from pydantic import BaseModel, Field
8
+
9
+ PageFormat = Literal["A4", "LETTER"]
10
+
11
+
12
+ class IdGridSpec(BaseModel):
13
+ """Specification for a vertical numeric/alphanumeric ID grid on a generated sheet."""
14
+
15
+ name: str
16
+ title: str
17
+ digits: int = Field(ge=1, le=14)
18
+ options: list[str] = Field(default_factory=lambda: [str(i) for i in range(10)])
19
+ validator: Literal["tr_tckn", "luhn", "digits", "non_empty"] | None = "digits"
20
+
21
+
22
+ class SheetSpec(BaseModel):
23
+ """High-level blueprint used by SheetGenerator to create a printable PDF + exact Template."""
24
+
25
+ preset_id: str = "custom"
26
+ title: str = "OPTICAL ANSWER SHEET"
27
+ subtitle: str = "Fill bubbles completely with a dark pen or pencil."
28
+ page_format: PageFormat = "A4"
29
+ dpi: int = Field(default=200, ge=150, le=300)
30
+ num_questions: int = Field(default=40, ge=5, le=120)
31
+ options: list[str] = Field(default_factory=lambda: ["A", "B", "C", "D", "E"])
32
+ questions_per_column: int = Field(default=20, ge=5, le=30)
33
+ include_booklet: bool = True
34
+ booklet_options: list[str] = Field(default_factory=lambda: ["A", "B", "C", "D"])
35
+ id_grids: list[IdGridSpec] = Field(
36
+ default_factory=lambda: [
37
+ IdGridSpec(name="STUDENT_ID", title="Student ID", digits=8, validator="digits")
38
+ ]
39
+ )
40
+ question_prefix: str = "q"
41
+
42
+
43
+ def get_sheet_presets() -> dict[str, SheetSpec]:
44
+ """Return built-in optical form presets ready for 1-click generation."""
45
+ return {
46
+ "quick_quiz_20": SheetSpec(
47
+ preset_id="quick_quiz_20",
48
+ title="QUICK QUIZ — 20 QUESTIONS",
49
+ subtitle="Mark one bubble per question. Generated by OMRKit.",
50
+ num_questions=20,
51
+ options=["A", "B", "C", "D"],
52
+ questions_per_column=10,
53
+ include_booklet=False,
54
+ id_grids=[
55
+ IdGridSpec(name="STUDENT_ID", title="Student ID", digits=6, validator="digits")
56
+ ],
57
+ ),
58
+ "standard_mcq_40": SheetSpec(
59
+ preset_id="standard_mcq_40",
60
+ title="STANDARD EXAM — 40 QUESTIONS",
61
+ subtitle="Fill bubbles darkly. ArUco corner anchors enable instant auto-alignment.",
62
+ num_questions=40,
63
+ options=["A", "B", "C", "D", "E"],
64
+ questions_per_column=20,
65
+ include_booklet=True,
66
+ booklet_options=["A", "B", "C", "D"],
67
+ id_grids=[
68
+ IdGridSpec(name="STUDENT_ID", title="Student ID", digits=8, validator="digits")
69
+ ],
70
+ ),
71
+ "turkish_exam_50": SheetSpec(
72
+ preset_id="turkish_exam_50",
73
+ title="OPTIK CEVAP KAGIDI — 50 SORU",
74
+ subtitle="Kodlamalari koyu kursun kalem ile daire disina tasirmadan yapiniz.",
75
+ num_questions=50,
76
+ options=["A", "B", "C", "D", "E"],
77
+ questions_per_column=25,
78
+ include_booklet=True,
79
+ booklet_options=["A", "B", "C", "D"],
80
+ id_grids=[
81
+ IdGridSpec(name="SINAV_KODU", title="Sinav Kodu", digits=6, validator="digits"),
82
+ IdGridSpec(
83
+ name="TC_KIMLIK_NO", title="TC Kimlik No", digits=11, validator="tr_tckn"
84
+ ),
85
+ ],
86
+ ),
87
+ "turkish_yks_120": SheetSpec(
88
+ preset_id="turkish_yks_120",
89
+ title="YKS / TYT DENEME OPTIK FORMU — 120 SORU",
90
+ subtitle="Turkce (1-40) | Sosyal (41-60) | Matematik (61-100) | Fen (101-120)",
91
+ num_questions=120,
92
+ options=["A", "B", "C", "D", "E"],
93
+ questions_per_column=30,
94
+ include_booklet=True,
95
+ booklet_options=["A", "B", "C", "D"],
96
+ id_grids=[
97
+ IdGridSpec(name="OGRENCI_NO", title="Ogrenci No", digits=8, validator="digits")
98
+ ],
99
+ ),
100
+ }
101
+
102
+
103
+ def get_sheet_preset(preset_id: str) -> SheetSpec:
104
+ """Look up a single preset by ID."""
105
+ presets = get_sheet_presets()
106
+ if preset_id not in presets:
107
+ available = ", ".join(sorted(presets))
108
+ raise ValueError(f"Unknown sheet preset '{preset_id}'. Available: {available}")
109
+ return presets[preset_id]
@@ -0,0 +1,6 @@
1
+ """Exam grading and Classical Test Theory psychometrics."""
2
+
3
+ from omrkit.grading.analytics import compute_exam_analytics
4
+ from omrkit.grading.grader import ExamGrader
5
+
6
+ __all__ = ["ExamGrader", "compute_exam_analytics"]