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 参照

インストール

0. Pythonのインストール確認

このツールを使用する前に、Python 3.10以上がインストールされていることを確認してください。

バージョン確認:

python3 --version

または

python --version

Python 3.10以上が表示されればOKです。インストールされていない場合は、以下の方法でインストールしてください。

Pythonのインストール方法

• Windows:

  • Python公式サイトから「Windows installer (64-bit)」をダウンロード
  • インストーラー実行時に 「Add Python to PATH」に必ずチェックを入れてください

• macOS:

  • Homebrewを使用（推奨）:

    brew install python@3.10
    

  • またはPython公式サイトからmacOS installerをダウンロード

• Linux (Ubuntu/Debian):

  sudo apt update
  sudo apt install python3.10 python3.10-venv python3-pip
  

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

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

2. 仮想環境の作成と有効化

仮想環境を作成:

python3 -m venv venv

仮想環境を有効化:

• Linux/macOS:

  source ./venv/bin/activate
  

• Windows:

  venv\Scripts\activate
  

仮想環境が有効化されると、プロンプトの先頭に (venv) が表示されます。

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

仮想環境を有効化した状態で、以下のコマンドを実行します:

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の場合: 📁 参照 ボタンでWindows標準のフォルダ選択ダイアログで選択してください
• macOSの場合: Finderでフォルダを選択し、Command + Option + C でパスをコピーして貼り付けてください

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

• 正解ラベルが記載されたExcelファイル（CHIBAMI_case_list_xxx.xlsx）を選択
• Windowsの場合: 📁 参照 ボタンでWindows標準のファイル選択ダイアログで選択してください
• macOSの場合: Finderでファイルを選択し、Command + Option + C でパスをコピーして貼り付けてください

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

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

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

画像ビューアー（中央）

• フレーム番号スライダー: マウスでスライダーを動かして、画像を前後にスクロール
• キーボードショートカット:
  • ← または a: 前のフレームに移動
  • → または f: 次のフレームに移動
• ◀▶ボタン: クリックでフレームを1つずつ移動
• 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/
│       └── ...
└── ...

⚠️ 重要: データ配置に関する推奨事項

画像データがクラウドストレージ（OneDrive、Google Drive、Dropboxなど）に保存されている場合、画像の読み込みに時間がかかる可能性があります。

推奨: アノテーション作業を開始する前に、画像データをローカルディスク（例: C:\Users\YourName\Documents\IVUS_Data\）にコピーしてください。

これにより、画像の読み込み速度が大幅に向上し、スムーズなアノテーション作業が可能になります。

出力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環境）またはmacOSで実行している可能性があります。

• Windowsの場合: Windows上で直接Pythonを実行してください。WSL環境では、パスを手入力（コピー&ペースト）してください。
• macOSの場合: Finderでフォルダ/ファイルを選択し、Command + Option + C でパスをコピーして貼り付けてください。

Q3: Pythonがインストールされていない、またはバージョンが古い

A3: Python 3.10以上が必要です。以下のコマンドでバージョンを確認してください。

python3 --version

または

python --version

インストールされていない、またはバージョンが3.10未満の場合は、インストールセクションを参照してインストールしてください。

• Windows: Python公式サイトからダウンロード（「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

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

プロジェクト構造

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

ライセンス

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

サポート

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

更新履歴

v1.0.0 (2025-12-08)

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