Upload 33 files

README.md

@@ -1,5 +1,5 @@
 ---
-title: DSE OMR V3.1 Mobile Scanner
+title: DSE OMR V3.1 Four-Corner Scanner
 emoji: 📊
 colorFrom: blue
 colorTo: indigo
@@ -10,60 +10,63 @@ app_file: app.py
 pinned: false
 ---
 
-# DSE OMR V3.1 手機陰影局部補救系統
+# DSE OMR V3.1：只使用四個大型定位標記
 
-V3.1 專為學生以手機拍攝 DSE 類型答題紙而設。系統先執行 V3 嚴格四角定位；若手機或手部陰影令一至兩個定位標記的黑白巢狀輪廓失真，才啟動局部補救。補救後仍必須通過完整四點幾何安全檢查，才會把圖片交給 OMRChecker。
+本版本以學生手機拍攝 DSE 類型答題紙為目標。答題紙只保留答案區四周的四個
+`144 × 144 px` 五層黑白大型定位標記，已移除所有每五題之間的小標記。
 
-## V3.1 主要更新
+## 核心流程
 
-- 保留 V3 的 `144 × 144 px` 五層黑白大型定位標記。
-- 第一階段仍使用全頁 contour hierarchy 嚴格偵測。
-- 只有全頁偵測未能形成可靠四點組合，且仍找到至少兩個嚴格候選時，才啟動 V3.1 局部補救。
-- 每個缺失角點在限定 ROI 內使用：CLAHE、局部 Otsu、Adaptive Threshold、邊緣匹配及 `marker_reference.png` 多尺度比對。
-- 最多補救兩個角點；完全缺失或相似度不足的定位符不會被猜測。
-- 局部補救得到的角點仍須通過四邊形面積、跨度、邊長比例、對角線比例及標記尺寸一致性檢查。
-- 偵測預覽中，V3 嚴格角點為綠色；局部補救角點以黃橙色及 `*` 標示。
-- `strictMarkerMode=true`：補救後仍不可靠便直接拒絕，不把錯誤校正圖交給 OMRChecker。
+`手機相片 → V3 嚴格四角偵測 → 必要時 V3.1 局部陰影補救 → 四點幾何安全檢查 → 3093×4374 透視校正 → OMRChecker 三輪掃描 → 成功輪次投票 → CSV／預覽／日誌`
+
+## 本版本的設計
+
+- 只使用四個大型定位標記。
+- 沒有題目之間的小型定位符號。
+- `template.json` 的 100 題答案座標保持不變。
+- V3.1 局部補救可處理手機或手部陰影令一至兩個大型標記對比下降的情況。
+- 補救角點仍須通過四邊形面積、跨度、比例及尺寸一致性檢查。
+- `strictMarkerMode=true`：四角不可靠便拒絕，不把錯誤校正圖交給 OMRChecker。
 
 ## Hugging Face 部署
 
 1. 解壓本 ZIP。
-2. 建立 Hugging Face **Gradio Space**。
-3. 將解壓後的全部檔案及資料夾一次拖入 Space 根目錄。
+2. 建立 Hugging Face Gradio Space。
+3. 將解壓後的所有檔案和資料夾上傳到 Space 根目錄。
 4. 等待 Build 完成。
-5. 第一次掃描會下載 OMRChecker，因此需較長時間。
+5. 第一次掃描會下載 OMRChecker 核心，因此需較長時間。
 
-> 不要只上傳 ZIP；Hugging Face Space 需要 ZIP 解壓後的根目錄檔案。
+不要只把 ZIP 本身上傳為單一檔案；Space 需要 ZIP 解壓後的根目錄內容。
 
-## 根目錄必要檔案
+## 必要檔案
 
 - `app.py`
 - `README.md`
 - `requirements.txt`
 - `packages.txt`
 - `template.jpg`
+- `template_lossless.png`
 - `template.json`
 - `marker_config.json`
 - `marker_reference.png`
+- `template_A4_print.pdf`
 
 ## 測試樣本
 
 `samples/` 內包括：
 
-- `sample_phone_perspective.jpg`：正常手機透視樣本，應由 V3 嚴格模式通過。
-- `sample_phone_shadow_rescue.jpg`：手機陰影破壞 TL 巢狀輪廓，應由 V3.1 局部補救通過。
-- `sample_phone_missing_tl.jpg`：TL 真正缺失，應維持安全拒絕。
-- `validation_shadow_detected.jpg`：局部補救標示結果。
-- `validation_shadow_warped.jpg`：補救後透視校正結果。
+- `sample_filled_clean.jpg`：平整填答案樣本。
+- `sample_phone_perspective.jpg`：正常手機透視樣本。
+- `sample_phone_detected.jpg`：四角偵測預覽。
+- `sample_phone_warped.jpg`：透視校正結果。
+- `sample_phone_shadow_rescue.jpg`：大型標記附近手機陰影測試。
+- `sample_phone_missing_tl.jpg`：真正缺失左上標記，應安全拒絕。
+- `sample_answer_key.csv`：測試答案。
 
 ## 拍攝要求
 
 - 四個大型定位標記必須完整入鏡。
