單元 5 · 第一個鏡頭跑起來

5.1 啟用相機

$ sudo raspi-config
  選單：Interface Options → Camera → Enable → Finish
$ sudo reboot

RPi5 的 Raspberry Pi OS 預設已啟用相機；此步驟為保險。Bookworm 後的 libcamera 不需要「camera=1」舊設定。

5.2 確認偵測（含輸出逐欄解讀）

$ rpicam-hello --list-cameras
Available cameras
-----------------
0 : ov5647 [2592x1944 10-bit RGGB]
    Modes: 'SGBRG10_CSI2P' : 640x480 1296x972 1296x730 2592x1944
           'YUV420_8_CSI2P' : 640x480 1296x972 1296x730 2592x1944

5.3 預覽 / 拍照 / 錄影（關鍵旗標全表）

rpicam-hello -t 10000              # 預覽 10 秒
rpicam-still -o shot.jpg           # 拍照
rpicam-vid  -t 5000 -o video.h264  # 錄 5 秒 H.264

5.4 調校用「固定參數」拍照（範本）

rpicam-still --raw -o fixed.dng     --shutter 20000 --gain 1.0     --awb off --awbgains 1.0,1.0

固定參數的目的是「重現同一個畫面」：不同時間拍的 RAW 才有可比性（單元 14 回歸用）。

5.5 觀察 AE 狀態（調校前置）

$ rpicam-still --info -o /dev/null
...
ExposureTime: 33333
AnalogueGain: 1.5
ColourGains: [1.7, 1.3]
...

這告訴你「自動模式下感測器目前的曝光/增益/AWB gains」——是理解場景曝光需求的依據。

5.6 picamera2 完整程式

from picamera2 import Picamera2

picam2 = Picamera2()
cfg = picam2.create_still_configuration()
picam2.configure(cfg)

picam2.set_controls({
    "AeEnable": False,           # 關自動曝光
    "ExposureTime": 20000,       # 快門 µs
    "AnalogueGain": 1.5,
    "AwbEnable": False,          # 關自動白平衡
    "ColourTemperature": 4500,   # 手動色溫
})
picam2.start()
picam2.capture_file("shot.jpg")
picam2.stop()

5.7 常見失敗快速對照

5.8 深入：rpicam-apps 的完整旗標解讀

除了基本拍照，rpicam-apps 是調校的「瑞士刀」：

rpicam-still --tuning-file v1.json --shutter 20000 --gain 1 -o v1.jpg
rpicam-still --tuning-file v2.json --shutter 20000 --gain 1 -o v2.jpg

5.9 練習：建立你的「標準測試拍攝」腳本

#!/bin/bash
# 固定參數拍 RAW，供後續所有單元使用
rpicam-still --raw -o test.dng \
  --shutter 20000 --gain 1.0 --awb off --awbgains 1.0,1.0
echo "已存 test.dng（RAW）"

1. 建立並執行上述腳本。
2. 確認 test.dng 產生。
3. 記錄「你看到的畫面」與「RAW 存在」兩件事。

進階真實情境 Worked Example：用 rpicam-apps 比較兩個 tuning 檔的差異

場景：你手上有兩版 tuning 檔（v1=出廠預設、v2=你手動調整過 NR/Sharpen），需要量化比較兩者在相同場景下的差異。

#!/bin/bash
# 固定參數拍攝，比較 tuning 效果
SHUTTER=20000
GAIN=1.0

# v1（預設 tuning）
rpicam-still --raw --shutter $SHUTTER --gain $GAIN \
  --awb off --awbgains 1,1 \
  --tuning-file /usr/share/libcamera/ipa/rpi/pisp/ov5647.json \
  -o compare_v1.jpg

# v2（手動 tuning）
rpicam-still --raw --shutter $SHUTTER --gain $GAIN \
  --awb off --awbgains 1,1 \
  --tuning-file ./my_tuning_v2.json \
  -o compare_v2.jpg

echo "拍攝完成，比較兩張圖的差異"
ls -la compare_v1.jpg compare_v2.jpg

深入原理擴充：rpicam-apps 與 libcamera 的控制抽象層

rpicam-apps 是 libcamera 的前端應用，但它對控制的處理比你想的複雜：

• --shutter 設的是 ExposureTime（µs），libcamera 內部會換算成感測器的曝光行數。若行數超出 frame length 限制，libcamera 會自動截斷而非報錯——你設 50ms 但實際可能只曝光 33ms。
• --gain 設的是 AnalogueGain（線性值），驅動會查 gain map 轉成暫存器值。OV5647 的 gain map 是非線性的——gain=2.0 不代表訊號強度是 gain=1.0 的兩倍。
• --awb off 後的 --awbgains 是「原始乘數」，不會經過 libcamera 的 AWB 演算法。這意味著你看到的是感測器 + 鏡頭的原始色彩響應，不帶任何校正。

診斷式疑難排解表

進階挑戰題

1. 寫一個 Python 腳本，自動化「固定曝光/增益拍攝 → rawpy 讀取 → 計算各通道均值/標準差」的完整流程，輸出 CSV 報告。
2. 用 rpicam-still 的 --info 輸出，追蹤 AE 收斂過程：每秒拍一張並記錄 ExposureTime/AnalogueGain，畫出收斂曲線。
3. 若要確保「不同時間拍的 RAW 可比較」，除了固定曝光/增益/AWB 外，還需要控制哪些環境變數？

延伸閱讀

