diff --git a/CLAUDE.md b/CLAUDE.md index cc62b05..c3bd1f7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -103,3 +103,4 @@ - キャリブレーション検証履歴: docs/06_TEST/TEST_01_キャリブレーション検証履歴.md（Step 8 イテレーション 8-1〜8-7 のフル記録．仮説／変更／数値／解釈／学びを時系列で） - シミュレーション実行記録: docs/06_TEST/TEST_02_シミュレーション実行記録.md（output/ 各サブディレクトリの索引．Step との対応・シーン/評価 config・主要指標・再現コマンド・削除推奨） +- 輝度マップ形状追跡: docs/06_TEST/TEST_03_輝度マップ形状追跡.md（数値とは独立に「形」を実機に近づける観点．比較パネル画像と LSC モデル化の構造的意義） diff --git "a/docs/04_SPEC/SPEC_04_\350\251\225\344\276\241\344\273\225\346\247\230.md" "b/docs/04_SPEC/SPEC_04_\350\251\225\344\276\241\344\273\225\346\247\230.md" index 0f1306e..a6e4c87 100644 --- "a/docs/04_SPEC/SPEC_04_\350\251\225\344\276\241\344\273\225\346\247\230.md" +++ "b/docs/04_SPEC/SPEC_04_\350\251\225\344\276\241\344\273\225\346\247\230.md" @@ -270,6 +270,7 @@ - [SPEC_03_基準設計の物理構成](SPEC_03_基準設計の物理構成.md): シーン物理仕様 - [TEST_01_キャリブレーション検証履歴](../06_TEST/TEST_01_キャリブレーション検証履歴.md): 評価値の歴史と検証経緯 - [TEST_02_シミュレーション実行記録](../06_TEST/TEST_02_シミュレーション実行記録.md): output/ 索引 +- [TEST_03_輝度マップ形状追跡](../06_TEST/TEST_03_輝度マップ形状追跡.md): 形を実機に近づける観点 - [PLAN_02_開発ステップ](../03_PLAN/PLAN_02_開発ステップ.md): 実測ターゲット出典 - 実装エントリ: - `src/sm_tias_lightsim/cli/evaluate.py`: CLI diff --git "a/docs/06_TEST/TEST_01_\343\202\255\343\203\243\343\203\252\343\203\226\343\203\254\343\203\274\343\202\267\343\203\247\343\203\263\346\244\234\350\250\274\345\261\245\346\255\264.md" "b/docs/06_TEST/TEST_01_\343\202\255\343\203\243\343\203\252\343\203\226\343\203\254\343\203\274\343\202\267\343\203\247\343\203\263\346\244\234\350\250\274\345\261\245\346\255\264.md" index 92ce370..b82eb75 100644 --- "a/docs/06_TEST/TEST_01_\343\202\255\343\203\243\343\203\252\343\203\226\343\203\254\343\203\274\343\202\267\343\203\247\343\203\263\346\244\234\350\250\274\345\261\245\346\255\264.md" +++ "b/docs/06_TEST/TEST_01_\343\202\255\343\203\243\343\203\252\343\203\226\343\203\254\343\203\274\343\202\267\343\203\247\343\203\263\346\244\234\350\250\274\345\261\245\346\255\264.md" @@ -287,42 +287,15 @@ - **形状指標と絶対値は別物**として扱う．多くのレバーは形状指標には不変（線形ゲイン）だが，絶対値は局所幾何との縮退で動きうる． - **失敗・予想外の記録は学びの宝庫**．方向性ドリフトを防ぐ核は「失敗を消さずに残す」こと． -## 輝度マップ形状の追跡 (Luminance Map Shape Tracking) +## 輝度マップ形状の追跡 (→ TEST_03) -数値指標 (CoV / 勾配 / C/P) は分布のばらつきを集約する量であり，**「形そのもの」は捕えない**．シミュレーションの「形」を実機に近づける観点は，指標残差の縮小とは別軸で追跡する必要がある． +数値指標と独立に **輝度マップの「形」** を実機に近づける観点は [TEST_03_輝度マップ形状追跡](TEST_03_輝度マップ形状追跡.md) に独立化した．要点のみ: -### 比較パネル +- これまで実施した 7 つの改善ステップ (8-1〜8-7) は **すべて「形を変えない変更」** だった（線形ゲイン・単調変換・局所幾何依存のいずれか）．シミュは初期から **Y 軸単調勾配**のままで，実機の **中央付近ピーク**には近づいていない． +- 実機の形 = シミュの Y 軸勾配 + カメラ系の動径補正．**LSC モデル化（[Step 8-N 候補](#step-8-n-候補-lsc-順方向モデル未着手)）は数値残差縮小だけでなく形の構造的改善を担う**． +- 以後の改善判断は **「数値 + 形」の 2 軸** で行う． -![輝度マップ形状の追跡: 実機 (TARGET) と Step 8-1 / 8-3 / 8-7 の比較](figures/luminance_map_evolution.png) - -### 観察された事実 - -実機 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 軸単調勾配**．形状指標がほぼ不変だったことと整合． - -### 学び (新規) - -- **数値の縮小 ≠ 形の改善**．Step 8-3 OETF は「指標数値の符号化ドメイン不一致」を解消したのみで，**シミュの形は実機の形に近づいていない**． -- これまで実施した 7 つの改善ステップ (8-1〜8-7) は **すべて「形を変えない変更」**だった: spp，反射率，OETF，max_depth，可視化，LED 物性，発光面サイズ．これらは線形ゲイン・単調変換・局所幾何依存のいずれかであり，**「ピクセル間の空間構造」を変える物理を含まない**． -- 実機の形 (中央付近にピークを持つ楕円状) ＝ **シミュの Y 軸勾配** + **カメラ系の動径補正パターン** の合成として説明可能．シミュ側にこの「動径補正」を加えない限り，形を実機に合わせることはできない． - -### LSC モデル化の意義 (再認識) - -[Step 8-N 候補 (LSC 順方向モデル)](#step-8-n-候補-lsc-順方向モデル未着手) は，単に「指標残差 1.6〜1.9× を縮める」だけでなく，**「シミュの空間勾配パターンに動径補正を重ね，実機の中央ピーク形状を作る」根本的な構造的改善**である．これは数値指標の改善より重要な観点で，**以後の改善判断はこの 2 軸 (数値 + 形) で行う**． - -### 再現コマンド - -新規 Step 完了後はこの比較パネルを再生成して形の変化を追跡する: - -```powershell -uv run python scripts/build_luminance_evolution_panel.py -``` - -新規 Step を追加するには `scripts/build_luminance_evolution_panel.py` の `PANELS` リストに 1 エントリ追加するだけで自動で並ぶ． +比較パネル・観察事実・物理的解釈の詳細は TEST_03 参照． ## 参照 (References) @@ -331,6 +304,7 @@ - [SPEC_02_シーン定義仕様](../04_SPEC/SPEC_02_シーン定義仕様.md) - [PLAN_02_開発ステップ](../03_PLAN/PLAN_02_開発ステップ.md) - [TEST_02_シミュレーション実行記録](TEST_02_シミュレーション実行記録.md)（各 Step に対応する `output/` ディレクトリの索引） +- [TEST_03_輝度マップ形状追跡](TEST_03_輝度マップ形状追跡.md)（数値と独立に「形」を実機に近づける観点） - 実装エントリ: - `src/sm_tias_lightsim/evaluation/oetf.py`（Step 8-3） - `src/sm_tias_lightsim/visualize/baker.py`（Step 8-5） @@ -340,7 +314,5 @@ - `configs/eval_baseline_linear.yaml`（Step 8-7） - `output/emitter_real/`（Step 8-7 検証レンダ） - `output/baseline_linear_npy/`（Step 8-7 比較基準） -- 輝度マップ形状の追跡: - - `scripts/build_luminance_evolution_panel.py`（比較パネル生成スクリプト） - - `docs/06_TEST/figures/luminance_map_evolution.png`（生成された比較パネル画像） +- 輝度マップ形状の追跡関連は [TEST_03_輝度マップ形状追跡](TEST_03_輝度マップ形状追跡.md) に集約 - 関連コミット: `26904da`（OETF 正規実装），`7181efa` / `c32ccd6` / `a0fe07d`（3D ビュー改善），`f5048a4`（LED 物性反映） diff --git "a/docs/06_TEST/TEST_02_\343\202\267\343\203\237\343\203\245\343\203\254\343\203\274\343\202\267\343\203\247\343\203\263\345\256\237\350\241\214\350\250\230\351\214\262.md" "b/docs/06_TEST/TEST_02_\343\202\267\343\203\237\343\203\245\343\203\254\343\203\274\343\202\267\343\203\247\343\203\263\345\256\237\350\241\214\350\250\230\351\214\262.md" index 54b130f..6b9a47e 100644 --- "a/docs/06_TEST/TEST_02_\343\202\267\343\203\237\343\203\245\343\203\254\343\203\274\343\202\267\343\203\247\343\203\263\345\256\237\350\241\214\350\250\230\351\214\262.md" +++ "b/docs/06_TEST/TEST_02_\343\202\267\343\203\237\343\203\245\343\203\254\343\203\274\343\202\267\343\203\247\343\203\263\345\256\237\350\241\214\350\250\230\351\214\262.md" @@ -114,4 +114,5 @@ - [SPEC_03_基準設計の物理構成](../04_SPEC/SPEC_03_基準設計の物理構成.md): 確定基準の物理仕様 - [SPEC_04_評価仕様](../04_SPEC/SPEC_04_評価仕様.md): 評価方法論（ROI / OETF / メトリクス / 可視化） - [SPEC_02_シーン定義仕様](../04_SPEC/SPEC_02_シーン定義仕様.md): シーン YAML と評価 YAML のスキーマ +- [TEST_03_輝度マップ形状追跡](TEST_03_輝度マップ形状追跡.md): 形を実機に近づける観点 - 生成スクリプト: `scripts/build_luminance_evolution_panel.py`（輝度マップ追跡用） diff --git "a/docs/06_TEST/TEST_03_\350\274\235\345\272\246\343\203\236\343\203\203\343\203\227\345\275\242\347\212\266\350\277\275\350\267\241.md" "b/docs/06_TEST/TEST_03_\350\274\235\345\272\246\343\203\236\343\203\203\343\203\227\345\275\242\347\212\266\350\277\275\350\267\241.md" new file mode 100644 index 0000000..8bfb759 --- /dev/null +++ "b/docs/06_TEST/TEST_03_\350\274\235\345\272\246\343\203\236\343\203\203\343\203\227\345\275\242\347\212\266\350\277\275\350\267\241.md" @@ -0,0 +1,112 @@ +# 輝度マップ形状追跡 (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" / "" / "figures" / "luminance_map.png", + "title": "Step 8-N: ", + "subtitle": "", + "metrics_csv": ROOT / "output" / "" / "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` 対象） diff --git a/scripts/build_luminance_evolution_panel.py b/scripts/build_luminance_evolution_panel.py index bf21c4b..dda3046 100644 --- a/scripts/build_luminance_evolution_panel.py +++ b/scripts/build_luminance_evolution_panel.py @@ -1,4 +1,4 @@ -"""TEST_01 用「輝度マップ形状の追跡」比較パネルを生成する. +"""TEST_03 用「輝度マップ形状追跡」比較パネルを生成する. 各改善 Step での輝度マップの「形」を 2×2 グリッドで並べ， タイトルに主要指標 (mean / CoV / 勾配 % / C/P) を併記する. @@ -12,6 +12,10 @@ 出力: docs/06_TEST/figures/luminance_map_evolution.png +ドキュメント: + docs/06_TEST/TEST_03_輝度マップ形状追跡.md（観察・解釈・LSC モデル化の意義） + docs/06_TEST/TEST_01_キャリブレーション検証履歴.md（Step 毎の改善履歴） + 新しい改善 Step を追加する場合は PANELS リストに 1 エントリ追加するだけ. """