diff --git "a/docs/04_SPEC/SPEC_01_\347\224\273\351\235\242\344\273\225\346\247\230.md" "b/docs/04_SPEC/SPEC_01_\347\224\273\351\235\242\344\273\225\346\247\230.md" new file mode 100644 index 0000000..78e8ff8 --- /dev/null +++ "b/docs/04_SPEC/SPEC_01_\347\224\273\351\235\242\344\273\225\346\247\230.md" @@ -0,0 +1,66 @@ +# 画面仕様 (Screen Specification) + +DeepTIAS の画面構成と操作を定める．本書は v2.7 時点の動作を記録したものであり，[要件定義書](../03_PLAN/PLAN_01_要件定義書.md) で修正対象とした不具合は「既知の不具合」として区別して記す． + +## 画面構成 (Layout) + +画面は 1 つ（`Form1`，タイトル「DeepTIAS2.7」）．処理の途中経過を画像で表示するパネルと，操作・状態表示の領域からなる． + +### 操作部 (Controls) + +| 部品 | 表示 | 役割 | +| --- | --- | --- | +| モード選択 | `Image(画像のみ)` / `Image&Calib(画像とカラーチャート)` | 解析モードを選ぶ．既定は `Image(画像のみ)` | +| Start ボタン | `Start` | 解析を開始する | +| Pause ボタン | `Pause` / `Continue` | 解析を一時停止・再開する．解析中のみ押せる | + +### 画像表示パネル (Image Panels) + +各パネルの見出しラベルは，その処理を実行している間だけ背景が赤になり，進行中の工程を示す． + +| 見出し | 表示する画像 | +| --- | --- | +| Input | 入力した舌画像 | +| Calibration | 色補正後の画像（Image&Calib のみ） | +| Detection | 検出した舌の矩形を描いた画像 | +| Segmentation | セグメンテーション結果（二値画像） | +| Mask | 元画像サイズに戻したマスク | +| Extraction | マスクで切り出した舌 | +| view | 領域分割の結果 | +| view2 | 未使用（常に空） | + +### 状態表示 (Status) + +| 表示 | 内容 | +| --- | --- | +| 状態 | 実行中の工程（日本語） | +| Processing File | 処理中のファイル名．待機中は `None` | +| Total Progress | 処理済み枚数 / 全枚数（例: `Total Progress: 3/10`） | + +## 操作の流れ (Operation Flow) + +1. 入力画像を所定のフォルダに置く（[入出力仕様](SPEC_03_入出力仕様.md)） +2. モードを選ぶ +3. Start を押す．Start とモード選択が押せなくなり，Pause が押せるようになる +4. 画像を 1 枚ずつ解析し，各パネルと状態表示が更新される +5. Pause を押すと，処理中の画像を終えた時点で停止する．ボタンが `Continue` に変わり，押すと再開する +6. 全画像を処理すると「Finished!」のメッセージが出る．Start が再び押せるようになり，Pause は押せなくなる + +## エラー時の表示 (Error Display) + +| 状況 | 表示・動作 | +| --- | --- | +| 舌を検出できない | 表示なし．`analysis.csv` に `<画像名>,Tongue detection error` を書き，次の画像へ進む | +| 舌領域が 1 つにまとまらない | 表示なし．`analysis.csv` に `<画像名>,Tongue segmentation error` を書き，次の画像へ進む | +| 小領域除去 DLL を呼べない | エラーダイアログ（`Unable to reprocess! ...`）を出し，残りの画像を処理せずに終了する | +| 上記以外の例外 | 表示されない（既知の不具合を参照） | + +## 既知の不具合 (Known Issues) + +[要件定義書](../03_PLAN/PLAN_01_要件定義書.md) の「実行を妨げる不具合の修正」で直す対象． + +- 舌領域が 1 つにまとまらない画像で，二値画像のウィンドウ（`dst2`）が開き，キーを押すまで解析が止まる +- 2 回目以降に Start を押すと，押した回数だけ解析が重複して実行される +- モード選択は一度 Start を押すと押せないままになる（モードを変えるにはアプリの再起動が必要） +- 解析中に想定外の例外が起きると，何も表示されずに止まり，Start も押せないままになる +- Pause の停止は画像 1 枚ごとにしか効かない（1 枚の処理中は止まらない） diff --git "a/docs/04_SPEC/SPEC_02_\350\247\243\346\236\220\345\207\246\347\220\206\344\273\225\346\247\230.md" "b/docs/04_SPEC/SPEC_02_\350\247\243\346\236\220\345\207\246\347\220\206\344\273\225\346\247\230.md" new file mode 100644 index 0000000..2efe236 --- /dev/null +++ "b/docs/04_SPEC/SPEC_02_\350\247\243\346\236\220\345\207\246\347\220\206\344\273\225\346\247\230.md" @@ -0,0 +1,91 @@ +# 解析処理仕様 (Analysis Pipeline Specification) + +1 枚の舌画像から特徴量を得るまでの処理を定める．本書は v2.7 時点の動作を記録したものであり，コード整理ではここに書いた処理結果を変えないことを合格基準とする（[要件定義書](../03_PLAN/PLAN_01_要件定義書.md) の非機能要件）． + +## 全体の流れ (Overview) + +```text +入力画像 + │ （Image&Calib のみ）色補正 → L*a*b* 画像 + ▼ +1. 舌検出 ──────────── 失敗 → "Tongue detection error" + ▼ +2. 舌領域抽出（セグメンテーション → 二値化 → 必要なら小領域除去） + │ 失敗 → "Tongue segmentation error" + ▼ +3. マスク作成・舌の切り出し + ▼ +4. 形状特徴の算出 + ▼ +5. 領域分割（Chiu 法・拡張 Chiu 法・5 点法） + ▼ +6. 領域ごとの色・テクスチャ特徴の算出 + ▼ +7. analysis.csv に 1 行追記 +``` + +## 色補正 (Color Calibration) + +Image&Calib モードのみ．舌画像と，同名のカラーチャート画像を使う． + +- `rgb2lab\TongueAnalysis.exe <舌画像> <カラーチャート画像> <出力CSV>` を実行し，画素ごとの L\*a\*b\* 値を CSV に得る +- CSV から L\*a\*b\* 画像を作り，BGR に変換して表示・後続処理に使う +- 以降の舌検出・舌領域抽出はこの補正後の画像で行う．舌の切り出しは元の画像で行う +- 色特徴（手順 6）は L\*a\*b\* の値で算出する + +## 1. 舌検出 (Tongue Detection) + +| 項目 | 内容 | +| --- | --- | +| モデル | `models/Detection_Normal.pb`（TensorFlow Object Detection API） | +| 前処理 | 画像を JPEG にエンコード → 256×256 に縮小 | +| 採用する矩形 | スコアが 0.5 を超える検出のうち，最もスコアが高いもの | +| 出力 | 元画像の座標系に戻した舌の矩形 | +| 失敗条件 | 該当する検出が無い，または例外が起きた | + +## 2. 舌領域抽出 (Tongue Segmentation) + +1. 検出した矩形で画像を切り出し，256×256 に縮小する +2. `models/ResUNet.onnx` で推論する（入力は BGR を 255 で割った値，出力は 2 チャネルのうち 1 チャネル目にシグモイドをかけたもの） +3. 推論結果を大津の二値化で二値画像にする +4. 二値画像の輪郭を数える（Canny でエッジを出してから輪郭を抽出）．輪郭が 0 個，または 3 個以上なら小領域除去を行う + - `RemoveSmallRegionDLL.dll` で面積 500 画素未満の領域を除去する（2 回実行．設定が異なる） + - 除去後も輪郭が 0 個，または 3 個以上なら失敗とする + +## 3. マスク作成・舌の切り出し (Mask & Extraction) + +- 二値画像を検出矩形の大きさに戻し，元画像と同じ大きさのマスクに貼り付ける +- マスクで元画像から舌を切り出す + +## 4. 形状特徴 (Shape Features) + +| 特徴量 | 内容 | +| --- | --- | +| width / height | 検出した矩形の幅・高さ | +| area | マスクの画素数（舌の面積） | +| topLeftX / topLeftY / bottomRightX / bottomRightY | 検出した矩形の左上・右下の座標 | + +## 5. 領域分割 (Region Division) + +マスクを舌の部位ごとに分ける．3 つの方法すべてを実行する． + +| 方法 | 名前 | 領域 | 概要 | +| --- | --- | --- | --- | +| Chiu 法 | `chiu` | lateral（舌辺），middle（舌中），tip（舌尖） | 舌尖は下から高さ 20%，舌辺は左右それぞれ幅 20% | +| 拡張 Chiu 法 | `exChiu` | 上記＋root（舌根） | Chiu 法に，上から高さ 20% の舌根を加える | +| 5 点法（自動版） | `fiveClick` | lateral，root，middle，tip | 舌の輪郭と重心から 5 点法の基準点を自動で求め，そこから得た 8 点で分ける | + +- ※ 5 点法は本来，人が画像上で 5 点をクリックする手法（海沼 2015，石川 2010）．本アプリではクリックせず自動で点を求める． + +## 6. 色・テクスチャ特徴 (Color & Texture Features) + +`python\TongueFeatures.exe <画像> <領域マスク> <色統計CSV> ` を領域分割の方法ごとに実行する． + +| 種類 | 特徴量 | 対象 | +| --- | --- | --- | +| 色統計量 | min，median，mean，max，variance，skewness，kurtosis | 領域 × チャネル（Image: B・G・R，Image&Calib: L・a・b） | +| GLCM（テクスチャ） | contrast，dissimilarity，homogeneity，ASM，energy，correlation | 領域ごと | + +## 7. 結果の集約 (Aggregation) + +画像 1 枚につき `analysis.csv` に 1 行を追記する．列の並びは [入出力仕様](SPEC_03_入出力仕様.md) を参照． diff --git "a/docs/04_SPEC/SPEC_03_\345\205\245\345\207\272\345\212\233\344\273\225\346\247\230.md" "b/docs/04_SPEC/SPEC_03_\345\205\245\345\207\272\345\212\233\344\273\225\346\247\230.md" new file mode 100644 index 0000000..2499d11 --- /dev/null +++ "b/docs/04_SPEC/SPEC_03_\345\205\245\345\207\272\345\212\233\344\273\225\346\247\230.md" @@ -0,0 +1,84 @@ +# 入出力仕様 (Input/Output Specification) + +DeepTIAS が読み込むファイルと書き出すファイルの場所・形式を定める．本書は v2.7 時点の動作を記録したものである． + +## フォルダの基準 (Base Directory) + +入出力のパスは，アプリの作業ディレクトリ（通常は `DeepTIAS2.7.exe` のあるフォルダ）を基準にした相対パスで決まっている． + +```text +（作業ディレクトリの 1 つ上） +├── Input\ +│ ├── TongueImage\ # 舌画像 +│ └── CalibrationColorChart\ # カラーチャート画像（Image&Calib のみ） +├── Output\ +│ └── \ # 実行ごとの出力フォルダ +└── （作業ディレクトリ）\ + ├── DeepTIAS2.7.exe + ├── models\ # 学習済みモデル + ├── python\ # TongueFeatures.exe + ├── rgb2lab\ # TongueAnalysis.exe と色補正データ + ├── template_outputDir\ # 出力フォルダの雛形（Image） + └── template_outputDir_withCalib\ # 出力フォルダの雛形（Image&Calib） +``` + +## 入力 (Input) + +| モード | フォルダ | 内容 | +| --- | --- | --- | +| 共通 | `..\Input\TongueImage\` | 舌画像．フォルダ内のファイルをすべて処理対象にする（実運用では `.bmp`） | +| Image&Calib | `..\Input\CalibrationColorChart\` | カラーチャート画像．舌画像と拡張子を除いたファイル名が同じものを対応させる | + +- ※ Image&Calib で対応するカラーチャート画像が無いと，解析が止まる（[画面仕様](SPEC_01_画面仕様.md) の既知の不具合）． + +## 出力フォルダ (Output Folder) + +実行ごとに `..\Output\\` を作り，雛形フォルダ（`template_outputDir` など）の中身をコピーしてから結果を書き込む． + +- ※ 日時の時は 12 時間表記（`hh`）のため，午前と午後で同じ名前になりうる． +- ※ Image&Calib では，現行ソースは出力先を `..\Output\debug\` に固定している（[要件定義書](../03_PLAN/PLAN_01_要件定義書.md) の未決事項）． + +```text +\ +├── analysis.csv # 全画像の特徴量（1 画像 1 行） +├── 1-detection\ +│ ├── 1-drawBox\ # 検出した矩形を描いた画像 +│ ├── 2-cropped\ # 矩形で切り出した画像 +│ └── 3-resized\ # 256×256 に縮小した画像 +├── 2-segmentation\ +│ ├── 1-modelOutput\ # モデルの出力 +│ ├── 2-binOutput\ # 二値化した画像 +│ ├── 2-binOutput(refined)\ # 小領域除去後の画像（必要な場合のみ） +│ ├── 3-resized\ # 検出矩形の大きさに戻した画像 +│ ├── 4-mask\ # 元画像サイズのマスク +│ └── 5-extraction\ # 切り出した舌 +├── 3-imgProc\ +│ ├── cvtColor\ # Image&Calib のみ +│ │ ├── LabCsv\ # 画素ごとの L*a*b* 値 +│ │ └── LabImg\ # L*a*b* から作った画像 +│ └── devideRegion\ +│ ├── chiu\ # 領域分割の結果（方法ごと） +│ ├── exChiu\ +│ └── fiveClick\ +└── 4-featureExtraction\ + ├── shape\ # 形状特徴（画像ごとの CSV） + └── region\ + └── \ + ├── colorStats\ # 色統計量（画像ごとの CSV） + └── GLCM\ # GLCM 特徴量（画像ごとの CSV） +``` + +## analysis.csv + +1 行目は雛形に書かれた見出し行．2 行目以降に画像 1 枚につき 1 行を追記する．列は全 305 列． + +| 順 | 列 | 列数 | 列名の形式 | +| --- | --- | --- | --- | +| 1 | 画像名 | 1 | `name` | +| 2 | 形状特徴 | 7 | `shape-<特徴量>`（width，height，area，topLeftX，topLeftY，bottomRightX，bottomRightY） | +| 3 | GLCM 特徴量 | 66 | `<方法>-<領域>-<特徴量>`．方法は chiu（3 領域）→ exChiu（4 領域）→ fiveClick（4 領域）の順，特徴量は 6 種 | +| 4 | 色統計量 | 231 | `<方法>-<領域>-<チャネル>-<統計量>`．方法・領域の順は GLCM と同じ，チャネルは 3 種，統計量は 7 種 | + +- チャネルは Image では `B`・`G`・`R`，Image&Calib では `L`・`a`・`b`．それ以外の列構成は両モードで同じ +- 失敗した画像は `<画像名>,Tongue detection error` または `<画像名>,Tongue segmentation error` の 2 列だけの行になる +- 従来の 5 点法による L\*a\*b\* 値に相当するのは `fiveClick-<領域>--mean` の列