Upload 13 files

.gitattributes

@@ -36,3 +36,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 template.jpg filter=lfs diff=lfs merge=lfs -text
 template.png filter=lfs diff=lfs merge=lfs -text
 template[[:space:]](8).jpg filter=lfs diff=lfs merge=lfs -text
+docs/template_coordinate_overlay.jpg filter=lfs diff=lfs merge=lfs -text
+template_A4_print.pdf filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,7 @@
+OMRChecker/
+generated/
+mock_libs/
+__pycache__/
+*.pyc
+*.pyo
+.DS_Store

README.md

@@ -1,5 +1,5 @@
 ---
-title: OMRChecker API
+title: DSE OMR Mobile Scanner
 emoji: 📊
 colorFrom: blue
 colorTo: indigo
@@ -10,10 +10,51 @@ app_file: app.py
 pinned: false
 ---
 
-# OMRChecker API
+# DSE OMR 手機相片辨識系統
 
-DSE OMR recognition backend for the HKDSE Biology assessment system.
+這個 Hugging Face Space 專案把以下流程整合在同一個 `app.py`：
 
-The Space lazily downloads the OMRChecker source on the first scan. Python packages are installed during the Hugging Face build from `requirements.txt`; no runtime `pip install` is performed.
+1. 上傳學生以手機拍攝的答題紙。
+2. 嘗試偵測答案區四個大型黑白定位標記。
+3. 將相片透視校正至 `3093 × 4374`。
+4. 交由 OMRChecker 執行三輪靈敏度掃描。
+5. 輸出融合答案 CSV、校正圖片、OMR 劃記圖及執行紀錄。
 
-The Gradio/FastAPI/Starlette versions are pinned because Gradio 4.44.1 still uses Starlette's legacy `TemplateResponse(name, context)` call form.
+## 上傳到 Hugging Face
+
+1. 在電腦解壓本 ZIP。
+2. 建立一個新的 **Gradio Space**。
+3. 把解壓後的全部檔案及資料夾一次拖入 Space 根目錄。
+4. 等待 Build 完成。
+5. 第一次辨識時，系統會下載 OMRChecker 原始碼，因此會比之後稍慢。
+
+> Hugging Face 不會自動執行 ZIP 內的專案。請先解壓，然後一次上傳解壓後的內容。
+
+## 根目錄必要檔案
+
+- `app.py`
+- `requirements.txt`
+- `packages.txt`
+- `README.md`
+- `template.jpg`
+- `template.json`
+- `marker_config.json`
+
+## 其他檔案
+
+- `template_A4_print.pdf`：供列印的答題紙。
+- `tools/add_markers_and_warp_colab.py`：Colab 版本的標記與透視校正工具。
+- `docs/template_coordinate_overlay.jpg`：答案座標核對圖。
+- `validate_project.py`：部署前檢查必要檔案、圖片尺寸及 JSON。
+
+## 拍攝要求
+
+- 四個大型定位標記必須完整入鏡。
+- 保持直向拍攝。
+- 避免強烈反光、陰影及模糊。
+- 紙張盡量攤平。
+- 低信心或分歧答案仍應由學生核對。
+
+## 回退機制
+
+若四角定位偵測失敗，系統不會立即終止，而會回退至 OMRChecker 的 `FeatureBasedAlignment` 流程，並在執行摘要顯示原因。

app.py

@@ -18,6 +18,7 @@ from typing import Any
 import cv2
 import gradio as gr
 import pandas as pd
+import numpy as np
 import fastapi
 import starlette
 
@@ -66,6 +67,7 @@ ROOT_DIR = Path(__file__).resolve().parent
 OMR_DIR = ROOT_DIR / "OMRChecker"
 MOCK_DIR = ROOT_DIR / "mock_libs"
 GENERATED_DIR = ROOT_DIR / "generated"
+MARKER_CONFIG_PATH = ROOT_DIR / "marker_config.json"
 
 OMR_REPO_URL = "https://github.com/Udayraj123/OMRChecker.git"
 OMR_REPO_BRANCH = "master"
