# 輝度マップ形状追跡 (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 の比較](figures/luminance_map_evolution.png)

生成スクリプト: [`scripts/build_luminance_evolution_panel.py`](../../scripts/build_luminance_evolution_panel.py)．**各画像は個別正規化**（min-max を独立に取る）で並べているため，色スケールは画像ごとに異なる．これは「形の異同」を強調するためであり，**絶対値の比較は metrics.csv で行う**こと．

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

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

| パネル | 形の特徴 |
| --- | --- |
| 実機 (TARGET) | ROI 中央〜下に明るい楕円状の大きな領域．左右にほぼ対称．カメラ系の異方性（光学系の周辺減光 + ISP LSC 補正残差）に支配される典型パターン |
| Step 8-1 (出発点，linear) | ROI 下端のみ明るく，上端に向かって単調に減衰する **Y 軸単調勾配**．LED 配置の物理的事実（下基板が Y=-70.2 のみで上対応の基板なし）を素直に反映 |
| Step 8-3 (OETF 適用後，sRGB) | 数値指標は半減（CoV 0.183 → 0.091）したが，**輝度マップの形は出発点と区別がつかない**．OETF はピクセル値の単調変換で**相対順序を変えない**ため形は構造的に不変 |
| Step 8-7 (発光面 size 1.5×1.5，linear) | 絶対値スケールは 2.83× 上昇したが，**形は出発点と同じ Y 軸単調勾配**．形状指標がほぼ不変だったことと整合 |

## 学び (Findings)

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

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

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

| Step | 種別 | 形への影響 |
| --- | --- | --- |
| 8-1 spp 校正 | MC ノイズ低減（線形平均化） | 形不変 |
| 8-2 反射率スイープ | 線形ゲイン + 一様な多重反射スケール | 形ほぼ不変 |
| 8-3 OETF 順方向適用 | 単調変換（非線形だが順序保存） | 形不変 |
| 8-4 max_depth 検証 | 多重反射の打ち切り位置（一様寄与） | 形ほぼ不変 |
| 8-5 3D 可視化改善 | 表示側の変更（物理計算には不介入） | 形不変 |
| 8-6 LED 物性確定 | 線形ゲイン（radiance 値の校正） | 形不変 |
| 8-7 発光面サイズ検証 | 局所幾何との縮退（絶対値変化）+ 点光源近似 | 形不変 |

これらはすべて **線形ゲイン・単調変換・局所幾何依存のいずれか** であり，**「ピクセル間の空間構造」を変える物理を含まない**．

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

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

```text
実機の形 = シミュの Y 軸勾配（LED 配置由来） + カメラ系の動径補正（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` 対象．再生成可能）

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

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

```python
PANELS = [
    # 既存エントリ ...
    {
        "image": ROOT / "output" / "<new_step_dir>" / "figures" / "luminance_map.png",
        "title": "Step 8-N: <description>",
        "subtitle": "<scene/eval setting>",
        "metrics_csv": ROOT / "output" / "<new_step_dir>" / "metrics.csv",
    },
]
```

追加後はパネルを再生成し，本ドキュメントの「観察された事実」表に 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` 対象）