IVUS合併症アノテーションツール

循環器内科医がIVUS（血管内超音波）画像を確認し、No reflow / Slow flow の合併症リスクを予測・アノテーションするためのStreamlitベースのWebアプリケーション。

目次

• 概要
• 機能
• 必要環境
• インストール
• 使い方
• データ形式
• トラブルシューティング

概要

このツールは、医師がIVUS画像（1症例あたり約20フレーム）を確認し、以下の情報をアノテーションできます：

• 合併症予測：No reflow/Slow flowの発生有無
• 確信度：予測の確信度（0-100%）
• 判断根拠：石灰化プラーク、減衰プラークなどの所見
• 自由記述：追加コメント

アノテーション結果はCSVファイルとして保存され、Excelで開いて分析できます。

機能

実装済み機能

• GUIベースの設定：起動時にフォルダ/ファイルをWindows標準ダイアログで選択
• 画像ビューアー：スライダーでフレームを前後にスクロール
• 症例ナビゲーション：前へ/次へボタン、ドロップダウン選択
• 進捗管理：完了済み症例に自動でチェックマーク表示
• 自動保存後進行：保存後、未完了の次の症例へ自動移動
• Excel互換CSV出力：日本語が正しく表示される utf-8-sig 形式
• Ground Truth記録：正解ラベルをCSVに記録（UI非表示）

必要環境

• OS: Windows 10/11（推奨）
• Python: 3.10以上
• 必要なPythonパッケージ: requirements.txt 参照

インストール

1. リポジトリのクローン

git clone <このリポジトリのURL>
cd ivus-complication-annotation-tool

2. 依存パッケージのインストール

pip install -r requirements.txt

インストールされるパッケージ:

• streamlit: Webアプリケーションフレームワーク
• pandas: CSV/Excelデータ処理
• Pillow: 画像読み込み・表示
• openpyxl: Excelファイル読み込み（pandasが使用）
• watchdog: 開発時の自動リロード

使い方

起動方法

streamlit run app.py

起動すると、自動的にブラウザが開き、設定画面が表示されます。

ステップ1: 設定画面

アプリケーション起動時、以下の3つの情報を入力します：

1. アノテーター名（必須）

• あなたの名前を入力してください
• 例: 田中

2. データディレクトリパス（必須）

• 症例フォルダ（CHIBAMI_xxx_pre）が含まれるディレクトリを選択
• 📁 参照 ボタンでWindows標準のフォルダ選択ダイアログで選択してください

3. Excelラベルファイルパス（必須）

• 正解ラベルが記載されたExcelファイル（CHIBAMI_case_list_xxx.xlsx）を選択
• 📁 参照 ボタンでWindows標準のファイル選択ダイアログで選択してください

注意: 全ての項目を正しく入力しないと、アノテーション開始ボタンが有効になりません。

ステップ2: アノテーション画面

設定完了後、メインのアノテーション画面が表示されます。

画像ビューアー（中央）

• フレーム番号スライダー: マウスでスライダーを動かして、画像を前後にスクロール
• 1症例あたり約20フレームの画像を確認できます

症例ナビゲーション（サイドバー上部）

• 症例を選択: ドロップダウンから任意の症例を選択
  • 完了済み症例には ✓ マークが表示されます
• ← 前へ / 次へ →: ボタンで前後の症例に移動

アノテーション入力（サイドバー下部）

Q1: 合併症予測 (No reflow/Slow flow)

• ラジオボタンで なし または あり を選択

Q2: 確信度 (%)

• スライダーで0〜100%の間で確信度を設定（デフォルト: 50%）

Q3: 判断根拠（複数選択可）

• 以下の選択肢から、該当するものを全てチェック:
  • 石灰化プラークが多い
  • 石灰化プラークが少ない
  • 減衰プラークが多い
  • 減衰プラークが少ない
  • その他（記述）

Q4: 自由記述欄

• 追加のコメントや所見を自由に記述

