# 白板撮影データ仕様（SmTIAS-Evaluation 引き渡し用） (White-Board Capture Data Specification)

本書は，TIASshot の白板撮影モードで取得し **SmTIAS-Evaluation 側へ引き渡す白板撮影データ**について，**実際の撮影設定値・ファイル構成・メタデータの意味・評価時の注意**をまとめたものである．撮影プロトコルの目的・基準値・質疑応答（Q&A）は [SPEC_03 白板撮影プロトコルと TIAS 撮影条件](SPEC_03_白板撮影_照明均一性評価.md) を参照する（本書は実データの説明，SPEC_03 は仕様・根拠という役割分担）．

## 概要 (Overview)

- TIASshot の **白板撮影モード（照明均一性評価用・`WHITEBOARD` ビルド限定）** で取得した素の RGB 画像データ．
- カメラ: **ImagingSource DFK 23UX249**（USB3 カラー産業用，Sony IMX249）．
- **校正なし**で撮影する（チャート検出・ホワイトバランス自動調整・TCC 色補正を一切行わない）．得られるのはカメラ素の RGB．
- 1 撮影セッション = 1 フォルダ（例: `<時刻>-白板/`）．

## 撮影設定（実際の値） (Capture Settings — Actual Values)

各撮影の正確な値は同梱の `whiteboard_meta.json` に記録される．代表値（DFK 23UX249）は以下のとおり．

| 項目 | 値 | 備考 |
| --- | --- | --- |
| カメラ | DFK 23UX249（SN 45610026） | |
| 撮影モード | 白板（校正なし・素 RGB） | チャート検出/WB 自動調整/TCC なし |
| 露出 | 16.6 ms（手動固定，≈1/60 s） | 自動露出なし（※ Q6 で実機確定） |
| ゲイン | 0（Auto OFF） | |
| ホワイトバランス | Auto OFF・固定 G 64 / B 140 / R 100 | 校正しないため device-state の固定値のまま |
| ガンマ | 100（= 1.0，線形）・トーンマップ OFF | |
| ノイズ低減 / シャープネス | Denoise 0 / Sharpness 0 | |
| Color Enhancement | **OFF**（撮影前に無効化） | 非線形の色強調を排除 |
| 明るさ (Brightness) | 50 | 黒レベル/オフセット相当か要確認（Q7） |
| 色補正行列 (CCM) | なし | ImagingSource は Color Matrix を持たない |
| シェーディング補正 (LSC) | **なし（ビネット未除去）** | DFK23 は在カメラ LSC を持たず補正データも無い（確認済） |
| 出力形式 | RGB24（8-bit/ch） | RAW ではない |
| 撮影枚数 | 既定 10（「連続撮影枚数」設定値） | SmTIAS と揃えるなら 12 に変更可 |

## データ構成・ファイル (Files)

1 セッションフォルダにフレーム数 × 2 枚の画像＋メタデータが入る．

| ファイル | 内容 | 解像度 |
| --- | --- | --- |
| `WhiteBoard_{NNNN}.png` | **ROI 切り出し画像**（評価対象の白板領域） | 1136 × 1528 |
| `WhiteBoard_full_{NNNN}.png` | **クロップなしフルフレーム**（四隅まで含む） | 1200 × 1920 |
| `whiteboard_meta.json` | 撮影条件＋飽和統計（後述） | — |

- ROI: config の `X0 / Y180 / W1136 / H1528` で切り出した白板領域．
- フル: センサ 1920 × 1200 を転置した **1200 × 1920**（クロップなし）．ROI で切り捨てた周辺部（上 180px・下 212px・右 64px）を含むため，**レンズビネットの確認・フラットフィールド補正用**に使う．
- 画像はいずれも RGB24（8-bit，OpenCV の BGR 並びで PNG 保存）．`{NNNN}` は 1 始まりの連番．

## メタデータ（whiteboard_meta.json） (Metadata Schema)