@@ -245,6 +247,251 @@ def _load_template_content(template_content: str | None) -> tuple[dict[str, Any]
         raise ValueError(f"{template_path.name} JSON 格式不正確：{error}") from error
 
 
+
+def _load_marker_config() -> dict[str, Any] | None:
+    """Load the optional four-corner marker configuration.
+
+    The Space can still run without marker_config.json, in which case the
+    original OMRChecker FeatureBasedAlignment path is used as a fallback.
+    """
+    if not MARKER_CONFIG_PATH.is_file():
+        return None
+
+    try:
+        data = json.loads(MARKER_CONFIG_PATH.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise ValueError(f"marker_config.json 無法讀取：{error}") from error
+
+    dimensions = data.get("pageDimensions")
+    markers = data.get("largeCornerMarkers")
+    if (
+        not isinstance(dimensions, list)
+        or len(dimensions) != 2
+        or not isinstance(markers, dict)
+    ):
+        raise ValueError("marker_config.json 缺少 pageDimensions 或 largeCornerMarkers。")
+
+    required = {"top_left", "top_right", "bottom_left", "bottom_right"}
+    if not required.issubset(markers):
+        raise ValueError("marker_config.json 的四個大型定位點不完整。")
+
+    return data
+
+
+def _resize_for_detection(image: np.ndarray, max_dimension: int = 1800) -> tuple[np.ndarray, float]:
+    """Downscale only for marker detection; return scale back to original."""
+    height, width = image.shape[:2]
+    longest = max(height, width)
+    if longest <= max_dimension:
+        return image.copy(), 1.0
+
+    ratio = max_dimension / float(longest)
+    resized = cv2.resize(
+        image,
+        (max(1, int(round(width * ratio))), max(1, int(round(height * ratio)))),
+        interpolation=cv2.INTER_AREA,
+    )
+    return resized, 1.0 / ratio
+
+
+def _square_marker_candidates(image: np.ndarray) -> list[dict[str, Any]]:
+    """Find high-contrast square candidates, including nested square markers."""
+    detection_image, scale_back = _resize_for_detection(image)
+    gray = cv2.cvtColor(detection_image, cv2.COLOR_BGR2GRAY)
+    gray = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8)).apply(gray)
+    blurred = cv2.GaussianBlur(gray, (5, 5), 0)
+    _, binary = cv2.threshold(
+        blurred, 0, 255, cv2.THRESH_BINARY_INV + cv2.THRESH_OTSU
+    )
+
+    contours, hierarchy = cv2.findContours(
+        binary, cv2.RETR_TREE, cv2.CHAIN_APPROX_SIMPLE
+    )
+    hierarchy_row = hierarchy[0] if hierarchy is not None else None
+    height, width = gray.shape[:2]
+    image_area = float(height * width)
+    min_area = max(35.0, image_area * 0.000015)
+    max_area = image_area * 0.025
+
+    candidates: list[dict[str, Any]] = []
+    for index, contour in enumerate(contours):
+        area = float(cv2.contourArea(contour))
+        if area < min_area or area > max_area:
+            continue
+
+        perimeter = cv2.arcLength(contour, True)
+        if perimeter <= 0:
+            continue
+        polygon = cv2.approxPolyDP(contour, 0.04 * perimeter, True)
+        x, y, box_width, box_height = cv2.boundingRect(contour)
+        if box_width < 6 or box_height < 6:
+            continue
+
+        aspect = box_width / float(box_height)
+        fill_ratio = area / float(box_width * box_height)
+        if not (0.68 <= aspect <= 1.32):
+            continue
+        if fill_ratio < 0.35:
+            continue
+        if len(polygon) < 4 or len(polygon) > 8:
+            continue
+
+        nested = False
+        if hierarchy_row is not None:
+            nested = hierarchy_row[index][2] >= 0 or hierarchy_row[index][3] >= 0
+
+        center_x = (x + box_width / 2.0) * scale_back
+        center_y = (y + box_height / 2.0) * scale_back
+        candidates.append(
+            {
+                "center": (center_x, center_y),
+                "area": area * scale_back * scale_back,
+                "nested": nested,
+                "aspect": aspect,
+                "fill_ratio": fill_ratio,
+            }
+        )
+
+    return candidates
+
+
+def _detect_large_corner_markers(
+    image: np.ndarray, marker_config: dict[str, Any]
+) -> tuple[np.ndarray, np.ndarray]:
+    """Detect and order the four large markers as TL, TR, BR, BL.
+
+    The scoring uses the expected normalized positions from marker_config.json,
+    while allowing moderate phone-camera perspective and surrounding margins.
+    """
+    candidates = _square_marker_candidates(image)
+    if len(candidates) < 4:
+        raise RuntimeError(f"只找到 {len(candidates)} 個方形候選，未��取得四角定位點。")
+
+    image_height, image_width = image.shape[:2]
+    page_width, page_height = map(float, marker_config["pageDimensions"])
+    expected_raw = marker_config["largeCornerMarkers"]
+    expected = {
+        "top_left": (
+            expected_raw["top_left"][0] / page_width,
+            expected_raw["top_left"][1] / page_height,
+        ),
+        "top_right": (
+            expected_raw["top_right"][0] / page_width,
+            expected_raw["top_right"][1] / page_height,
+        ),
+        "bottom_right": (
+            expected_raw["bottom_right"][0] / page_width,
+            expected_raw["bottom_right"][1] / page_height,
+        ),
+        "bottom_left": (
+            expected_raw["bottom_left"][0] / page_width,
+            expected_raw["bottom_left"][1] / page_height,
+        ),
+    }
+
+    largest_area = max(candidate["area"] for candidate in candidates)
+    selected: dict[str, tuple[float, float]] = {}
+    used_indices: set[int] = set()
+
+    # Broad region constraints reject the DSE logo and the smaller group marks.
+    regions = {
+        "top_left": lambda nx, ny: nx < 0.62 and 0.15 < ny < 0.68,
+        "top_right": lambda nx, ny: nx > 0.50 and 0.15 < ny < 0.68,
+        "bottom_right": lambda nx, ny: nx > 0.50 and ny > 0.58,
+        "bottom_left": lambda nx, ny: nx < 0.62 and ny > 0.58,
+    }
+
+    for marker_name in ("top_left", "top_right", "bottom_right", "bottom_left"):
+        expected_x, expected_y = expected[marker_name]
+        best_index: int | None = None
+        best_score = float("inf")
+
+        for index, candidate in enumerate(candidates):
+            if index in used_indices:
+                continue
+            center_x, center_y = candidate["center"]
+            normalized_x = center_x / float(image_width)
+            normalized_y = center_y / float(image_height)
+            if not regions[marker_name](normalized_x, normalized_y):
+                continue
+
+            distance = ((normalized_x - expected_x) ** 2 + (normalized_y - expected_y) ** 2) ** 0.5
+            size_ratio = candidate["area"] / max(largest_area, 1.0)
+            nested_penalty = 0.0 if candidate["nested"] else 0.06
+            size_penalty = 0.08 * (1.0 - min(size_ratio, 1.0))
+            score = distance + nested_penalty + size_penalty
+
+            if score < best_score:
+                best_score = score
+                best_index = index
+
+        if best_index is None:
+            raise RuntimeError(f"未能在合理範圍內找到 {marker_name} 定位點。")
+
+        used_indices.add(best_index)
+        selected[marker_name] = candidates[best_index]["center"]
+
+    points = np.array(
+        [
+            selected["top_left"],
+            selected["top_right"],
+            selected["bottom_right"],
+            selected["bottom_left"],
+        ],
+        dtype=np.float32,
+    )
+
+    # Reject degenerate quadrilaterals before perspective transformation.
+    polygon_area = abs(float(cv2.contourArea(points.reshape(-1, 1, 2))))
+    if polygon_area < image_width * image_height * 0.08:
+        raise RuntimeError("四個定位點形成的區域過小，可能誤認了小標記。")
+
+    debug_image = image.copy()
+    labels = ("TL", "TR", "BR", "BL")
+    for label, (point_x, point_y) in zip(labels, points):
+        position = (int(round(point_x)), int(round(point_y)))
+        cv2.circle(debug_image, position, 18, (0, 255, 0), 5)
+        cv2.putText(
+            debug_image,
+            label,
+            (position[0] + 18, position[1] - 18),
+            cv2.FONT_HERSHEY_SIMPLEX,
+            1.0,
+            (0, 120, 0),
+            3,
+            cv2.LINE_AA,
+        )
+
+    return points, debug_image
+
+
+def _warp_with_large_markers(
+    image: np.ndarray, marker_config: dict[str, Any]
+) -> tuple[np.ndarray, np.ndarray]:
+    source_points, debug_image = _detect_large_corner_markers(image, marker_config)
+    page_width, page_height = map(int, marker_config["pageDimensions"])
+    marker_points = marker_config["largeCornerMarkers"]
+    destination_points = np.array(
+        [
+            marker_points["top_left"],
+            marker_points["top_right"],
+            marker_points["bottom_right"],
+            marker_points["bottom_left"],
+        ],
+        dtype=np.float32,
+    )
+
+    transform = cv2.getPerspectiveTransform(source_points, destination_points)
+    warped = cv2.warpPerspective(
+        image,
+        transform,
+        (page_width, page_height),
+        flags=cv2.INTER_CUBIC,
+        borderMode=cv2.BORDER_CONSTANT,
+        borderValue=(255, 255, 255),
+    )
+    return warped, debug_image
+
 def _expand_question_label(label: Any) -> list[int]:
     text = str(label).strip()
 
