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

概要 (Overview)

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

render: シーン定義 YAML + STL メッシュを入力に，Mitsuba 3 で擬似撮影画像（PNG）と輝度マップを出力する．
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] に登録する：

[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"

使い方：

# シミュ実行
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%）との一致を確認するための運用：

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

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

既知の前提 (Assumptions)

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