# 技術スタック (Tech Stack)

## 概要 (Overview)

Fusion 360 で設計中の MiniTIAS 筐体を CPU 上で光学シミュレーションし，
MiniTias-Evaluation と互換の指標で照明均一性を評価できるようにする．

## 言語・実行環境 (Language & Runtime)

| 項目 | 採用 | 備考 |
| --- | --- | --- |
| 言語 | Python | MiniTias-Evaluation と揃え，評価コード（`uniformity.py`）を共有しやすくするため |
| Python バージョン | 3.12（`.python-version` で固定） | Mitsuba 3 の Windows wheel が安定して配布されている範囲 |
| OS | Windows 10 / 11（主） | macOS / Linux でも理論上動作するが優先サポートしない |
| ハードウェア | CPU のみ（当面） | 将来 GPU（CUDA）への移行はオプションとして残す（後述） |

## シミュレーションコア (Simulation Core)

| 項目 | 採用 | 備考 |
| --- | --- | --- |
| シミュレータ | **Mitsuba 3**（3.8.x） | 物理ベース・モンテカルロレンダラ．Python API あり |
| バリアント (variant) | `llvm_ad_rgb` をメインで使用 | Dr.Jit + LLVM JIT による CPU 並列化．scalar より高速で AD（自動微分）対応 |
| 将来の拡張 | `llvm_ad_spectral`（スペクトル），`cuda_ad_rgb`（GPU） | 色再現性 / GPU 化の段階で切り替える |
| 必須ランタイム | LLVM-C.dll（Windows） | Dr.Jit が JIT 実行時に呼ぶ．`winget install LLVM.LLVM` で導入 |

### 採用理由

- 物理量（放射照度・配光）を素直に扱え，実測値とのキャリブレーションに向く
- BSDF（半透明散乱・拡散反射）が組み込みで揃っており，ディフューザーを既存実装で書ける
- Python API なので評価指標コードと同じスクリプトに統合できる
- 色再現性の検証に拡張する際もスペクトル変種に切替えるだけで済む

## 依存管理 (Dependency Management)

| 項目 | 採用 | 備考 |
| --- | --- | --- |
| パッケージマネージャ | **uv**（Astral 製） | 高速・クロスプラットフォーム・ロックファイル付き |
| 設定ファイル | `pyproject.toml`（PEP 621） | プロジェクト依存をここに集約 |
| ロックファイル | `uv.lock` | コミット対象（再現性のため） |
| Python バージョン管理 | `uv` 内蔵（`.python-version`） | pyenv 不要．`uv sync` で自動取得 |

### 環境再現コマンド

```powershell
# 1. uv のインストール（初回のみ）
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 2. 依存とランタイムを同期
uv sync
```

## 主要依存ライブラリ (Key Dependencies)

| カテゴリ | パッケージ | 用途 |
| --- | --- | --- |
| シミュレータ | `mitsuba` | 光線追跡コア |
| 数値計算 | `numpy` | 配列計算（評価指標と共用） |
| ジオメトリ | `trimesh` | STL の読み込み・三角形メッシュ操作 |
| 画像 I/O | `pillow` | PNG 出力（実機画像と同形式に揃える） |
| 可視化 | `matplotlib` | 輝度マップ・ヒストグラム・放射状プロファイル等 |
| 表データ | `pandas` | 均一性指標 CSV の生成・統計集計 |
| テスト | `pytest` | 単体テスト |
| Lint / Format | `ruff` | コードチェック・整形（uv エコシステムと整合） |

※ 具体的なバージョン制約は `pyproject.toml` で固定し，`uv.lock` で再現を保証する．

## ジオメトリ受け渡し (Geometry Pipeline)

Fusion 360 → SmTIAS-LightSim の橋渡し方式：

| 項目 | 採用 | 備考 |
| --- | --- | --- |
| エクスポート形式 | **STL**（バイナリ） | Fusion 360 標準機能で出力可．trimesh で安定して読める |
| 単位 | mm（Fusion 360 デフォルト） | Mitsuba シーンに渡す際は m に換算する（後段で実装） |
| 材料の受け渡し | STL ではメタ情報が落ちるため，**別 YAML / JSON で材料割当を管理** | 例: 「インナー筐体 = 拡散反射 90% / ディフューザー = 透過 60% 散乱角 40°」等 |

OBJ / 3MF も将来検討可．現時点では情報量と Python での扱いやすさのバランスで STL を採用．

## MiniTias-Evaluation コードの取り扱い (Reuse Policy)

均一性評価コードは **コピーして独立運用**（方針 a）．

- `MiniTias-Evaluation/src/uniformity.py` を本リポジトリ内に複製して使う
- 配置先（仮）: `src/sm_tias_lightsim/uniformity.py`
- ファイル冒頭に元の SHA / 出典を docstring で明記
- シミュレータ向けに必要があれば自由に拡張する（例: float64 直接入力の関数追加）

## ディレクトリ構成プレビュー (Directory Layout Preview)

詳細はフェーズ 4（仕様設計）で確定する．現時点の想定:

```
src/sm_tias_lightsim/
  ├── geometry/        # STL 読込・座標変換
  ├── scene/           # Mitsuba シーン構築（光源・材料・センサ）
  ├── render/          # レンダリング実行・画像出力
  ├── uniformity.py    # 評価指標（MiniTias-Evaluation からコピー）
  └── pipeline.py      # 全体パイプライン CLI
configs/               # シーン・材料・LED 配置の YAML/JSON
output/                # 結果（画像・CSV・図）
tests/                 # pytest
```

## GPU 対応への移行パス (Future GPU Support)

CPU で性能不足になった場合の道筋を残しておく:

1. Mitsuba 3 の variant を `cuda_rgb` または `cuda_spectral` に切替える
2. CUDA Toolkit + 対応 NVIDIA ドライバを Windows に導入（手順書化）
3. シーンコード自体は variant 切替えで動くため，アルゴリズム変更は基本不要

## 参考リンク (References)

- Mitsuba 3 公式: https://www.mitsuba-renderer.org/
- Mitsuba 3 Python tutorial: https://mitsuba.readthedocs.io/en/stable/src/quickstart/python_intro.html
- uv: https://docs.astral.sh/uv/
- trimesh: https://trimesh.org/