README.md

---
title: DSE OMR V3.1 Four-Corner Scanner
emoji: 📊
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: "4.44.1"
python_version: "3.10.14"
app_file: app.py
pinned: false
---

# DSE OMR V3.1：只使用四個大型定位標記

本版本以學生手機拍攝 DSE 類型答題紙為目標。答題紙只保留答案區四周的四個
`144 × 144 px` 五層黑白大型定位標記，已移除所有每五題之間的小標記。

## 核心流程

`手機相片 → 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 根目錄。
4. 等待 Build 完成。
5. 第一次掃描會下載 OMRChecker 核心，因此需較長時間。

不要只把 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_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`：測試答案。

## 拍攝要求

- 四個大型定位標記必須完整入鏡。
- 不要讓手機本體或手指真正遮住定位標記。
- 避免嚴重反光、動態模糊及裁切。
- 相機不要太近，保留紙張四周少量背景。
- 系統拒絕圖片時應重新拍攝。