# 輝度マップ形状追跡 (Luminance Map Shape Tracking)

数値指標 (CoV / 勾配 / C/P) は分布のばらつきを集約する量であり，**「形そのもの」は捕えない**．本ドキュメントはシミュレーション結果と実機の **輝度マップ形状**を画像で並べ，改善 Step ごとに形がどう変わったか／変わっていないかを追跡する．

関連:

- 改善イテレーションの履歴: [TEST_01_キャリブレーション検証履歴](TEST_01_キャリブレーション検証履歴.md)
- 評価方法論: [SPEC_04_評価仕様](../04_SPEC/SPEC_04_評価仕様.md)
- 実行記録: [TEST_02_シミュレーション実行記録](TEST_02_シミュレーション実行記録.md)

## なぜ「形」を別軸で追跡するのか (Motivation)

均一性の数値指標（CoV，勾配 %，中心/周辺比）は **分布の集約値** であり，**空間的なピーク位置・対称性・勾配方向** といった「形の特徴」を区別できない．例えば:

- 実機: ROI 中央付近にピークを持つ楕円状の分布 → C/P ≈ 1.065
- シミュ: ROI 下端にピークを持つ Y 軸単調勾配 → C/P ≈ 1.328

両者は **形が全く違う**が，どちらも「C/P 比という数値」だけで議論すると同じ尺度上に並んでしまう．**シミュレーションを実機に近づける**には数値だけでなく形の一致も必要．

## 比較パネル (Comparison Panel)

![輝度マップ形状の追跡: 実機 (TARGET) と Step 8-1 / 8-3 / 8-7 の比較（共有 colorbar・実機色域基準）](figures/luminance_map_evolution.png)

生成スクリプト: [`scripts/build_luminance_evolution_panel.py`](../../scripts/build_luminance_evolution_panel.py)．

### 表示方針: mean 揃え + 共有 colorbar（実機色域基準）

