diff --git "a/docs/04_SPEC/SPEC_03_\347\231\275\346\235\277\346\222\256\345\275\261_\347\205\247\346\230\216\345\235\207\344\270\200\346\200\247\350\251\225\344\276\241.md" "b/docs/04_SPEC/SPEC_03_\347\231\275\346\235\277\346\222\256\345\275\261_\347\205\247\346\230\216\345\235\207\344\270\200\346\200\247\350\251\225\344\276\241.md" new file mode 100644 index 0000000..f0807d2 --- /dev/null +++ "b/docs/04_SPEC/SPEC_03_\347\231\275\346\235\277\346\222\256\345\275\261_\347\205\247\346\230\216\345\235\207\344\270\200\346\200\247\350\251\225\344\276\241.md" @@ -0,0 +1,238 @@ +# 白板撮影プロトコルと TIAS 撮影条件(照明均一性評価) (White-Board Capture Protocol & TIAS Conditions) + +本書は,従来型口腔内画像取得装置 **TIAS** の照明均一性を評価するための **白板撮影プロトコル**(撮影の目標・要件)と,それに対する **TIASshot(撮影アプリ)の現行撮影条件**,および **SmTIAS-Evaluation 側との確認結果(Q&A)** を 1 つにまとめたものである.最終目的は **TIAS と SmTIAS の照明均一性を装置間比較する**ことにある. + +> **外部参照について**: 本書が参照する `PLAN_01 要件定義書`・`SPEC_02 照明均一性評価アルゴリズム`・`TECH_01 DNG 対応要求仕様`・`TEST_01/03 評価報告書` 等は,**別プロジェクト「SmTIAS-Evaluation」側のドキュメント**であり本リポジトリには含まれない.本書ではプレーンテキストで参照名のみ示す. +> +> **構成**: Part 1 = 撮影プロトコル(こう撮るべき/SmTIAS 基準),Part 2 = TIAS の現行撮影条件(実際どう撮るか),Part 3 = 確認事項と SmTIAS の回答・依頼事項. + +--- + +# Part 1: 撮影プロトコル (Capture Protocol) + +SmTIAS と同一の評価パイプライン・同一指標で比較できる白板データを取得するためのプロトコル(撮影の目標・要件). + +## 目的 (Purpose) + +白板(全面が一様反射率の面光源応答ターゲット)を撮影し,**被写体の反射率ムラを排除して,観測される輝度ムラを照明系のムラに帰着させる**.取得データから CoV・最大/最小比・中心周辺勾配・動径 min/max 比などの均一性指標を算出する(指標定義は SmTIAS-Evaluation の SPEC_02). + +### なぜ条件を SmTIAS と揃えるのか + +主目的は **SmTIAS と TIAS の照明系の差**を見ること.撮影条件(露出・WB・現像処理)が両装置で異なると「照明系の差」と「撮影条件の差」が混在し比較が成立しない. + +※ ただし CoV・最大/最小比等は画像内の**相対ばらつき指標**であり,全画素に等しく作用する係数(露出スケール・線形ゲイン等)には不変である.したがって**最優先で揃えるべきは「線形性を壊す処理(トーンカーブ・自動露出・自動 WB・ノイズ低減)の有無」**であり,露出値・ISO の絶対一致は副次的である. + +## 撮影対象(白板) (Target: White Board) + +- TIAS の積分球開口部に合致する**別白板**を用いる(SmTIAS 用白板とは物理形状が異なるため流用しない). +- 開口部全面を均一反射率で覆える寸法・形状.表面は均一拡散反射(マット)で,光沢・色ムラ・汚れ・傷がないこと. +- 白板の白色面のみを ROI とし,開口縁・筐体壁面・フレーム・ラベル等は除外する. + +## 揃える基準値(SmTIAS 定量撮影モード) (Reference Settings) + +SmTIAS は定量撮影モードで **RAW_SENSOR (DNG) を線形・無補正で取得**している(機種 SH-02M / AQUOS sense3).TIAS 側はこの設定思想に揃える. + +| 項目 | SmTIAS 定量モードの値 | 揃える狙い | +| --- | --- | --- | +| 出力形式 | RAW_SENSOR (DNG, 10-bit linear) | トーンカーブ・sRGB 符号化を経ない線形信号 | +| 自動露出 (AE) | OFF(手動固定) | フレーム間で露出を変動させない | +| 露出時間 | 8,333,333 ns(≒ 1/120 s) | 固定露出 | +| ISO 感度 | 40(最低感度) | ノイズ最小・固定 | +| ホワイトバランス (AWB) | OFF,ゲイン [1,1,1,1],色変換 identity | 生の比率を保つ | +| オートフォーカス (AF) | OFF(手動固定) | フォーカス固定 | +| ノイズ低減 (NR) | OFF | 空間平滑化で輝度分布を歪めない | +| エッジ強調 | OFF | シャープ化による輝度改変を避ける | +| トーンマップ | 線形 (CONTRAST_CURVE_LINEAR) | 入射光量に比例した値を保つ | +| シェーディング補正 (LSC) | **適用してビネット除去**※ | レンズ由来の周辺減光を除き照明系のムラだけを残す | +| ブラックレベルロック | true | 黒レベルを固定 | + +※ **シェーディング補正(LSC)は他の処理と性質が逆で,必ず適用してビネットを除去する**.NR・トーンカーブ・エッジ強調は信号を不可逆に歪めるため OFF にするが,LSC は**レンズ由来の周辺減光(ビネット)を除く**補正であり,掛けないと照明系のムラとカメラのビネットが混在してしまう.SmTIAS では実機 DNG が LSC 未補正で出力されるため評価側でシェーディングマップを順適用して除去している.**未補正のまま評価すると指標が大きく悪化する**(SmTIAS 実測: CoV 0.070→0.146,中心周辺勾配 8.4%→31%,動径 min/max 0.86→0.53). + +## 設定方針 (Capture Policy) + +優先度の高い順に: + +1. **線形・無加工で取得する(最優先)**: AE・AWB・NR・エッジ強調・トーンカーブを OFF にし,可能なら RAW で保存する. +2. **シェーディング補正(ビネット除去)は必ず適用する**: 上記とは逆に,レンズ由来の周辺減光は補正して除く(在カメラ補正 or RAW+シェーディングマップで評価側補正). +3. **すべて手動固定する**: 露出・ゲイン・WB・フォーカスを手動固定し,全撮影で同一値. +4. **飽和・黒つぶれを避ける**: 白板最明部が飽和せず,かつレンジの 7〜9 割程度になるよう露出を調整する(SmTIAS は飽和画素率 0%・p99 が白レベル 1023 に対し約 880). +5. **露出値の一致は副次的**: 「線形・無加工・飽和なし」を満たした上で TIAS 固有の最適露出を選び,その値を記録する. + +## 撮影手順 (Procedure) + +1. **設置**: TIAS 開口部に白板を装着し,カメラ・白板・装置の相対位置を固定する. +2. **設定適用**: 上記設定を適用(処理 OFF・手動固定・可能なら RAW).**シェーディング補正は OFF にせずビネットを除去できる状態にする**. +3. **露出調整**: 白板最明部がレンジの 7〜9 割程度になるよう調整し,値を確定・記録. +4. **外乱光条件**: 原則 TIAS 自前照明のみ.室内照明の影響を見たい場合は位置・露出固定のまま室内灯 ON/OFF の連続 2 枚を撮影する. +5. **複数枚撮影**: 同一条件で複数枚(SmTIAS では 12 枚)撮影し,再現性(SSIM・指標分散)を評価できるようにする. +6. **記録**: 各撮影の条件(露出・ISO・WB・外乱光の有無・温度等)と,使用したカメラ仕様を記録する. + +## データ管理・命名 (Data Management) + +- **保存先**: SmTIAS-Evaluation 側の `data/tias/whiteboard/` に配置する想定. +- **RAW の場合**: RAW 本体に加え撮影条件・センサ特性のメタデータ(JSON 等)を併置する(SmTIAS の `*.meta.json` に準拠できると後段の解析が容易). +- **ファイル名**: 装置・対象・撮影日時が判別できる命名(例: `TIAS_<日付>_<連番>`). + +--- + +# Part 2: TIAS 現行撮影条件 (Current TIAS Conditions) + +撮影アプリ **TIASshot**(C# / WinForms,Lucam + ImagingSource を制御)が,照明均一性評価用に**実際にどの条件で撮影するか**を,コード・設定ファイルから抽出したもの. + +## 前提: 校正なしの撮影 (Premise: No Calibration) + +通常の TIASshot(舌診用途)は「チャート検出 → WB 自動調整 → TCC 色補正 → sRGB 出力」という校正フローを行う.しかし照明均一性評価では色を合わせること自体が目的でないため,白板撮影では **WB 自動調整・TCC 色補正・チャート検出を一切行わず,カメラ素の RGB のみを保存**する.WB のチャンネルゲインは設定ファイル/デバイス状態の**固定値**のまま. + +> TIASshot には校正を前提としない独立撮影パス(`#if DEBUG` 限定の白板撮影モード)を実装済み.本 Part はその撮影が用いる設定を記す. + +## カメラ構成と出力形式 (Cameras & Output) + +- **Lucam(Lumenera)優先 → 無ければ ImagingSource** にフォールバック.接続中のカメラは画面の機種名欄(`txtDeviceName`)で確認できる. +- 出力は **いずれも RGB24(8-bit/ch,デモザイク済み)**.RAW ではない. +- **実機の主対象は ImagingSource DFK 23UX249**(基準データ・実撮影で使用,SN 45610026). + +| カメラ | 機種 | 解像度(ROI 後) | 出力 | +| --- | --- | --- | --- | +| Lucam | Lumenera Lw110 | 1280 × 1024 | RGB24 8-bit | +| ImagingSource | DFK 33UX178 | ROI 1840 × 2440 | RGB24 8-bit | +| ImagingSource | DFK 23UX249 | ROI 1136 × 1528 | RGB24 8-bit | + +## カメラ別 撮影条件 (Per-Camera Settings) + +設定元: `Lucam.cs`+`config.xml`,`DFK33UX178.xml`/`DFK23UX249.xml`(デバイス状態). + +### Lucam (Lumenera Lw110) + +| 項目 | 値 | 備考 | +| --- | --- | --- | +| 出力 | RGB24 8-bit | PF_8 → デモザイク(HIGH_QUALITY) | +| 露出 | 60 ms(手動固定) | 自動露出なし | +| ゲイン | 1.5(固定) | | +| ホワイトバランス | B 2.62 / G 1.72 / R 1.70(固定) | 校正なしのため自動調整しない | +| 色補正行列 (CCM) | **LED(適用)** ⚠ | SDK 内蔵の光源別 3×3 補正(チャンネル混合).白板モードでは NONE 推奨 | +| NR / エッジ / トーンカーブ | アプリ側で適用なし | | +| シェーディング補正 | **適用なし** ⚠ | ビネット未除去・マップ未保存.SDK に `LSC_X`/`LSC_Y`(2 係数の簡易補正)あり(未使用) | + +### ImagingSource DFK 33UX178 + +| 項目 | 値 | 備考 | +| --- | --- | --- | +| 出力 | RGB24 8-bit(3072×2048,ROI 切出) | | +| 露出 | 手動 ≈1/60 s | ※自動フラグ二重・要確認 | +| ゲイン | 1.0(Auto OFF) | | +| ホワイトバランス | Auto OFF・G64/B134/R79(固定) | | +| ガンマ | 1.0(線形)・トーンマップ OFF | | +| NR / シャープネス | Denoise 0 / Sharpness 0 | | +| 色補正行列 (Color Matrix) | **OFF** | カメラ内 CCM 無効 | +| 明るさ (Brightness) | 240 | ※黒レベル/オフセット相当か要確認 | +| シェーディング補正 | 設定項目なし・**適用なし** ⚠ | | + +### ImagingSource DFK 23UX249(実機の主対象) + +| 項目 | 値 | 備考 | +| --- | --- | --- | +| 出力 | RGB24 8-bit(1920×1200,ROI 切出) | | +| 露出 | 手動 ≈1/60 s(16.6 ms) | ※自動フラグ二重・要確認 | +| ゲイン | 0.0(Auto OFF) | | +| ホワイトバランス | Auto OFF・G64/B140/R100(固定) | | +| ガンマ | 100(= 1.0,線形)・トーンマップ OFF | スケール表記が DFK33 と異なるだけ | +| NR / シャープネス | Denoise 0 / Sharpness 0 | | +| 色強調 (Color Enhancement) | 既定 ON ⚠ → **白板モードで OFF にする** | DFK33(CCM OFF)と異なる色処理.非線形の懸念 | +| 明るさ (Brightness) | 50 | ※要確認(DFK33=240 と差大) | +| シェーディング補正 | 設定項目なし・**適用なし** ⚠ | | + +## SPEC_03 基準値との対照 (Comparison) + +○=合致,△=条件付き/要確認,✗=相違. + +| 項目 | SmTIAS 基準 | Lucam | DFK33UX178 | DFK23UX249 | +| --- | --- | --- | --- | --- | +| 出力形式 | RAW 10-bit linear | ✗ RGB24 8-bit | ✗ RGB24 8-bit | ✗ RGB24 8-bit | +| 自動露出 | OFF 固定 | ○ | △ 要確認 | △ 要確認 | +| ゲイン | 固定 | ○ | ○ | ○ | +| ホワイトバランス | OFF・identity | △ 固定(非 identity) | △ 固定(非 identity) | △ 固定(非 identity) | +| NR | OFF | ○ | ○ | ○ | +| エッジ強調 | OFF | ○ | ○ | ○ | +| トーンカーブ | 線形 | ○ | ○ γ1.0 | ○ γ1.0 | +| 色補正/色処理 | identity | ✗ LED CCM | ○ CCM OFF | ✗ Color Enhancement ON(白板モードで OFF) | +| シェーディング (LSC) | 適用してビネット除去 | ✗ 未除去 | ✗ 未除去 | ✗ 未除去 | +| 黒レベル | lock | △ 要確認 | △ Brightness 240 | △ Brightness 50 | + +## 現状の出力・保存 (Output) + +- 通常は `Shot{NO}.png`(RGB24)+ `sRGB{CN}_{NO}.jpg`(TCC 変換後)を `C:\TIAS_Data\日付\時刻-名称\` に保存するが,**白板モードでは sRGB を生成せず RGB(PNG) のみ**保存し,撮影条件+飽和統計を JSON サイドカー(`whiteboard_meta.json`)で併置する. +- 白板モードのメタデータ記録項目: 機種・SN・解像度/ROI・露出(ms)・ゲイン・WB ゲイン・Color Enhancement 状態・γ/トーンマップ・Denoise/Sharpness・Brightness(黒レベル)・**シェーディング補正状態(=未補正・LSC 保留)**・飽和率・p99・ch 別 mean/max・撮影日時. + +--- + +# Part 3: 確認事項と SmTIAS-Evaluation の回答 (Q&A) + +TIAS 側の現行条件に対する確認事項と,SmTIAS-Evaluation 側の回答.**致命的に対応が必要なのは Q5(ビネット)と Q7(黒レベル)の 2 点**,残りは概ね許容(条件付き). + +## Q1. 8-bit RGB(非 RAW)の許容性 → ○ 許容(条件付き) + +許容してよい.白板平均が 8-bit レンジの中〜上(mean 150〜200)にあれば量子化ノイズの CoV 寄与は約 0.002 程度で,SmTIAS の CoV 0.04〜0.07 に対し無視できる.条件は撮影パスが**真に線形**(γ=1.0・トーンマップ OFF,確認済)であること.8-bit の真のリスクはビット深度でなく隠れた非線形なので,リニアリティだけ実機で担保すること.主指標は CoV・中心周辺勾配・動径 min/max(輪帯平均でロバスト)とする.**生 Bayer の追加実装は不要**. + +## Q2. デモザイクの許容性 → ○ 許容 + +白板の照明ムラは低空間周波数であり,デモザイク補間アーティファクト(エッジ・高周波で発生)はほぼ無関係.HIGH_QUALITY で問題なし. + +## Q3. 固定・非 identity の WB → ○ そのまま評価可 + +固定 WB のまま評価してよい.正確な根拠は「一様ゲインだから」ではなく,**「全チャンネルが同一の空間パターンを持つ限り,固定の線形結合(WB でも CCM でも)は空間パターンをスカラ倍に保つので相対指標は不変」**だから.唯一の注意: 色ビネット等で照明色が空間的に変わるとチャンネルごとに空間パターンが異なり合成 CoV がわずかに動く(Lucam の B=2.62 のように WB ゲインが大きいと増幅されうる).**ロバストチェックとして緑チャンネル単体でも均一性を算出**することを推奨(単一チャンネルは一様ゲインに完全不変,G は輝度寄与 0.72 で代表性も高い). + +## Q4. 色処理の機種差 → 可能な限り OFF を推奨 + +- **Color Enhancement(DFK23)は非線形(彩度強調)の可能性が高く害**.必ず OFF に(白板モードで実装済み). +- **CCM(Lucam)は固定線形なので輝度均一性への一次影響は小さい**が,①クリップによる非線形化,②機種間不一致が残る.**NONE 推奨**(両方を解消し 3 系統が揃う). + +## Q5. ★ シェーディング / ビネット(最大の論点)→ フラットフィールド補正で対応(独立光源で) + +- 測定モデル: 画像 I = 照明 L × レンズビネット V ×(白板で一様な反射率).欲しいのは L,邪魔は V. +- **落とし穴**: 「TIAS 自身の光で均一面を別撮りして割る」と **L と V を分離できない**(参照画像も `L×V` のため,割っても反射率比 ≒1 になるだけ). +- **正しいフラットフィールド**: V を特性化するには **TIAS 照明とは独立な既知の一様光源**(均一 LED パネル/ライトボックス/別の積分球出力等)で画面全面を撮影し,正規化して V(x,y) を得て白板画像を除算する.まず SDK/カメラベンダ(Lumenera / The Imaging Source)のレンズシェーディングデータが使えないかも確認を(Lumenera には `LSC_X`/`LSC_Y` の簡易補正があるが 2 係数の粗いモデルで要検証). +- 特性化できない場合は,結果を**「照明×レンズの系全体の均一性」と明記**し,レンズ補正済みの SmTIAS とは**直接比較不可(TIAS 照明均一性の下限値)**として留保する. +- 重要な理由: **TIAS は積分球で照明が本来きわめて均一なはず**.だとすると未補正画像のムラは**ほぼレンズビネットを測っているだけ**になりうる.レンズ補正済み SmTIAS と未補正 TIAS を比べると TIAS が不当に悪く見えるため,フェアな比較には V 除去が必須. + +## Q6. 露出の自動/手動 → 手動固定を確定・検証 + +手動固定が必須.実機で有効露出がフレーム間一定か(SDK 読み戻し or 連続フレームの平均輝度が一定か)で検証し,二重フラグのどちらが効いているかを確定する. + +## Q7. ★ 黒レベル / Brightness → ダークフレーム減算(要注意) + +- Brightness が**加算オフセット(ペデスタル)**なら均一性指標を**良い方に偏らせる**(加算 c に対し CoV = σ/(μ+c),max/min = (max+c)/(min+c) がともに縮む).DFK33=240 と DFK23=50 の差が**そのまま指標差として混入**し機種間比較が無効になる. +- 対策: **機種ごとにダークフレーム(遮光/無照明)を撮影して真の黒レベルを実測し,指標算出前に減算する**(SmTIAS は黒レベル 64 を減算).Brightness が加算か乗算かを SDK で確認し,加算なら減算,乗算なら一様係数で不変扱い. +- 要確認: 8-bit で Brightness=240 が純加算ペデスタルなら白板は即 255 飽和でレンジがほぼ無くなる → **240 は別スケールの制御の可能性が高い**.意味の確定が必要. + +## Q8. 飽和回避(8-bit)→ ヒストグラムで検証・記録 + +ROI 内で値 255(念のため ≥254)の画素数 = 0 を確認.目安は最明部 180〜230(レンジの 70〜90%).**飽和画素率・p99・チャンネル別 max をショットごとに記録**(白板モードで実装済み). + +## Q9. 出力形式・メタデータ → JSON サイドカーを推奨 + +SmTIAS の `*.meta.json` に倣い,**ショットごとに JSON サイドカー**で記録(白板モードで実装済み): 機種・解像度/ROI・露出・ゲイン・WB チャンネルゲイン・CCM/Color Enhancement の状態・γ/トーンマップ・Denoise/Sharpness・Brightness(黒レベル)・シェーディング補正状態+使用フラットフィールド/ダークフレーム名・外乱光条件・飽和/低露出画素率・チャンネル別 mean/max・撮影日時. + +## 依頼事項まとめ (Action Items for TIAS Side) + +- [ ] **独立な一様光源**でフラットフィールド(レンズビネット V)を取得する手段の確保(Q5).不可なら系全体評価+留保で運用. +- [ ] 機種ごとの**ダークフレーム取得**と Brightness の意味(加算/乗算)の確定(Q7). +- [x] **色処理 OFF**(DFK23 Color Enhancement OFF)(Q4)— 白板モードで実装済み.Lucam CCM=NONE は未対応. +- [ ] 露出の手動固定の実機確定(Q6). +- [x] **JSON サイドカー**メタデータ(Q9)と飽和チェックの記録(Q8)— 白板モードで実装済み. + +--- + +## 関連(外部参照) (Related — External) + +以下は別プロジェクト「SmTIAS-Evaluation」側のドキュメント(本リポジトリには含まれない). + +- `PLAN_01 要件定義書` — 評価対象・優先度(優先度 2: SmTIAS vs TIAS 照明均一性比較) +- `SPEC_02 照明均一性評価アルゴリズム` — 評価指標・ROI 設定・解析手順 +- `TECH_01 DNG 対応要求仕様` — DNG/メタデータ・LSC の扱い +- `TEST_01 照明均一性評価報告書` — SmTIAS 単体の撮影実績(12 枚) +- `TEST_03 外乱光影響評価報告書` — 外乱光条件の撮影手法・未補正で指標が悪化する実測例 + +本リポジトリ側の関連: + +- 白板撮影モードの実装: `TIASshot/Cameras/IScam.cs`(`ShotWhiteBoard`),`TIASshot/Utils/ImageStats.cs`(飽和統計・JSON) +- カメラ設定の出典: `TIASshot/Cameras/Lucam.cs`,`TIASshot/DFK33UX178.xml`,`TIASshot/DFK23UX249.xml`,`TIASshot/config.xml`