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" new file mode 100644 index 0000000..c649ff5 --- /dev/null +++ "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" @@ -0,0 +1,63 @@ +# コーディング規約 (Coding Standards) + +基本方針として PEP 8 および Ruff の自動チェックに準拠する．本ガイドでは PEP 8 でカバーされないプロジェクト固有のルールのみ定義する． + +## フォーマット (Formatting) + +- フォーマッター・リンター: Ruff（`ruff.toml` で設定済み） +- 行長: 88 文字（`ruff.toml` で設定済み） +- クォート: ダブルクォート `"` + +## 命名規則 (Naming) + +PEP 8 に準拠する． + +| 対象 | 形式 | 例 | +| --- | --- | --- | +| モジュール | `snake_case` | `uniformity.py` | +| 関数・変数 | `snake_case` | `calc_cov` | +| 定数 | `UPPER_SNAKE_CASE` | `DEFAULT_ROI_SIZE` | +| クラス | `PascalCase` | `UniformityResult` | + +## import 順序 (Import Order) + +Ruff（`isort` 互換）で自動整列する．順序: + +1. 標準ライブラリ +2. サードパーティ（numpy，cv2，colour 等） +3. プロジェクト内モジュール + +## 型ヒント (Type Hints) + +- 関数の引数と戻り値に型ヒントを付ける +- NumPy 配列は `numpy.ndarray` を使用する + +```python +def calc_cov(image: numpy.ndarray) -> float: +``` + +## コメント (Comments) + +- 「何をしているか」ではなく「なぜそうしているか」を書く +- 論文・規格への参照がある場合はコメントに明記する + +```python +# CIE ΔE2000 を使用（CIEDE2000, CIE 142-2001） +delta_e = colour.delta_E(lab1, lab2, method="CIE 2000") +``` + +## docstring + +- 公開関数には Google スタイルの docstring を付ける + +```python +def load_image(path: str) -> numpy.ndarray: + """PNG 画像を読み込み RGB 配列として返す． + + Args: + path: 画像ファイルのパス． + + Returns: + RGB 画像の NumPy 配列（H x W x 3, uint8）． + """ +``` diff --git "a/docs/01_GUIDE/GUIDE_07_\343\203\207\343\202\243\343\203\254\343\202\257\343\203\210\343\203\252\346\247\213\351\200\240\350\246\217\345\211\207.md" "b/docs/01_GUIDE/GUIDE_07_\343\203\207\343\202\243\343\203\254\343\202\257\343\203\210\343\203\252\346\247\213\351\200\240\350\246\217\345\211\207.md" new file mode 100644 index 0000000..11953bd --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_07_\343\203\207\343\202\243\343\203\254\343\202\257\343\203\210\343\203\252\346\247\213\351\200\240\350\246\217\345\211\207.md" @@ -0,0 +1,38 @@ +# ディレクトリ構造規則 (Directory Structure) + +## プロジェクトルート (Project Root) + +```text +MiniTias-Evaluation/ +├── src/ # ソースコード +│ ├── io/ # 画像の読み込み +│ ├── analysis/ # 解析ロジック +│ ├── visualization/ # 可視化 +│ └── export/ # 結果出力 +├── scripts/ # 実行スクリプト +├── tests/ # テストコード +├── data/ # 入力画像（Git 管理外） +├── output/ # 解析結果（Git 管理外） +├── docs/ # ドキュメント +└── MiniTias/ # 参照用コピー（Git 管理外） +``` + +## 配置ルール (Placement Rules) + +| 種類 | 配置先 | 備考 | +| --- | --- | --- | +| 解析ロジック | `src/` 配下の該当パッケージ | 1 モジュール = 1 責務 | +| 実行スクリプト | `scripts/` | CLI のエントリーポイント | +| テスト | `tests/` | `src/` の構造に対応させる | +| 入力画像 | `data/{装置名}/{撮影物}/` | 例: `data/minitias/whiteboard/` | +| 出力結果 | `output/figures/`，`output/results/` | 図は PNG，数値は CSV | +| 設定ファイル | プロジェクトルート | `pyproject.toml`，`ruff.toml` 等 | + +## テストの対応関係 (Test Mapping) + +`tests/` は `src/` のディレクトリ構造に対応させる． + +```text +src/analysis/uniformity.py → tests/analysis/test_uniformity.py +src/io/loader.py → tests/io/test_loader.py +``` 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" new file mode 100644 index 0000000..35eb0ad --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_08_\343\203\206\343\202\271\343\203\210\346\226\271\351\207\235.md" @@ -0,0 +1,47 @@ +# テスト方針 (Testing Strategy) + +## テストフレームワーク (Framework) + +- pytest を使用する（`pyproject.toml` で設定済み） + +## テストの種類 (Test Types) + +| 種類 | 対象 | 例 | +| --- | --- | --- | +| ユニットテスト | 個々の関数・モジュール | `calc_cov` が既知の配列で正しい値を返す | +| 統合テスト | パイプライン全体の連結 | 画像読み込みから CSV 出力まで通しで動く | + +## テスト対象の優先度 (Priority) + +1. **解析ロジック**（`uniformity.py`，`color.py`）— 数値の正しさが論文の信頼性に直結する +2. **入出力**（`loader.py`，`exporter.py`）— 形式変換のミスを防ぐ +3. **可視化**（`plotter.py`）— 出力ファイルが生成されることを確認する程度でよい + +## テストデータ (Test Data) + +- 小さなテスト用画像（例: 8x8 px）を `tests/fixtures/` に配置する +- 既知の値を持つ合成画像で期待値と比較する + +```python +# 例: 均一な白画像（全ピクセル 200）→ CoV = 0.0 +uniform_image = numpy.full((8, 8), 200, dtype=numpy.uint8) +assert calc_cov(uniform_image) == 0.0 +``` + +## 実行方法 (Execution) + +```bash +# 全テスト実行 +pytest + +# 特定のテストファイル +pytest tests/analysis/test_uniformity.py + +# 詳細出力 +pytest -v +``` + +## カバレッジ基準 (Coverage) + +- 解析ロジック（`src/analysis/`）: 主要関数を網羅する +- 厳密なカバレッジ率は設けない（研究用プロジェクトのため） diff --git "a/docs/01_GUIDE/GUIDE_09_\343\202\250\343\203\251\343\203\274\343\203\217\343\203\263\343\203\211\343\203\252\343\203\263\343\202\260\346\226\271\351\207\235.md" "b/docs/01_GUIDE/GUIDE_09_\343\202\250\343\203\251\343\203\274\343\203\217\343\203\263\343\203\211\343\203\252\343\203\263\343\202\260\346\226\271\351\207\235.md" new file mode 100644 index 0000000..124c58e --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_09_\343\202\250\343\203\251\343\203\274\343\203\217\343\203\263\343\203\211\343\203\252\343\203\263\343\202\260\346\226\271\351\207\235.md" @@ -0,0 +1,38 @@ +# エラーハンドリング方針 (Error Handling) + +## 基本方針 (Principle) + +- 研究用のローカル実行ツールのため，過度な防御的プログラミングは行わない +- エラーは早期に検出し，原因がわかるメッセージで失敗させる + +## エラーの分類 (Error Categories) + +| 分類 | 例 | 対処 | +| --- | --- | --- | +| 入力エラー | 画像ファイルが存在しない，形式が不正 | メッセージを出して即終了 | +| 計算エラー | ゼロ除算，配列サイズ不一致 | 原因を特定できるメッセージで例外を送出 | +| 出力エラー | 書き込み先ディレクトリが存在しない | ディレクトリを自動作成する | + +## 実装ルール (Rules) + +- 入力の検証は **システム境界**（画像読み込み時）で行う + +```python +def load_image(path: str) -> numpy.ndarray: + if not Path(path).exists(): + raise FileNotFoundError(f"画像ファイルが見つかりません: {path}") +``` + +- 内部関数間では型や値の検証を重複させない +- `print` ではなく例外で失敗を通知する +- 例外は握りつぶさない（空の `except:` 禁止） + +## ログ出力 (Logging) + +- 現時点では `print` による簡易出力で十分とする +- 処理の開始・完了を表示する程度にとどめる + +```python +print(f"解析開始: {image_path}") +print(f"結果を保存しました: {output_path}") +``` diff --git "a/docs/01_GUIDE/GUIDE_10_\343\203\252\343\203\225\343\202\241\343\202\257\343\202\277\343\203\252\343\203\263\343\202\260\346\226\271\351\207\235.md" "b/docs/01_GUIDE/GUIDE_10_\343\203\252\343\203\225\343\202\241\343\202\257\343\202\277\343\203\252\343\203\263\343\202\260\346\226\271\351\207\235.md" new file mode 100644 index 0000000..eaa15b3 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_10_\343\203\252\343\203\225\343\202\241\343\202\257\343\202\277\343\203\252\343\203\263\343\202\260\346\226\271\351\207\235.md" @@ -0,0 +1,27 @@ +# リファクタリング方針 (Refactoring Policy) + +## 判断基準 (When to Refactor) + +以下に該当する場合にリファクタリングを検討する． + +- 同じ処理が 3 箇所以上に重複している +- 1 つの関数が複数の責務を持っている +- 関数の引数が 5 つ以上になっている +- テストが書きにくい構造になっている + +## 実施タイミング (Timing) + +- 機能実装の完了後（`/implement` の Phase 3）に行う +- 機能追加とリファクタリングは同一コミットに混ぜない + +## 方針 (Approach) + +- テストが通っている状態を維持しながら変更する +- 外部から見た振る舞い（入出力）を変えない +- 変更前にテストを実行し，変更後にも同じテストが通ることを確認する + +## やらないこと (Out of Scope) + +- 動いているコードの「見た目だけ」の書き換え（Ruff が自動で対応する範囲） +- 将来の要件を見越した過度な抽象化 +- 使われていないコードの温存（不要なら削除する） diff --git "a/docs/01_GUIDE/GUIDE_11_\346\251\237\350\203\275\345\256\237\350\243\205\345\256\214\344\272\206\343\203\225\343\203\255\343\203\274.md" "b/docs/01_GUIDE/GUIDE_11_\346\251\237\350\203\275\345\256\237\350\243\205\345\256\214\344\272\206\343\203\225\343\203\255\343\203\274.md" new file mode 100644 index 0000000..75b7151 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_11_\346\251\237\350\203\275\345\256\237\350\243\205\345\256\214\344\272\206\343\203\225\343\203\255\343\203\274.md" @@ -0,0 +1,35 @@ +# 機能実装完了フロー (Implementation Completion Flow) + +## 概要 (Overview) + +機能実装からコミットまでに実施するチェックリスト．`/implement` の全フェーズ完了後に確認する． + +## チェックリスト (Checklist) + +### コード品質 + +- [ ] Ruff でフォーマット・リントを実行しエラーがないこと + +```bash +ruff check src/ tests/ +ruff format --check src/ tests/ +``` + +### テスト + +- [ ] pytest で全テストが通ること + +```bash +pytest +``` + +### ドキュメント + +- [ ] 公開関数に docstring があること +- [ ] API やデータ構造を変更した場合，`docs/` を更新したこと + +### コミット前の最終確認 + +- [ ] `git diff` で意図しない変更が含まれていないこと +- [ ] `.env` やクレデンシャルがステージングされていないこと +- [ ] コミットメッセージが GUIDE_04 の書式に従っていること