DigiHouse
日本語

TECH ARTICLE · 7 MIN READ

Blog / DigiHouse

W11｜MediaPipe 感知與結構化 JSON 輸出

W11 第三小時實作：把手勢辨識結果像填表一樣轉成 JSON，分開原始影像、結構化資料與應用決策。

DigiHouse 技術內容7 分鐘閱讀

本週完成成果

你會理解鏡頭畫面不是直接變成「答案」：MediaPipe 先產生手勢與關鍵點結果，程式再整理成 JSON，最後由應用決定如何使用。

完成標準｜個人腳本能輸出一筆合法 JSON；小組 detector 記錄時間、手勢、信心值與必要座標；未提交人臉影片或可識別影像。

課前準備

步驟 1｜確認拍攝規則：只拍自己自願展示的手部或使用教師提供測試影像，不拍旁人、人臉、名牌與私人空間。

預期結果｜所有測試者知道用途與是否保存；預設不保存原始影像。

步驟 2｜Codespaces：安裝本週鎖定依賴。攝影機不能直接從遠端環境使用時，改用教師提供圖片／錄影，不繞過瀏覽器權限。

bash
python -m pip install -r courseware/gs3073-b/requirements-week11.txt
python -c "import sys, mediapipe; print(sys.version); print(mediapipe.__version__)"

預期結果｜記錄 Python 與 MediaPipe 版本，並選擇 image、video 或 live stream 模式。

步驟 3｜下載模型前核對官方文件與教師指定 hash／路徑；不要執行來源不明模型。

預期結果｜gesture_recognizer.task 來源可追蹤且不進 Git 大檔。

第三小時｜個人技術實作

故事開始｜猜拳時，人先看到畫面，再判斷手指形狀，最後說「剪刀」。電腦也要分幾站：影像、特徵點、手勢分類、信心值。JSON 就像統一格式的裁判紀錄表。

老師先問｜信心值 0.9 就代表百分之百正確嗎？不是。它是模型對特定輸入的分數，光線、角度、膚色與遮擋都可能影響結果，仍需測試。

生活比喻｜JSON 像包裹上的標準寄件單：每一格有固定名稱，後面的程式不必重新看影片，只讀手勢、時間與分數。

先看全程地圖｜先看懂資料與決策怎麼移動，再開始操作。圖中的箭頭代表下一步，不代表可以跳過人工確認。

text
┌──────────┐ → ┌──────────┐ → ┌──────────┐
│ 手部影像  │   │ MediaPipe │   │ 手勢＋關鍵點│
└──────────┘   └──────────┘   └────┬─────┘
                                    ↓
                           ┌──────────┐
                           │ JSON 紀錄 │
                           └────┬─────┘
                                ↓
                           人工核對／應用

步驟 4｜個人：先不使用鏡頭，建立一筆示範 JSON 並確認可被重新讀取。

python
import json

record = {'gesture': 'Open_Palm', 'score': 0.91, 'timestamp_ms': 1200}
encoded = json.dumps(record, ensure_ascii=False)
print(encoded)
print(json.loads(encoded)['gesture'])

預期結果｜week11_mediapipe_test.py 輸出合法 JSON 與 Open_Palm。

步驟 5｜小組：依官方 guide 建立 Gesture Recognizer，先用一張核准圖片測試。

bash
python codes/mediapipe/gesture_detector.py --image samples/hand_open.jpg --output output/gesture.json

預期結果｜產生 JSON；若無手勢，明確輸出 empty result，不捏造類別。

步驟 6｜檢查 JSON 欄位與型別。

json
{
  "source": "teacher-sample",
  "timestamp_ms": 0,
  "gesture": "Open_Palm",
  "score": 0.91,
  "landmarks": []
}

預期結果｜時間為數字、score 為 0–1 數字、gesture 為字串；不含姓名或影像路徑中的個資。

步驟 7｜用不同光線或角度測三次，人工記錄實際手勢、模型結果與是否一致。

預期結果｜至少保留一筆模型不確定或錯誤的案例與可能原因。

課堂收束｜請同學把「看到畫面」到「應用採取動作」分成四站說一次。若把模型輸出直接當命令，漏掉人工核對與低信心處理，就還沒完成設計。

指定閱讀與課後作業

指定閱讀｜依課綱完成個人 week11_mediapipe_test.py；操作細節以 Google AI Edge Gesture Recognizer Python 官方 guide 為準。

課後作業方向｜個人繳交 JSON 基礎測試；小組在 feat-mediapipe 分支完成 detector，將結果整合到專案前先定義低信心或無偵測時的行為。

步驟 8｜個人：加入 JSON schema 說明與一筆 empty-result 測試。

預期結果｜沒有偵測時程式仍輸出合法、可判斷的結果。

步驟 9｜小組：提交 detector 與 README 操作段落。

bash
git add week11_mediapipe_test.py codes/mediapipe/gesture_detector.py README.md
git commit -m 'W11: structure gesture results as reviewed JSON'
git push -u origin HEAD

預期結果｜Repo 不含原始人臉影片、大型模型檔或未取得同意的影像。

驗收方式

bash
python week11_mediapipe_test.py
python -m json.tool output/gesture.json >/dev/null 2>&1 || true
git diff --check

通過條件｜JSON 合法且欄位型別清楚；有 empty／低信心處理；測試記錄包含錯誤案例；隱私邊界被遵守。

應提交的 Repo 檔案

必交｜week11_mediapipe_test.py、codes/mediapipe/gesture_detector.py。只提交課綱指定成果與重現所需說明；不得提交 API key、個資、私人對話、未授權資料或大型模型檔。

常見問題與排除

問題 1｜Codespaces 看不到鏡頭：使用核准測試檔或在本機擷取後只上傳去識別必要樣本。

問題 2｜mediapipe 安裝失敗：核對 Python 與官方支援平台，不任意降級整個環境。

問題 3｜JSON 出現 NaN：在輸出前驗證數值並以 null 或明確錯誤表示。

引用資料

國立中央大學授課課綱／劉書銘老師，《劉書銘老師課程大綱_基礎模型與生成式人工智慧-更新版.pdf》；教師提供附件。用途：W1–W16 時段、實作主題、評量與交付物。

Google AI Edge，《Gesture recognition guide for Python》；https://developers.google.com/edge/mediapipe/solutions/vision/gesture_recognizer/python；查閱日期：2026-08-04。用途：W11 MediaPipe Gesture Recognizer Python 安裝、模型與輸出。

Python Software Foundation，《JSON encoder and decoder》；https://docs.python.org/3/library/json.html；查閱日期：2026-08-04。用途：W6 JSON 讀取、解析與輸出。