@@ -462,9 +709,10 @@ def _format_answer_summary(final_answers: dict[int, str]) -> str:
     return "\n".join(lines)
 
 
+
 def process_omr(image_file: str | None, template_content: str | None = None):
     if image_file is None:
-        return None, None, "錯誤：請先上傳答案卡圖片。"
+        return None, None, None, "錯誤：請先上傳答案卡圖片。"
 
     with PROCESS_LOCK:
         request_root: Path | None = None
@@ -478,9 +726,7 @@ def process_omr(image_file: str | None, template_content: str | None = None):
                 raise ValueError("OpenCV 無法讀取上傳圖片。")
 
             image_height, image_width = image.shape[:2]
-            dimension_info = (
-                f"【圖片載入成功】解析度：{image_width} × {image_height} px"
-            )
+            dimension_info = f"【圖片載入成功】解析度：{image_width} × {image_height} px"
 
             base_template, _ = _load_template_content(template_content)
             question_numbers = _question_numbers_from_template(base_template)
@@ -493,13 +739,55 @@ def process_omr(image_file: str | None, template_content: str | None = None):
             result_dir = GENERATED_DIR / request_id
             result_dir.mkdir(parents=True, exist_ok=True)
 
-            scans: list[dict[str, Any]] = []
             logs = [
                 dimension_info,
                 f"【Template】題號範圍：q{question_numbers[0]}–q{question_numbers[-1]}，共 {question_count} 題",
-                "--- 開始三輪多重採樣 ---",
             ]
 
+            # -------------------------------------------------------
+            # Stage 1: marker-based perspective correction.
+            # If marker detection fails, keep the original image and allow
+            # OMRChecker FeatureBasedAlignment to attempt recovery.
+            # -------------------------------------------------------
+            omr_input_path = Path(image_file)
+            corrected_preview: Path | None = None
+            marker_debug_path: Path | None = None
+            marker_config = _load_marker_config()
+
+            if marker_config is not None:
+                try:
+                    warped, marker_debug = _warp_with_large_markers(image, marker_config)
+                    corrected_preview = result_dir / "01_perspective_corrected.jpg"
+                    marker_debug_path = result_dir / "00_detected_markers.jpg"
+                    cv2.imwrite(
+                        str(corrected_preview),
+                        warped,
+                        [int(cv2.IMWRITE_JPEG_QUALITY), 95],
+                    )
+                    cv2.imwrite(
+                        str(marker_debug_path),
+                        marker_debug,
+                        [int(cv2.IMWRITE_JPEG_QUALITY), 92],
+                    )
+                    omr_input_path = corrected_preview
+                    logs.append("【四角校正】成功偵測四個大型定位點，已完成透視校正。")
+                except Exception as marker_error:
+                    fallback_path = result_dir / "01_original_fallback.jpg"
+                    shutil.copy2(image_file, fallback_path)
+                    corrected_preview = fallback_path
+                    logs.append(
+                        "【四角校正】未成功，已回退至 OMRChecker FeatureBasedAlignment："
+                        f"{type(marker_error).__name__}: {marker_error}"
+                    )
+            else:
+                fallback_path = result_dir / "01_original_no_marker_config.jpg"
+                shutil.copy2(image_file, fallback_path)
+                corrected_preview = fallback_path
+                logs.append("【四角校正】沒有 marker_config.json，使用原始對齊流程。")
+
+            scans: list[dict[str, Any]] = []
+            logs.append("--- 開始三輪多重採樣 ---")
+
             for index, profile in enumerate(SENSITIVITY_PROFILES, start=1):
                 profile_dir = request_root / f"profile_{index}"
                 images_dir = profile_dir / "images"