-- 輕至中度手機陰影可以嘗試局部補救，但不要讓手機本體或手指真正遮住標記。
+- 不要讓手機本體或手指真正遮住定位標記。
 - 避免嚴重反光、動態模糊及裁切。
 - 相機不要太近，保留紙張四周少量背景。
-- 系統拒絕圖片時應重新拍攝，不要強行提交。
-
-## 執行流程
-
-`手機相片 → V3 全頁嚴格偵測 →（必要時）V3.1 四角 ROI 局部補救 → 四點整組幾何驗證 → 3093×4374 透視校正 → OMRChecker 三輪掃描 → 成功輪次投票 → CSV／預覽／日誌`
+- 系統拒絕圖片時應重新拍攝。

VALIDATION_REPORT.txt

@@ -1,59 +1,23 @@
-DSE OMR Hugging Face V3.1 Validation Report
-===========================================
+DSE OMR V3.1 Four Large Markers Only
+=====================================
 
-Project version
----------------
-DSE-OMR-v3.1-local-shadow-rescue
-
-Static validation
------------------
-PASS  Required root files present
-PASS  app.py Python syntax
-PASS  template.jpg = 3093 x 4374
-PASS  template_lossless.png = 3093 x 4374
-PASS  template.json pageDimensions = 3093 x 4374
-PASS  marker_config.json pageDimensions = 3093 x 4374
-PASS  largeMarkerOuterSize = 144
-PASS  strictMarkerMode = true
-PASS  localRescue.enabled = true
-PASS  minimumGlobalCandidates = 2
-PASS  maxRescueCorners = 2
-PASS  16 small group markers retained
-
-Functional marker tests
------------------------
-PASS  sample_phone_perspective.jpg
-      Expected: V3 strict four-marker detection
-      Result: strict pass; no rescue used
-
-PASS  sample_phone_shadow_rescue.jpg
-      Expected: mobile-phone shadow breaks one strict contour hierarchy
-      Result: V3.1 local ROI rescue pass; geometry validation passed
-
-PASS  sample_phone_missing_tl.jpg
-      Expected: genuine missing TL marker must not be guessed
-      Result: safely rejected; image was not sent to OMRChecker
-
-Additional stress observations
-------------------------------
-PASS  even low light
-PASS  bright exposure
-PASS  warm/cool colour casts
-PASS  left-side shadow
-PASS  diagonal shadow via local rescue
-PASS  top-bright/bottom-dark via local rescue
-PASS  vignette via local rescue
-PASS  low-light sensor noise
-REJECT low-light motion blur (intended safety rejection)
-
-Limitations
------------
-- Full OMRChecker answer recognition is executed in Hugging Face after the
-  upstream OMRChecker repository is downloaded on first use.
-- Local rescue corrects lighting-induced loss of marker hierarchy; it does not
-  invent a marker that is cropped out, physically covered, or severely blurred.
-
-Final status
-------------
 PROJECT VALIDATION PASSED
-V3.1 strict detection, phone-shadow rescue and missing-marker rejection passed.
+
+Checks completed:
+- app.py syntax: PASS
+- validate_project.py syntax: PASS
+- Colab marker tool syntax: PASS
+- template.jpg size 3093 × 4374: PASS
+- template_lossless.png size 3093 × 4374: PASS
+- exactly four large markers in marker_config.json: PASS
+- no smallGroupMarkers setting: PASS
+- no smallMarkerOuterSize setting: PASS
+- 16 former small-marker positions cleared from template: PASS
+- normal phone-perspective four-corner detection: PASS
+- perspective warp output: PASS
+- missing-TL sample safely rejected: PASS
+- template PDF regenerated: PASS
+- Hugging Face required files present: PASS
+
+Normal sample local rescue used: False
+Shadow sample local rescue used: True

docs/ARCHITECTURE.md

