diff --git a/.claude/rules/testing.md b/.claude/rules/testing.md index 75cd5e4..c71675a 100644 --- a/.claude/rules/testing.md +++ b/.claude/rules/testing.md @@ -10,16 +10,18 @@ | 種類 | 目的 | 対象 | | --- | --- | --- | -| 回帰テスト | コード整理の前後で解析結果が変わらないことを確かめる | サンプル画像を解析した `analysis.csv` と，旧ビルドで出した正解の比較 | +| 回帰テスト | 研究で使われてきた旧 exe と同じ解析結果が出ることを確かめる | サンプル画像を現行ソースで解析した `analysis.csv` と，旧 exe（2021 年 12 月版 `DeepTIAS2.7.exe`）で出した正解の比較 | | 単体テスト | 切り出した処理が単体で正しく動くことを確かめる | 領域分割，形状特徴，CSV の組み立て等，画面に依存しない処理 | - **回帰テストを最優先する．**本プロジェクトの目的は「解析結果を変えずに整理する」ことであり，その保証の中心になる． +- **正解は旧 exe の出力である．**研究データは旧 exe で出されており，過去のデータと比べられることを守るため．現行ソースの出力を正解にしない． - 画面（`Form1`）の操作は自動テストの対象にしない．人が動作確認する． ## 回帰テストの決まり (Regression Tests) -- 正解データ（入力画像と，旧ビルドで出した `analysis.csv`・中間画像）は `DeepTIAS.Tests/TestData/` に置き，Git LFS で管理する． -- 比較は `analysis.csv` の列構成（見出し行）と値で行う．小数の値は，浮動小数点の誤差を考えて許容誤差を決めて比べる（許容誤差は正解データ作成時に決め，テストコードに理由を書く）． +- 正解データ（入力画像と，旧 exe で出した `analysis.csv`・中間画像）は `DeepTIAS.Tests/TestData/` に置き，Git LFS で管理する．どの exe（パス・ビルド日）でいつ出したかを `TestData/README.md` に記録する． +- 比較は `analysis.csv` の列構成（見出し行）と値で行う．小数の値は許容誤差を決めて比べる．許容誤差は旧 exe と現行ソースの比較結果（[開発ステップ](../../docs/03_PLAN/PLAN_02_開発ステップ.md) のステップ 3）をもとに決め，値と理由をテストコードに書く． +- 列ごとに許容誤差を変える場合（例: OpenCV のバージョン差で特定の列だけずれる）は，ユーザーの承認を得てから設定し，対象の列と理由を記録する． - 正解データを作り直すのは，解析結果を変える変更をユーザーが承認したときだけとする．テストを通すために正解データを書き換えてはならない． - 外部 exe・モデルを使うため時間がかかる．テスト名やカテゴリで単体テストと区別し，単体テストだけを素早く回せるようにする． diff --git a/CLAUDE.md b/CLAUDE.md index 5e29b6e..90e87ea 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,7 +11,7 @@ ### DeepTIAS 固有 -- **解析結果（`analysis.csv` の列構成と値）を変えない**．コード整理の合格基準であり，変える必要がある場合は必ずユーザーの承認を得る（[PLAN_01](docs/03_PLAN/PLAN_01_要件定義書.md)・[SPEC_02](docs/04_SPEC/SPEC_02_解析処理仕様.md)） +- **解析結果（`analysis.csv` の列構成と値）を旧 exe（研究で使われてきた 2021 年 12 月版）と一致させ，変えない**．コード整理の合格基準であり，変える必要がある場合は必ずユーザーの承認を得る（[PLAN_01](docs/03_PLAN/PLAN_01_要件定義書.md)・[SPEC_02](docs/04_SPEC/SPEC_02_解析処理仕様.md)） - 回帰テストの正解データを，テストを通すために書き換えない（`.claude/rules/testing.md`） - ソースの無い外部バイナリ（`TongueFeatures.exe`・`TongueAnalysis.exe`・ネイティブ DLL）は作り直さずに使う - モデル・exe・DLL などの大きなバイナリは Git LFS で管理する（新しい拡張子は先に `git lfs track`） diff --git "a/docs/03_PLAN/PLAN_01_\350\246\201\344\273\266\345\256\232\347\276\251\346\233\270.md" "b/docs/03_PLAN/PLAN_01_\350\246\201\344\273\266\345\256\232\347\276\251\346\233\270.md" index cda1124..35c4026 100644 --- "a/docs/03_PLAN/PLAN_01_\350\246\201\344\273\266\345\256\232\347\276\251\346\233\270.md" +++ "b/docs/03_PLAN/PLAN_01_\350\246\201\344\273\266\345\256\232\347\276\251\346\233\270.md" @@ -5,11 +5,12 @@ - DeepTIAS は，TIAS（舌画像撮影システム）で撮影した舌画像を一括解析し，舌の形状・色・テクスチャの特徴量を CSV に出力する Windows デスクトップアプリである． - 前任者が開発した v2.7（C# WinForms，2021 年 12 月版）を引き継いだ．ソースコードは本リポジトリに，実行に必要なバイナリ一式は旧ビルド出力フォルダ（`DeepTIAS2.7.1-Latest`）にのみ存在する． - 現状，リポジトリ単体ではビルド・実行できない（NuGet パッケージ未復元，ネイティブ DLL・外部 exe・雛形フォルダの欠落，csproj のリポジトリ外参照）．また配布済み exe は現行ソースと一致しない（旧ソースは OpenCvSharp3 / .NET 4.7.1，現行ソースは OpenCvSharp4 / .NET 4.8）． +- 研究で使われてきた解析結果は，この配布済み exe（2021 年 12 月版 `DeepTIAS2.7.exe`．以下「旧 exe」）で出したものである． ## 目的 (Goals) 1. リポジトリを clone して手順どおりに進めれば，誰でもビルド・実行できる状態にする． -2. 解析結果を変えずに，コードを保守しやすい形に整理する． +2. 旧 exe と同じ解析結果を保ったまま，コードを保守しやすい形に整理する（過去の研究データと比べられるようにするため）． ## 対象ユーザー (Target Users) @@ -49,11 +50,13 @@ - コード整理 - 未使用コード・ファイル（`Form1 - backups.cs`，未使用の Settings，未使用メソッド，未使用 NuGet 参照）の削除 - 2 つの解析モードでほぼ重複している処理（約 420 行）の共通化 - - 解析結果（`analysis.csv`）が整理前後で変わらないことを確かめるテストの整備 +- 旧 exe との解析結果の一致の確認 + - 同じ入力に対する旧 exe と現行ソースの `analysis.csv` を比べ，ずれがあれば原因を調べて旧 exe に合わせる（合わせ方はユーザーと相談して決める） + - 旧 exe の結果を正解とし，それと一致し続けることを確かめる回帰テストの整備 ### やらないこと (Out of Scope) -- 新しい解析機能の追加，解析手法・パラメータの変更 +- 新しい解析機能の追加，解析手法・パラメータの変更（旧 exe の結果に合わせるための修正を除く） - モデルの再学習・差し替え - ソースの無い外部バイナリ（`TongueFeatures.exe`，`TongueAnalysis.exe`，`TongueAnalysisDLL.dll`，`RemoveSmallRegionDLL.dll`）の作り直し - `ColorSubdivision`（ソリューション外の試作プロジェクト）の保守 @@ -61,7 +64,7 @@ ## 非機能要件 (Non-functional Requirements) - 動作環境: Windows 10 / 11（x64），.NET Framework 4.8，メモリ 8 GB 以上 -- 互換性: 整理の前後で，同じ入力に対する `analysis.csv` の列構成と値が一致すること +- 互換性: 同じ入力に対する `analysis.csv` の列構成と値が，旧 exe の結果と一致すること（数値は許容誤差の範囲で．許容誤差は旧 exe との比較結果をもとに決める） - 性能: 1 枚あたりの処理時間を現状より悪化させないこと ## 制約・リスク (Constraints & Risks) @@ -69,7 +72,8 @@ - 外部バイナリにはソースが無く，不具合があっても修正できない． - `rgb2lab\TongueAnalysis.exe` と `TongueAnalysisDLL.dll` はデバッグビルドで，Visual Studio のデバッグ用ランタイム（`ucrtbased.dll` 等）が入った PC でしか動かない可能性がある． - 入出力のパスが作業ディレクトリ基準（`..\Input`，`..\Output`）で固定されている． -- 解析の正しさを確かめる基準は，旧ビルドでの実行結果しか無い． +- 解析の正しさを確かめる基準は，旧 exe での実行結果しか無い． +- 旧 exe と現行ソースは OpenCV のバージョンが異なる（3.2 と 4.9）ため，解析結果がずれている可能性がある．ずれの大きさと原因は比べてみるまで分からない． ## 未決事項 (Open Questions) diff --git "a/docs/03_PLAN/PLAN_02_\351\226\213\347\231\272\343\202\271\343\203\206\343\203\203\343\203\227.md" "b/docs/03_PLAN/PLAN_02_\351\226\213\347\231\272\343\202\271\343\203\206\343\203\203\343\203\227.md" index fe0be73..b7dbc17 100644 --- "a/docs/03_PLAN/PLAN_02_\351\226\213\347\231\272\343\202\271\343\203\206\343\203\203\343\203\227.md" +++ "b/docs/03_PLAN/PLAN_02_\351\226\213\347\231\272\343\202\271\343\203\206\343\203\203\343\203\227.md" @@ -4,7 +4,8 @@ ## 進め方の方針 (Approach) -- **先に「結果が変わらないこと」を確かめる手段を作り，それからコードを整理する．**回帰テスト（ステップ 3）より前には，解析結果に影響しない変更だけを行う． +- **研究で使われてきた旧 exe（2021 年 12 月版）の解析結果を正解とする．**過去の研究データと比べられることを最優先にするため． +- **先に「旧 exe と同じ結果が出る」ことを確かめ，それからコードを整理する．**回帰テスト（ステップ 4）より前には，解析結果に影響しない変更だけを行う．ただしステップ 3 で旧 exe とのずれが見つかった場合は，ずれを直す変更をユーザーの承認のもとで行う． - 各ステップは `/implement` で進め，ステップごとに作業ブランチを切って `main` に取り込む． ## ステップ一覧 (Steps) @@ -13,10 +14,11 @@ | --- | --- | --- | --- | | 1 | 実行に必要なファイルの取り込み | ビルドだけで実行ファイル一式が揃うようにする | なし | | 2 | 実行を妨げる不具合の修正 | 解析を最後まで安定して回せるようにする | なし | -| 3 | テストプロジェクトと回帰テストの作成 | 整理の前後で結果が変わらないことを確かめる手段を作る | なし | -| 4 | 未使用コード・参照の削除 | 読む量を減らし，不要な依存（脆弱性のある Newtonsoft.Json 等）をなくす | なし（回帰テストで確認） | -| 5 | 解析処理の切り出しと重複の統合 | 画面から解析処理を分け，2 モードの重複（約 420 行）をなくす | なし（回帰テストで確認） | -| 6 | エラー処理とログの整備 | 失敗の原因が分かるようにする | なし（回帰テストで確認） | +| 3 | 旧 exe と現行ソースの解析結果の比較 | 現行ソースが研究データと同じ結果を出すかを確かめる | ずれがあれば旧 exe に合わせる（ユーザー承認のもと） | +| 4 | テストプロジェクトと回帰テストの作成 | 旧 exe と同じ結果であり続けることを確かめる手段を作る | なし | +| 5 | 未使用コード・参照の削除 | 読む量を減らし，不要な依存（脆弱性のある Newtonsoft.Json 等）をなくす | なし（回帰テストで確認） | +| 6 | 解析処理の切り出しと重複の統合 | 画面から解析処理を分け，2 モードの重複（約 420 行）をなくす | なし（回帰テストで確認） | +| 7 | エラー処理とログの整備 | 失敗の原因が分かるようにする | なし（回帰テストで確認） | ## 各ステップの内容 (Step Details) @@ -39,29 +41,39 @@ - Image&Calib の出力先が `Output\debug` に固定されている件は，ユーザーの判断を得てから直す（[要件定義書](PLAN_01_要件定義書.md) の未決事項） - 完了条件: 複数枚の画像を両モードで続けて解析でき，途中で止まらない -### 3. テストプロジェクトと回帰テストの作成 +### 3. 旧 exe と現行ソースの解析結果の比較 + +配布済みの旧 exe は現行ソースからビルドしたものではない（旧 exe は OpenCvSharp3 / OpenCV 3.2，現行ソースは OpenCvSharp4 / OpenCV 4.9）．二値化・輪郭検出・縮小などは OpenCV のバージョンで結果が変わりうるため，整理を始める前に一致するかを確かめる． + +- 同じ入力画像（Image・Image&Calib の両モード）を旧 exe と現行ソースの両方で解析し，`analysis.csv` を列ごとに比べる +- 一致しない場合は，どの工程（検出・抽出・領域分割・特徴量）でずれるかを中間画像で突き止め，原因を調べる +- ずれを直す方針（OpenCV のバージョンを合わせる，処理を旧版に合わせる等）はユーザーと相談して決める．解析結果を変える変更のため，承認なしに行わない +- 比較の結果（一致した列・ずれた列とその大きさ・原因）を記録に残す +- 完了条件: 現行ソースの結果が旧 exe の結果と許容誤差の範囲で一致する．または，残るずれをユーザーが確認し，許容すると判断している + +### 4. テストプロジェクトと回帰テストの作成 - MSTest のテストプロジェクト `DeepTIAS.Tests` をソリューションに追加する -- サンプル画像で正解データ（`analysis.csv` と中間画像）を作り，`DeepTIAS.Tests/TestData/` に置く -- 解析を実行して正解データと比べる回帰テストを作る（両モード） +- 旧 exe でサンプル画像を解析した結果（`analysis.csv` と中間画像）を正解データとし，`DeepTIAS.Tests/TestData/` に置く +- 現行ソースで解析して正解データと比べる回帰テストを作る（両モード）．許容誤差はステップ 3 の比較結果をもとに決める - 開発コマンド（[ENV_04](../02_ENV/ENV_04_開発コマンド.md)）にテストの実行コマンドを追記する - 完了条件: 回帰テストが通り，わざと解析結果を変えると失敗する -### 4. 未使用コード・参照の削除 +### 5. 未使用コード・参照の削除 - 使われていないファイル（`Form1 - backups.cs`，`Settings.Designer.cs`・`Settings1.Designer.cs`）を削除する - 使われていないメソッド・フィールド・`DllImport` 宣言・`using` を削除する - 使われていない NuGet 参照（Microsoft.ML 一式，Newtonsoft.Json，OpenCvSharp.WpfExtensions 等）と，リポジトリ外を指す参照（OpenCvSharp.Blob，v4.7.1 の絶対パス）を削除する - 使われていないモデル `models/ResUnet_0.9518.pb` の扱いを決める（削除するか，別の場所に保管するか） -### 5. 解析処理の切り出しと重複の統合 +### 6. 解析処理の切り出しと重複の統合 - `Form1.cs` の解析処理を，画面に依存しないクラスに切り出す（置き場所は `.claude/rules/project-structure.md`） - Image と Image&Calib でほぼ同じ処理を 1 つにまとめ，違い（色補正の有無，雛形，チャネル）だけを分ける - 解析結果に影響する数値を名前付きの定数にまとめる - 切り出した処理に単体テストを追加する -### 6. エラー処理とログの整備 +### 7. エラー処理とログの整備 - `.claude/rules/error-handling.md` に沿って，握りつぶしている例外をなくし，失敗の原因をダイアログとログで伝える - 外部 exe の終了コードと出力ファイルを確認する @@ -71,13 +83,6 @@ 要件定義書の「やらないこと」のとおり，新機能の追加，解析手法の変更，モデルの差し替え，外部バイナリの作り直しは本計画に含めない． -## 未決事項 (Open Questions) +## 前提 (Assumptions) -- 回帰テストの正解データを何で作るか（下記） - -### 正解データの作り方 - -配布済みの旧 exe（2021 年版）は現行ソースからビルドしたものではない（OpenCvSharp3 / .NET 4.7.1 時点のソース）．そのため，旧 exe と現行ソースの解析結果が一致するとは限らない． - -- **案 A（推奨）**: ステップ 2 完了時点の現行ソースで解析した結果を正解データにする．旧 exe の結果とも比べ，差があれば記録しておく（差の原因調査は本計画の対象外） -- **案 B**: 旧 exe の結果を正解データにする．現行ソースの結果と差がある場合，整理を始める前に差の原因を調べる必要がある +- 研究で使われてきた解析結果は，旧ビルド出力（`DeepTIAS2.7.1-Latest`）にある 2021 年 12 月版の `DeepTIAS2.7.exe` で出したものとする．これより古い版で出したデータが混ざっている場合は，比べる相手を決め直す diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md index b78379a..da0d0b1 100644 --- a/docs/PROGRESS.md +++ b/docs/PROGRESS.md @@ -15,3 +15,6 @@ - 設計判断: 目的を「誰でもビルド・実行できる」「解析結果を変えずに整理」の 2 つに絞り，回帰テストを作ってから整理する順序にした．.NET への移行は TensorFlowSharp の作り直しが要るため対象外． - 環境: 存在しない `OpenCvSharpExtern.dll` の参照を削除してビルドが通ることを確認済み（NuGet の runtime パッケージが同 DLL を配置する）．実行は外部バイナリ取り込み後に確認する． - 未実装・後段: PLAN_02 ステップ 1 から．未決事項は Image&Calib の出力先固定（`Output\debug`）と回帰テストの正解データの作り方． + +- [x] **回帰テストの正解を旧 exe の出力に決定**: 研究で使われてきた解析結果が旧 exe（2021 年 12 月版）の出力と判明したため，正解を旧 exe の出力とし，PLAN_02 にステップ 3「旧 exe と現行ソースの解析結果の比較」を追加した． + - 設計判断: 当初は「現行ソースの結果を正解（案 A）」としていたが，それでは現行ソースと旧 exe のずれ（OpenCV 3.2 → 4.9）を正解として固めてしまい，過去の研究データと比べられなくなるため不採用とした．