Ping Pong Ball 検出および可視化プログラム

概要

本プロジェクトは, 指定された画像ディレクトリ内の画像から卓球ボールと思われる対象を検出し, ユーザーのクリック操作により各画像上の検出点（中心座標）を記録するプログラムと, 記録結果を画像上に描画して確認する可視化プログラムの2つのモジュールで構成されています.

• main.py は画像の読み込み, クリック操作による検出, 順序検証および検出結果のCSV形式での保存を行います.
• visual.py は, 保存されたCSVファイル (ping-pong-detection.csv) の検出結果を読み込み, 画像上に検出点とラベルを描画して表示します.

システム要件

• OS: Windows, macOS, Linux（OpenCVが動作する環境）
• Python: 3.x（推奨 3.7以上）
• 必要なPythonライブラリ:
  • opencv-python
  • numpy
  • python-dotenv

インストール方法

1. Pythonをインストールしてください.
2. プロジェクトルートに .env ファイルを作成し, 以下のように画像ディレクトリのパスを指定します.

   IMAGE_DIR=パス/to/your/image_directory
   

3. 以下の内容で requirements.txt を作成し, 必要なライブラリをインストールしてください.

   opencv-python
   numpy
   python-dotenv
   

4. 以下のコマンドを実行してライブラリをインストールします.

   pip install -r requirements.txt
   

フォルダ構成例

project/
│   main.py
│   visual.py
│   .env
│   requirements.txt
│   ping-pong-detection.csv   （検出結果のCSVファイル; 実行時に自動生成）
│
└── IMAGE_DIR/
    ├── image1.png
    ├── image2.jpg
    └── ...  （対象となる画像ファイル）

使用方法

1. 画像検出プログラム (main.py)

• コマンドラインから main.py を実行します.
• プログラム実行時に, コマンドライン引数としてビュー モードを指定します.
  • 例: フロントビューの場合は 1 を, 背面ビューの場合は 2 を指定します.

  python main.py 1
  

• プログラムは .env ファイルで指定された IMAGE_DIR 内の画像ファイルを取得し, ファイル名に含まれる角度情報（例: _<angle>_angle）に基づいてソートします.
• 各画像について, ウィンドウが表示されます.
  • 左クリック: クリック位置をシード点として領域拡張法により対象領域（卓球ボール）の中心座標と面積を検出し, 検出結果の順序検証を行った上で記録します.
  • 右クリック: 最後に記録した検出点を取り消します.
  • f キー: 現在の画像での検出を終了し, 結果を内部リストに保存します.
  • ESC キー: プログラムを終了し, すべての検出結果を ping-pong-detection.csv に保存します.

2. 検出結果の可視化プログラム (visual.py)

• コマンドラインから visual.py を実行します.

  python visual.py
  

• プログラムは, .env ファイルで指定された IMAGE_DIR 内の画像と, ping-pong-detection.csv に記録された検出結果を読み込みます.
• 画像上に検出された各ポイントおよびそのラベルが描画され, ウィンドウに表示されます.
• キー操作:
  • n キー: 次の画像を表示します.
  • p キー: 前の画像を表示します.
  • ESC キー: プログラムを終了します.

各ファイルの詳細

main.py

• 機能:
  画像ディレクトリ内の各画像に対して, ユーザーのクリック操作により卓球ボールの中心座標を検出し, 検出点の順序（相対位置）を検証した上で記録します.
  最終的な検出結果は CSV形式 (ping-pong-detection.csv) で保存されます.
• 主な関数:
  • validate_relative_position(center, pos_number, centers): 前回までの検出結果との相対位置関係に基づき, 新たに検出された点の妥当性をチェックします.
  • region_growing(image, seed_point, threshold, max_distance): クリックされたシード点からの類似色領域を8近傍に展開する領域拡張法を実装します.
  • detect_ping_pong_ball(image, click_point, max_distance): 領域拡張法を用いて対象領域の重心と面積を算出します.
  • on_mouse_click(event, x, y, flags, param): マウスクリックイベントを処理し, 検出点の追加または取り消しを行います.
  • save_results および save_all_results: 画像ごとの検出結果および全画像の結果を CSVファイルに保存します.
  • sort_key(filename): ファイル名中の _<angle>_angle パターンから角度情報を抽出し, 画像をソートするためのキーを返します.

visual.py

• 機能:
  ping-pong-detection.csv に記録された検出結果を読み込み, 対応する画像上に検出ポイントとラベルを描画して可視化します.
• 主な関数:
  • read_csv_data(csv_file): CSVファイルから各画像の検出結果を辞書形式で読み込みます.
  • draw_points(image, points): 指定された検出点とラベルを画像上に描画します.
  • sort_key(filename): 画像ファイル名から角度情報を抽出してソートに利用します.

注意点

• .env ファイルにおいて, IMAGE_DIR が正しく設定されていない場合はエラーとなります.
• 画像ファイル名には, 角度情報（例: _<angle>_angle）が含まれている必要があります.
• 検出結果のCSVファイルは, プログラム実行時に上書き保存されるため, 必要な場合はバックアップを行ってください.