@@ -515,8 +803,7 @@ def process_omr(image_file: str | None, template_content: str | None = None):
                 )
                 _write_headless_config(profile_dir)
                 _copy_alignment_assets(current_template, profile_dir)
-
-                shutil.copy2(image_file, images_dir / "sheet.jpg")
+                shutil.copy2(omr_input_path, images_dir / "sheet.jpg")
 
                 environment = os.environ.copy()
                 environment["PYTHONPATH"] = (
@@ -595,17 +882,13 @@ def process_omr(image_file: str | None, template_content: str | None = None):
                 final_answers[number] = final_answer
 
                 if len(vote_counts) > 1:
-                    logs.append(
-                        f"q{number} 分歧：{dict(vote_counts)} → {final_answer}"
-                    )
+                    logs.append(f"q{number} 分歧：{dict(vote_counts)} → {final_answer}")
 
             final_valid_count = sum(answer != "—" for answer in final_answers.values())
             logs.append(
                 f"融合後辨識：{final_valid_count}/{question_count} 題；空白 {question_count - final_valid_count} 題。"
             )
 
-            # Return a CSV that matches the fused answers, rather than a raw
-            # CSV from only one sensitivity profile.
             fused_csv = result_dir / "omr_fused_answers.csv"
             pd.DataFrame(
                 [{f"q{number}": final_answers[number] for number in question_numbers}]
@@ -615,9 +898,7 @@ def process_omr(image_file: str | None, template_content: str | None = None):
             checked_image: Path | None = None
             if best_scan["image"] and Path(best_scan["image"]).is_file():
                 source_image = Path(best_scan["image"])
-                checked_image = result_dir / (
-                    "checked_omr" + source_image.suffix.lower()
-                )
+                checked_image = result_dir / ("checked_omr" + source_image.suffix.lower())
                 shutil.copy2(source_image, checked_image)
 
             combined_log = (
@@ -630,14 +911,15 @@ def process_omr(image_file: str | None, template_content: str | None = None):
 
             return (
                 str(fused_csv),
+                str(corrected_preview) if corrected_preview else None,
                 str(checked_image) if checked_image else None,
                 combined_log,
             )
 
         except subprocess.TimeoutExpired:
-            return None, None, "錯誤：OMRChecker 單輪處理超過 180 秒，已中止。"
+            return None, None, None, "錯誤：OMRChecker 單輪處理超過 180 秒，已中止。"
         except Exception as error:
-            return None, None, f"錯誤：{type(error).__name__}: {error}"
+            return None, None, None, f"錯誤：{type(error).__name__}: {error}"
         finally:
             if request_root is not None:
                 shutil.rmtree(request_root, ignore_errors=True)
@@ -646,7 +928,7 @@ def process_omr(image_file: str | None, template_content: str | None = None):
 interface = gr.Interface(
     fn=process_omr,
     inputs=[
-        gr.Image(type="filepath", label="1. 上傳 OMR 答案卡圖片 (JPG/PNG)"),
+        gr.Image(type="filepath", label="1. 上傳已填寫的 OMR 答案卡相片 (JPG/PNG)"),
         gr.Textbox(
             lines=6,
             label="2. [選填] Template JSON 配置",
@@ -655,13 +937,15 @@ interface = gr.Interface(
     ],
     outputs=[
         gr.File(label="下載融合辨識結果 (CSV)"),
-        gr.Image(label="視覺化劃記檢視圖片"),
-        gr.Textbox(label="辨識答案與執行摘要", lines=18),
+        gr.Image(label="四角校正後圖片／回退原圖"),
+        gr.Image(label="OMRChecker 視覺化劃記檢視"),
+        gr.Textbox(label="辨識答案與執行摘要", lines=20),
     ],
-    title="DSE OMR 雲端辨識系統 API 後端",
+    title="DSE OMR 手機相片辨識系統",
     description=(
-        "以 OMRChecker 執行三輪靈敏度掃描及多數決。"
-        "正式提交前仍須由學生在前端人工核對。"
+        "先嘗試偵測答案區四個大型定位標記並作透視校正，"
+        "再以 OMRChecker 執行三輪靈敏度掃描及融合。"
+        "正式提交前仍建議學生核對辨識結果。"
     ),
 )
 
@@ -670,4 +954,4 @@ if __name__ == "__main__":
         server_name=os.getenv("GRADIO_SERVER_NAME", "0.0.0.0"),
         server_port=int(os.getenv("GRADIO_SERVER_PORT", "7860")),
         show_error=True,
-    )
+    )

marker_config.json

@@ -0,0 +1,104 @@
+{
+  "templateVersion": "DSE-OMR-v2-marked",
+  "pageDimensions": [
+    3093,
+    4374
+  ],
+  "answerRegionBounds": {
+    "left": 829,
+    "top": 1598,
+    "right": 2917,
+    "bottom": 4170
+  },
+  "largeCornerMarkers": {
+    "top_left": [
+      790,
+      1555
+    ],
+    "top_right": [
+      2960,
+      1555
+    ],
+    "bottom_left": [
+      790,
+      4220
+    ],
+    "bottom_right": [
+      2960,
+      4220
+    ]
+  },
+  "largeMarkerOuterSize": 72,
+  "smallGroupMarkers": [
+    [
+      1310,
+      2122
+    ],
+    [
+      1310,
+      2637
+    ],
+    [
+      1310,
+      3152
+    ],
+    [
+      1310,
+      3667
+    ],
+    [
+      1830,
+      2122
+    ],
+    [
+      1830,
+      2637
+    ],
+    [
+      1830,
+      3152
+    ],
+    [
+      1830,
+      3667
+    ],
+    [
+      2350,
+      2122
+    ],
+    [
+      2350,
+      2637
+    ],
+    [
+      2350,
+      3152
+    ],
+    [
+      2350,
+      3667
+    ],
+    [
+      2870,
+      2122
+    ],
+    [
+      2870,
+      2637
+    ],
+    [
+      2870,
+      3152
+    ],
+    [
+      2870,
+      3667
+    ]
+  ],
+  "smallMarkerOuterSize": 34,
+  "notes": [
+    "Large markers are for four-point perspective correction before OMRChecker.",
+    "Small markers are placed in the blank gaps after every five questions and outside A-D bubble regions.",
+    "The OMRChecker template.json itself does not read marker_config.json; app.py uses it during pre-warping."
+  ]
+}

project_manifest.json

@@ -0,0 +1,50 @@
+{
+  ".gitignore": {
+    "size_bytes": 69,
+    "sha256": "220f22568b058b917b79feb609ec12fc63085941efafd3698cf4575c0f6ad05f"
+  },
+  "README.md": {
+    "size_bytes": 1800,
+    "sha256": "476f5b35cc85679dbc72d05326b950910a297a13cb772ed48e12e63c1ec09bb8"
+  },
+  "app.py": {
+    "size_bytes": 32997,
+    "sha256": "b9c1bbdcb8166332922be3d27edc6586d1699cc7a2077eff143cfd71d859e146"
+  },
+  "docs/template_coordinate_overlay.jpg": {
+    "size_bytes": 1972251,
+    "sha256": "1cf0df0ac58e75f9db078994caeab2f723ac082cadd35d1f5f37c1943257fe09"
+  },
+  "marker_config.json": {
+    "size_bytes": 1406,
+    "sha256": "222fc1a1b2df9056d5f2af4677828397c31923e1388055f87638d66187997887"
+  },
+  "packages.txt": {
+    "size_bytes": 32,
+    "sha256": "4de86580e7ebc03a7790808fa6655cac191045bd030c15d4cc07acf03e6706f1"
+  },
+  "requirements.txt": {
+    "size_bytes": 576,
+    "sha256": "b7411f9ebbf827d2272fb789c10c2d03ae27e7f3f908d0d0f4da5b4103497e22"
+  },
+  "template.jpg": {
+    "size_bytes": 2201218,
+    "sha256": "6444e117c802ca2ceb3e12a60bcb219b54c732f3c299dad874c5a4c8ea66b82a"
+  },
+  "template.json": {
+    "size_bytes": 4723,
+    "sha256": "d49c9a881225afae81cae9521a85a68c044d5d86844b3774cc9130de1d484bd2"
+  },
+  "template_A4_print.pdf": {
+    "size_bytes": 717825,
+    "sha256": "dc11564a20df544e5523bdaf353c56455f9311e1f4d5301f3abb1e3a79079940"
+  },
+  "tools/add_markers_and_warp_colab.py": {
+    "size_bytes": 6825,
+    "sha256": "5182f2ca645dbdac0479b1fdb7d0a09c6551656047086f726ac6cb9a95ce0c85"
+  },
+  "validate_project.py": {
+    "size_bytes": 1236,
+    "sha256": "b6a88ebed905bb132b0342f940e3a80c90be83f08dcb97256b4e7347ef06d772"
+  }
+}

template.json

@@ -1,270 +1,270 @@
-{
-  "pageDimensions": [
-    3093,
-    4374
-  ],
-  "bubbleDimensions": [
-    60,
-    30
-  ],
-  "preProcessors": [
-    {
-      "name": "FeatureBasedAlignment",
-      "options": {
-        "reference": "template.jpg",
-        "maxFeatures": 1000,
-        "2d": true
-      }
-    },
-    {
-      "name": "Levels",
-      "options": {
-        "low": 0.1,
-        "high": 0.9
-      }
-    }
-  ],
-  "customLabels": {},
-  "fieldBlocks": {
-    "MCQBlock_Col1_1": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        990,
-        1680
-      ],
-      "fieldLabels": [
-        "q1..5"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    },
-    "MCQBlock_Col1_2": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        990,
-        2195
-      ],
-      "fieldLabels": [
-        "q6..10"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    },
-    "MCQBlock_Col1_3": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        990,
-        2710
-      ],
-      "fieldLabels": [
-        "q11..15"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    },
-    "MCQBlock_Col1_4": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        990,
-        3225
-      ],
-      "fieldLabels": [
-        "q16..20"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    },
-    "MCQBlock_Col1_5": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        990,
-        3740
-      ],
-      "fieldLabels": [
-        "q21..25"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    },
-    "MCQBlock_Col2_1": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        1510,
-        1680
-      ],
-      "fieldLabels": [
-        "q26..30"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    },
-    "MCQBlock_Col2_2": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        1510,
-        2195
-      ],
-      "fieldLabels": [
-        "q31..35"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    },
-    "MCQBlock_Col2_3": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        1510,
-        2710
-      ],
-      "fieldLabels": [
-        "q36..40"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    },
-    "MCQBlock_Col2_4": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        1510,
-        3225
-      ],
-      "fieldLabels": [
-        "q41..45"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    },
-    "MCQBlock_Col2_5": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        1510,
-        3740
-      ],
-      "fieldLabels": [
-        "q46..50"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    },
-    "MCQBlock_Col3_1": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        2030,
-        1680
-      ],
-      "fieldLabels": [
-        "q51..55"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    },
-    "MCQBlock_Col3_2": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        2030,
-        2195
-      ],
-      "fieldLabels": [
-        "q56..60"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    },
-    "MCQBlock_Col3_3": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        2030,
-        2710
-      ],
-      "fieldLabels": [
-        "q61..65"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    },
-    "MCQBlock_Col3_4": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        2030,
-        3225
-      ],
-      "fieldLabels": [
-        "q66..70"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    },
-    "MCQBlock_Col3_5": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        2030,
-        3740
-      ],
-      "fieldLabels": [
-        "q71..75"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    },
-    "MCQBlock_Col4_1": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        2550,
-        1680
-      ],
-      "fieldLabels": [
-        "q76..80"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    },
-    "MCQBlock_Col4_2": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        2550,
-        2195
-      ],
-      "fieldLabels": [
-        "q81..85"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    },
-    "MCQBlock_Col4_3": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        2550,
-        2710
-      ],
-      "fieldLabels": [
-        "q86..90"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    },
-    "MCQBlock_Col4_4": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        2550,
-        3225
-      ],
-      "fieldLabels": [
-        "q91..95"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    },
-    "MCQBlock_Col4_5": {
-      "fieldType": "QTYPE_MCQ4",
-      "origin": [
-        2550,
-        3740
-      ],
-      "fieldLabels": [
-        "q96..100"
-      ],
-      "bubblesGap": 75,
-      "labelsGap": 92
-    }
-  }
-}
+{
+  "pageDimensions": [
+    3093,
+    4374
+  ],
+  "bubbleDimensions": [
+    60,
+    30
+  ],
+  "preProcessors": [
+    {
+      "name": "FeatureBasedAlignment",
+      "options": {
+        "reference": "template.jpg",
+        "maxFeatures": 2000,
+        "2d": true
+      }
+    },
+    {
+      "name": "Levels",
+      "options": {
+        "low": 0.1,
+        "high": 0.9
+      }
+    }
+  ],
+  "customLabels": {},
+  "fieldBlocks": {
+    "MCQBlock_Col1_1": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        990,
+        1680
+      ],
+      "fieldLabels": [
+        "q1..5"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    },
+    "MCQBlock_Col1_2": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        990,
+        2195
+      ],
+      "fieldLabels": [
+        "q6..10"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    },
+    "MCQBlock_Col1_3": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        990,
+        2710
+      ],
+      "fieldLabels": [
+        "q11..15"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    },
+    "MCQBlock_Col1_4": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        990,
+        3225
+      ],
+      "fieldLabels": [
+        "q16..20"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    },
+    "MCQBlock_Col1_5": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        990,
+        3740
+      ],
+      "fieldLabels": [
+        "q21..25"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    },
+    "MCQBlock_Col2_1": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        1510,
+        1680
+      ],
+      "fieldLabels": [
+        "q26..30"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    },
+    "MCQBlock_Col2_2": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        1510,
+        2195
+      ],
+      "fieldLabels": [
+        "q31..35"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    },
+    "MCQBlock_Col2_3": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        1510,
+        2710
+      ],
+      "fieldLabels": [
+        "q36..40"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    },
+    "MCQBlock_Col2_4": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        1510,
+        3225
+      ],
+      "fieldLabels": [
+        "q41..45"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    },
+    "MCQBlock_Col2_5": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        1510,
+        3740
+      ],
+      "fieldLabels": [
+        "q46..50"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    },
+    "MCQBlock_Col3_1": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        2030,
+        1680
+      ],
+      "fieldLabels": [
+        "q51..55"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    },
+    "MCQBlock_Col3_2": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        2030,
+        2195
+      ],
+      "fieldLabels": [
+        "q56..60"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    },
+    "MCQBlock_Col3_3": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        2030,
+        2710
+      ],
+      "fieldLabels": [
+        "q61..65"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    },
+    "MCQBlock_Col3_4": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        2030,
+        3225
+      ],
+      "fieldLabels": [
+        "q66..70"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    },
+    "MCQBlock_Col3_5": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        2030,
+        3740
+      ],
+      "fieldLabels": [
+        "q71..75"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    },
+    "MCQBlock_Col4_1": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        2550,
+        1680
+      ],
+      "fieldLabels": [
+        "q76..80"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    },
+    "MCQBlock_Col4_2": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        2550,
+        2195
+      ],
+      "fieldLabels": [
+        "q81..85"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    },
+    "MCQBlock_Col4_3": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        2550,
+        2710
+      ],
+      "fieldLabels": [
+        "q86..90"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    },
+    "MCQBlock_Col4_4": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        2550,
+        3225
+      ],
+      "fieldLabels": [
+        "q91..95"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    },
+    "MCQBlock_Col4_5": {
+      "fieldType": "QTYPE_MCQ4",
+      "origin": [
+        2550,
+        3740
+      ],
+      "fieldLabels": [
+        "q96..100"
+      ],
+      "bubblesGap": 75,
+      "labelsGap": 92
+    }
+  }
+}