[Step 8-8](TEST_01_キャリブレーション検証履歴.md#step-8-8-linear-評価モードへの-mean-揃え正規化導入) で導入した **mean 揃え正規化** をパネル生成にも適用している．具体的には:

1. **各 ROI を mean=target_mean (146.7146) に線形ゲインで揃える** — 線形ゲインなので形状指標 (CoV / 勾配 / C/P / max-min) は厳密に不変
2. **共有 colorbar の値域は実機 ROI の 5〜95 パーセンタイル** (≈ 134〜155) を採用 — 実機色域を「基準座標」として固定
3. **シミュは実機色域からはみ出ると飽和** — 上端の暗領域は黒に振り切れ，下端の明領域は白に飽和

この表示方針により **「シミュが実機色域を逸脱している事実」が視覚的に直接見える**．数値 (CoV / 勾配) だけでは伝わらない「分布の広がりの違い」と「形（ピーク位置・対称性）の違い」が同時に確認できる．

## 観察された事実 (Observations)

実機 vs シミュ全 Step を並べて見て判明したこと:

| パネル | 形の特徴 | 共有 colorbar での見え方 |
| --- | --- | --- |
| 実機 (TARGET) | ROI 中央〜下に明るい楕円状の大きな領域．左右にほぼ対称．カメラ系の異方性（光学系の周辺減光 + ISP LSC 補正残差）に支配される典型パターン | 全体が中間色（実機色域内）でグラデーション．CoV=0.0426 の穏やかな分布 |
| Step 8-1 (出発点，linear + mean 正規化) | ROI 下端のみ明るく，上端に向かって単調に減衰する **Y 軸単調勾配**．LED 配置の物理的事実（**下・左・右の 3 基板 U 字型配置で上対応の基板なし**）を素直に反映 | 下端は白く完全飽和，上端は黒く振り切れ．**実機色域に収まらない急峻な勾配**．CoV=0.1826 |
| Step 8-3 (OETF 適用後，sRGB) | 数値指標は半減（CoV 0.183 → 0.089）したが，**輝度マップの形は出発点と区別がつかない**．OETF はピクセル値の単調変換で**相対順序を変えない**ため形は構造的に不変 | Step 8-1 と全く同じ形．CoV だけが半減（OETF の非線形圧縮で分布が縮む）が，飽和パターンは継続 |
| Step 8-7 (発光面 size 1.5×1.5，linear + mean 正規化) | 絶対値スケールは 2.83× 上昇したが，**形は出発点と同じ Y 軸単調勾配**．形状指標がほぼ不変だったことと整合 | Step 8-1 と区別不能の形．mean 正規化で表示スケールが完全に揃う |
| Step 8-9 (LED 位置を Fusion STL から正確化，linear + mean 正規化) | LED 位置を「3+ギャップ+3」の実機配置に直したが，**形は依然として Y 軸単調勾配**．数値指標 CoV/勾配/C/P も 1% 以内の微変化 | Step 8-1 と区別不能の形．LED 位置の数 mm 誤差は多重反射で平滑化される |
| Step 8-10 (LED 配光を spot emitter で表現，cutoff=90/beam=30) | 数値指標は悪化（CoV +4%, 勾配 +15%, C/P +5%）が，**目視で下端の明るい領域が中央寄りに集中**．**X 方向の対称性が部分的に改善**．Y 方向の偏りは不変 | 他の 4 シミュは下端が X 全幅で明るいが，spot は下中央のみが集中して明るい．左右端はやや暗く，**実機の中央ピーク楕円の X 方向成分に部分的に符号一致** |
| Step 8-11 (データシート従順版，cos^1.2 相当 spot + R=0.89) | spot 集中度を上げる (FWHM 112°) + 反射率を 0.89 に．Step 8-10 と 8-9 の中間の数値．**形は依然 Y 軸単調勾配**で 8-10 の X 方向効果は cos^1.2 と反射率上昇が打ち消し合いやや緩和 | Step 8-10 と類似の形だが集中度がわずかに緩和．**データシート従順度を上げても形は変わらない**ことを確定 |

## 学び (Findings)

### 1. 数値の縮小 ≠ 形の改善

Step 8-3 OETF は「指標数値の符号化ドメイン不一致」を解消したのみで，**シミュの形は実機の形に近づいていない**．OETF は単調変換であり，ピクセル間の相対順序を保つため形は不変．

### 2. これまでの全改善ステップは「形を変えない変更」だった

| Step | 種別 | 形への影響 |
| --- | --- | --- |
| 8-1 spp 校正 | MC ノイズ低減（線形平均化） | 形不変 |
| 8-2 反射率スイープ | 線形ゲイン + 一様な多重反射スケール | 形ほぼ不変 |
| 8-3 OETF 順方向適用 | 単調変換（非線形だが順序保存） | 形不変 |
| 8-4 max_depth 検証 | 多重反射の打ち切り位置（一様寄与） | 形ほぼ不変 |
| 8-5 3D 可視化改善 | 表示側の変更（物理計算には不介入） | 形不変 |
| 8-6 LED 物性確定 | 線形ゲイン（radiance 値の校正） | 形不変 |
| 8-7 発光面サイズ検証 | 局所幾何との縮退（絶対値変化）+ 点光源近似 | 形不変 |
| 8-8 linear mean 正規化 | 表示用の線形ゲイン（指標は不変） | 形不変 |
| 8-9 LED 位置の Fusion STL 反映 | LED 数 mm 移動，多重反射で平滑化 | 形不変 |
| 8-10 LED 配光を spot emitter | LED 中央集中型配光で X 方向の対称性に変化 | **X 方向の対称性が部分改善**（Y 方向は不変） |
| 8-11 データシート従順版 (cos^1.2 spot + R=0.89) | spot 集中度上昇 + 反射率上昇の打ち消し合い | 形は不変（8-10 と類似），数値指標は 8-10 と 8-9 の中間 |

8-10 / 8-11 で **「形を変える可能性のある変更」は LED 指向性 (spot config) のみ** であり，これは数値指標を悪化させたが目視で X 方向の対称性向上を確認．Step 8-11 でデータシート従順度を上げても形は構造的に変わらない．依然として **Y 方向の中央ピーク**は LSC モデル化が必要．

### 3. 実機の形 = シミュの形 + 動径補正

実機の輝度マップ形状（中央付近にピークを持つ楕円状）は，

```text
実機の形 = シミュの Y 軸勾配（LED 配置由来） + カメラ系の動径補正（LSC 残差）
```

として説明可能．シミュ側にこの **動径補正** を加えない限り，形を実機に合わせることはできない．

### 4. 「形」と「分布の広がり」は別次元の差

mean 揃え + 共有 colorbar 表示により判明したこと: シミュ vs 実機は **形（ピーク位置・対称性）が違う** だけでなく **分布の広がり（CoV）も違う**（実機 0.0426 vs シミュ 0.18+ 系で約 4.3×）．LSC モデル化はこの両方を同時に縮める可能性があるが，どちらが先に解消するかは実装してみないと分からない．

### 5. 光線追跡の方向（path / ptracer）は形を変えない（Mitsuba 上で実証）

[Step 8-12](TEST_01_キャリブレーション検証履歴.md#step-8-12-helmholtz-相反原理の-mitsuba-上での実証検証) で perspective sensor + scalar_rgb + spp=4096 で path と ptracer を直接比較．**bot/top 比が path 2.035 vs ptracer 2.006 で誤差 1.4% で一致** ＝ **Helmholtz 相反原理が Mitsuba 上でも「形について」実証された**．

絶対値は Mitsuba 実装の正規化差で 1.99× 違うが，形（空間パターン）は同じ．これにより**「光線追跡の方向を変えれば形が変わるかも」という直感が物理的にも実装的にも成立しないこと**が確定し，**LSC モデル化が唯一の道**であることが強化された．

## LSC モデル化の意義 (再認識) (Significance of LSC Modeling)

[TEST_01 Step 8-N 候補（LSC 順方向モデル）](TEST_01_キャリブレーション検証履歴.md#step-8-n-候補-lsc-順方向モデル未着手) は，単に「指標残差 1.6〜1.9× を縮める」だけでなく，**「シミュの空間勾配パターンに動径補正を重ね，実機の中央ピーク形状を作る」根本的な構造的改善** である．

LSC は ROI 中心からの距離に依存する動径ゲインで，

- 周辺を持ち上げる（実機 ISP の補正と同じ符号）
- ROI 中央を相対的に明るく見せる
- シミュの Y 軸勾配と合成すると「中央寄りピーク」の形が現れる

→ **以後の改善判断はこの 2 軸（数値 + 形）で行う**．数値残差だけ追っていると「形は変わっていない」改善で満足してしまう恐れがある．

## 再現コマンド (Reproduction)

```powershell
uv run python scripts/build_luminance_evolution_panel.py
```

出力先: `docs/06_TEST/figures/luminance_map_evolution.png`（`.gitignore` 対象．再生成可能）

### スクリプトの処理フロー

1. 各データソース（実機 PNG / シミュ `luminance.npy`）から **生輝度配列** を読み込み
2. 実機: Rec.709 luma 変換 → ROI 抽出（`configs/eval_real.yaml` の roi 設定）
3. シミュ: 2D luminance.npy をそのまま ROI 抽出（`configs/eval_baseline.yaml` の roi 設定）
4. Step 8-3 のみ OETF + 露出アンカーを順方向適用，他は **mean 揃え正規化** ([Step 8-8 `apply_mean_anchor`](TEST_01_キャリブレーション検証履歴.md#step-8-8-linear-評価モードへの-mean-揃え正規化導入)) で mean=146.7146 に統一
5. **共有 colorbar の値域は実機 ROI の 5〜95 パーセンタイル** で固定し，全画像を `hot` cmap + 同一 vmin/vmax で描画

### 新規 Step を追加する場合

`scripts/build_luminance_evolution_panel.py` の `PANELS` リストに 1 エントリ追加するだけで自動でパネルに並ぶ:

```python
PANELS = [
    # 既存エントリ ...
    {
        "loader": _load_sim_linear,                    # or _load_sim_oetf / _load_real
        "args": (ROOT / "output" / "<new_step_dir>" / "luminance.npy",),
        "title": "Step 8-N: <description>",
        "subtitle": "<scene/eval setting>",
    },
]
```

追加後はパネルを再生成し，本ドキュメントの「観察された事実」表に 1 行追加する．

## 参照 (References)

- [TEST_01_キャリブレーション検証履歴](TEST_01_キャリブレーション検証履歴.md): イテレーションの時系列詳細
- [TEST_02_シミュレーション実行記録](TEST_02_シミュレーション実行記録.md): output/ 各サブディレクトリの索引
- [SPEC_04_評価仕様](../04_SPEC/SPEC_04_評価仕様.md): 輝度マップ生成（`figures/luminance_map.png`）の規約
- [SPEC_03_基準設計の物理構成](../04_SPEC/SPEC_03_基準設計の物理構成.md): LED 配置（Y 軸偏り）の根拠
- 生成スクリプト: `scripts/build_luminance_evolution_panel.py`
- 生成画像: `docs/06_TEST/figures/luminance_map_evolution.png`（`.gitignore` 対象）