評価仕様 (Evaluation Specification)

sm-evaluate CLI が担う シミュレーション結果 / 実測 PNG の照明均一性評価 の方法論を定義する．本書はアルゴリズム・物理動機・規約をまとめ，実装の根拠（why）と入出力（what）を記述する．評価設定 YAML のスキーマ詳細は SPEC_02_シーン定義仕様 の evaluation セクションを参照．

関連:

• 評価結果の歴史: TEST_01_キャリブレーション検証履歴
• 物理シーン仕様: SPEC_03_基準設計の物理構成
• 評価 YAML スキーマ: SPEC_02_シーン定義仕様 §evaluation
• 実装エントリ: src/sm_tias_lightsim/cli/evaluate.py, src/sm_tias_lightsim/evaluation/, src/sm_tias_lightsim/uniformity.py

概要 (Overview)

シミュレーション結果（output/<run>/luminance.npy または render_uint8.png）と実測 PNG (reference_measurement/.../*.png) を 同一の評価パイプラインに通し，無次元の均一性指標（CoV，勾配 %，中心/周辺比 等）を算出する．シミュと実測を比較可能にする鍵は OETF 順方向適用 で，シミュの linear ドメインを実機の sRGB 符号化ドメインに揃える操作である（後述）．

設計目的は MiniTias-Evaluation との 数値整合性（実測 PNG に対し小数点 14 桁レベルで一致確認済み，TEST_01 既知差分 #9）と，シミュ⇄実測の 公平な比較．

評価パイプライン (Evaluation Pipeline)

入力 (PNG / luminance.npy)
    │
    ▼  uint8 PNG → 0..255 配列, luminance.npy → float32 配列のまま
[1] 読み込み
    │
    ▼  Rec.709 加重和 Y = 0.2126R + 0.7152G + 0.0722B (RGB 入力時)
[2] luma 変換
    │
    ▼  ROI 設定 (image_pixel 型) に従い (x, y, width, height) 領域を切り出す
[3] ROI 抽出
    │
    ▼  normalization.enabled = true のとき: linear ドメインで mean を target_mean に揃える線形ゲイン
[4] mean 正規化 (任意・linear モード用、OETF と排他)
    │
    ▼  oetf.enabled = true のとき: 標準 sRGB OETF を順方向適用 + 実測 mean アンカー
[5] OETF 順方向適用 (任意・シミュ用、normalization と排他)
    │
    ▼  (任意) quantize_uint8: float → uint8 量子化
[6] 量子化
    │
    ▼  CoV, std, max-min, mean, max, min を計算
[7] 全体指標
    │
    ▼  3 ゾーン分類 (center/middle/periphery) → 中心/周辺比，勾配 %
[8] ゾーン指標
    │
    ▼  20 ビンの放射状プロファイル
[9] 動径指標
    │
    ▼  metrics.csv, figures/{luminance_map, histogram, radial_profile, zone_map}.png
[10] 出力

各ステージの実装は以下のモジュールに分かれる:

ROI 仕様 (Region of Interest)

評価板の 撮影範囲内の有効領域 を矩形で切り出す．評価設定 YAML の roi セクションで指定する．

image_pixel 型

実測 PNG の座標系（左上原点，X 右，Y 下）で 絶対ピクセル座標を直接指定する．シミュ画像と実測画像で 物理対応する同じ領域を切り出すために，シミュ側の ROI は実測 ROI の物理対応関係から決定する．

roi:
  type: image_pixel
  x: 24          # 左上 X
  y: 37          # 左上 Y
  width: 464
  height: 450

実機 ⇄ シミュの物理対応（既存値）

シミュ ROI と実機 ROI は 物理対応済み（評価板の同じ XY 領域）．シミュの orthographic センサと実機カメラの向き変換は SPEC_03 画像 ↔ 物理 の向き を参照．

OETF 順方向適用の仕様 (Forward OETF Application)

最重要セクション．シミュ linear 結果と実測 sRGB PNG を直接比較すると CoV や勾配の絶対値は不一致になる．これを データに合わせて回す係数ゼロで解消するのが OETF 順方向適用．

物理動機

• 実機 PNG は ISP 内で sRGB OETF (IEC 61966-2-1) が掛かった非線形符号化値．Camera2 YUV_420_888 → BT.601 は定義上ガンマ済み R'G'B' 上の量．
• シミュは Mitsuba の linear 放射輝度．
• 無次元指標 (CoV / 勾配 / C/P) は線形変換に対してのみ不変．非線形 OETF を介すと値が変わる．
• 両者を同じドメイン（gamma 空間 luma）に揃えれば，「物理が同じなら指標も同じ」が成り立つ．

標準 OETF（IEC 61966-2-1）

        ┌─ 12.92 · L                       (L ≤ 0.0031308)
V(L) = ─┤
        └─ 1.055 · L^(1/2.4) − 0.055       (L  > 0.0031308)

L は linear（0..1 正規化），V は sRGB 符号化値（0..1）．実装は evaluation/oetf.py の apply_srgb_oetf()．

露出アンカー（mean 一致）

露出（線形ゲイン）は AE が制御する量で，シミュ側で任意に決められない．実測 ROI mean に対数二分でアンカーする：

1. シミュ linear ROI 全体に係数 α を掛ける
2. OETF を順方向適用し uint8 量子化
3. 量子化後 mean が実測 mean (146.7146) に一致する α を対数二分で求める
4. 線形ゲインなので 形状指標 (CoV / 勾配 / C/P) は α に対し不変．データに合わせて回す自由度はゼロ．

二重適用禁止規則

• 実測 PNG には絶対に OETF を適用しない．ISP で既に sRGB 符号化されているため二重適用になる．
• configs/eval_real.yaml は oetf セクション無し（無効）．configs/eval_baseline.yaml は oetf.enabled: true（シミュ用）．
• スキーマ詳細は SPEC_02 §evaluation 参照．

luma vs luminance と演算順序の整合

実測 MiniTias-Evaluation の「輝度値」は厳密には Rec.709 luma Y'（ガンマ済み成分への加重和 Y' = 0.2126R' + 0.7152G' + 0.0722B'，ガンマを戻さない）．シミュ側は linear luminance に直接 OETF を当てている．OETF は非線形なので一般に Σwᵢ·f(xᵢ) ≠ f(Σwᵢ·xᵢ) だが，矛盾しない:

• Rec.709 重みは合計 1 (0.2126 + 0.7152 + 0.0722 = 1.0000)．
• R=G=B=x の無彩色画素では「チャネル別 OETF→加重和」Σwᵢ·f(x) = f(x) も「加重和→OETF」f(x·Σwᵢ) = f(x) も厳密に一致．
• シミュは白色 LED（RGB 等価 radiance）＋無彩色拡散材で厳密に R=G=B → 「luminance に直接 OETF」 ＝ 「実測の演算順（チャネル別 OETF → Rec.709 加重和）」と数値同値．
• 本質: OETF は不整合を作る操作ではなく消す操作．OETF 前のシミュ＝linear 空間 luma，実測＝gamma 空間 luma で別ドメイン（真の不整合）．OETF 後は両者とも gamma 空間 luma になり，突合が正当化される．

残る近似（モデル誤差として正直に保持）

1. 無彩色等価が厳密なのはシミュ側のみ．実測白板画像は LED 分光・ISP ホワイトバランス・センサ応答で微小に非グレー（R'≈G'≈B' が完全でない分の luma vs luminance 差）．
2. カメラ実 OETF ≠ 厳密 sRGB（独自トーンマップ）．
3. ISP レンズシェーディング補正の残差（TEST_01 既知差分 #6，未対処）．

量子化（任意）

oetf.quantize_uint8: true で float → uint8 量子化を施す．実測 PNG が uint8 のため，公平比較には量子化を入れる．量子化ノイズ ≈ ±0.5 単位は無次元指標にほぼ影響しない（spp=1024 の MC ノイズの方が大きい）．

mean 正規化（linear モード用） (Mean Anchor Normalization for Linear Mode)

OETF を適用しない linear ドメインでの評価結果について mean を target_mean に揃える線形ゲイン正規化 を行う．OETF の露出アンカーと同じ思想を，OETF を介さない linear 評価モードに対称展開したもの．

物理動機

シミュ側の radiance 値は scene YAML での暫定値（実測 mean アンカー）で決まるが，シーン設定を変えると（例: 発光面サイズや反射率の変更）絶対値スケールが大きく動く （Step 8-7 で実証．size を 2.8×3.5 → 1.5×1.5 mm に変えると mean が 2.83× 上昇）．数値指標 (CoV / 勾配 / C/P) は 線形ゲインに対し不変 なので形状指標の比較は問題ないが，輝度マップを画像で見比べる際に color scale が桁違いになり「形」の比較が阻害される ．

linear ドメインで mean を共通の target_mean に揃えれば，color scale を揃えた状態で複数シミュ結果の形を視覚的・数値的に公平比較できる．

計算式

α = target_mean / values.mean()
normalized = values × α

線形ゲイン α を全要素に乗算するのみ．返り値は (normalized, α) のタプル．values.mean() == 0 の場合は ValueError．

不変性（厳密）

OETF との排他制御

oetf.enabled=true と normalization.enabled=true を同時指定すると ValidationError（OETF の露出ソルバが既に mean アンカーを行うため二重適用になる）．EvaluationConfig._validate_oetf_normalization_exclusive で保証．

後方互換

normalization キー省略時は無変換．既存設定（configs/eval_real.yaml，configs/eval_baseline.yaml）は変更不要．configs/eval_baseline_linear.yaml のみ新規追加された設定．

主用途

TEST_03 輝度マップ形状追跡 における 複数 Step の輝度マップ形状比較．発光面サイズ・反射率等を変えたシミュレーション結果を，共通の色スケールで並べることで「形」の異同を視覚的に判定できる．

メトリクス定義 (Metrics Definitions)

ROI 内の輝度配列 Y を入力に，以下を算出．計算式は uniformity.py 実装と一致．

全体指標

ゾーン分類 (3 zones)

ROI 中心からの 正規化楕円距離 d に基づき分類:

d = sqrt( ((x - cx) / (W/2))² + ((y - cy) / (H/2))² )

ゾーン指標

ゾーン境界 (0.33, 0.66) は評価 YAML の zones.boundaries で変更可．

動径プロファイル

正規化距離 d を 20 ビン（既定）に分け，各ビンの平均輝度を取る．figures/radial_profile.png でグラフ化．

動径 min/max 比（オプション）

metrics.radial_min_max: true で有効化．動径プロファイル（20 ビン平均）の 最小ビン値 ÷ 最大ビン値．画素単位 max_min 比よりノイズ・外れ値に対しロバスト．

metrics.csv に radial_min_max_ratio / radial_min_distance / radial_min / radial_max の 4 列を末尾に追加．既定 False（既存挙動互換）．metrics.radial_profile の有無に関わらず内部で動径プロファイルを算出するため独立して有効化可能．実装: evaluation/radial.py:calc_radial_min_max_ratio（MiniTias-Evaluation の src/analysis/spatial.py からマージ）．

可視化規約 (Figure Conventions)

sm-evaluate は figures/ に以下 4 種を生成．MiniTias-Evaluation 互換スタイル．

実装: evaluation/visualize.py．

出力ファイル仕様 (Output Files)

sm-evaluate --output <dir>/ で以下を生成:

<dir>/
├── metrics.csv          # 1 行 ヘッダ + 1 行 値（評価結果サマリ）
└── figures/
    ├── luminance_map.png
    ├── histogram.png
    ├── radial_profile.png
    └── zone_map.png

metrics.csv カラム定義（ヘッダ順）

cov, std, max_min_ratio, mean, max, min,
center_mean, center_std, middle_mean, middle_std, periphery_mean, periphery_std,
center_periphery_ratio, gradient_magnitude

すべて float．gradient_magnitude は上記「勾配 %」と同じ値．

キャリブレーション目標 (Calibration Target)

PLAN_02_開発ステップ より，実測 baseline 1 枚 (MiniTIAS_20260408_144434) に対する数値:

シミュ側はこれらの値に 数値だけでなく形（輝度マップ分布）も近づけることが目標．形の追跡は TEST_01 輝度マップ形状の追跡 を参照．

キャリブレーション経過（要約） (Calibration Progression Summary)

Step 8 で実施した検証イテレーションの結論サマリ．各 Step の仮説・変更・数値・解釈・学びの詳細は TEST_01_キャリブレーション検証履歴 を参照．

確定基準

• 設定: R=0.85, max_depth=8, spp=1024, OETF=on
• 評価: sRGB ドメイン（OETF 順方向適用後の uint8 量子化値で比較）
• 残差: CoV 0.089 vs 実測 0.0427 = 2.1×（初期 spp=128 時の 5.5× から大幅縮小）

寄与順（訂正済み）

OETF（最大・約 2/3，解消済み）＞ ISP LSC（残差主因候補・未対処）＞ 反射率（弱いレバー）

旧版「主因は ISP レンズシェーディング (83%)」は OETF を抜かした交絡判断で誤りだった．OETF 適用後で寄与順を訂正．

主要な発見（時系列）

次のアクション

残差 1.6〜1.9× に対する LSC（ISP レンズシェーディング）順方向モデルの設計・実装．物理動機づけ低自由度形（cos⁴ ベース等）に限定し overfitting を回避．詳細は TEST_01 Step 8-N 候補 参照．

反射率は均一性からは一意に定まらない（物理範囲内で縮退）ため暫定 0.85 据え置き．実フィラメント分光反射率データ入手時に再校正．

参照 (References)

• SPEC_02_シーン定義仕様 §evaluation: 評価 YAML スキーマ
• SPEC_03_基準設計の物理構成: シーン物理仕様
• TEST_01_キャリブレーション検証履歴: 評価値の歴史と検証経緯
• TEST_02_シミュレーション実行記録: output/ 索引
• TEST_03_輝度マップ形状追跡: 形を実機に近づける観点
• PLAN_02_開発ステップ: 実測ターゲット出典
• 実装エントリ:
  • src/sm_tias_lightsim/cli/evaluate.py: CLI
  • src/sm_tias_lightsim/uniformity.py: Rec.709 luma + CoV/std/max-min
  • src/sm_tias_lightsim/evaluation/oetf.py: 標準 sRGB OETF + 露出アンカー
  • src/sm_tias_lightsim/evaluation/normalize.py: mean 正規化（linear モード用）
  • src/sm_tias_lightsim/evaluation/roi.py: ROI 抽出
  • src/sm_tias_lightsim/evaluation/zones.py: 3 ゾーン分類 + C/P + 勾配 %
  • src/sm_tias_lightsim/evaluation/radial.py: 動径プロファイル
  • src/sm_tias_lightsim/evaluation/visualize.py: 4 種 figures 生成