diff --git "a/docs/04_SPEC/SPEC_04_\347\231\275\346\235\277\346\222\256\345\275\261\343\203\207\343\203\274\343\202\277\344\273\225\346\247\230.md" "b/docs/04_SPEC/SPEC_04_\347\231\275\346\235\277\346\222\256\345\275\261\343\203\207\343\203\274\343\202\277\344\273\225\346\247\230.md" new file mode 100644 index 0000000..ea05593 --- /dev/null +++ "b/docs/04_SPEC/SPEC_04_\347\231\275\346\235\277\346\222\256\345\275\261\343\203\207\343\203\274\343\202\277\344\273\225\346\247\230.md" @@ -0,0 +1,90 @@ +# 白板撮影データ仕様(SmTIAS-Evaluation 引き渡し用) (White-Board Capture Data Specification) + +本書は,TIASshot の白板撮影モードで取得し **SmTIAS-Evaluation 側へ引き渡す白板撮影データ**について,**実際の撮影設定値・ファイル構成・メタデータの意味・評価時の注意**をまとめたものである.撮影プロトコルの目的・基準値・質疑応答(Q&A)は [SPEC_03 白板撮影プロトコルと TIAS 撮影条件](SPEC_03_白板撮影_照明均一性評価.md) を参照する(本書は実データの説明,SPEC_03 は仕様・根拠という役割分担). + +## 概要 (Overview) + +- TIASshot の **白板撮影モード(照明均一性評価用・DEBUG 限定)** で取得した素の 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 生成)