@@ -1,14 +1,25 @@
-# V3.1 Architecture
-
-1. 讀取手機相片與 template／marker 設定。
-2. V3 全頁 CLAHE、Otsu、RETR_TREE 巢狀方框偵測。
-3. 嘗試從嚴格候選形成四點組合並執行幾何驗證。
-4. 若失敗但仍有至少兩個嚴格候選：
-   - 找出缺失角點的限定 ROI；
-   - 使用 CLAHE、局部 Otsu、Adaptive Threshold、Canny edge；
-   - 以 marker_reference.png 做多尺度及小角度模板比對；
-   - 最多補救兩角。
-5. 將嚴格及補救候選重新組合，重新執行四點幾何安全檢查。
-6. 通過後用 homography 映射至 3093×4374。
-7. 成功校正後移除第二次 FeatureBasedAlignment。
-8. OMRChecker 執行三輪靈敏度掃描，僅成功輪次參與投票。
+# 系統架構
+
+## 目前定位結構
+
+本專案只使用四個大型五層黑白定位標記：
+
+- top_left
+- top_right
+- bottom_left
+- bottom_right
+
+題目之間沒有小型定位標記，也沒有局部五題區塊校正。
+
+## 處理層
+
+1. 圖片載入與基本檢查
+2. V3 全頁大型標記偵測
+3. 必要時 V3.1 四角 ROI 局部陰影補救
+4. 四點幾何安全驗證
+5. `warpPerspective` 映射至 `3093 × 4374`
+6. 按 `template.json` 執行 OMRChecker
+7. 三輪靈敏度掃描及成功輪次投票
+8. 輸出 CSV、定位預覽、校正預覽與日誌
+
+四角校正成功後會停用第二次 `FeatureBasedAlignment`，避免雙重幾何變換。

docs/TEMPLATE_COORDINATES.md

@@ -1,12 +1,25 @@
-# Template V3 座標
-
-- 頁面：`3093 x 4374`
-- 答案區：`(829,1598)` 至 `(2917,4170)`
-- 大型標記外尺寸：`144px`
-- TL：`(720, 1410)`
-- TR：`(3015, 1410)`
-- BL：`(720, 4285)`
-- BR：`(3015, 4285)`
-- 小型標記外尺寸：`34px`
-
-答案框座標仍由根目錄的 `template.json` 定義；V3 沒有移動原本 100 題的答案位置。
+# 模板及定位座標
+
+## 頁面
+
+- 寬：3093 px
+- 高：4374 px
+
+## 四個大型定位標記
+
+- TL：[720, 1410]
+- TR：[3015, 1410]
+- BL：[720, 4285]
+- BR：[3015, 4285]
+- 外框尺寸：144 px
+- 黑白巢狀層數：5
+
+## 小標記
+
+本版本沒有任何題目間小標記。`marker_config.json` 亦不包含
+`smallGroupMarkers` 或 `smallMarkerOuterSize`。
+
+## 答案座標
+
+100 題答案座標繼續由 `template.json` 的 20 個五題 field block 定義。
+移除小標記沒有移動任何答案格，因此不需要改動 field block 座標。

docs/TESTING_GUIDE.md

@@ -1,23 +1,19 @@
-# V3.1 Testing Guide
+# 測試指引
 
-## 必測三張
+建議依次上傳：
 
 1. `sample_phone_perspective.jpg`
-   - 預期：V3 strict pass，四角全為綠色。
 2. `sample_phone_shadow_rescue.jpg`
-   - 預期：V3.1 local rescue pass，至少一角為黃橙色並帶 `*`。
 3. `sample_phone_missing_tl.jpg`
-   - 預期：安全拒絕，不進入 OMRChecker。
 
-## 日誌判讀
+正常樣本應找到四個大型標記並完成透視校正。陰影樣本可由嚴格模式或
+V3.1 局部補救通過。缺失 TL 的樣本必須拒絕。
 
-- `V3 嚴格模式成功`：沒有使用補救。
-- `V3.1 局部補救成功`：陰影中的缺失角點已恢復且幾何檢查通過。
-- `未通過 V3.1 安全檢查`：應重新拍攝。
+檢查畫面：
 
-## 不應放寬的情況
+- TL、TR、BR、BL 是否落在四個大型標記。
+- 校正後紅色答案欄是否垂直。
+- OMRChecker 是否成功返回 CSV。
+- 執行摘要中是否沒有 config schema 錯誤。
 
-- 定位標記真正被裁走或遮住。
-- 嚴重動態模糊。
-- 反光把黑白環帶完全洗白。
-- 只找到 0–1 個全頁嚴格候選。
+本版本沒有小標記，因此不需要檢查題目間定位符號。

docs/V3_1_CHANGELOG.md

@@ -1,8 +1,9 @@
-# V3.1 Changelog
+# V3.1 Four-Large-Markers-Only 變更
 
