# アーキテクチャ設計 (Architecture)

## 概要 (Overview)

SmTIAS-LightSim は次の 2 段階を独立した CLI として提供する．

1. **render**: シーン定義 YAML + STL メッシュを入力に，Mitsuba 3 で擬似撮影画像（PNG）と輝度マップを出力する．
2. **evaluate**: PNG または輝度マップ + ROI 設定を入力に，MiniTias-Evaluation 互換の均一性指標（CSV）と可視化（PNG）を出力する．

evaluate を独立させることで，**実測 PNG（MiniTIAS で撮影したもの）にも同じコマンドが使える**．シミュレーションと実測を同じ物差しで比較できる．

## 全体パイプライン (Pipeline)

```
                         [Fusion 360]
                              ↓ STL export
    ┌─────────────────────────────────────────────────────────────┐
    │  configs/                                                  │
    │   ├── scene_baseline.yaml   (光源・材料・センサ・評価面定義) │
    │   └── meshes/                                              │
    │       └── *.stl                                            │
    └─────────────────────────────────────────────────────────────┘
                              ↓
    ┌─────────────── render ──────────────┐
    │  scene/builder  →  Mitsuba scene    │
    │  render/runner  →  mi.render(...)   │
    │  render/output  →  PNG / luminance  │
    └──────────────────────────────────────┘
                              ↓
                  output/<scene-id>/
                    ├── render.png
                    └── luminance.npy
                              ↓
    ┌─────────────── evaluate ────────────┐
    │  evaluation/roi      →  ROI抽出     │
    │  uniformity.py       →  CoV / std    │
    │  evaluation/zones    →  3ゾーン      │
    │  evaluation/radial   →  放射プロファ  │
    │  evaluation/visualize → 可視化PNG    │
    └──────────────────────────────────────┘
                              ↓
                  output/<scene-id>/
                    ├── metrics.csv
                    └── figures/
                        ├── luminance_map.png
                        ├── histogram.png
                        ├── radial_profile.png
                        └── zone_map.png
```

## モジュール構成 (Modules)

```
src/sm_tias_lightsim/
├── __init__.py
├── geometry/
│   ├── loader.py        # trimesh で STL 読込・三角形配列取得
│   └── transforms.py    # 単位変換 (mm→m)・座標系変換
├── scene/
│   ├── schema.py        # YAML スキーマ定義・バリデーション
│   ├── builder.py       # YAML → Mitsuba scene dict 変換の本体
│   ├── lights.py        # LED 光源 (point / area / spot) のシーン要素生成
│   ├── materials.py     # BSDF（拡散・誘電体・薄膜散乱等）の生成
│   └── sensors.py       # カメラセンサ (perspective / orthographic) の生成
├── render/
│   ├── runner.py        # mi.set_variant + mi.render の実行
│   └── output.py        # HDR film → PNG / luminance.npy 出力
├── uniformity.py        # MiniTias-Evaluation からコピー（Rec.709, CoV, max/min）
├── evaluation/
│   ├── roi.py           # 画像 ROI 抽出（image_pixel / scene_face）
│   ├── zones.py         # 3 ゾーン分析（center / middle / periphery）
│   ├── radial.py        # 放射状プロファイル生成
│   └── visualize.py     # matplotlib による可視化 PNG 出力
├── visualize/
│   ├── baker.py         # 各 face 中心の直接照度ベイク（shadow ray + cosine + 距離減衰）
│   └── viewer.py        # PyVista による 3D インタラクティブビューア
└── cli/
    ├── render.py        # `sm-render` エントリポイント
    ├── evaluate.py      # `sm-evaluate` エントリポイント
    └── visualize.py     # `sm-visualize` エントリポイント
```

## 各層の責務 (Module Responsibilities)