template_A4_print.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:dc11564a20df544e5523bdaf353c56455f9311e1f4d5301f3abb1e3a79079940
+size 717825

tools/add_markers_and_warp_colab.py

@@ -0,0 +1,192 @@
+# -*- coding: utf-8 -*-
+"""
+Colab-ready utility for HKDSE-style OMR templates.
+
+What this script can do:
+1) Add large corner markers + small in-between-group markers to the original template image.
+2) Detect the 4 large corner markers from a phone photo.
+3) Perspective-warp the answer sheet back to the template size (3093 x 4374).
+
+Recommended Colab usage:
+- Upload the ORIGINAL unmarked template as: template_original.jpg
+- Run add_markers_to_template() once to generate:
+    template_marked_3093x4374.jpg
+    template_marked_A4.pdf
+- Later, for student phone photos, call warp_sheet_from_photo('student_photo.jpg')
+  to get a corrected sheet image before OMR reading.
+"""
+
+from pathlib import Path
+from PIL import Image, ImageDraw
+import cv2
+import numpy as np
+
+TEMPLATE_SIZE = (3093, 4374)  # width, height
+CORNER_MARKERS = [
+    (961, 1726),   # top-left
+    (3043, 1726),  # top-right
+    (961, 4255),   # bottom-left
+    (3043, 4255),  # bottom-right
+]
+SMALL_MARKERS = [
+    # x, y centers of the small double-square markers in the blank gap
+    # between q5/6, q10/11, q15/16, q20/21 for each of the 4 columns.
+    (1299, 2323), (1299, 2842), (1299, 3361), (1299, 3880),
+    (1818, 2323), (1818, 2842), (1818, 3361), (1818, 3880),
+    (2338, 2323), (2338, 2842), (2338, 3361), (2338, 3880),
+    (2857, 2323), (2857, 2842), (2857, 3361), (2857, 3880),
+]
+
+BLACK = (0, 0, 0)
+WHITE = (255, 255, 255)
+
+
+def draw_corner_marker(draw, cx, cy, outer=72, border=4, fill_margin=10):
+    """Large high-contrast square marker for 4-point detection."""
+    x0 = int(cx - outer / 2)
+    y0 = int(cy - outer / 2)
+    x1 = x0 + outer
+    y1 = y0 + outer
+    draw.rectangle([x0, y0, x1, y1], outline=BLACK, width=border, fill=WHITE)
+    draw.rectangle([x0 + fill_margin, y0 + fill_margin, x1 - fill_margin, y1 - fill_margin], fill=BLACK)
+
+
+def draw_small_double_square(draw, cx, cy, outer=34, border=2, fill_margin=5, core=9):
+    """Small double-square marker placed in the blank space after each 5 questions."""
+    x0 = int(cx - outer / 2)
+    y0 = int(cy - outer / 2)
+    x1 = x0 + outer
+    y1 = y0 + outer
+    draw.rectangle([x0, y0, x1, y1], outline=BLACK, width=border, fill=WHITE)
+    draw.rectangle([x0 + fill_margin, y0 + fill_margin, x1 - fill_margin, y1 - fill_margin], outline=BLACK, width=border, fill=WHITE)
+    c0x = int(cx - core / 2)
+    c0y = int(cy - core / 2)
+    c1x = c0x + core
+    c1y = c0y + core
+    draw.rectangle([c0x, c0y, c1x, c1y], fill=BLACK)
+
+
+def add_markers_to_template(input_path='template_original.jpg',
+                            output_img='template_marked_3093x4374.jpg',
+                            output_pdf='template_marked_A4.pdf'):
+    img = Image.open(input_path).convert('RGB')
+    if img.size != TEMPLATE_SIZE:
+        raise ValueError(f'Input size must be {TEMPLATE_SIZE}, got {img.size}')
+
+    draw = ImageDraw.Draw(img)
+    for cx, cy in CORNER_MARKERS:
+        draw_corner_marker(draw, cx, cy)
+    for cx, cy in SMALL_MARKERS:
+        draw_small_double_square(draw, cx, cy)
+
+    img.save(output_img, quality=95, subsampling=0)
+    img.save(output_pdf, resolution=300.0)
+    print('Saved:', output_img)
+    print('Saved:', output_pdf)
+
+
+def order_points(pts):
+    pts = np.array(pts, dtype=np.float32)
+    s = pts.sum(axis=1)
+    diff = np.diff(pts, axis=1)
+    tl = pts[np.argmin(s)]
+    br = pts[np.argmax(s)]
+    tr = pts[np.argmin(diff)]
+    bl = pts[np.argmax(diff)]
+    return np.array([tl, tr, br, bl], dtype=np.float32)
+
+
+def detect_corner_markers(image_bgr, debug=False):
+    """Detect the 4 large black corner markers from a phone photo.
+    Returns 4 ordered points: TL, TR, BR, BL.
+    """
+    gray = cv2.cvtColor(image_bgr, cv2.COLOR_BGR2GRAY)
+    blur = cv2.GaussianBlur(gray, (5,5), 0)
+    # Strong threshold for black markers
+    _, th = cv2.threshold(blur, 90, 255, cv2.THRESH_BINARY_INV)
+
+    contours, _ = cv2.findContours(th, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+    h, w = gray.shape[:2]
+    candidates = []
+    for c in contours:
+        area = cv2.contourArea(c)
+        if area < (h*w)*0.0002:  # too small
+            continue
+        peri = cv2.arcLength(c, True)
+        approx = cv2.approxPolyDP(c, 0.05 * peri, True)
+        x, y, bw, bh = cv2.boundingRect(c)
+        aspect = bw / max(bh, 1)
+        if 0.7 <= aspect <= 1.3:
+            M = cv2.moments(c)
+            if M['m00'] == 0:
+                continue
+            cx = M['m10'] / M['m00']
+            cy = M['m01'] / M['m00']
+            # prioritize near the outer parts of the page
+            edge_score = min(cx, cy, w-cx, h-cy)
+            candidates.append((area, edge_score, (cx, cy), c))
+
+    if len(candidates) < 4:
+        raise RuntimeError('Could not find 4 corner markers.')
+
+    # Keep larger, more edge-localized blobs.
+    candidates.sort(key=lambda x: (-x[0], x[1]))
+    pts = [item[2] for item in candidates[:12]]
+
+    # choose one from each quadrant around image center
+    cx0, cy0 = w/2, h/2
+    quad = {'tl': None, 'tr': None, 'br': None, 'bl': None}
+    best = {'tl': 1e18, 'tr': 1e18, 'br': 1e18, 'bl': 1e18}
+    for pt in pts:
+        x, y = pt
+        d = 0
+        if x < cx0 and y < cy0:
+            d = (x)**2 + (y)**2; key='tl'
+        elif x >= cx0 and y < cy0:
+            d = (w-x)**2 + (y)**2; key='tr'
+        elif x >= cx0 and y >= cy0:
+            d = (w-x)**2 + (h-y)**2; key='br'
+        else:
+            d = (x)**2 + (h-y)**2; key='bl'
+        if d < best[key]:
+            best[key] = d
+            quad[key] = pt
+
+    if any(v is None for v in quad.values()):
+        raise RuntimeError('Detected markers are incomplete across quadrants.')
+
+    return np.array([quad['tl'], quad['tr'], quad['br'], quad['bl']], dtype=np.float32)
+
+
+def warp_sheet_from_photo(photo_path, output_path='warped_sheet.jpg', debug_path=None):
+    img = cv2.imread(str(photo_path))
+    if img is None:
+        raise FileNotFoundError(photo_path)
+
+    src_pts = detect_corner_markers(img)
+    dst_pts = np.array([
+        [CORNER_MARKERS[0][0], CORNER_MARKERS[0][1]],
+        [CORNER_MARKERS[1][0], CORNER_MARKERS[1][1]],
+        [CORNER_MARKERS[3][0], CORNER_MARKERS[3][1]],
+        [CORNER_MARKERS[2][0], CORNER_MARKERS[2][1]],
+    ], dtype=np.float32)
+
+    M = cv2.getPerspectiveTransform(src_pts, dst_pts)
+    warped = cv2.warpPerspective(img, M, TEMPLATE_SIZE)
+    cv2.imwrite(str(output_path), warped)
+
+    if debug_path:
+        dbg = img.copy()
+        for x, y in src_pts.astype(int):
+            cv2.circle(dbg, (x, y), 16, (0, 255, 0), -1)
+        cv2.imwrite(str(debug_path), dbg)
+
+    print('Saved:', output_path)
+    return warped
+
+
+if __name__ == '__main__':
+    # Example usage in Colab
+    # add_markers_to_template('template_original.jpg')
+    # warp_sheet_from_photo('student_photo.jpg', 'warped_sheet.jpg', 'debug_detected_markers.jpg')
+    pass

validate_project.py

@@ -0,0 +1,44 @@
+from pathlib import Path
+import json
+import sys
+from PIL import Image
+
+ROOT = Path(__file__).resolve().parent
+REQUIRED = [
+    "app.py",
+    "requirements.txt",
+    "packages.txt",
+    "README.md",
+    "template.jpg",
+    "template.json",
+    "marker_config.json",
+]
+
+errors = []
+for filename in REQUIRED:
+    if not (ROOT / filename).is_file():
+        errors.append(f"Missing: {filename}")
+
+try:
+    image = Image.open(ROOT / "template.jpg")
+    if image.size != (3093, 4374):
+        errors.append(f"template.jpg size is {image.size}, expected (3093, 4374)")
+except Exception as error:
+    errors.append(f"template.jpg cannot be read: {error}")
+
+for filename in ("template.json", "marker_config.json"):
+    try:
+        data = json.loads((ROOT / filename).read_text(encoding="utf-8"))
+        if data.get("pageDimensions") != [3093, 4374]:
+            errors.append(f"{filename} pageDimensions is not [3093, 4374]")
+    except Exception as error:
+        errors.append(f"{filename} cannot be read: {error}")
+
+if errors:
+    print("PROJECT VALIDATION FAILED")
+    for error in errors:
+        print("-", error)
+    sys.exit(1)
+
+print("PROJECT VALIDATION PASSED")
+print("All required files exist and template dimensions are correct.")