# 要件定義書 (Requirements Definition)

## 背景 (Background)

- 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. 旧 exe と同じ解析結果を保ったまま，コードを保守しやすい形に整理する（過去の研究データと比べられるようにするため）．

## 対象ユーザー (Target Users)

- 研究室で舌画像の解析を行う研究者・学生（アプリの利用者）
- DeepTIAS を今後保守・改良する開発者（引き継ぎ先を含む）

## 現行機能 (Current Features)

### 解析モード (Analysis Modes)

| モード | 入力 | 概要 |
| --- | --- | --- |
| Image（画像のみ） | `..\Input\TongueImage\` の画像 | RGB で解析する（1 枚あたり約 15〜30 秒） |
| Image&Calib（画像とカラーチャート） | 上記＋`..\Input\CalibrationColorChart\` の同名画像 | カラーチャートで色補正し，L\*a\*b\* で解析する（1 枚あたり約 5 分） |

### 処理の流れ (Pipeline)

1. 舌検出: TensorFlow モデル（`Detection_Normal.pb`）で舌の矩形を検出する
2. 舌領域抽出: ONNX モデル（`ResUNet.onnx`）でセグメンテーションし，二値化・小領域除去（`RemoveSmallRegionDLL.dll`）でマスクを作る
3. 形状特徴: 幅・高さ・面積・外接矩形を算出する
4. 領域分割: Chiu 法（3 領域），拡張 Chiu 法（4 領域），5 点法の自動版（4 領域）でマスクを分割する
5. 色・テクスチャ特徴: 領域ごとに色統計量（最小・中央値・平均・最大・分散・歪度・尖度）と GLCM 特徴量を算出する（`python\TongueFeatures.exe`）
6. 出力: `..\Output\<日時>\` に中間画像と，全画像を 1 行ずつまとめた `analysis.csv`（305 列）を書き出す
7. 色補正（Image&Calib のみ）: 解析前に `rgb2lab\TongueAnalysis.exe` でカラーチャートから L\*a\*b\* 画像を作る

## スコープ (Scope)

### やること (In Scope)

- ビルド・実行環境の整備
  - 実行に必要なバイナリ（ネイティブ DLL・外部 exe・色補正データ・出力雛形）をリポジトリに取り込み，Git LFS で管理する
  - csproj の壊れた参照（リポジトリ外パス，存在しないファイル，絶対パス）を直し，NuGet 復元だけでビルドできるようにする
  - ビルド出力フォルダに実行ファイル一式が揃うようにする
- 実行を妨げる不具合の修正
  - デバッグ用の残骸（`Cv2.ImShow` / `WaitKey` で処理が止まる，Calib モードの出力先が `Output\debug` 固定）
  - Start を 2 回押すと処理が重複して走る，例外が握りつぶされて操作不能になる
- コード整理
  - 未使用コード・ファイル（`Form1 - backups.cs`，未使用の Settings，未使用メソッド，未使用 NuGet 参照）の削除
  - 2 つの解析モードでほぼ重複している処理（約 420 行）の共通化
- 旧 exe との解析結果の一致の確認
  - 同じ入力に対する旧 exe と現行ソースの `analysis.csv` を比べ，ずれがあれば原因を調べて旧 exe に合わせる（合わせ方はユーザーと相談して決める）
  - 旧 exe の結果を正解とし，それと一致し続けることを確かめる回帰テストの整備

### やらないこと (Out of Scope)

- 新しい解析機能の追加，解析手法・パラメータの変更（旧 exe の結果に合わせるための修正を除く）
- モデルの再学習・差し替え
- ソースの無い外部バイナリ（`TongueFeatures.exe`，`TongueAnalysis.exe`，`TongueAnalysisDLL.dll`，`RemoveSmallRegionDLL.dll`）の作り直し
- `ColorSubdivision`（ソリューション外の試作プロジェクト）の保守

## 非機能要件 (Non-functional Requirements)

- 動作環境: Windows 10 / 11（x64），.NET Framework 4.8，メモリ 8 GB 以上
- 互換性: 同じ入力に対する `analysis.csv` の列構成と値が，旧 exe の結果と一致すること（数値は許容誤差の範囲で．許容誤差は旧 exe との比較結果をもとに決める）
- 性能: 1 枚あたりの処理時間を現状より悪化させないこと

## 制約・リスク (Constraints & Risks)

- 外部バイナリにはソースが無く，不具合があっても修正できない．
- `rgb2lab\TongueAnalysis.exe` と `TongueAnalysisDLL.dll` はデバッグビルドで，VC++ のデバッグ用ランタイム（`ucrtbased.dll` 等）が入った PC でしか動かない．デバッグ用ランタイムは再配布できないため，Image&Calib モードを使う PC ごとに Build Tools の「C++ ビルド ツール」等を入れる必要がある（[ENV_02](../02_ENV/ENV_02_環境構築手順.md) 手順 1）．
- 入出力のパスが作業ディレクトリ基準（`..\Input`，`..\Output`）で固定されている．
- 解析の正しさを確かめる基準は，旧 exe での実行結果しか無い．
- 旧 exe と現行ソースは OpenCV のバージョンが異なる（3.2 と 4.9）ため，解析結果がずれている可能性がある．ずれの大きさと原因は比べてみるまで分からない．

## 未決事項 (Open Questions)

- .NET Framework 4.8 から新しい .NET への移行を将来の対象にするか