| 層 | 責務 | 主要な型・出入力 |
| --- | --- | --- |
| `geometry` | STL を読み，Mitsuba が扱える単位・座標系に揃える．メッシュの妥当性チェック | 入力: STL ファイルパス．出力: 頂点・面配列 + 単位情報 |
| `scene/builder` | YAML 設定全体を Mitsuba scene dict に変換するエントリ．他のサブ層を呼ぶ | 入力: YAML dict．出力: Mitsuba scene |
| `scene/lights` | YAML 光源定義 → Mitsuba の `point` / `area` / etc. emitter | 1 LED 定義 → 1 emitter |
| `scene/materials` | YAML 材料定義 → Mitsuba BSDF（`diffuse` / `dielectric` / `thindielectric`） | 1 材料定義 → 1 BSDF |
| `scene/sensors` | YAML センサ定義 → Mitsuba `perspective` センサ | 1 センサ定義 → 1 sensor |
| `render/runner` | Mitsuba scene + パラメータ → 輝度配列 | spp / max_depth / variant 切替 |
| `render/output` | 輝度配列 → PNG / luminance.npy ファイル | tone mapping 等の選択肢を持つ |
| `evaluation/roi` | 画像 + ROI 定義 → ROI 内の輝度配列 | image_pixel / scene_face 両対応 |
| `uniformity` | 輝度配列 → 均一性指標 dict | MiniTias-Evaluation 仕様準拠 |
| `evaluation/zones` | 輝度配列 → 中心 / 中間 / 周辺の各統計 | 距離正規化を内部で行う |
| `evaluation/radial` | 輝度配列 → 中心からの距離 vs 平均輝度 | プロット用データ |
| `evaluation/visualize` | 各種統計 → matplotlib 図 PNG | 可視化のみ．データ加工はしない |
| `visualize/baker` | シーン + 光源 → 各 mesh face 中心の直接照度（W/m²） | Phase A は直接光のみ（shadow ray + cosine + 距離減衰）．Phase B で多重反射対応予定 |
| `visualize/viewer` | シーン + 照度 → PyVista インタラクティブ 3D ウィンドウ | メッシュ着色（viridis）/ 光源マーカー / センサ視線 / 座標軸 |
| `cli/render`, `cli/evaluate`, `cli/visualize` | 各ステップの CLI ラッパー | 引数パース・ファイル I/O |

## エントリポイント (CLI Entry Points)

`pyproject.toml` の `[project.scripts]` に登録する：

```toml
[project.scripts]
sm-render = "sm_tias_lightsim.cli.render:main"
sm-evaluate = "sm_tias_lightsim.cli.evaluate:main"
sm-visualize = "sm_tias_lightsim.cli.visualize:main"
```

使い方：

```powershell
# シミュ実行
uv run sm-render --scene configs/scene_baseline.yaml --output output/baseline/

# 評価（シミュ画像）
uv run sm-evaluate --image output/baseline/render.png --config configs/eval_default.yaml --output output/baseline/

# 評価（実測画像）
uv run sm-evaluate --image data/whiteboard_real.png --config configs/eval_default.yaml --output output/real/

# 3D 照度ビューア（キャリブレーション中の調査ツール）
uv run sm-visualize --scene configs/scene_baseline.yaml                       # インタラクティブウィンドウを開く
uv run sm-visualize --scene configs/scene_baseline.yaml --screenshot vis.png  # PNG 保存のみ
```

## ディレクトリ構成（プロジェクトルート）

```
SmTIAS-LightSim/
├── src/sm_tias_lightsim/   # 上述
├── configs/
│   ├── scene_baseline.yaml
│   ├── eval_default.yaml
│   └── meshes/             # STL ファイル群
├── output/                 # シミュ・評価結果（.gitignore 対象）
├── tests/
│   ├── test_geometry.py
│   ├── test_scene_builder.py
│   ├── test_uniformity.py
│   └── fixtures/
└── docs/
```

## キャリブレーション戦略 (Calibration)

実測値（CoV ≈ 0.0426，勾配 ≈ 6%）との一致を確認するための運用：

1. 現行 MiniTIAS の構成を `scene_baseline.yaml` に再現
2. `sm-render → sm-evaluate` で指標を算出
3. 実測値と比較し，差分が大きい場合は次の順で疑う：
   - ① 光源の配光（Lambertian / cosine 分布の前提が妥当か）
   - ② 材料パラメータ（拡散反射率・透過散乱）
   - ③ ジオメトリの単位・座標
   - ④ サンプル数（spp）が不足していないか
4. 一致した時点でキャリブレーション完了．以降の改良案はこのベースラインからの相対比較で評価

許容範囲の数値は基準設計のレンダリング結果を見て確定する（`PLAN_02_開発ステップ.md` 内で定義）．

## 既知の前提 (Assumptions)

- 入力 STL は閉じたメッシュ（モンテカルロ光線が漏れない）であること
- 単位は YAML 側で明示する（`unit: mm`）．Fusion 360 の既定 mm 出力を想定
- LED の配光は当初 Lambertian で仮置きし，必要に応じて IES データに置換可能な構造にしておく
- 色再現性は将来課題（要件定義書のスコープ外）