-- 新增手機／手部陰影局部補救。
-- 保留 V3 全頁嚴格 contour hierarchy 偵測作第一階段。
-- 缺失角點使用限定 ROI、多尺度 marker reference、局部 Otsu、Adaptive Threshold 及 edge matching。
-- 至少需要兩個 V3 嚴格候選，最多補救兩角。
-- 局部結果必須再次通過完整四點幾何驗證。
-- 真正缺失 TL 的負面樣本仍會被拒絕。
+- 保留四個 `144 × 144 px` 五層黑白大型定位標記。
+- 移除 16 個每五題之間的小型定位標記。
+- 從 `marker_config.json` 移除小標記座標及尺寸設定。
+- Colab 產生工具只會加入四個大型標記。
+- 保留 V3 嚴格偵測、V3.1 局部陰影補救及幾何安全檢查。
+- 重新產生 template、PDF、座標圖及所有測試樣本。
+- 答案格座標及 OMRChecker 三輪辨識流程不變。

docs/V3_CHANGELOG.md

@@ -1,20 +1,9 @@
-# V3 更新紀錄
-
-## 定位紙設計
-
-- 大型標記：72px -> 144px。
-- 座標：TL `(720,1410)`、TR `(3015,1410)`、BL `(720,4285)`、BR `(3015,4285)`。
-- 造型：黑/白/黑/白/黑五層巢狀方形。
-- 小型分隔標記維持 34px。
-
-## 偵測器
-
-- 強制 hierarchy depth。
-- 依頁面比例估計大型標記像素尺寸，排除小型標記。
-- 四角候選整組組合及幾何驗證。
-- 失敗圖會顯示所有通過初步篩選的候選框。
-
-## 安全行為
-
-- 預設 strict mode，不再把誤判 TL/TR/BL/BR 的圖片交給 OMRChecker。
-- 可在 `marker_config.json` 將 `strictMarkerMode` 設為 `false` 才啟用舊回退模式。
+# V3.1 Four-Large-Markers-Only 變更
+
+- 保留四個 `144 × 144 px` 五層黑白大型定位標記。
+- 移除 16 個每五題之間的小型定位標記。
+- 從 `marker_config.json` 移除小標記座標及尺寸設定。
+- Colab 產生工具只會加入四個大型標記。
+- 保留 V3 嚴格偵測、V3.1 局部陰影補救及幾何安全檢查。
+- 重新產生 template、PDF、座標圖及所有測試樣本。
+- 答案格座標及 OMRChecker 三輪辨識流程不變。

marker_config.json

@@ -1,5 +1,5 @@
 {
-  "templateVersion": "DSE-OMR-v3.1-local-shadow-rescue",
+  "templateVersion": "DSE-OMR-v3.1-four-large-markers-only",
   "pageDimensions": [
     3093,
     4374
@@ -31,73 +31,6 @@
   },
   "largeMarkerOuterSize": 144,
   "largeMarkerNestedLevels": 5,
-  "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,
   "detection": {
     "minNestedDepth": 3,
     "minQuadrilateralAreaRatio": 0.2,
@@ -123,13 +56,12 @@
     ]
   },
   "notes": [
-    "V3 enlarges the four main markers from 72 px to 144 px.",
-    "Large markers use five alternating black/white square layers for contour-hierarchy validation.",
-    "V3.1 keeps strict full-page detection first, then activates local rescue only when the four-marker set is incomplete.",
-    "Local rescue uses corner ROI CLAHE, local Otsu, adaptive threshold, edge matching and marker_reference.png.",
-    "At least two strict global candidates are required before rescue; all recovered points must still pass four-point geometry validation.",
-    "Strict marker mode rejects the image when a reliable four-marker set is not found.",
-    "Small group markers remain 34 px and are reserved for future local-warp checks."
+    "This variant keeps only the four 144 px five-layer large corner markers.",
+    "All 16 small markers between five-question groups have been removed.",
+    "V3.1 strict full-page detection remains the first stage.",
+    "Local corner-ROI rescue remains available when phone or hand shadow degrades one or two large markers.",
+    "Recovered points must still pass full four-point geometry validation.",
+    "No local group-marker correction is performed or required in this project."
   ],
   "localRescue": {
     "enabled": true,
@@ -155,4 +87,4 @@
     "adaptiveBlockSize": 31,
     "adaptiveC": 7
   }
-}
+}

project_manifest.json

