diff --git a/.gitignore b/.gitignore index e7cdea6..696412a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ venv/ __pycache__/ +.pytest_cache/ .DS_Store \ No newline at end of file diff --git a/README.md b/README.md index b7464b0..405f0b1 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,12 @@ # IVUS合併症アノテーションツール -循環器内科医がIVUS（血管内超音波）画像を確認し、No reflow / Slow flow の合併症リスクを予測・アノテーションするためのStreamlitベースのWebアプリケーション。 +循環器内科医がIVUS（血管内超音波）画像を確認し、No reflow / Slow flow の合併症リスクを予測・アノテーションするためのツール。 ## 目次 - [概要](#概要) -- [機能](#機能) - [必要環境](#必要環境) -- [インストール](#インストール) +- [インストールと起動](#インストールと起動) - [使い方](#使い方) - [データ形式](#データ形式) - [トラブルシューティング](#トラブルシューティング) @@ -16,7 +15,7 @@ ## 概要 -このツールは、医師がIVUS画像（1症例あたり約20フレーム）を確認し、以下の情報をアノテーションできます： +IVUS画像（1症例あたり約20フレーム）を確認し、以下の情報をアノテーションします： - **合併症予測**：No reflow/Slow flowの発生有無 - **確信度**：予測の確信度（0-100%） @@ -27,182 +26,73 @@ --- -## 機能 - -### 実装済み機能 - -- **GUIベースの設定**：起動時にフォルダ/ファイルをWindows標準ダイアログで選択 -- **画像ビューアー**：スライダーでフレームを前後にスクロール -- **症例ナビゲーション**：前へ/次へボタン、ドロップダウン選択 -- **進捗管理**：完了済み症例に自動でチェックマーク表示 -- **自動保存後進行**：保存後、未完了の次の症例へ自動移動 -- **Excel互換CSV出力**：日本語が正しく表示される utf-8-sig 形式 -- **Ground Truth記録**：正解ラベルをCSVに記録（UI非表示） - ---- - ## 必要環境 -- **OS**: Windows 10/11（推奨） +- **OS**: Windows 10/11、macOS - **Python**: 3.10以上 -- **必要なPythonパッケージ**: requirements.txt 参照 --- -## インストール +## インストールと起動 -### 0. Pythonのインストール確認 +### Python 3.10以上がインストール済みの場合 -このツールを使用する前に、**Python 3.10以上**がインストールされていることを確認してください。 +1. **Windows**: `start_windows.bat` をダブルクリック +2. **macOS**: `start_mac.command` をダブルクリック -**バージョン確認:** +初回起動時、必要なパッケージが自動的にインストールされ、ブラウザが開きます。 + +### Pythonがインストールされていない場合 + +#### Windows +[Python公式サイト](https://www.python.org/downloads/)から「Windows installer (64-bit)」をダウンロードしてインストール +- インストール時に **「Add Python to PATH」に必ずチェック** + +#### macOS +Homebrewを使用（推奨）: ```bash -python3 --version +brew install python@3.10 ``` -または - -```bash -python --version -``` - -Python 3.10以上が表示されればOKです。インストールされていない場合は、以下の方法でインストールしてください。 - -#### Pythonのインストール方法 - -- **Windows**: - - [Python公式サイト](https://www.python.org/downloads/)から「Windows installer (64-bit)」をダウンロード - - インストーラー実行時に **「Add Python to PATH」に必ずチェック**を入れてください - -- **macOS**: - - Homebrewを使用（推奨）: - ```bash - brew install python@3.10 - ``` - - または[Python公式サイト](https://www.python.org/downloads/)からmacOS installerをダウンロード - -- **Linux (Ubuntu/Debian)**: - ```bash - sudo apt update - sudo apt install python3.10 python3.10-venv python3-pip - ``` - -### 1. リポジトリのクローン - -```bash -git clone <このリポジトリのURL> -cd ivus-complication-annotation-tool -``` - -### 2. 仮想環境の作成と有効化 - -**仮想環境を作成:** -```bash -python3 -m venv venv -``` - -**仮想環境を有効化:** - -- **Linux/macOS:** - ```bash - source ./venv/bin/activate - ``` - -- **Windows:** - ```bash - venv\Scripts\activate - ``` - -仮想環境が有効化されると、プロンプトの先頭に `(venv)` が表示されます。 - -### 3. 依存パッケージのインストール - -仮想環境を有効化した状態で、以下のコマンドを実行します: - -```bash -pip install -r requirements.txt -``` - -**インストールされるパッケージ**: -- streamlit: Webアプリケーションフレームワーク -- pandas: CSV/Excelデータ処理 -- Pillow: 画像読み込み・表示 -- openpyxl: Excelファイル読み込み（pandasが使用） -- watchdog: 開発時の自動リロード - --- ## 使い方 -### 起動方法 - -```bash -streamlit run app.py -``` - 起動すると、自動的にブラウザが開き、設定画面が表示されます。 ### ステップ1: 設定画面 -アプリケーション起動時、以下の3つの情報を入力します： +起動時に以下の3つの情報を入力します： -#### 1. アノテーター名（必須） -- あなたの名前を入力してください -- 例: 田中 +1. **アノテーター名**: あなたの名前（例: 田中） +2. **データディレクトリパス**: 症例フォルダ（CHIBAMI_xxx_pre）が含まれるディレクトリ +3. **Excelラベルファイルパス**: 正解ラベルが記載されたExcelファイル（CHIBAMI_case_list_xxx.xlsx） -#### 2. データディレクトリパス（必須） -- 症例フォルダ（CHIBAMI_xxx_pre）が含まれるディレクトリを選択 -- **Windowsの場合**: 📁 参照 ボタンでWindows標準のフォルダ選択ダイアログで選択してください -- **macOSの場合**: Finderでフォルダを選択し、`Command + Option + C` でパスをコピーして貼り付けてください - -#### 3. Excelラベルファイルパス（必須） -- 正解ラベルが記載されたExcelファイル（CHIBAMI_case_list_xxx.xlsx）を選択 -- **Windowsの場合**: 📁 参照 ボタンでWindows標準のファイル選択ダイアログで選択してください -- **macOSの場合**: Finderでファイルを選択し、`Command + Option + C` でパスをコピーして貼り付けてください - -**注意**: 全ての項目を正しく入力しないと、アノテーション開始ボタンが有効になりません。 +**📁 参照ボタン** をクリックすると、フォルダ/ファイル選択ダイアログが開きます（Windows）。 ### ステップ2: アノテーション画面 -設定完了後、メインのアノテーション画面が表示されます。 +#### 画像ビューアー +- スライダーで約20フレームの画像を前後にスクロール +- キーボードショートカット: `←/→` または `a/f` でフレーム移動 -#### 画像ビューアー（中央） -- **フレーム番号スライダー**: マウスでスライダーを動かして、画像を前後にスクロール -- **キーボードショートカット**: - - `←` または `a`: 前のフレームに移動 - - `→` または `f`: 次のフレームに移動 -- **◀▶ボタン**: クリックでフレームを1つずつ移動 -- 1症例あたり約20フレームの画像を確認できます +#### 症例ナビゲーション +- ドロップダウンで症例を選択（完了済み症例には ✓ マーク） +- **← 前へ / 次へ →** ボタンで前後の症例に移動 -#### 症例ナビゲーション（サイドバー上部） -- **症例を選択**: ドロップダウンから任意の症例を選択 - - 完了済み症例には ✓ マークが表示されます -- **← 前へ / 次へ →**: ボタンで前後の症例に移動 +#### アノテーション入力 -#### アノテーション入力（サイドバー下部） - -**Q1: 合併症予測 (No reflow/Slow flow)** -- ラジオボタンで なし または あり を選択 - -**Q2: 確信度 (%)** -- スライダーで0〜100%の間で確信度を設定（デフォルト: 50%） - -**Q3: 判断根拠**（複数選択可） -- 以下の選択肢から、該当するものを全てチェック: - - 石灰化プラークが多い - - 石灰化プラークが少ない - - 減衰プラークが多い - - 減衰プラークが少ない - - その他（記述） - -**Q4: 自由記述欄** -- 追加のコメントや所見を自由に記述 +1. **合併症予測**: なし / あり を選択 +2. **確信度**: スライダーで0〜100%を設定 +3. **判断根拠**: 該当するものを全てチェック（複数選択可） + - 石灰化プラークが多い / 少ない + - 減衰プラークが多い / 少ない + - その他（記述） +4. **自由記述欄**: 追加のコメントや所見 #### 保存 -- **💾 保存して次へ ボタン**をクリック -- **バリデーション**: Q3（判断根拠）が最低1つ選択されていない場合、エラーメッセージが表示されます -- 保存成功後、自動的に次の未完了症例へ移動します +**💾 保存して次へ** ボタンをクリックすると、自動的に次の未完了症例へ移動します。 --- @@ -212,44 +102,16 @@ ``` データディレクトリ/ -├── CHIBAMI_134_pre/ -│ ├── images/ -│ │ ├── frame_134_4440.png -│ │ ├── frame_134_4500.png -│ │ │ └── ... (約20枚) -│ └── ... (その他のマスクデータなど) -├── CHIBAMI_135_pre/ -│ └── images/ -│ └── ... +├── CHIBAMI_134_pre/images/*.png (約20枚) +├── CHIBAMI_135_pre/images/*.png └── ... ``` -**⚠️ 重要: データ配置に関する推奨事項** - -画像データがクラウドストレージ（OneDrive、Google Drive、Dropboxなど）に保存されている場合、画像の読み込みに時間がかかる可能性があります。 - -**推奨**: アノテーション作業を開始する前に、画像データを**ローカルディスク**（例: `C:\Users\YourName\Documents\IVUS_Data\`）にコピーしてください。 - -これにより、画像の読み込み速度が大幅に向上し、スムーズなアノテーション作業が可能になります。 +**推奨**: 画像データは**ローカルディスク**に配置してください（クラウドストレージは読み込みが遅い場合があります）。 ### 出力CSV形式 -保存されるCSVファイル名: annotations_{アノテーター名}.csv - -**保存場所**: データディレクトリ直下 - -**CSVカラム**: - -| カラム名 | 説明 | 例 | -|---------|------|-----| -| timestamp | 保存日時 | 2025-12-08 19:30:45 | -| case_id | 症例番号 | 134 または 134.1 | -| prediction | 合併症予測 | あり または なし | -| confidence | 確信度(%) | 75 | -| reasons | 判断根拠（セミコロン区切り） | 石灰化プラークが多い; 減衰プラークが多い | -| comment | 自由記述 | 明確な所見あり | -| annotator | アノテーター名 | 田中 | -| ground_truth | 正解ラベル | True / False / (空=不明) | +**保存場所**: データディレクトリ直下 (`annotations_{アノテーター名}.csv`) **文字エンコーディング**: utf-8-sig（Excelで開いても文字化けしません） @@ -257,98 +119,19 @@ ## トラブルシューティング -### Q1: アプリが起動しない +### Pythonがインストールされていない +Python 3.10以上をインストールしてください。 +- **Windows**: [Python公式サイト](https://www.python.org/downloads/)（「Add Python to PATH」に必ずチェック） +- **macOS**: `brew install python@3.10` -**A1**: 必要なパッケージがインストールされているか確認してください。 +### 📁 参照ボタンが機能しない +macOSの場合、Finderでフォルダ/ファイルを選択し、`Command + Option + C` でパスをコピーして貼り付けてください。 -```bash -pip install -r requirements.txt -``` - -または -```bash -python -m pip install -r .\requirements.txt -``` - -### Q2: 📁 参照 ボタンを押してもダイアログが開かない - -**A2**: WSL（Linux環境）またはmacOSで実行している可能性があります。 - -- **Windowsの場合**: Windows上で直接Pythonを実行してください。WSL環境では、パスを手入力（コピー&ペースト）してください。 -- **macOSの場合**: Finderでフォルダ/ファイルを選択し、`Command + Option + C` でパスをコピーして貼り付けてください。 - -### Q3: Pythonがインストールされていない、またはバージョンが古い - -**A3**: Python 3.10以上が必要です。以下のコマンドでバージョンを確認してください。 - -```bash -python3 --version -``` - -または - -```bash -python --version -``` - -インストールされていない、またはバージョンが3.10未満の場合は、[インストールセクション](#0-pythonのインストール確認)を参照してインストールしてください。 - -- **Windows**: [Python公式サイト](https://www.python.org/downloads/)からダウンロード（「Add Python to PATH」に必ずチェック） -- **macOS**: `brew install python@3.10` （Homebrew推奨） -- **Linux (Ubuntu/Debian)**: `sudo apt install python3.10 python3.10-venv python3-pip` - -### Q4: フォルダ/ファイルが見つからないとエラーが出る - -**A4**: パスが正しいか確認してください。 - -- **Windowsパスの例**: C:\Users\YourName\Documents\data -- **macOS/Linuxパスの例**: /Users/YourName/Documents/data または /home/YourName/Documents/data -- **WSLパスの例**: /mnt/d/Research/data/...（Windows環境では使えません） - -### Q5: CSVをExcelで開くと文字化けする - -**A5**: 通常は発生しませんが、もし発生した場合: - -1. Excelでデータ→テキストファイルから を選択 -2. エンコーディングをUTF-8に指定して開く - -### Q6: 画像が表示されない - -**A6**: 以下を確認してください: - -1. データディレクトリ内に CHIBAMI_{番号}_pre/images/ フォルダが存在するか -2. images/ フォルダ内に frame_*.png ファイルが存在するか -3. PNGファイルが破損していないか - -### Q7: 進捗が保存されない - -**A7**: CSVファイルの保存先を確認してください。 - -- 保存先: {データディレクトリ}/annotations_{アノテーター名}.csv -- 例: C:\Users\YourName\Documents\data\annotations_tanaka.csv - -ファイルの書き込み権限があるか確認してください。 +### 画像が表示されない +データディレクトリ内に `CHIBAMI_{番号}_pre/images/*.png` が存在するか確認してください。 --- -## プロジェクト構造 - -``` -ivus-complication-annotation-tool/ -├── app.py # メインアプリケーション -├── requirements.txt # 依存パッケージリスト -├── README.md # このファイル -├── CLAUDE.md # プロジェクトガイドライン -└── utils/ # ユーティリティモジュール - ├── __init__.py # パッケージ初期化 - ├── excel.py # Excelラベル読み込み - ├── data_loader.py # 症例データ読み込み - └── annotation_saver.py # アノテーション保存 -``` - ---- - - --- ## ライセンス @@ -357,19 +140,10 @@ --- -## サポート - -不具合や質問がある場合は、プロジェクト管理者にご連絡ください。 - ---- - ## 更新履歴 +### v1.1.0 (2025-12-22) +- 確信度をスライダー方式に変更 + ### v1.0.0 (2025-12-08) - 初回リリース -- GUIベースの設定画面 -- Windows標準フォルダ選択ダイアログ -- 画像ビューアー -- アノテーション入力フォーム -- CSV保存機能 -- 進捗管理機能