單元 8 · RAW 擷取與資料格式

8.1 V4L2 Bayer format 與 fourcc

8.2 驗證 Bayer order（關鍵實作）

python3 - <<'EOF'
import rawpy, numpy as np
raw = rawpy.imread('t.dng').raw_image
h, w = raw.shape
roi = raw[h//4:3*h//4, w//4:3*w//4]
cells = [roi[0::2,0::2].mean(), roi[0::2,1::2].mean(),
         roi[1::2,0::2].mean(), roi[1::2,1::2].mean()]
print('R=%.1f Gr=%.1f Gb=%.1f B=%.1f' % tuple(cells))
EOF

判別法：對純紅色光源/卡片拍 RAW——R 位置（若 order 正確）應最亮。若 B 位置最亮 → order 是反的。

8.3 bit depth 與動態範圍

8.4 ROI / binning

• Full resolution：2592×1944 全像素讀出。
• Binning：2×2 合併像素 → 提升感光、降解析度。
• Crop：裁切中心區域（改變視角）。
• 調校時固定「同 size + 同 format」，避免 binning 造成的參數漂移。

rpicam-still --width 1296 --height 972 -o half.jpg

8.5 RAW 分析的標準流程（總結）

1. 固定參數拍 RAW（單元 5 範本）。
2. 驗證 Bayer order（本單元）。
3. 統計黑位與缺陷像素（單元 7/13）。
4. 之後的 LSC/CCM/NR 校正都以這份「乾淨 RAW」為輸入。

8.6 DNG 檔結構（RAW 封裝）

DNG 是 Adobe 的 RAW 封裝（TIFF 基底）。調校時透過 rawpy/dcraw 讀，但理解結構有助除錯：

python3 - <<'EOF'
import rawpy
raw = rawpy.imread('t.dng')
print('Bayer pattern:', raw.raw_pattern)          # 驗證 order
print('BlackLevel:', raw.black_level_per_channel)
print('WhiteLevel:', raw.white_level)
EOF

8.7 常見 RAW 格式錯誤

8.8 多模式 RAW 的一致性（調校前必修）

rpicam-hello --list-cameras          # 記錄要調校的 mode
rpicam-still --width 2592 --height 1944 --raw -o full.dng   # 固定全解析

8.9 深入：10-bit RAW 的 packing 與解包

10-bit 資料在記憶體中的 packing 方式影響解碼：

8.10 深入：Bayer order 在 DNG 的驗證

python3 - <<'EOF'
import rawpy
r = rawpy.imread('t.dng')
print('raw_pattern:')
for row in r.raw_pattern:
    print(' ', row)   # 0=R,1=G,2=B（依 libraw 慣例）
EOF

比對 datasheet 的 RGGB 起點，確認平台設定一致。

8.11 練習

1. 用 test.dng 驗證 Bayer order（raw_pattern）。
2. 量測黑位與 white_level。
3. 記錄「本平台 RAW 的正確解析參數」。

進階真實情境 Worked Example：用 v4l2-ctl 直接擷取未經 libcamera 處理的原始 RAW

場景：你要驗證「rpicam-still 的 DNG 是否真的包含原始 Bayer 資料」，需要從 V4L2 層直接擷取。

# 1. 確認 V4L2 裝置與 format
v4l2-ctl -d /dev/video0 --list-formats-ext
# 找到 SGBRG10_1X10 或 SRGGB10_1X10

# 2. 設定 format 並單次擷取
v4l2-ctl -d /dev/video0 \
  --set-fmt-video=width=2592,height=1944,pixelformat=SBGGR10 \
  --stream-mmap --stream-count=1 --stream-to=raw_v4l2.bin

# 3. 用 rawpy 驗證
python3 - <<'EOF'
import rawpy, numpy as np
# 注意：V4L2 輸出可能是 packed 10-bit，rawpy 可能無法直接讀
# 需要先確認 packing 格式
data = np.fromfile('raw_v4l2.bin', dtype=np.uint8)
print(f"原始資料大小: {len(data)} bytes")
print(f"期望大小 (2592*1944*10/8): {2592*1944*10//8}")
EOF

深入原理擴充：10-bit MIPI CSI-2 packing 與 byte 對齊

OV5647 輸出 10-bit RAW，但 MIPI CSI-2 傳輸層以 byte 為單位，packing 方式影響資料解讀：

• Unpacked（16-bit per pixel）：每像素佔 2 byte，高 10 位有效、低 6 位填 0。記憶體占用翻倍但解碼簡單。
• Packed（MIPI CSI-2 標準）：每 5 byte 塞 4 像素（4×10=40 bit = 5×8 bit），無 padding。解碼需要知道起始像素的 bit alignment。
• RPi5 的 unicam 預設使用 unpacked 模式（16-bit per pixel），所以 rawpy 可以直接讀。但若你在客製板上改用 packed 模式，需要手動解包。

診斷式疑難排解表

進階挑戰題

1. 寫一個 Python 腳本，自動比較 rpicam-still 的 DNG 與 v4l2-ctl 的原始 raw 資料，量化兩者的差異（mean error、max error）。
2. 若 OV5647 從 2592×1944 切到 640×480（跳過 binning，用 cropping），Bayer order 是否改變？設計實驗驗證。
3. 研究 MIPI CSI-2 的 packed 10-bit 格式，寫一個解包函數將 packed 資料還原為 16-bit per pixel。

延伸閱讀

• 下一篇：單元 9 · 各平台 ISP 架構差異。
• V4L2 Bayer format
• 學習路線：複習全站

專案級端到端 Worked Example：自動化 RAW 健康報告專案

場景：每次拍攝後都要確認 RAW 是否「乾淨」：Bayer order 正確、bit depth 正確、黑位合理、無缺陷像素。本專案建一個 raw_report.py 一鍵產出 RAW 健康報告，整合單元 8（格式）、7（黑位）、13（缺陷像素）、5（拍攝）知識。

#!/usr/bin/env python3
import sys, rawpy, numpy as np

def report(path):
    raw = rawpy.imread(path)
    img = raw.raw_image
    roi = img[img.shape[0]//4:3*img.shape[0]//4,
              img.shape[1]//4:3*img.shape[1]//4].astype(float)
    print(f"檔案: {path}")
    print(f"shape: {img.shape}  white_level: {raw.white_level}")
    print(f"Bayer pattern:\n{raw.raw_pattern}")
    print(f"BlackLevel/ch: {raw.black_level_per_channel}")
    cells = [roi[0::2,0::2].mean(), roi[0::2,1::2].mean(),
             roi[1::2,0::2].mean(), roi[1::2,1::2].mean()]
    print(f"通道均值: R={cells[0]:.0f} Gr={cells[1]:.0f} "
          f"Gb={cells[2]:.0f} B={cells[3]:.0f}")
    hot = (img > roi.mean() + 10*roi.std()).sum()
    print(f"hot pixels (>10σ): {hot}  max: {img.max()}")

report(sys.argv[1])

./raw_report.py first.dng
# 預期：
# shape: (1944, 2592)  white_level: 1023
# Bayer pattern 顯示 0/1/2 排列（驗證 RGGB）
# BlackLevel/ch 四通道合理（~100）
# 通道均值差異不大、hot pixels 少
# 判讀：任一異常 → 回對應單元診斷

量測/驗證 SOP：RAW 完整性驗證

1. 用 --raw 拍攝基準 RAW（固定參數）。
2. 執行 raw_report.py，檢查 shape 與 white_level（2592×1944 / 1023）。
3. 核對 raw_pattern 與預期 Bayer order（RGGB）。
4. 檢查四通道黑位（差異 <20 階）與均值合理性。
5. 檢查 hot pixel 數量與 max 值。
6. 存報告，與基準比較（回歸用）。

平台間對照：RAW 格式與解析

互動式檢核清單

• - [ ] 能說出 fourcc 與 CSI/Sensor order 的關係。
• - [ ] 已建立並驗證 raw_report.py。
• - [ ] 能用純色卡驗證 Bayer order。
• - [ ] 能說出 10-bit packing（packed/unpacked）的差異。
• - [ ] 能解釋 bit depth 對動態範圍的影響。
• - [ ] 已完成一次 RAW 健康報告並存檔。

第 3 輪深度加深

① Register 位元級完整工作流：OV5647 RAW 輸出格式設定

② 多層疑難排解決策樹

決策樹 A：RAW 檔解碼後全黑或全白

RAW 解碼異常
├─ 檢查 A：Bayer 順序是否正確
│  ├─ 不確定 → 依序嘗試 RGGB/BGGR/GRBG/GBRG，看哪個畫面正確
│  └─ 正確 → 繼續
├─ 檢查 B：位元深度是否匹配
│  ├─ 10-bit 用 8-bit 解讀 → 發暗 → 確認 unpack 設定
│  └─ 匹配 → 繼續
├─ 檢查 C：stride / padding 是否正確
│  ├─ stride 不對 → 行對齊錯誤 → 調整 bytes_per_line
│  └─ 正確 → 繼續
└─ 檢查 D：是否存在 data offset
   ├─ 有 → RAW data 前有 metadata header → 跳過 header
   └─ 無 → 格式設定問題

③ 量測驗證完整 SOP：RAW 資料完整性驗證

1. 工具：rawpy, numpy, Python
2. 步驟：
   a. 擷取 RAW 檔（遮光，短曝光）
   b. raw = rawpy.imread('test.raw')
   c. print(raw.shape, raw.dtype, raw.min(), raw.max(), raw.mean())
   d. 確認 dtype=uint16 (10-bit packed in 16-bit), shape[2]=width
3. 驗證清單：
   a. 遮光 RAW：mean < 50 (10-bit scale 0-1023) → 黑位 OK
   b. 白卡 RAW：mean > 500 → 有光線到達 sensor
   c. 有 pattern 的測試圖：能辨識邊緣 → 解碼正確
   d. pixel 值 range：min ≥ 0, max ≤ 1023 (10-bit)
4. 常見偏差：little-endian vs big-endian 位元反轉；packed vs unpacked 格式不符

④ 四平台終極對照

⑤ 完整 Bring-up 專案 Checklist

• - [ ] 確認感測器輸出的 Bayer 順序（RGGB/BGGR/GRBG/GBRG）
• - [ ] 確認位元深度（8/10/12-bit）
• - [ ] 擷取遮光 RAW 並驗證黑位
• - [ ] 擷取白卡 RAW 並驗證飽和點
• - [ ] 用 rawpy 正確解碼 RAW 並顯示
• - [ ] 驗證 BPP (bits per pixel) 與 stride
• - [ ] 測試不同解析度的 RAW 擷取
• - [ ] 整理 RAW 格式規格表存入專案文件