@@ -1,130 +1,193 @@
 {
-  ".gitignore": {
-    "size_bytes": 69,
-    "sha256": "220f22568b058b917b79feb609ec12fc63085941efafd3698cf4575c0f6ad05f"
-  },
-  "README.md": {
-    "size_bytes": 2925,
-    "sha256": "109f5f6ad4e617019cde8c37acdd224df13c6a226a51c83ce0d20573c0715e86"
-  },
-  "VALIDATION_REPORT.txt": {
-    "size_bytes": 1953,
-    "sha256": "bb1b66058920c864fd5f44b83af12af71dccb23d27472fc16ea3cda23ca28175"
-  },
-  "app.py": {
-    "size_bytes": 55081,
-    "sha256": "d96a6f4a48b071774d1dfcacbf787581260e4a9e301dd3232582716629c4c3e7"
-  },
-  "docs/ARCHITECTURE.md": {
-    "size_bytes": 723,
-    "sha256": "1bcd1b4979e3238ccc520d4dc218557ccca879018bf63ff78b13041263cda366"
-  },
-  "docs/TEMPLATE_COORDINATES.md": {
-    "size_bytes": 353,
-    "sha256": "c53f9dd30fb5b5938fdda5f1fbd89c2bda5136515684c3b89740a22dc69c3213"
-  },
-  "docs/TESTING_GUIDE.md": {
-    "size_bytes": 709,
-    "sha256": "3a33930526df391e052f8a2dc24fc24a05f6e60feb0f0d514868cac14037d322"
-  },
-  "docs/V3_1_CHANGELOG.md": {
-    "size_bytes": 420,
-    "sha256": "bb980211944e3f5c05f3f6ee91c216b49dbefeb1d218b6a60de048e11bedd5ee"
-  },
-  "docs/V3_CHANGELOG.md": {
-    "size_bytes": 661,
-    "sha256": "efa46cb301f4a361cfc2d0c54551570c5eb04bf0b80c800dffd0ec7048cd0823"
-  },
-  "docs/template_coordinate_overlay.jpg": {
-    "size_bytes": 1599880,
-    "sha256": "2a047c39f005de0d2a20b30c369505401c8060cc1581aa81e918c22edd36eb7d"
-  },
-  "marker_config.json": {
-    "size_bytes": 2803,
-    "sha256": "7f4a1f660d9609766187a92fbaae4a577851800a6e69c767249480c7bfee5819"
-  },
-  "marker_reference.png": {
-    "size_bytes": 1497,
-    "sha256": "9b896e436e359df8a3bdba19013cce4d646ba9e2eb38ce590fa9ff5065a6eba3"
-  },
-  "packages.txt": {
-    "size_bytes": 32,
-    "sha256": "4de86580e7ebc03a7790808fa6655cac191045bd030c15d4cc07acf03e6706f1"
-  },
-  "requirements.txt": {
-    "size_bytes": 576,
-    "sha256": "b7411f9ebbf827d2272fb789c10c2d03ae27e7f3f908d0d0f4da5b4103497e22"
-  },
-  "samples/sample_answer_key.csv": {
-    "size_bytes": 597,
-    "sha256": "c61e0234c426ef58c6aa7d6a998e313c6223dc769b16df2fc7a4ec11ff024ec7"
-  },
-  "samples/sample_filled_clean.jpg": {
-    "size_bytes": 1533382,
-    "sha256": "e9ddaa0c6abfb1ce7327b491e893c9368f9c732b6f6ade01e6d32072f0a922c1"
-  },
-  "samples/sample_phone_detected.jpg": {
-    "size_bytes": 603541,
-    "sha256": "298b30859ef9d5e355c05638540205939d29a127bcea087d94b7fe9a97e3675d"
-  },
-  "samples/sample_phone_missing_tl.jpg": {
-    "size_bytes": 582004,
-    "sha256": "019e0dcc680b84aac7261ecaa657a0d760e12948bb9e2137d492ba107427b76a"
-  },
-  "samples/sample_phone_perspective.jpg": {
-    "size_bytes": 476343,
-    "sha256": "36afed2af57fad73f8d3938de401ec02e415fcce06c1f9a8c35c952af4352d71"
-  },
-  "samples/sample_phone_shadow_rescue.jpg": {
-    "size_bytes": 396067,
-    "sha256": "71afc6b1ce658511fe3c039a3539f50fcab3457363e19f679c3749fa7e65bd50"
-  },
-  "samples/sample_phone_warped.jpg": {
-    "size_bytes": 1589690,
-    "sha256": "9491f19b1c41ba2448ba0a6d71e1234eb96dd079b7bed39c1d9fd0bb6dadb1cb"
-  },
-  "samples/validation_missing_failed.jpg": {
-    "size_bytes": 587623,
-    "sha256": "8e905fd74b05344e0bfc6a7a5e396abca12f8c4266a5ead4d0695cd49b66bbd2"
-  },
-  "samples/validation_shadow_detected.jpg": {
-    "size_bytes": 541116,
-    "sha256": "5a21a7e403ec05f2bab664ad4f02ffaeb7fcef852e2ca3e545241fea80ca7b64"
-  },
-  "samples/validation_shadow_warped.jpg": {
-    "size_bytes": 1195295,
-    "sha256": "edcf2d2f5c7072dd680f1b108892fc43fc567d4e24e2a873bcb7cc7d5c95000f"
-  },
-  "template.jpg": {
-    "size_bytes": 1769252,
-    "sha256": "569cdf55938b6a90a9575569ddcdc050ce236784b0b7610a03f45493a315db62"
-  },
-  "template.json": {
-    "size_bytes": 4723,
-    "sha256": "d49c9a881225afae81cae9521a85a68c044d5d86844b3774cc9130de1d484bd2"
-  },
-  "template_A4_print.pdf": {
-    "size_bytes": 8170224,
-    "sha256": "05b38fffc36d6bb4daabbe51bbc18ebb76dd8e7a9b359d1a029dec04c346a542"
-  },
-  "template_lossless.png": {
-    "size_bytes": 5097851,
-    "sha256": "b9eebc6d7581218978ad52425a18a34d4715a797c49beb50bdd9e0536bba3648"
-  },
-  "tools/add_markers_and_warp_colab.py": {
-    "size_bytes": 5146,
-    "sha256": "178ec38a1a81bc146a3cdb42599ed164fe4382d24010f19f6bb0bcd0adc8f4f8"
-  },
-  "tools/generate_filled_sample.py": {
-    "size_bytes": 869,
-    "sha256": "9562dfe9a13aed8d8c13ff86b1415c399c5a629a10e1706b8fbc387729d53777"
-  },
-  "tools/test_marker_v31.py": {
-    "size_bytes": 1414,
-    "sha256": "28bddae2d69932cec4f6c871c91a24e1c9db82cc2612ae231cc330fa7b8566a7"
-  },
-  "validate_project.py": {
-    "size_bytes": 2735,
-    "sha256": "13c54cc6e5eee1699a7dd818f723e7c5b264b0948476e54c798696b522d023e4"
-  }
-}
+  "project": "DSE OMR V3.1 Four Large Markers Only",
+  "template_version": "DSE-OMR-v3.1-four-large-markers-only",
+  "large_marker_count": 4,
+  "small_marker_count": 0,
+  "files": [
+    {
+      "path": ".gitignore",
+      "size_bytes": 69,
+      "sha256": "220f22568b058b917b79feb609ec12fc63085941efafd3698cf4575c0f6ad05f"
+    },
+    {
+      "path": "README.md",
+      "size_bytes": 2424,
+      "sha256": "0d885050aef4963afe8a90496322ea15102bbff3f9b75b7d72f559206ecc3a7a"
+    },
+    {
+      "path": "VALIDATION_REPORT.txt",
+      "size_bytes": 779,
+      "sha256": "7f3a17271ca4636c3dea290e849f36bcdce3ec73454f5cddf612dcbb8ba02887"
+    },
+    {
+      "path": "__pycache__/app.cpython-313.pyc",
+      "size_bytes": 68024,
+      "sha256": "5c99d35bc4003ea494844b88c5b3ba1bb589422fb3e47b4bd2bfd9c001738c05"
+    },
+    {
+      "path": "__pycache__/validate_project.cpython-313.pyc",
+      "size_bytes": 4362,
+      "sha256": "55c81cd08cc9e50693aba2a3cf2c9f831259bdb64bf209e015567ac68c183e4c"
+    },
+    {
+      "path": "app.py",
+      "size_bytes": 55081,
+      "sha256": "d96a6f4a48b071774d1dfcacbf787581260e4a9e301dd3232582716629c4c3e7"
+    },
+    {
+      "path": "docs/ARCHITECTURE.md",
+      "size_bytes": 661,
+      "sha256": "b4ab0a6766dc79e7c2fb273f690a8e83b02df883e031e5389ca2fdbaa4d9d191"
+    },
+    {
+      "path": "docs/TEMPLATE_COORDINATES.md",
+      "size_bytes": 557,
+      "sha256": "10e43a06ea3e74f37ab9588da894fbb652c12de70563ca29251013118c4755f3"
+    },
+    {
+      "path": "docs/TESTING_GUIDE.md",
+      "size_bytes": 582,
+      "sha256": "1830a6284a1cfd09c9bcb13305b302e66436143f6f411bbaa97726e42f35ce46"
+    },
+    {
+      "path": "docs/V3_1_CHANGELOG.md",
+      "size_bytes": 481,
+      "sha256": "588aa9895b36abd22e30ef05a3dd7f8efd6bf8560180290ed203d058602cc230"
+    },
+    {
+      "path": "docs/V3_CHANGELOG.md",
+      "size_bytes": 481,
+      "sha256": "588aa9895b36abd22e30ef05a3dd7f8efd6bf8560180290ed203d058602cc230"
+    },
+    {
+      "path": "docs/template_coordinate_overlay.jpg",
+      "size_bytes": 1651047,
+      "sha256": "3db779e3a69622ecf047373df6882bf70c8d3a52f253acc496c28d1a046b433d"
+    },
+    {
+      "path": "marker_config.json",
+      "size_bytes": 1936,
+      "sha256": "6d12faf818e64a16dde6e6762cfcbd08b676a50a0de4b84ca36b2e9371b8a7b9"
+    },
+    {
+      "path": "marker_reference.png",
+      "size_bytes": 1497,
+      "sha256": "9b896e436e359df8a3bdba19013cce4d646ba9e2eb38ce590fa9ff5065a6eba3"
+    },
+    {
+      "path": "packages.txt",
+      "size_bytes": 32,
+      "sha256": "4de86580e7ebc03a7790808fa6655cac191045bd030c15d4cc07acf03e6706f1"
+    },
+    {
+      "path": "project_manifest.json",
+      "size_bytes": 4580,
+      "sha256": "58d8f4e19bcd6e3fad305e09779bb63826c86938b2096b1e8f75f4fb4564bce6"
+    },
+    {
+      "path": "requirements.txt",
+      "size_bytes": 576,
+      "sha256": "b7411f9ebbf827d2272fb789c10c2d03ae27e7f3f908d0d0f4da5b4103497e22"
+    },
+    {
+      "path": "samples/sample_answer_key.csv",
+      "size_bytes": 597,
+      "sha256": "c61e0234c426ef58c6aa7d6a998e313c6223dc769b16df2fc7a4ec11ff024ec7"
+    },
+    {
+      "path": "samples/sample_filled_clean.jpg",
+      "size_bytes": 1647356,
+      "sha256": "0731fad2c9712cf8f02a3662286f92ac801e8632b116ead97d756b63e599473b"
+    },
+    {
+      "path": "samples/sample_phone_detected.jpg",
+      "size_bytes": 624509,
+      "sha256": "f80183c0fb42961d9f889b2865236d369ad2c305160e64eb3c1142a7c01263a2"
+    },
+    {
+      "path": "samples/sample_phone_missing_tl.jpg",
+      "size_bytes": 608318,
+      "sha256": "963d897dbc2969b68bc5dd558c2c78f792863e4d2b55fbc50d669e1ab3a702d4"
+    },
+    {
+      "path": "samples/sample_phone_perspective.jpg",
+      "size_bytes": 609664,
+      "sha256": "05ee2debd12a855ee8f999fbe3e0732c159b5718013ccebc97d76e8187ea971a"
+    },
+    {
+      "path": "samples/sample_phone_shadow_rescue.jpg",
+      "size_bytes": 611829,
+      "sha256": "ee14c40f1e9826766247cde4fb3e15134a81e0b0f1ac43383718d1aed462e109"
+    },
+    {
+      "path": "samples/sample_phone_warped.jpg",
+      "size_bytes": 1490520,
+      "sha256": "ecd740b282740f2fd4843b82cb979357328e0960596aa3807ab0b0032f5efaaa"
+    },
+    {
+      "path": "samples/validation_missing_failed.jpg",
+      "size_bytes": 629418,
+      "sha256": "20bed2ae0cfc3a5d9ea377570cf79c2cac4b974a6a28a8aebbc0ba53cad0bba5"
+    },
+    {
+      "path": "samples/validation_shadow_detected.jpg",
+      "size_bytes": 636319,
+      "sha256": "9bf985c6686f0c06a5f579d708c5a7859eb15e78d286349149011a364522f4cc"
+    },
+    {
+      "path": "samples/validation_shadow_warped.jpg",
+      "size_bytes": 1501053,
+      "sha256": "e79b1d775c0afb472b80a50f811b8c6883901a12641453ca8534d5f3f67297b4"
+    },
+    {
+      "path": "template.jpg",
+      "size_bytes": 1760828,
+      "sha256": "6b8ae7fcb30f1bd928015ec2ca1ddb6e7d4bd982b93fdf7f81778f7fcfe626e9"
+    },
+    {
+      "path": "template.json",
+      "size_bytes": 4723,
+      "sha256": "d49c9a881225afae81cae9521a85a68c044d5d86844b3774cc9130de1d484bd2"
+    },
+    {
+      "path": "template_A4_print.pdf",
+      "size_bytes": 716725,
+      "sha256": "ba117aa756a9c4cecc0b913563e91e2c8998d4f36688530afe0a677e685657db"
+    },
+    {
+      "path": "template_lossless.png",
+      "size_bytes": 6858945,
+      "sha256": "71c031b628adea74b435bda57e46eaa555d68f3aed0804ea69f95fa0fc60ad40"
+    },
+    {
+      "path": "tools/__pycache__/add_markers_and_warp_colab.cpython-313.pyc",
+      "size_bytes": 8417,
+      "sha256": "5f054c790adb40f5f578259472070b6ecec4632bab83b6e55d2126c6af776ca7"
+    },
+    {
+      "path": "tools/__pycache__/generate_filled_sample.cpython-313.pyc",
+      "size_bytes": 2083,
+      "sha256": "0f889cb32338dd181b1fa366f1394ea870fdfc80ab99ea316ac41093f7d01fc1"
+    },
+    {
+      "path": "tools/add_markers_and_warp_colab.py",
+      "size_bytes": 4775,
+      "sha256": "60342bae732564aee6b4671a648c8cafdfca53c38f891f4ba9c687acb466fbec"
+    },
+    {
+      "path": "tools/generate_filled_sample.py",
+      "size_bytes": 869,
+      "sha256": "9562dfe9a13aed8d8c13ff86b1415c399c5a629a10e1706b8fbc387729d53777"
+    },
+    {
+      "path": "tools/test_marker_v31.py",
+      "size_bytes": 1414,
+      "sha256": "28bddae2d69932cec4f6c871c91a24e1c9db82cc2612ae231cc330fa7b8566a7"
+    },
+    {
+      "path": "validate_project.py",
+      "size_bytes": 2805,
+      "sha256": "5732882b7ef24bd24c6b2712db042d124212c0b647f407be0bf8579814a8fabc"
+    }
+  ]
+}