| フィールド | 意味 |
| --- | --- |
| `capture_datetime` | 撮影日時 |
| `device_name` / `serial_number` | カメラ機種名・シリアル |
| `roi_x` / `roi_y` / `roi_width` / `roi_height` | ROI 座標・サイズ |
| `full_frame_saved` / `full_width` / `full_height` | フルフレーム保存有無・サイズ |
| `num_frames` | 撮影枚数 |
| `exposure_ms` | 露出時間（ミリ秒） |
| `gain` | ゲイン（device ネイティブ値） |
| `brightness` | 明るさ（黒レベル/オフセット相当・要確認） |
| `gamma` | ガンマ（100 = 1.0 線形） |
| `wb_blue` / `wb_green` / `wb_red` | ホワイトバランスのチャンネルゲイン（固定値） |
| `color_enhancement_enabled` / `color_enhancement_note` | Color Enhancement の状態（false = 無効化済み） |
| `gamma_setting` / `tone_mapping` / `denoise` / `sharpness` / `color_matrix` | 固定状態の記録（device-state 由来の決め打ち文字列） |
| `shading_correction` / `shading_correction_note` | シェーディング補正状態（"未補正"・ビネット混入の注記） |
| `frame_stats[]` | フレームごとの統計（下記） |

`frame_stats[]` の各要素:

| フィールド | 意味 |
| --- | --- |
| `frame` | フレーム番号（1 始まり） |
| `saturated_ratio` | 飽和画素率（輝度 ≥ 254 の割合） |
| `p99_luminance` | 輝度の 99 パーセンタイル |
| `mean_B` / `mean_G` / `mean_R` | チャンネル別 平均値 |
| `max_B` / `max_G` / `max_R` | チャンネル別 最大値 |

※ `frame_stats` は **ROI 画像に対する統計**（白板領域の露出・飽和チェック用）．フルフレーム側の統計は含まない．代表的な実測値: 飽和率 0・p99 ≒ 181（レンジの約 71%＝飽和なしで十分な信号量）．

## 評価時の注意・留保 (Notes for Evaluation)

SPEC_03 の Q&A に基づく留保事項．

- **8-bit RGB（RAW でない）**: Q1 で許容（線形性は確認済み: γ1.0・トーンマップ OFF）．主指標は CoV・中心周辺勾配・動径 min/max（輪帯平均でロバスト）を推奨．
- **ビネット未除去（最重要）**: DFK 23UX249 は在カメラのレンズシェーディング補正を持たず，補正データも付加されない（device-state・公式仕様で確認済）．したがって観測ムラには**レンズビネットが含まれる**．V の除去には **TIAS 照明とは独立な一様光源でのフラットフィールド撮影**が必要（Q5）．**`WhiteBoard_full_*`（四隅を含むフルフレーム）はこの V 特性化・目視確認のために提供**している．補正しないまま評価する場合は「照明×レンズの系全体の均一性」として留保すること．
- **固定・非 identity の WB**: 校正しないためチャンネルゲインは固定（[1,1,1] ではない）．相対ばらつき指標には不変だが（Q3），ロバストチェックとして**緑チャンネル単体でも均一性を算出**することを推奨．
- **黒レベル（Brightness=50）**: 加算オフセットか別スケールかが未確定（Q7）．機種間比較の前に**ダークフレーム減算**で真の黒レベルを実測・減算することを推奨．
- **露出の手動固定**: device-state の自動フラグが二重で，手動固定を実機で確定する必要がある（Q6）．

## 関連 (Related)

- [SPEC_03 白板撮影プロトコルと TIAS 撮影条件](SPEC_03_白板撮影_照明均一性評価.md) — プロトコル・基準値・SmTIAS 回答（詳細・根拠）
- 実装: `TIASshot/Cameras/IScam.cs`（`ShotWhiteBoard`），`TIASshot/Utils/ImageStats.cs`（飽和統計・JSON 生成）