保存

• 💾 保存して次へ ボタンをクリック
• バリデーション: Q3（判断根拠）が最低1つ選択されていない場合、エラーメッセージが表示されます
• 保存成功後、自動的に次の未完了症例へ移動します

データ形式

入力データ構造

データディレクトリ/
├── CHIBAMI_134_pre/
│   ├── images/
│   │   ├── frame_134_4440.png
│   │   ├── frame_134_4500.png
│   │   └── ... (約20枚)
│   └── ... (その他のマスクデータなど)
├── CHIBAMI_135_pre/
│   └── images/
│       └── ...
└── ...

重要:

• フォルダ名: CHIBAMI_{症例番号}_pre
• 画像形式: PNG
• 画像ファイル名: frame_{症例番号}_{フレーム番号}.png

出力CSV形式

保存されるCSVファイル名: annotations_{アノテーター名}.csv

保存場所: データディレクトリ直下

CSVカラム:

文字エンコーディング: utf-8-sig（Excelで開いても文字化けしません）

トラブルシューティング

Q1: アプリが起動しない

A1: 必要なパッケージがインストールされているか確認してください。

pip install -r requirements.txt

または

python -m pip install -r .\requirements.txt

Q2: 📁 参照 ボタンを押してもダイアログが開かない

A2: WSL（Linux環境）で実行している可能性があります。このツールはWindows環境での使用を前提としています。

• 対処法: Windows上で直接Pythonを実行してください。
• WSL環境では、パスを手入力（コピー&ペースト）してください。

Q3: フォルダ/ファイルが見つからないとエラーが出る

A3: パスが正しいか確認してください。

• Windowsパスの例: C:\Users\YourName\Documents\data
• WSLパスの例: /mnt/d/Research/data/...（Windows環境では使えません）

Q4: CSVをExcelで開くと文字化けする

A4: 通常は発生しませんが、もし発生した場合:

1. Excelでデータ→テキストファイルから を選択
2. エンコーディングをUTF-8に指定して開く

Q5: 画像が表示されない

A5: 以下を確認してください:

1. データディレクトリ内に CHIBAMI_{番号}_pre/images/ フォルダが存在するか
2. images/ フォルダ内に frame_*.png ファイルが存在するか
3. PNGファイルが破損していないか

Q6: 進捗が保存されない

A6: CSVファイルの保存先を確認してください。

• 保存先: {データディレクトリ}/annotations_{アノテーター名}.csv
• 例: C:\Users\YourName\Documents\data\annotations_tanaka.csv

ファイルの書き込み権限があるか確認してください。

プロジェクト構造

ivus-complication-annotation-tool/
├── app.py                    # メインアプリケーション
├── requirements.txt          # 依存パッケージリスト
├── README.md                 # このファイル
├── CLAUDE.md                 # プロジェクトガイドライン
└── utils/                    # ユーティリティモジュール
    ├── __init__.py           # パッケージ初期化
    ├── excel.py              # Excelラベル読み込み
    ├── data_loader.py        # 症例データ読み込み
    └── annotation_saver.py   # アノテーション保存

開発者向け情報

コーディング規約

• 変数名・関数名: 英語（スネークケース）
• UIラベル: 日本語
• 型ヒント: 可能な限り使用
• 詳細は CLAUDE.md を参照

起動コマンド（開発用）

# 自動リロード有効
python -m streamlit run app.py

# ポート指定
streamlit run app.py --server.port 8501

# ブラウザを自動で開かない
streamlit run app.py --server.headless true

ライセンス

研究用途のみ。商用利用不可。

サポート

不具合や質問がある場合は、プロジェクト管理者にご連絡ください。

更新履歴

v1.0.0 (2025-12-08)

• 初回リリース
• GUIベースの設定画面
• Windows標準フォルダ選択ダイアログ
• 画像ビューアー
• アノテーション入力フォーム
• CSV保存機能
• 進捗管理機能