template_A4_print.pdf

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:05b38fffc36d6bb4daabbe51bbc18ebb76dd8e7a9b359d1a029dec04c346a542
-size 8170224
+oid sha256:ba117aa756a9c4cecc0b913563e91e2c8998d4f36688530afe0a677e685657db
+size 716725

tools/add_markers_and_warp_colab.py

@@ -2,7 +2,7 @@
 """Colab utility for the DSE OMR V3 large-marker template.
 
 Functions:
-- add_v3_markers(): add four 144px five-layer markers and 34px group markers.
+- add_v3_markers(): add only four 144px five-layer corner markers.
 - detect_and_warp(): detect the four large markers and perspective-correct a photo.
 
 For the full production detector and OMR flow, use app.py in the Space project.
@@ -13,19 +13,12 @@ import numpy as np
 
 PAGE_SIZE = (3093, 4374)
 LARGE_SIZE = 144
-SMALL_SIZE = 34
 LARGE_MARKERS = {
     'top_left': (720, 1410),
     'top_right': (3015, 1410),
     'bottom_left': (720, 4285),
     'bottom_right': (3015, 4285),
 }
-SMALL_MARKERS = [
-    (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),
-]
 
 
 def _draw_nested_marker(img, center, size):
@@ -51,8 +44,6 @@ def add_v3_markers(input_path='template_original.jpg',
     img = cv2.resize(img, PAGE_SIZE, interpolation=cv2.INTER_CUBIC)
     for point in LARGE_MARKERS.values():
         _draw_nested_marker(img, point, LARGE_SIZE)
-    for point in SMALL_MARKERS:
-        _draw_nested_marker(img, point, SMALL_SIZE)
     cv2.imwrite(output_path, img, [int(cv2.IMWRITE_JPEG_QUALITY), 97])
     return output_path
 

validate_project.py

@@ -43,8 +43,8 @@ try:
         errors.append('V3.1 largeMarkerOuterSize must remain 144')
     if markers.get('strictMarkerMode') is not True:
         errors.append('strictMarkerMode must default to true')
-    if len(markers.get('smallGroupMarkers', [])) != 16:
-        errors.append('Expected 16 small group markers')
+    if 'smallGroupMarkers' in markers or 'smallMarkerOuterSize' in markers:
+        errors.append('Small group marker settings must not exist in this variant')
     rescue = markers.get('localRescue') or {}
     if rescue.get('enabled') is not True:
         errors.append('V3.1 localRescue.enabled must be true')
@@ -65,4 +65,4 @@ if errors:
     sys.exit(1)
 
 print('PROJECT VALIDATION PASSED')
-print('V3.1 template, local-shadow rescue settings and required files are present.')
+print('V3.1 four-large-marker-only template, local-shadow rescue settings and required files are present.')