diff --git a/docs/05_TECH/README.md b/docs/05_TECH/README.md new file mode 100644 index 0000000..ac94c3a --- /dev/null +++ b/docs/05_TECH/README.md @@ -0,0 +1,86 @@ +# 05_TECH — エンジニア向けの技術設計 (Technical Design Docs) + +このディレクトリには **エンジニア向けの技術設計ドキュメント** が集まっている．3 種類のドキュメントが混在するので，**最初にこの README で位置付けを確認**するのが効率的． + +## 種類分類 + +| アイコン | 種類 | 性質 | 読み方 | +| --- | --- | --- | --- | +| 🟢 | **現状方針（結論集約）** | 永続的，変更時のみ更新 | **「今どうなっているか」を知りたい人はここから** | +| 🔵 | **議論の経緯（過程記録）** | 履歴的，原則更新しない | **「なぜそうなったか」を辿るためのドキュメント** | + +## 🟢 まず読むべき — 現状方針（3 ファイル） + +SmTIAS-LightSim プロジェクトの **現状の設計判断・取り扱い方針** をここに集約している．「今どうなっているか」を理解したい場合はこの 3 つから読む． + +| 順序 | ファイル | 内容 | +| --- | --- | --- | +| 1 | [TECH_07_LSC取り扱い方針.md](TECH_07_LSC取り扱い方針.md) | 3 プロジェクト (MiniTias / MiniTiasEval / SmTIAS-LightSim) での LSC 役割分担．シミュ側で LSC を扱わない物理的根拠．却下した代替案 3 つの理由 | +| 2 | [TECH_08_実機変更とシミュ側対応.md](TECH_08_実機変更とシミュ側対応.md) | 実機側 8 項目変更に対するシミュ側 3 層 (シーン定義 / sm-render / sm-evaluate) の対応マッピング．タイプ I (本質構造同一) / タイプ II (許容している構造的差異) の分類 | +| 3 | [TECH_09_LEDデータシート調査結果.md](TECH_09_LEDデータシート調査結果.md) | OEM 元 HONGLITRONIC データシート発見と判明事項．配光は Lambertian と数値一致．Step 8-10/8-11 試行の事後評価．SPEC_03 訂正事項 | + +### 主な結論（読まずに済むサマリ） + +| 観点 | 結論 | +| --- | --- | +| LSC 補正 | 実機側 (MiniTiasEval) で順方向適用．**シミュ側は扱わない** (orthographic で構造的に等価) | +| ガンマ補正 | sm-evaluate で **OETF off** (実機 DNG が linear) | +| 絶対値スケール調整 | mean アンカー正規化で target_mean=207.82 に揃え | +| LED 配光モデル | **area light Lambertian (cos θ)** — データシート実測と数値一致 | +| 残差 2.63× の主因候補 | LSC / 配光由来ではなく，**物理モデル誤差 (反射率精度・幾何精度等)** に絞られる | + +## 🔵 議論の経緯 — プロジェクト間ハンドオフ往復 (6 ファイル) + +MiniTias 撮影アプリ + MiniTiasEval 解析ツールへの「要求 → 報告 → 回答 → 受領」のハンドオフ記録．**読まなくても現状方針 (TECH_07〜09) は理解できる**が，「なぜそういう判断になったか」を辿るときに参照する． + +### 経緯マップ + +```text +[MiniTias 撮影アプリへの要求と回答] + TECH_01 (要求書) ────→ MiniTias 実装 + │ ↓ + TECH_02 (引き継ぎ手順) TECH_03 (実装報告 + SHADING_MODE 相談) + │ + ↓ + TECH_04 (回答書 + SHADING_MODE 判断) + │ + ↓ + ★ 結論集約 → TECH_07 LSC 取り扱い方針 + +[MiniTiasEval DNG 対応への要求と受領] + TECH_05 (要求書) ────→ MiniTiasEval 実装 + │ + ↓ + TECH_06 (引き継ぎ受領記録) + │ + ↓ + ★ 関連結論 → TECH_07 LSC 取り扱い方針 + TECH_08 対応マッピング +``` + +### 各ファイルの役割 + +| ファイル | 役割 | +| --- | --- | +| [TECH_01_定量撮影モード要求仕様.md](TECH_01_定量撮影モード要求仕様.md) | SmTIAS-LightSim → MiniTias 撮影アプリ への要求書．Camera2 API 設定変更・DNG 化等 | +| [TECH_02_MiniTIAS引き継ぎ手順.md](TECH_02_MiniTIAS引き継ぎ手順.md) | TECH_01 を MiniTias 側 Claude セッションで作業着手する際の作業ガイド | +| [TECH_03_定量モード実装報告とSHADING_MODE相談.md](TECH_03_定量モード実装報告とSHADING_MODE相談.md) | MiniTias 側からの実装報告．SHADING_MODE の扱いを SmTIAS-LightSim 側に相談 | +| [TECH_04_MiniTIASへの回答.md](TECH_04_MiniTIASへの回答.md) | TECH_03 への回答．SHADING_MODE = HIGH_QUALITY 維持を判断．フェーズ A/B 分割方針 | +| [TECH_05_MiniTiasEvaluation_DNG対応要求仕様.md](TECH_05_MiniTiasEvaluation_DNG対応要求仕様.md) | SmTIAS-LightSim → MiniTiasEval 解析ツール への要求書．`apply_lsc_*` 関連は訂正済 | +| [TECH_06_MiniTias-Evaluation引き継ぎ受領.md](TECH_06_MiniTias-Evaluation引き継ぎ受領.md) | MiniTiasEval 側からの実装受領記録．重要な設計判断 (LSC は順方向適用) を集約 | + +## 関連ディレクトリ + +| ディレクトリ | 役割 | +| --- | --- | +| [04_SPEC/](../04_SPEC/) | ユーザー視点の仕様書．特に `SPEC_03 基準設計の物理構成` は TECH_09 で訂正対象になっている | +| [06_TEST/](../06_TEST/) | 試行履歴・実行記録．特に [TEST_01 キャリブレーション検証履歴](../06_TEST/TEST_01_キャリブレーション検証履歴.md) は Step 8 系の主軸記録 | + +## 新規ドキュメント追加のガイド + +新しい TECH ドキュメントを追加するときは： + +1. **どのカテゴリか判断**: 🟢 結論集約 / 🔵 過程記録 +2. **連番を継続**: TECH_10, TECH_11, ... +3. **本 README に追記**: 該当カテゴリのリストに 1 行追加 +4. **GUIDE_03 ファイル命名規則** に従う ([../01_GUIDE/GUIDE_03_ファイル命名規則.md](../01_GUIDE/GUIDE_03_ファイル命名規則.md)) diff --git a/docs/06_TEST/README.md b/docs/06_TEST/README.md new file mode 100644 index 0000000..d993e4f --- /dev/null +++ b/docs/06_TEST/README.md @@ -0,0 +1,67 @@ +# 06_TEST — テスト計画・品質保証 (Test & Quality Assurance Docs) + +このディレクトリには **試行・検証の履歴と記録** が集まっている．SmTIAS-LightSim のキャリブレーション作業を中心に，過去の試行を時系列・観点別に追跡する． + +## 種類分類 + +| アイコン | 種類 | 性質 | 読み方 | +| --- | --- | --- | --- | +| 🟡 | **キャリブ作業の中核（更新中）** | 永続的，新規 Step ごとに追記 | **「過去の試行と現状」を辿る主軸** | +| 🔵 | **クローズ済みの試行履歴** | 履歴的，原則更新しない | 「中断・完了した別軸の試行」を参照する | +| 📋 | **外部スナップショット** | 取り込み済み，更新は元側で | 元プロジェクト ([MiniTias-Evaluation](https://github.com/rintoHasegawa/MiniTias-Evaluation)) を参照 | + +## 🟡 キャリブ作業の中核 — 3 ファイル + +SmTIAS-LightSim のシミュ vs 実機キャリブレーションの **主軸記録**．Step 8 系の試行を時系列・観点別に追跡する． + +| 順序 | ファイル | 内容 | +| --- | --- | --- | +| 1 | [TEST_01_キャリブレーション検証履歴.md](TEST_01_キャリブレーション検証履歴.md) | Step 8-1〜8-13 + Step 8-N 候補の **時系列フル記録**．各イテレーションの仮説／変更／結果／解釈／学び．新規 Step 追加時はここに追記 | +| 2 | [TEST_02_シミュレーション実行記録.md](TEST_02_シミュレーション実行記録.md) | `output/` 配下に蓄積された **実行結果ディレクトリの索引**．「何の試行か・どう再現するか」を辿れる．`output/` は gitignore 対象なので手元になくてもこのドキュメントで網羅 | +| 3 | [TEST_03_輝度マップ形状追跡.md](TEST_03_輝度マップ形状追跡.md) | 数値指標 (CoV / 勾配等) では捉えられない **「形そのもの」を画像比較**．`figures/luminance_map_evolution.png` の比較パネルとセット．`scripts/build_luminance_evolution_panel.py` で生成 | + +### 3 ファイルの使い分け + +| 知りたいこと | 読むべきファイル | +| --- | --- | +| 「過去どんな Step を試したか，何が判明したか」 | **TEST_01** | +| 「`output/baseline_spot/` って何のレンダ結果？」 | **TEST_02** | +| 「シミュは形が実機と全然違うのか？」 | **TEST_03**（画像で一目） | + +## 🔵 クローズ済みの試行履歴 — 1 ファイル + +| ファイル | 状態 | 内容 | +| --- | --- | --- | +| [TEST_04_シミュレーション速度最適化履歴.md](TEST_04_シミュレーション速度最適化履歴.md) | **中断** | Speed-0 ベースライン計測・Speed-1 LLVM JIT 自動検出を完了．Speed-2 path bake wavefront 化はテンプレ保持．再開条件 4 項目を明記 | + +→ 再開条件 (path bake samples を増やすユースケース発生 / NVIDIA GPU 利用可 / クラウド計算活用 / 反復回数増加) に該当した時のみ参照． + +## 📋 外部スナップショット — 2 ファイル + +[MiniTias-Evaluation](https://github.com/rintoHasegawa/MiniTias-Evaluation) で作成された報告書を SmTIAS-LightSim 側にも取り込んだもの．**原本は MiniTias-Evaluation 側**にあり，バグ修正・追記は元側で行う．本リポジトリは「スナップショット」として保持． + +| ファイル | 元側 | 内容 | +| --- | --- | --- | +| [TEST_05_PNG_DNG評価比較.md](TEST_05_PNG_DNG評価比較.md) | REPORT_02 | PNG sRGB 経路と DNG linear+LSC 経路の数値比較．**ガンマ圧縮で CoV が約 2 倍縮まる**ことを実証．真の linear 比較への移行根拠 | +| [TEST_06_外乱光影響評価.md](TEST_06_外乱光影響評価.md) | REPORT_03 | 室内灯 ON/OFF で照明均一性指標がほぼ変わらない（差 1% 未満）ことを実証．SmTIAS の自前照明が支配的 | + +### 取り込みの位置付け + +外部スナップショットの取り込み経緯は [TECH_06 MiniTias-Evaluation 引き継ぎ受領](../05_TECH/TECH_06_MiniTias-Evaluation引き継ぎ受領.md) に記載．原本リンクの一部は MiniTias-Evaluation リポジトリ起点で，SmTIAS-LightSim 側からは到達しない（リンク切れは許容と各ファイル冒頭に明記）． + +## 関連ディレクトリ + +| ディレクトリ | 役割 | +| --- | --- | +| [05_TECH/](../05_TECH/) | 結論集約 (TECH_07〜09) と過程記録 (TECH_01〜06)．キャリブ作業の **方針側** が集まる | +| [04_SPEC/](../04_SPEC/) | ユーザー視点の仕様書．特に [SPEC_04 評価仕様](../04_SPEC/SPEC_04_評価仕様.md) は TEST_01 と表裏 | +| `figures/` | TEST_03 等の比較パネル画像．`scripts/build_luminance_evolution_panel.py` で再生成可能 | + +## 新規ドキュメント追加のガイド + +新しい TEST ドキュメントを追加するときは： + +1. **どのカテゴリか判断**: 🟡 キャリブ中核 / 🔵 クローズ済み / 📋 外部スナップショット +2. **連番を継続**: TEST_07, TEST_08, ... +3. **本 README に追記**: 該当カテゴリのリストに 1 行追加 +4. 既存 TEST_01〜03 を **どう更新するか** も検討（特に新規 Step 追加時は TEST_01 が主軸）