🍓 在 Raspberry Pi 5 上用 PiCamera2 + MediaPipe 做手勢偵測

適用：RP5 + Pi Camera Module v3（或 v2），搭配 MediaPipe Python 版本實現低延遲、即時的手部偵測。

---

🧰 一、環境需求

✅ 硬體：

• Raspberry Pi 5

• Raspberry Pi Camera Module v2/v3

• 相機已透過 CSI 線接上，並在 raspi-config 啟用

✅ 軟體與套件：

• Raspberry Pi OS Bookworm（64-bit）

• Python 3.9+

• picamera2 (libcamera)

• mediapipe>=0.10.9

• opencv-python

---

🛠️ 二、安裝步驟

1. 開啟相機介面

sudo raspi-config
# Interface Options > Camera > Enable
# 然後重新啟動
sudo reboot

2. 安裝必要套件

sudo apt update && sudo apt install -y \
    python3-opencv python3-picamera2 libatlas-base-dev

pip install mediapipe==0.10.9

---

📷 三、PiCamera2 + MediaPipe 程式碼範例

建立檔案 hand_tracking_picamera2.py，內容如下：

import cv2
import mediapipe as mp
from picamera2 import Picamera2
import time

# 初始化 MediaPipe
mp_hands = mp.solutions.hands
mp_drawing = mp.solutions.drawing_utils
hands = mp_hands.Hands(static_image_mode=False, max_num_hands=2)

# 初始化 PiCamera2
picam2 = Picamera2()
picam2.preview_configuration.main.size = (640, 480)
picam2.preview_configuration.main.format = "RGB888"
picam2.preview_configuration.align()
picam2.configure("preview")
picam2.start()

# 等待相機穩定
time.sleep(2)

while True:
    frame = picam2.capture_array()
    image = cv2.cvtColor(frame, cv2.COLOR_RGB2BGR)
    results = hands.process(frame)

    if results.multi_hand_landmarks:
        for hand_landmarks in results.multi_hand_landmarks:
            mp_drawing.draw_landmarks(
                image, hand_landmarks, mp_hands.HAND_CONNECTIONS)

    cv2.imshow("RP5 - Hand Tracking (PiCamera2)", image)
    if cv2.waitKey(1) & 0xFF == 27:
        break

cv2.destroyAllWindows()
picam2.stop()

---

🚀 執行方式

python3 hand_tracking_picamera2.py

如果你看到攝影機畫面與即時手部骨架圖，即表示成功！

---

🔧 常見問題解決

問題	解決方式
無法開啟攝影機	確認 libcamera 安裝，使用 libcamera-hello 測試是否能顯示畫面
AttributeError: 'NoneType' object has no attribute 'shape'	相機未啟動或 frame 為空，檢查 picam2.start() 前是否有 sleep(2) 等待時間
CPU 使用率高或畫面延遲	可降低解析度（例如改為 320x240）或限制 FPS

---

📚 延伸應用建議

• ✅ 加入 GPIO 控制：比手勢控制燈泡 / 馬達

• ✅ 整合 Flask 打造 Web 前端畫面 + WebSocket 手勢傳輸

• ✅ 加入姿勢偵測 Pose 或整合式 Holistic

---

📎 參考資源

• MediaPipe 官方

• PiCamera2 官方文件

• libcamera 工具