# 要件定義書 (Requirements)

## プロジェクトの目的 (Purpose)

舌診支援システム [TIASjudge](https://github.com/rintoHasegawa/TIASjudge) の舌色 5 分類（紫・暗赤・紅・淡紅・淡白）を，機械学習で推定できるかを検証する．現行の TIASjudge は Lab 色空間のルールベースで分類しており，本プロジェクトでは機械学習版の到達点を把握して，将来 TIASjudge に組み込む判断材料を得る．

本フェーズのゴールは**現状把握**である．「このデータで機械学習がどこまでできるか」を，信頼できる評価基盤の上で数値として示すことを目的とし，精度の絶対値目標は置かない．

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

- **直接**: 開発者本人（研究用途）
- **間接**: TIASjudge を使う臨床側（将来，モデルが組み込まれた場合）

## スコープ (Scope)

### やること (In Scope)

- 舌領域セグメンテーション済み画像から舌色 5 分類を推定するモデルの学習・評価
- 研究室の計算サーバでの学習基盤（コード転送・リモート実行・結果回収）
- **手元 PC に臨床データを置かずに開発できる仕組み**（合成データでの実装確認，リモート側での集計）
- 既存ルールベース（TIASjudge）との同一テストセットでの比較
- 実験記録と評価レポート

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

- 舌領域セグメンテーションモデルの学習（既にセグメンテーション済みのデータを使う）
- 舌色 5 分類以外の所見（舌苔・舌形・歯痕等）
- TIASjudge 本体への組み込み実装（別リポジトリの作業）
- 撮影条件の色補正・キャリブレーション（SmTIAS 側の課題）
- 臨床データを手元 PC に配置すること

## データ (Data)

| 項目 | 内容 |
| --- | --- |
| 入力 | 舌領域のみをセグメンテーションした舌画像 |
| 規模 | 1000 枚以上（正確な枚数・患者数・クラス分布は研究室 PC で確認して確定する） |
| 正解ラベル | 医師・専門家の診断記録による舌色 5 分類 |
| 保管場所 | 原本は研究室 PC．一度だけ計算サーバへコピーし，以降は再転送しない |
| 手元 PC | 一切置かない |

## 制約 (Constraints)

- **データ取り扱い**: 臨床データを手元 PC に置かない．リポジトリにも含めない．手元へ持ち帰るのは非個人情報の派生物のみ（集計指標・学習曲線・混同行列・ログ・モデル重み）
- **計算資源**: 研究室の GPU サーバ（共用．他ユーザーが GPU を使っていることがある）
- **接続経路**: 学外からは研究室 PC を SSH の踏み台（ProxyJump）として経由する
- **認証情報**: 計算サーバに GitHub の認証情報は置かない（コードは常に手元から送る）
- **人間の作業**: 倫理審査・データ利用許諾の確認，研究室 PC での SSH サーバ運用の可否確認

## 成功基準 (Success Criteria)

本フェーズは現状把握のため，以下を満たせば成功とする．

1. 患者単位の分割で，再現可能な評価基盤ができている
2. 同一テストセットで，既存ルールベースと機械学習モデルの性能を並べて比較できる
3. 機械学習モデルの到達点がクラス別の数値（混同行列・クラス別性能）で示され，次の判断（組み込むか・手法を変えるか）ができる
4. 手元に臨床データを置かないまま実験を回せ，その手順が文書化されている

※ 精度の絶対値目標は本フェーズでは設定しない．ベースライン確立後に別途決める．

## 評価の方針 (Evaluation Policy)

- **患者単位で分割する**．画像単位のランダム分割は行わない（同一患者の画像が train / test に跨ると精度が過大に出る）
- クラス不均衡が想定されるため，accuracy だけで判断せず macro F1・混同行列・クラス別 recall を併せて見る
- 医師ラベルの評価者間のばらつきが性能の上限を決めるため，把握できる範囲で確認する
- 既存ルールベースを同一テストセットで実行し，比較のベースラインとする

## 成果物 (Deliverables)

- 学習・評価コード（本リポジトリ）
- リモート実行ツール（コード送信・実行・結果回収）
- 学習済みモデルの重み（研究室側に保管．必要に応じて手元へ回収）
- 実験記録・評価レポート（実装フェーズで `06_TEST` 配下に作成）

## 前提・未確定事項 (Assumptions & Open Questions)

研究室 PC でデータを確認してから確定する項目．

- 画像の枚数・患者数・クラスごとの分布
- 画像形式・解像度・マスク外領域の扱い（黒塗りか透明か）
- 患者 ID がファイル名等から辿れるか（患者単位分割の前提）
- ラベルの保存形式（CSV・アプリのデータ等），1 画像に複数評価者のラベルがあるか
- 倫理審査・データ利用許諾の状況