diff --git a/CLAUDE.md b/CLAUDE.md index 61d48de..d1b25d0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,8 +5,10 @@ ## 開発進捗 -現在の進捗: GUIDE_01 フェーズ 2(技術選定)— `ENV_01_技術スタック.md` 作成中 +現在の進捗: GUIDE_01 フェーズ 4(仕様設計)— `SPEC_01_*.md` 作成中 ※ フェーズ 1(方針決定)完了: [docs/03_PLAN/PLAN_01_要件定義書.md](docs/03_PLAN/PLAN_01_要件定義書.md) +※ フェーズ 2(技術選定)完了: [docs/02_ENV/ENV_01_技術スタック.md](docs/02_ENV/ENV_01_技術スタック.md) +※ フェーズ 3(環境構築)完了: [docs/02_ENV/ENV_02_環境構築手順.md](docs/02_ENV/ENV_02_環境構築手順.md), [docs/02_ENV/ENV_03_管理者用環境構築手順.md](docs/02_ENV/ENV_03_管理者用環境構築手順.md) ※ ステップ完了時にここを更新すること. ## 必須ルール(コード実装時) diff --git "a/docs/02_ENV/ENV_01_\346\212\200\350\241\223\343\202\271\343\202\277\343\203\203\343\202\257.md" "b/docs/02_ENV/ENV_01_\346\212\200\350\241\223\343\202\271\343\202\277\343\203\203\343\202\257.md" new file mode 100644 index 0000000..4207ef2 --- /dev/null +++ "b/docs/02_ENV/ENV_01_\346\212\200\350\241\223\343\202\271\343\202\277\343\203\203\343\202\257.md" @@ -0,0 +1,116 @@ +# 技術スタック (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** | 物理ベース・モンテカルロレンダラ.Python API あり | +| バリアント (variant) | `llvm_rgb` をメインで使用 | LLVM JIT による CPU 並列化.`scalar_rgb` よりも実用的に速い | +| 将来の拡張 | `llvm_spectral`(スペクトル),`cuda_rgb`(GPU) | 色再現性 / GPU 化の段階で切り替える | + +### 採用理由 + +- 物理量(放射照度・配光)を素直に扱え,実測値とのキャリブレーションに向く +- 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/ diff --git "a/docs/02_ENV/ENV_02_\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206.md" "b/docs/02_ENV/ENV_02_\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206.md" new file mode 100644 index 0000000..a62edd7 --- /dev/null +++ "b/docs/02_ENV/ENV_02_\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206.md" @@ -0,0 +1,99 @@ +# 環境構築手順 (Environment Setup) + +新規参加者・別デバイス・環境を作り直す場合の手順.Windows 10 / 11 を前提とする. + +## 前提条件 (Prerequisites) + +| ツール | 用途 | 入手元 | +| --- | --- | --- | +| Git | リポジトリ操作 | https://git-scm.com/download/win | +| GitHub CLI(`gh`) | PR 作成・マージ | https://cli.github.com/ | +| Fusion 360(任意) | 筐体 3D モデル編集.シミュレーション実行のみなら不要 | https://www.autodesk.co.jp/products/fusion-360 | + +Python は **uv** が自動で取得するため,手動インストール不要. + +## 手順 (Steps) + +### 1. uv をインストール + +PowerShell を開き,以下を実行する. + +```powershell +powershell -c "irm https://astral.sh/uv/install.ps1 | iex" +``` + +バージョンを確認: + +```powershell +uv --version +``` + +### 2. リポジトリをクローン + +```powershell +git clone https://github.com/rintoHasegawa/SmTIAS-LightSim.git +cd SmTIAS-LightSim +``` + +### 3. 依存と Python ランタイムを同期 + +```powershell +uv sync +``` + +このコマンドだけで以下が実行される: + +- `.python-version` に書かれた Python 3.12 を uv が自動取得 +- `pyproject.toml` + `uv.lock` から完全同一の依存関係を再現 +- 仮想環境 `.venv/` を作成 + +### 4. 動作確認 + +```powershell +uv run python -c "import mitsuba; mitsuba.set_variant('llvm_rgb'); print(mitsuba.__version__)" +``` + +Mitsuba のバージョンが表示されれば OK. + +### 5. ツール類の確認 + +```powershell +uv run pytest --version # テスト実行用 +uv run ruff --version # Lint / Format 用 +``` + +## よくある操作 (Common Tasks) + +| やりたいこと | コマンド | +| --- | --- | +| 依存追加 | `uv add <パッケージ名>` | +| 開発用依存追加 | `uv add --dev <パッケージ名>` | +| 依存更新 | `uv lock --upgrade` → `uv sync` | +| スクリプト実行 | `uv run python <スクリプト>` | +| テスト実行 | `uv run pytest` | +| Lint / Format | `uv run ruff check .` / `uv run ruff format .` | + +## トラブルシューティング (Troubleshooting) + +### `uv sync` が遅い / 失敗する + +- ネットワーク状態を確認.Mitsuba 3 の wheel はサイズが大きい(〜100 MB) +- 企業ネットワーク内ではプロキシ設定が必要:`uv` は環境変数 `HTTPS_PROXY` を尊重する + +### `mitsuba.set_variant('llvm_rgb')` でエラー + +- LLVM ランタイムが Mitsuba wheel に同梱されているはずだが,万一エラーになる場合は `scalar_rgb` に切り替えて挙動を切り分け.恒久対応は upstream 側 issue を参照 + +### Python 3.12 が手元にない + +- `uv sync` が自動で取得する.手動インストール不要 + +## GPU 対応(任意) + +CPU で実行が遅すぎる場合のオプション.導入は **任意**: + +1. NVIDIA ドライバを更新 +2. CUDA Toolkit 12.x をインストール(Mitsuba 3 のドキュメントが指定するバージョンに従う) +3. コード側で `mitsuba.set_variant('cuda_rgb')` に切替え + +詳細は Mitsuba 3 公式ドキュメントを参照. diff --git "a/docs/02_ENV/ENV_03_\347\256\241\347\220\206\350\200\205\347\224\250\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206.md" "b/docs/02_ENV/ENV_03_\347\256\241\347\220\206\350\200\205\347\224\250\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206.md" new file mode 100644 index 0000000..0089b9d --- /dev/null +++ "b/docs/02_ENV/ENV_03_\347\256\241\347\220\206\350\200\205\347\224\250\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206.md" @@ -0,0 +1,80 @@ +# 管理者用環境構築手順 (Admin Setup) + +プロジェクト立ち上げ時に **一度だけ** 実施する作業をまとめる.既に完了した項目もチェック付きで記録しておく. + +## 1. GitHub リポジトリ作成(完了済み) + +- [x] `rintoHasegawa/SmTIAS-LightSim` を Private で作成 +- [x] `main` ブランチを作成・初期コミット +- [x] programming-template から初回同期(`/sync-template`) +- [x] `MiniTIAS/` と `MiniTias-Evaluation/` を `.gitignore` に追加(参照用ローカルコピーのため) + +## 2. uv の動作確認(完了済み) + +ローカル環境で uv をインストール済みであれば次へ.未導入であれば `ENV_02_環境構築手順.md` の手順 1 を実施. + +## 3. プロジェクト初期化(実装フェーズで実行) + +以下はフェーズ 7(実装開始)の最初に行う. + +### 3.1 pyproject.toml の生成 + +```powershell +uv init --package --no-readme --no-workspace +``` + +その後,`pyproject.toml` の依存関係を `ENV_01_技術スタック.md` の主要依存ライブラリ表に従って追記する. + +例: + +```powershell +uv add mitsuba numpy trimesh pillow matplotlib pandas +uv add --dev pytest ruff +``` + +### 3.2 Python バージョン固定 + +```powershell +uv python pin 3.12 +``` + +`.python-version` ファイルが生成される.これをコミットする. + +### 3.3 ロックファイルの初期生成とコミット + +```powershell +uv lock +git add pyproject.toml uv.lock .python-version +git commit -m "[add] uv によるプロジェクト初期化と Mitsuba 3 依存の追加" +``` + +## 4. リポジトリ運用設定 + +### 4.1 デフォルトブランチの確認 + +- [x] GitHub の Settings → Branches → Default branch が `main` になっていること + +### 4.2 ブランチ保護(任意) + +1 人運用のため必須ではないが,誤プッシュ防止に以下を推奨: + +- Settings → Branches → Add rule +- Branch name pattern: `main` +- Require a pull request before merging(チェック) +- Require approvals は無効でよい(1 人運用のため) + +未設定でも開発に支障はない. + +## 5. 外部サービス(任意・将来) + +現時点では外部サービス連携は不要.以下は将来検討事項として残しておく: + +- **CI / CD(GitHub Actions)**: pytest と ruff の自動実行.運用が安定してから導入する +- **GitHub Pages**: シミュレーション結果のレポート公開用.現状は不要 + +これらは管理者がコンソール操作で設定する作業のため,AI からは実施しない. + +## 6. メンバー追加時の手続き + +1. 新規参加者を GitHub リポジトリの Collaborator に追加(管理者の手動操作) +2. 参加者は `ENV_02_環境構築手順.md` に従って自分の環境を構築