| --- |
| license: mit |
| tags: |
| - table-tennis |
| - ball-detection |
| - pytorch |
| language: |
| - ja |
| --- |
| |
| # TTNet - Table Tennis Ball Detection (Fine-tuned on OpenTTGames) |
|
|
| TTNet（CVPR2020）の学習済みモデル。OpenTTGames データセットで 3フェーズ学習を行ったチェックポイント一式。 |
| 元のリポジトリ: [maudzung/TTNet-Real-time-Analysis-System-for-Table-Tennis-Pytorch](https://github.com/maudzung/TTNet-Real-time-Analysis-System-for-Table-Tennis-Pytorch) |
|
|
| --- |
|
|
| ## チェックポイント一覧 |
|
|
| | ファイル名 | 説明 | |
| |---|---| |
| | `ttnet_1st_phase_best.pth` | stride=1（120fps想定）Phase 1 best (epoch 17) | |
| | `ttnet_2nd_phase_best.pth` | stride=1 Phase 2 best (epoch 3) | |
| | `ttnet_3rd_phase_best.pth` | stride=1 Phase 3 best (epoch 3) ← stride=1推論用 | |
| | `ttnet_30fps_1st_phase_best.pth` | stride=4（30fps対応）Phase 1 best (epoch 12) | |
| | `ttnet_30fps_2nd_phase_best.pth` | stride=4 Phase 2 best (epoch 7) | |
| | `ttnet_30fps_3rd_phase_best.pth` | stride=4 Phase 3 best (epoch 1) ← stride=4推論用 | |
|
|
| --- |
|
|
| ## 学習環境 |
|
|
| - GPU: NVIDIA GeForce RTX 4070 Ti Super (16GB) |
| - PyTorch 2.4.0 (CUDA 12.1) |
| - データセット: [OpenTTGames](https://lab.osai.ai/datasets/openttgames/) |
| - 学習: game_1〜4（約46,000フレーム） |
| - 検証: game_5（約7,300フレーム） |
|
|
| --- |
|
|
| ## 学習方法 |
|
|
| ### フレーム画像の抽出 |
|
|
| ```bash |
| cd TTNet/TTNet-Real-time-Analysis-System-for-Table-Tennis-Pytorch/prepare_dataset |
| |
| # stride=1（120fps想定） |
| python extract_smooth_labellings.py |
| # → dataset/training/images/ に出力（約39GB） |
| |
| # stride=4（30fps対応） |
| python extract_smooth_labellings.py --frame_stride 4 |
| # → dataset/training/images_stride4/ に出力（約39GB） |
| ``` |
|
|
| ### Phase 1〜3 の学習（stride=1） |
|
|
| ```bash |
| bash train_ttnet.sh |
| # 内部で以下を順番に実行: |
| # Phase 1: ボール全体検出 + セグメンテーション |
| # Phase 2: ローカル検出 + イベント検出 |
| # Phase 3: 全タスク fine-tune |
| # 重みの保存先: TTNet/checkpoints/ttnet_{1,2,3}rd_phase/ |
| ``` |
|
|
| ### Phase 1〜3 の学習（stride=4、30fps対応） |
|
|
| ```bash |
| bash train_ttnet_30fps.sh |
| # stride=4 専用スクリプト。モデル構造は変更なし（9フレーム27ch入力） |
| # 重みの保存先: TTNet/checkpoints/ttnet_30fps_{1,2,3}rd_phase/ |
| ``` |
|
|
| --- |
|
|
| ## 学習結果 |
|
|
| ### stride=1（game_1〜4 学習 / game_5 検証） |
|
|
| | フェーズ | 内容 | Best Val Loss | Best Epoch | |
| |---------|------|--------------|-----------| |
| | Phase 1 | Global検出 + セグメンテーション | 0.1804 | 17 / 30 | |
| | Phase 2 | Local検出 + イベント検出 | 0.1252 | 3 / 30 | |
| | Phase 3 | 全タスク Fine-tune | 0.2865 | 3 / 30 | |
|
|
| ### stride=4（game_1〜4 学習 / game_5 検証） |
|
|
| | フェーズ | 内容 | Best Val Loss | Best Epoch | |
| |---------|------|--------------|-----------| |
| | Phase 1 | Global検出 + セグメンテーション | 0.2664 | 12 / 30 | |
| | Phase 2 | Local検出 + イベント検出 | 0.0961 | 7 / 30 | |
| | Phase 3 | 全タスク Fine-tune | 0.3456 | 1 / 30 | |
|
|
| --- |
|
|
| ## 推論方法 |
|
|
| ```bash |
| source venv_ttnet/bin/activate |
| |
| # stride=1（120fps想定映像向け） |
| python run_ball_trajectory.py \ |
| --player haruya \ |
| --video 1 \ |
| --pretrained_path TTNet/checkpoints/ttnet_3rd_phase/ttnet_3rd_phase_best.pth \ |
| --gpu_idx 0 |
| |
| # stride=4（30fps映像向け） |
| python run_ball_trajectory.py \ |
| --player haruya \ |
| --video 1 \ |
| --pretrained_path TTNet/checkpoints/ttnet_30fps_3rd_phase/ttnet_30fps_3rd_phase_best.pth \ |
| --frame_stride 4 \ |
| --run-id stride4 |
| ``` |
|
|
| --- |
|
|
| ## TTNet のモデル構造（概要） |
|
|
| 1. **Global Stage**: 9フレームスタック（27ch、320×128）を入力。Conv×6 + FC×3 で 448次元の1Dガウス分布を出力し、`argmax` でボール位置を粗く推定（X方向320px + Y方向128px） |
| 2. **Local Stage**: Global推定位置を中心に元画像をクロップして再度同じネットワークに通し、精密な座標を算出 |
| 3. **最終座標**: `bx = x_global × (1920/320) + x_local - 160`、`by = y_global × (1080/128) + y_local - 64` |
| 4. **Segmentation / Event Spotting**: Global中間特徴からデコードして卓球台マスクとバウンス・ネット接触を並列に検出 |
|
|
| --- |
|
|
| ## ドメインシフトについて（重要な注意事項） |
|
|
| - 学習データ（OpenTTGames）: 暗い競技会場・固定俯瞰カメラ・120fps |
| - 本研究で適用した映像: 明るい体育館・角度のある手持ちカメラ・30fps |
| - stride=4 による 30fps 対応後も全フレームで `x=-160, y=543` の固定値となり検出不能 |
| - **公式映像（OpenTTGames game_5）では正しく検出できることを確認済み**（ドメインシフトが原因） |
| - このため、事前学習済み重みで様々な映像環境に対応できる **TrackNetV3** に移行した |
| |