• 下一篇：單元 6 · Sensor Bring-up 與除錯。
• RPi Camera Guide
• 學習路線：複習全站

專案級端到端 Worked Example：標準測試拍攝管線專案

場景：所有後續調校（黑位/LSC/色彩/NR）都需要「可重現的拍攝」。本專案建立一套標準拍攝管線：固定參數、自動命名、產出 DNG + metadata 記錄，讓不同天拍的圖可以互相比較。整合單元 5（rpicam 旗標）、8（RAW）、14（版本管理）知識。

#!/bin/bash
# 用法：./capture_pipeline.sh <標籤> [shutter] [gain]
TAG=${1:-test}; SHUTTER=${2:-20000}; GAIN=${3:-1.0}
OUT=shots/$(date +%Y%m%d_%H%M%S)_${TAG}
mkdir -p shots

# 固定曝光/增益/AWB，拍 RAW（單元 5 範本）
rpicam-still --raw -o ${OUT}.dng \
  --shutter $SHUTTER --gain $GAIN --awb off --awbgains 1.0,1.0

# 同時寫入 metadata（場景、條件）
cat > ${OUT}.meta <<EOF
date: $(date)
tag: $TAG
shutter_us: $SHUTTER
gain: $GAIN
awb: off (1.0,1.0)
scene: （填寫：室內日光燈 / 日光 / 逆光 / 低光）
EOF

# 立即用 rawpy 驗證 RAW 可讀且非全黑
python3 - < 50, "RAW 太暗，檢查曝光"
print("RAW 驗證通過")
EOF
echo "已產出 ${OUT}.dng + ${OUT}.meta"

./capture_pipeline.sh indoor_a 20000 1.0
# 預期輸出：
# shape=(1944, 2592) mean=512
# RAW 驗證通過
# 已產出 shots/20260817_101530_indoor_a.dng + .meta
ls shots/

量測/驗證 SOP：拍攝一致性驗證

1. 固定相機、光源、拍攝距離與鏡頭設定。
2. 用 capture_pipeline.sh 拍基準 RAW（室內日光燈，20000µs, gain 1）。
3. 間隔 10 分鐘重拍一次，比較兩張 RAW 的 ROI 均值（差異 <5%）。
4. 確認 metadata 檔記錄完整（時間、參數、場景）。
5. 用 --info 確認 AE/AWB 已關閉（無浮動）。
6. 存檔並標記「基準」。

平台間對照：標準拍攝工具

互動式檢核清單

• - [ ] 能逐欄讀懂 list-cameras 輸出。
• - [ ] 已建立並驗證 capture_pipeline.sh。
• - [ ] 已完成「間隔重拍」一致性驗證（<5%）。
• - [ ] 能說明 --raw 對調校的意義（ISP 前資料）。
• - [ ] 能用 --info 判讀 AE/AWB 狀態。
• - [ ] 已存一份基準 RAW 與 metadata。

第 3 輪深度加深

① Register 位元級完整工作流：OV5647 完整初始化序列（簡化版）

② 多層疑難排解決策樹

決策樹 A：rpicam-hello 出現 but 畫面全黑

畫面全黑
├─ 檢查 A：overlay 是否已更新（重啟後 dmesg 有無新 probe）
│  ├─ 無 → sudo raspi-config 或手動改 config.txt 重啟
│  └─ 有 → 繼續
├─ 檢查 B：rpicam-hello -k --nopreview -t 5000 --raw 有無 RAW 檔
│  ├─ 有 RAW 且非全黑 → preview 問題，非 sensor 問題
│  └─ RAW 全黑 → sensor 無輸出
├─ 檢查 C：手動設定曝光（排除 AE 問題）
│  ├─ 手動曝光有畫面 → AE tuning 問題
│  └─ 手動曝光仍全黑 → sensor 硬體問題
└─ 檢查 D：檢查 GPIO 供電（A09 / cam1_reg / cam0_reg）
   ├─ 無 2.8V / 1.8V → 電源模組異常
   └─ 供電正常 → sensor 損壞

③ 量測驗證完整 SOP：首次影像品質快速評估

1. 拍攝條件：5000K 光源箱、18% 灰卡、三腳架、手動曝光 10ms、ISO 100
2. 量測項目：
   a. 平均亮度（mean pixel value）：預期 80-120 (8-bit scale)
   b. 平均偏色（R-G, B-G）：各 <10
   c. 暗角比（四角 mean / 中心 mean）：>0.85 為合格
   d. 銳利度（水平邊緣 MTF10）：>0.3 LP/pixel
3. 工具：rawpy + numpy + scipy.ndimage
4. 判讀：四項全通過 = 首次影像 OK；任一不通過 = 對應單元深入排查
5. 常見偏差：色溫偏差 → AWB 未啟用；暗角嚴重 → 鏡頭未對準

④ 四平台終極對照

⑤ 完整 Bring-up 專案 Checklist

• - [ ] 確認 config.txt 已加入正確 dtoverlay
• - [ ] 重啟後 dmesg 確認 probe 成功
• - [ ] i2cdetect 確認 I2C 通訊正常
• - [ ] rpicam-hello --list-cameras 確認 camera 列出
• - [ ] 執行 rpicam-hello -k --nopreview -t 5000 確認有影像
• - [ ] 拍攝 RAW 檔並用 rawpy 驗證尺寸
• - [ ] 在灰卡條件下量測亮度/偏色/暗角
• - [ ] 調整曝光確認 sensor 對光線有反應
• - [ ] 整理 bring-up log 記錄每步結果