diff --git a/.claude/rules/coding-style.md b/.claude/rules/coding-style.md new file mode 100644 index 0000000..1145806 --- /dev/null +++ b/.claude/rules/coding-style.md @@ -0,0 +1,127 @@ +--- +paths: ["src/**", "scripts/**"] +--- + +# コーディング規約 (Coding Standards) + +Python コード（`src/**`・`scripts/**`）を編集するときは本ルールに従うこと． + +## 基本方針 (Basic Policy) + +- ruff を唯一の lint / format ツールとして使用する．設定は `pyproject.toml` の `[tool.ruff]` に集約． +- 標準（PEP 8 + Effective Python）から逸脱しない範囲で，ruff の自動修正に従う． +- プロジェクト固有のルールはこのファイルに最小限で書く． +- 別ツール（black, isort, mypy 等）は導入しない（ruff で完結）． + +## 適用 ruff ルール + +`pyproject.toml` の `[tool.ruff.lint]` で `select = ["E", "F", "W", "I", "B", "UP", "N"]` を選択． + +| ルール | 内容 | +| --- | --- | +| E (pycodestyle) | PEP 8 形式エラー | +| F (pyflakes) | 未使用変数・未定義シンボル等 | +| W (pycodestyle) | 形式警告 | +| I (isort) | import 文の並び順 | +| B (flake8-bugbear) | バグになりやすいパターン検出 | +| UP (pyupgrade) | Python 3.12 機能で書き換え可能なコードの提案 | +| N (pep8-naming) | クラス・関数・変数命名 | + +行長は 100 文字（Mitsuba API や数式リテラルが長くなりがちなため）． + +実行コマンド： + +```powershell +uv run ruff check . # 検査のみ +uv run ruff check . --fix # 自動修正 +uv run ruff format . # フォーマット適用 +``` + +## 型ヒント (Type Hints) + +- **公開関数（モジュールから export される関数・クラス）**: 引数と戻り値に型ヒント必須 +- **内部ヘルパ・テストコード**: 任意．書ける所は書く +- **Mitsuba / Dr.Jit の戻り値**: 型ヒントが不完全．`Any` または `np.ndarray` でフォールバック可 + +例： + +```python +import numpy as np + + +def to_grayscale(image: np.ndarray) -> np.ndarray: + """RGB → 輝度変換．...""" + ... +``` + +静的型チェック（mypy / pyright）は当面導入しない．必要が出てから追加． + +## docstring + +- **公開関数・クラス**: docstring 必須 +- **書式**: Google スタイル（`Args:` / `Returns:` / `Raises:`）に統一 +- **言語**: 日本語可．数式は LaTeX 表記（`$Y = 0.2126 R + ...$`）を許可 +- **数式の出典**: 引用 `[1]` を残し，参考文献は同モジュールの末尾コメントまたは docstring 末尾に列挙 + +例： + +```python +def to_grayscale(image: np.ndarray) -> np.ndarray: + """RGB 画像を Rec.709 輝度係数でグレースケールに変換する [1]． + + $Y = 0.2126 R + 0.7152 G + 0.0722 B$ + + Args: + image: 入力 RGB 画像（H x W x 3, uint8）． + + Returns: + 輝度画像（H x W, float64, 値域 0.0〜255.0）． + + References: + [1] ITU-R BT.709 + """ +``` + +## 命名規則 (Naming) + +ruff `N` ルールでチェック． + +| 対象 | スタイル | 例 | +| --- | --- | --- | +| モジュール | snake_case | `uniformity.py`, `scene_builder.py` | +| パッケージ | snake_case | `sm_tias_lightsim` | +| 関数・変数 | snake_case | `to_grayscale`, `roi_image` | +| クラス | PascalCase | `SceneBuilder`, `LedLight` | +| 定数 | UPPER_SNAKE_CASE | `REC709_COEFF_R` | +| プライベート | 接頭辞 `_` | `_validate_roi` | + +## コメント + +- **WHY を書く**：何をしているかは識別子で表現．コメントは「なぜこの実装か」「数式の出典」「制約」に限定する． +- **TODO** は `# TODO(rintoHasegawa): 内容` 形式で記述する． + +## import 順序 + +ruff `I` で自動整列．以下の順： + +1. 標準ライブラリ +2. サードパーティ（`mitsuba`, `numpy`, `trimesh` 等） +3. プロジェクト内（`from sm_tias_lightsim import ...`） + +手動整列不要． + +## CLI 引数 + +- 短縮形より長い形を優先（`--scene` を主，`-s` は併用） +- `argparse` 標準を使用 +- ヘルプ文は日本語可 + +## エラー処理 + +- 例外の使い分け・方針は `.claude/rules/error-handling.md` に定義する（`src/**`・`scripts/**` 編集時に自動ロードされる）． + +## 参考 (References) + +- [PEP 8 — Style Guide for Python Code](https://peps.python.org/pep-0008/) +- [Google Python Style Guide — Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) +- [ruff documentation](https://docs.astral.sh/ruff/) diff --git a/.claude/rules/error-handling.md b/.claude/rules/error-handling.md new file mode 100644 index 0000000..044bccb --- /dev/null +++ b/.claude/rules/error-handling.md @@ -0,0 +1,27 @@ +--- +paths: ["src/**", "scripts/**"] +--- + +# エラーハンドリング方針 (Error Handling) + +例外を raise / 捕捉するコード（`src/**`・`scripts/**`）を書くときは本ルールに従うこと．コーディング全般の規約は `.claude/rules/coding-style.md` を参照する． + +## 例外の使い分け (Exception Types) + +| 状況 | 送出する例外 | +| --- | --- | +| ユーザー入力（YAML / STL ファイル等）の内容・形式の問題 | `ValueError` に統一して raise | +| 内部論理エラー（到達しないはずの分岐・不変条件違反等） | `RuntimeError` | +| Pydantic を使うバリデーション | `pydantic.ValidationError` をそのまま伝播（握りつぶさない） | + +## 方針 (Policy) + +- **最小限主義**: 独自例外クラスの階層はまだ導入しない．上表の標準例外で表現できる範囲に留める．表現しきれないケースが増えてきた時点で独自例外の導入を検討する． +- **メッセージは日本語可**: 原因と対処が分かる具体的なメッセージを付ける（例: どのファイル・どのフィールドが不正か）． +- **握りつぶさない**: `except:` で例外を無言で捨てない．捕捉するなら再送出するか，ログを残した上で明示的に処理する． +- **境界で検証する**: ユーザー入力の検証は入口（CLI・スキーマ読込）で行い，核計算モジュールは「検証済みの正しい入力が来る」前提で書く（`.claude/rules/project-structure.md` の依存方向・純関数優先と対応）． + +## 参考 (References) + +- [Python 公式ドキュメント — 組み込み例外](https://docs.python.org/3/library/exceptions.html) +- [Pydantic — Error Handling](https://docs.pydantic.dev/latest/errors/errors/) diff --git a/.claude/rules/project-structure.md b/.claude/rules/project-structure.md new file mode 100644 index 0000000..63ed0ed --- /dev/null +++ b/.claude/rules/project-structure.md @@ -0,0 +1,35 @@ +--- +paths: ["src/**", "tests/**", "scripts/**"] +--- + +# プロジェクト構成ルール (Project Structure) + +ソース・テスト・スクリプトを追加・移動するときは本ルールに従い，責務ごとのサブパッケージ配置を保つこと．設計の背景は `docs/04_SPEC/SPEC_01_アーキテクチャ設計.md` を参照する（本ルールは配置規則のみを定める）． + +## ディレクトリ構成 (Layout) + +```text +src/sm_tias_lightsim/ +├── __init__.py +├── uniformity.py # Rec.709 輝度変換 + CoV/std/max-min（核計算） +├── cli/ # CLI エントリポイント（render / evaluate / visualize） +├── scene/ # YAML → Mitsuba scene（schema / builder / lights / materials / sensors） +├── geometry/ # STL 読込・単位変換・メッシュ分割（loader / transforms / subdivide） +├── render/ # Mitsuba 実行と出力（runner / output） +├── evaluation/ # 評価パイプライン（roi / zones / radial / oetf / normalize / shape_metrics / visualize …） +├── visualize/ # 3D 可視化（baker / projection / viewer） +└── runtime/ # 実行時ヘルパ（llvm_init 等） + +tests/ # src のサブパッケージ構造をミラー（testing.md 参照） +scripts/ # 単発の調査・キャリブ・図生成スクリプト（パッケージ外） +configs/ # シーン YAML・評価 YAML・メッシュ等（コード外の設定・入力） +``` + +## 配置ルール (Placement Rules) + +- **1 モジュール 1 責務**: 新しい機能は責務に合うサブパッケージに置く．該当が無ければ新サブパッケージを作る（安易に既存モジュールへ肥大化させない）． +- **サブパッケージ間の依存方向**: `cli` → 各機能パッケージ → 核計算（`uniformity` 等）の一方向を保つ．核計算モジュールから上位（`cli`・`visualize`）を import しない． +- **純関数を優先**: 副作用（ファイル I/O・Mitsuba 実行）は `render`・`cli`・`output` 等の縁に寄せ，`evaluation`・`geometry`・`visualize/projection` 等は入力→出力の純関数として書く（テスト容易性のため．`testing.md` の「核計算は必ず単体テスト」と対応）． +- **テストの配置**: `tests/` は `src/sm_tias_lightsim/` のサブパッケージ構造をミラーする（詳細は `.claude/rules/testing.md`）． +- **調査・使い捨てコード**: 恒久的に使わない単発スクリプトは `src/` ではなく `scripts/` に置く（パッケージの公開 API を汚さない）． +- **設定・入力データ**: シーン/評価 YAML・STL・生成物は `configs/` 配下に置き，コード（`src/`）に埋め込まない． diff --git a/.claude/rules/testing.md b/.claude/rules/testing.md new file mode 100644 index 0000000..ba5acda --- /dev/null +++ b/.claude/rules/testing.md @@ -0,0 +1,107 @@ +--- +paths: ["tests/**", "**/test_*.py", "**/conftest.py"] +--- + +# テスト方針 (Test Policy) + +テストコード（`tests/**`・`test_*.py`・`conftest.py`）を追加・編集するときは本ルールに従うこと． + +## 基本方針 (Basic Policy) + +- フレームワーク: **pytest** +- 配置: `tests/` 配下に `src/sm_tias_lightsim/` のサブパッケージ構造をミラー +- カバレッジ目標: **数値目標なし**．代わりに「核となる計算ロジックは必ず単体テスト」というルールを徹底する +- 通常実行: `uv run pytest` +- 重いテストを含む実行: `uv run pytest -m "" --no-strict-markers` ／ デフォルトでスキップは `-m "not slow"` + +## テストの配置 + +``` +tests/ +├── conftest.py # 共通フィクスチャ +├── fixtures/ # テストデータ（小さい STL / 既知の輝度マップ等） +├── geometry/ +│ └── test_loader.py +├── scene/ +│ ├── test_builder.py +│ └── test_schema.py +├── render/ +│ └── test_runner.py # 軽量シーンの end-to-end +├── test_uniformity.py # MiniTias-Evaluation 互換の数値検証 +└── evaluation/ + ├── test_roi.py + └── test_zones.py +``` + +## ファイル・関数命名 + +- ファイル: `test_<対象モジュール>.py` +- 関数: `test_<振る舞い>` 例: `test_grayscale_conversion_uses_rec709_coefficients` +- クラス（任意）: `Test<クラス名>` で振る舞いごとにグループ化可能 + +## 必ずテストを書く対象 (Mandatory) + +- **核計算ロジック**: `uniformity.py`, `evaluation/zones.py`, `evaluation/radial.py` + - 既知の入力（合成輝度マップ）に対して期待値を確認 + - MiniTias-Evaluation の元実装と数値が一致することを保証 +- **入力バリデーション**: `scene/schema.py` + - 不正 YAML が `ValidationError` を投げること + - 必須フィールド欠落・参照不整合を検出すること +- **データ変換**: `geometry/transforms.py`（mm ↔ m 等） + - 変換が可逆であること +- **YAML → Mitsuba scene 変換**: `scene/builder.py` + - 期待される scene dict を生成すること（実レンダリングはせず構造のみ確認） + +## テストを必須としない対象 (Optional) + +- **CLI のエントリポイント**（`cli/render.py`, `cli/evaluate.py`） + - 統合テスト 1 本でカバー +- **可視化**（`evaluation/visualize.py`） + - 図の見栄えはテストしにくい．「ファイルが生成されたか」程度の smoke テストで十分 + +## モック方針 (Mocking) + +- **Mitsuba をモックしない**．小さい合成シーン（64×64 等）で実物を回す + - 理由: モックすると物理量の妥当性検証ができなくなる．実機との比較が目的のため +- **ファイル I/O はモックしない**．`tmp_path` フィクスチャで実ファイルを使う +- **乱数を含むテスト**は必ず `seed` を固定する + +## 重いテストの扱い (Slow Tests) + +レンダリングを伴うテストは `@pytest.mark.slow` を付けて区別： + +```python +import pytest + + +@pytest.mark.slow +def test_render_baseline_matches_reference(): + ... +``` + +- 通常実行（高速）: `uv run pytest -m "not slow"` +- 全テスト実行（CI 等）: `uv run pytest` + +マーカー定義は `pyproject.toml` の `[tool.pytest.ini_options]` に登録済み． + +## /implement パイプラインでのテスト + +`/implement` の流れ： + +1. **Phase 1（実装 / coder）**: 機能実装 → 人間が動作確認 +2. **Phase 2（テスト / tester）**: この方針に従いテストを追加 +3. **Phase 3（リファクタ / refactorer）**: テストを safety net として品質改善 +4. **Phase 4**: ドキュメント更新 + +Phase 2 でテストが書きにくいと感じたら，それは設計が悪いシグナル．Phase 3 でモジュールを分割するか責務を見直す． + +## テスト失敗時の運用 + +- ルール変更による失敗: 規約・仕様を改める根拠があれば SPEC / GUIDE を先に更新してからテストを書き直す +- バグ起因の失敗: 修正してから再実行 +- 単に flaky なテスト: `seed` 固定漏れか，乱数依存の境界値．`seed` を見直す + +## 参考 (References) + +- [pytest documentation](https://docs.pytest.org/) +- [Mitsuba 3 — Differentiable rendering tutorials](https://mitsuba.readthedocs.io/en/stable/) （小規模シーンの組み立て例） diff --git a/CLAUDE.md b/CLAUDE.md index c7a3239..51f7cf4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -79,9 +79,7 @@ - プロジェクト立ち上げフロー: docs/01_GUIDE/GUIDE_01_プロジェクト立ち上げフロー.md - エージェント運用ルール: docs/01_GUIDE/GUIDE_02_エージェント運用ルール.md -- コーディング規約: docs/01_GUIDE/GUIDE_06_コーディング規約.md -- テスト方針: docs/01_GUIDE/GUIDE_08_テスト方針.md -- ※ Git 規約・ドキュメント書式・命名規則・進捗記録は `.claude/rules/`（git-conventions / markdown-style / docs-naming / progress-log）に定義されている（git-conventions は常時，他は該当ファイル編集時に自動ロード） +- ※ コーディング規約・テスト方針・構成規則・エラー処理・Git 規約・ドキュメント書式・命名規則・進捗記録は `.claude/rules/`（coding-style / testing / project-structure / error-handling / git-conventions / markdown-style / docs-naming / progress-log）に path-scoped rule として定義されている（git-conventions は常時，他は該当ファイル編集時に自動ロード） ### 02_ENV（環境） diff --git "a/docs/01_GUIDE/GUIDE_06_\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204.md" "b/docs/01_GUIDE/GUIDE_06_\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204.md" deleted file mode 100644 index d77a5f9..0000000 --- "a/docs/01_GUIDE/GUIDE_06_\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204.md" +++ /dev/null @@ -1,124 +0,0 @@ -# コーディング規約 (Coding Standards) - -## 基本方針 (Basic Policy) - -- ruff を唯一の lint / format ツールとして使用する．設定は `pyproject.toml` の `[tool.ruff]` に集約． -- 標準（PEP 8 + Effective Python）から逸脱しない範囲で，ruff の自動修正に従う． -- プロジェクト固有のルールはこのファイルに最小限で書く． -- 別ツール（black, isort, mypy 等）は導入しない（ruff で完結）． - -## 適用 ruff ルール - -`pyproject.toml` の `[tool.ruff.lint]` で `select = ["E", "F", "W", "I", "B", "UP", "N"]` を選択． - -| ルール | 内容 | -| --- | --- | -| E (pycodestyle) | PEP 8 形式エラー | -| F (pyflakes) | 未使用変数・未定義シンボル等 | -| W (pycodestyle) | 形式警告 | -| I (isort) | import 文の並び順 | -| B (flake8-bugbear) | バグになりやすいパターン検出 | -| UP (pyupgrade) | Python 3.12 機能で書き換え可能なコードの提案 | -| N (pep8-naming) | クラス・関数・変数命名 | - -行長は 100 文字（Mitsuba API や数式リテラルが長くなりがちなため）． - -実行コマンド： - -```powershell -uv run ruff check . # 検査のみ -uv run ruff check . --fix # 自動修正 -uv run ruff format . # フォーマット適用 -``` - -## 型ヒント (Type Hints) - -- **公開関数（モジュールから export される関数・クラス）**: 引数と戻り値に型ヒント必須 -- **内部ヘルパ・テストコード**: 任意．書ける所は書く -- **Mitsuba / Dr.Jit の戻り値**: 型ヒントが不完全．`Any` または `np.ndarray` でフォールバック可 - -例： - -```python -import numpy as np - - -def to_grayscale(image: np.ndarray) -> np.ndarray: - """RGB → 輝度変換．...""" - ... -``` - -静的型チェック（mypy / pyright）は当面導入しない．必要が出てから追加． - -## docstring - -- **公開関数・クラス**: docstring 必須 -- **書式**: Google スタイル（`Args:` / `Returns:` / `Raises:`）に統一 -- **言語**: 日本語可．数式は LaTeX 表記（`$Y = 0.2126 R + ...$`）を許可 -- **数式の出典**: 引用 `[1]` を残し，参考文献は同モジュールの末尾コメントまたは docstring 末尾に列挙 - -例： - -```python -def to_grayscale(image: np.ndarray) -> np.ndarray: - """RGB 画像を Rec.709 輝度係数でグレースケールに変換する [1]． - - $Y = 0.2126 R + 0.7152 G + 0.0722 B$ - - Args: - image: 入力 RGB 画像（H x W x 3, uint8）． - - Returns: - 輝度画像（H x W, float64, 値域 0.0〜255.0）． - - References: - [1] ITU-R BT.709 - """ -``` - -## 命名規則 (Naming) - -ruff `N` ルールでチェック． - -| 対象 | スタイル | 例 | -| --- | --- | --- | -| モジュール | snake_case | `uniformity.py`, `scene_builder.py` | -| パッケージ | snake_case | `sm_tias_lightsim` | -| 関数・変数 | snake_case | `to_grayscale`, `roi_image` | -| クラス | PascalCase | `SceneBuilder`, `LedLight` | -| 定数 | UPPER_SNAKE_CASE | `REC709_COEFF_R` | -| プライベート | 接頭辞 `_` | `_validate_roi` | - -## コメント - -- **WHY を書く**：何をしているかは識別子で表現．コメントは「なぜこの実装か」「数式の出典」「制約」に限定する． -- **TODO** は `# TODO(rintoHasegawa): 内容` 形式で記述する． - -## import 順序 - -ruff `I` で自動整列．以下の順： - -1. 標準ライブラリ -2. サードパーティ（`mitsuba`, `numpy`, `trimesh` 等） -3. プロジェクト内（`from sm_tias_lightsim import ...`） - -手動整列不要． - -## CLI 引数 - -- 短縮形より長い形を優先（`--scene` を主，`-s` は併用） -- `argparse` 標準を使用 -- ヘルプ文は日本語可 - -## エラー処理（最小限） - -- ユーザー入力（YAML / STL ファイル）の問題は `ValueError` に統一して raise -- 内部論理エラーは `RuntimeError` -- Pydantic を使うバリデーションは `pydantic.ValidationError` をそのまま伝播 -- これ以上の例外設計は GUIDE_09（エラーハンドリング方針）が必要になった時点で追加する - -## 参考 (References) - -- [PEP 8 — Style Guide for Python Code](https://peps.python.org/pep-0008/) -- [Google Python Style Guide — Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) -- [ruff documentation](https://docs.astral.sh/ruff/) diff --git "a/docs/01_GUIDE/GUIDE_08_\343\203\206\343\202\271\343\203\210\346\226\271\351\207\235.md" "b/docs/01_GUIDE/GUIDE_08_\343\203\206\343\202\271\343\203\210\346\226\271\351\207\235.md" deleted file mode 100644 index f77c9dc..0000000 --- "a/docs/01_GUIDE/GUIDE_08_\343\203\206\343\202\271\343\203\210\346\226\271\351\207\235.md" +++ /dev/null @@ -1,101 +0,0 @@ -# テスト方針 (Test Policy) - -## 基本方針 (Basic Policy) - -- フレームワーク: **pytest** -- 配置: `tests/` 配下に `src/sm_tias_lightsim/` のサブパッケージ構造をミラー -- カバレッジ目標: **数値目標なし**．代わりに「核となる計算ロジックは必ず単体テスト」というルールを徹底する -- 通常実行: `uv run pytest` -- 重いテストを含む実行: `uv run pytest -m "" --no-strict-markers` ／ デフォルトでスキップは `-m "not slow"` - -## テストの配置 - -``` -tests/ -├── conftest.py # 共通フィクスチャ -├── fixtures/ # テストデータ（小さい STL / 既知の輝度マップ等） -├── geometry/ -│ └── test_loader.py -├── scene/ -│ ├── test_builder.py -│ └── test_schema.py -├── render/ -│ └── test_runner.py # 軽量シーンの end-to-end -├── test_uniformity.py # MiniTias-Evaluation 互換の数値検証 -└── evaluation/ - ├── test_roi.py - └── test_zones.py -``` - -## ファイル・関数命名 - -- ファイル: `test_<対象モジュール>.py` -- 関数: `test_<振る舞い>` 例: `test_grayscale_conversion_uses_rec709_coefficients` -- クラス（任意）: `Test<クラス名>` で振る舞いごとにグループ化可能 - -## 必ずテストを書く対象 (Mandatory) - -- **核計算ロジック**: `uniformity.py`, `evaluation/zones.py`, `evaluation/radial.py` - - 既知の入力（合成輝度マップ）に対して期待値を確認 - - MiniTias-Evaluation の元実装と数値が一致することを保証 -- **入力バリデーション**: `scene/schema.py` - - 不正 YAML が `ValidationError` を投げること - - 必須フィールド欠落・参照不整合を検出すること -- **データ変換**: `geometry/transforms.py`（mm ↔ m 等） - - 変換が可逆であること -- **YAML → Mitsuba scene 変換**: `scene/builder.py` - - 期待される scene dict を生成すること（実レンダリングはせず構造のみ確認） - -## テストを必須としない対象 (Optional) - -- **CLI のエントリポイント**（`cli/render.py`, `cli/evaluate.py`） - - 統合テスト 1 本でカバー -- **可視化**（`evaluation/visualize.py`） - - 図の見栄えはテストしにくい．「ファイルが生成されたか」程度の smoke テストで十分 - -## モック方針 (Mocking) - -- **Mitsuba をモックしない**．小さい合成シーン（64×64 等）で実物を回す - - 理由: モックすると物理量の妥当性検証ができなくなる．実機との比較が目的のため -- **ファイル I/O はモックしない**．`tmp_path` フィクスチャで実ファイルを使う -- **乱数を含むテスト**は必ず `seed` を固定する - -## 重いテストの扱い (Slow Tests) - -レンダリングを伴うテストは `@pytest.mark.slow` を付けて区別： - -```python -import pytest - - -@pytest.mark.slow -def test_render_baseline_matches_reference(): - ... -``` - -- 通常実行（高速）: `uv run pytest -m "not slow"` -- 全テスト実行（CI 等）: `uv run pytest` - -マーカー定義は `pyproject.toml` の `[tool.pytest.ini_options]` に登録済み． - -## /implement パイプラインでのテスト - -`/implement` の流れ： - -1. **Phase 1（実装 / coder）**: 機能実装 → 人間が動作確認 -2. **Phase 2（テスト / tester）**: この方針に従いテストを追加 -3. **Phase 3（リファクタ / refactorer）**: テストを safety net として品質改善 -4. **Phase 4**: ドキュメント更新 - -Phase 2 でテストが書きにくいと感じたら，それは設計が悪いシグナル．Phase 3 でモジュールを分割するか責務を見直す． - -## テスト失敗時の運用 - -- ルール変更による失敗: 規約・仕様を改める根拠があれば SPEC / GUIDE を先に更新してからテストを書き直す -- バグ起因の失敗: 修正してから再実行 -- 単に flaky なテスト: `seed` 固定漏れか，乱数依存の境界値．`seed` を見直す - -## 参考 (References) - -- [pytest documentation](https://docs.pytest.org/) -- [Mitsuba 3 — Differentiable rendering tutorials](https://mitsuba.readthedocs.io/en/stable/) （小規模シーンの組み立て例） diff --git "a/docs/02_ENV/ENV_04_\351\226\213\347\231\272\343\202\263\343\203\236\343\203\263\343\203\211.md" "b/docs/02_ENV/ENV_04_\351\226\213\347\231\272\343\202\263\343\203\236\343\203\263\343\203\211.md" new file mode 100644 index 0000000..a373ab4 --- /dev/null +++ "b/docs/02_ENV/ENV_04_\351\226\213\347\231\272\343\202\263\343\203\236\343\203\263\343\203\211.md" @@ -0,0 +1,47 @@ +# 開発コマンド (Development Commands) + +日常の開発で使うコマンドをまとめる．人間とエージェント（tester・coder，`/auto-refactor`・`/auto-audit`）がコマンドを推測せずに済むよう，本ファイルを唯一の参照先とする．新しいコマンドが確定・変更されたら本ファイルに反映する． + +## 前提 (Prerequisites) + +- パッケージ管理・実行は **uv** に統一する．コマンドは原則 `uv run <...>` で実行する． +- 依存の同期: `uv sync`（`dev` グループを含めて全依存をインストール） +- Python は `>=3.12`（`pyproject.toml` の `requires-python`）． + +## シミュレーション・評価 (CLI) + +`pyproject.toml` の `[project.scripts]` で定義されたエントリポイント． + +| コマンド | 役割 | 実装 | +| --- | --- | --- | +| `uv run sm-render ` | シーン YAML をレンダリングし PNG / luminance.npy を出力 | `cli/render.py` | +| `uv run sm-evaluate <入力> ` | PNG / luminance.npy を評価し metrics.csv + figures/ を出力 | `cli/evaluate.py` | +| `uv run sm-visualize ` | シーンを 3D 表示 / スクリーンショット出力 | `cli/visualize.py` | + +各コマンドの詳細オプションは `--help` で確認する（例: `uv run sm-visualize --help`）． + +## テスト (Tests) + +テスト方針の詳細は `.claude/rules/testing.md` を参照． + +```bash +uv run pytest # 通常実行 +uv run pytest -m "not slow" # 重い（レンダリングを伴う）テストを除外 +uv run pytest tests/evaluation/test_roi.py # 個別ファイル +``` + +- `slow` マーカーは `pyproject.toml` の `[tool.pytest.ini_options]` に登録済み． + +## Lint / フォーマット (Lint & Format) + +規約の詳細は `.claude/rules/coding-style.md` を参照．ruff を唯一の lint / format ツールとする． + +```bash +uv run ruff check . # 検査のみ +uv run ruff check . --fix # 自動修正 +uv run ruff format . # フォーマット適用 +``` + +## 環境変数 (Environment Variables) + +- `DRJIT_LIBLLVM_PATH` — Mitsuba の LLVM JIT に必要（未設定時は `runtime/llvm_init.py` が標準パスを自動探索）．詳細は `docs/02_ENV/ENV_02_環境構築手順.md` を参照．