zakezhang/tennis-video-private-coach

テニス動画プライベートコーチ

アマチュアプレーヤーの練習動画を、行動に移せるレビューに変換します: ストロークのどの部分が崩れているか、それを証明するショット、そして次に正確に何を練習すべきか。壁打ち、ボールマシン、コーチ、または練習パートナーと練習する初心者から中級者向けに構築されています。

要件: Python 3、ffmpeg を実行でき、pip パッケージ (ultralytics, opencv-python, numpy, scipy, Pillow) をインストールできる環境。GPU があれば役立ちますが必須ではありません。

0. 最初に確認すること (まだ知らないことだけ)

1. フレーム内でプレーヤーは誰か: 服の色、髪型、位置。コーチ、パートナー、隣のコートの人々が映り込むことがよくあります。
2. 利き手、およびバックハンドが 片手打ちか両手打ちか (または学習中の場合はその両方)。
3. レベルと目標: テニス歴と達成したいこと (例: 「年内にラリーができてセットがプレイできるようになりたい」)。
4. 環境: 壁打ち / ボールマシン / コーチフィーディング / ラリー; インドアかアウトドアか。
5. カメラ: 後方、横、または正面; スマートフォンの高さ; フレームレート。
6. 怪我: 膝、肩、肘、背中の最近の痛み。ある場合、フットワークと着地に特に注意します。
7. 最も解決したい問題 (例: 「ボールがよく飛びすぎる」または「コンタクトポイントが不安定」)。レポートは最初にそれに答える必要があります。
8. 過去のレポート (もしあれば)。比較のために。

1. レポートがすべきこと

• 結論から述べる。 最大の問題と最大の改善点を一文で述べ、その後に詳細を述べます。具体的に述べ、すべての批判を証拠で裏付けます。賞賛だけではありません。以前のレビューで間違っていた点があれば、明示的に述べます。
• すべての主張を動画で裏付ける。 各ケースには、アノテーション付きのスローモーションクリップが付き、棒人間のアニメーションではなく、プレーヤーの実際の映像に描画されます。
• デフォルトは 4 カテゴリ × 3 ショット: ベストフォアハンド、ワーストフォアハンド、ベストバックハンド、ワーストバックハンド (12 クリップ)。各カテゴリには、3 列の比較表と、3 つのショットに共通する点を一文で記載します。カテゴリに使用可能なショットが 3 つ未満の場合は、見つかった数を記載します。
• 片手打ちと両手打ちのバックハンドは分けて扱う。 プレーヤーが両方を練習している場合、片手打ちは独自のセクションを設け、両手打ちの統計から除外します。
• 崩れているフェーズを特定する: テイクバック / ラケットドロップ / コンタクトポイント / フォロースルーの方向 / フットワーク / 準備のタイミング / 高いボールの処理 / フォアハンド・バックハンドの判断。
• 常に膝とフットワークをチェックする: 空中での打撃、片足での着地、ロックされた真っ直ぐな脚でのピボット。
• データの限界を明記する: サンプルサイズ、読み取れなかったショットの数、カメラアングルのバイアス。何かが見えない場合は、数値を推測するのではなく、その旨を述べます。
• プレーヤーが従える計画で締めくくる: 2～4 のドリルと反復回数または時間、および次の段階に進むための条件。

2. パイプライン

2.1 トランスコードと音声抽出

• 4K HEVC スマートフォン映像は重いです。960 幅の H.264 分析用コピーを作成します: ffmpeg -i IN.MOV -vf scale=960:-2 -r 30 -an -c:v libx264 -preset veryfast -crf 24 p.mp4 (一部のスマートフォンは 29.97 fps で録画します。30 に強制することで時間変換が簡単になります。)
• 音声を別途抽出してコンタクトを特定します: ffmpeg -i IN.MOV -vn -ac 1 -ar 22050 a.wav
• 長い動画はタイムアウトを避けるために 4～5 分のチャンクに分割して処理します。多数の短いクリップがある場合は、まず各クリップから 1 フレームを概要シートに取得し、どのクリップがプレーヤーの背後からのアングルとして使用可能か、どれが遠すぎるか (テクニックを見るためだけに使用) を判断します。
• 壁打ちセッションの場合、ネットライン周辺を拡大した「壁」コピーをクロップして、ネット/アウトを判断します。

2.2 ポーズ推定

• Ultralytics YOLO ポーズモデルを使用します (yolo11n-pose.pt; より高い精度には yolo11m-pose.pt)。インドアでは、4 フレームごとに imgsz 640、conf 0.3 で十分です。アウトドアでは、人物が小さく数が多いため、2 フレームごとに imgsz 960、conf 0.25 を使用します。
• 正しい人物を追跡する。 フレーム内に 1 人の人物がいる場合は、最大のバウンディングボックスを取得します。コーチなど他の人物がいる場合は、各検出を服装でスコアリングします: 胴体ポリゴン (肩と腰) 内の中央 HSV 輝度と彩度、およびショートパンツ/ズボンの腰から膝の領域の色。前のフレームから大きくジャンプした場合にペナルティを追加して、トラックが人物を切り替えないようにします。
• 左右は画像の x 座標で判断し、モデルの左/右ラベルは使用しません。後方から見て、プレーヤーの右側は画像の右側です。

2.3 すべてのスイングを見つける

• スイングは手首の速度のピークです: 動きの大きい方の手首のフレーム間変位をボックスの高さで割り、2 サンプルで平滑化し、閾値約 0.16 (4 フレームごとのサンプリングの場合。より密なサンプリングではスケールダウン)。
• ピーク間は少なくとも 1.6 秒必要。 1.0 秒のギャップは、フォロースルー後の回復を 2 回目のスイングとしてカウントします。通常のリズムは 3～4 秒に 1 スイングです。
• フォアハンドかバックハンドか: ピークの 1.1 秒前から 0.25 秒前のウィンドウで、両手の中点が腰の正中線のどちら側にあるか。利き手側がフォアハンドを意味します。一部は間違う可能性があります。特集するショットについては、フレームごとに確認します。
• 以下のすべてのメトリクスを手首速度のピーク (tp と呼ぶ) に固定して、セッション間で比較可能にします。

2.4 音からコンタクトを特定する

• 1500 Hz でハイパスフィルター; 110 サンプルウィンドウでエネルギーベロシティを計算; 周囲 401 ウィンドウの中央値より少なくとも 10 dB 高く、かつ少なくとも 50 ウィンドウ離れたピークを見つけます。
• 秒に変換するには window_index × 110 / 22050 を使用します。 ショートカットとして 0.005 を掛けると、4 分ごとに約 0.5 秒ずれ、長い動画の後半が台無しになります。
• 壁打ち: [tp−0.1, tp+0.55] 秒以内で、背景より少なくとも 15 dB 高い最も大きなピーク (通常 tp の 0.2～0.35 秒後) を取得します。壁にボールが当たる音 (コンタクトの約 0.45 秒後) も大きいので、選択しないようにします。
• アウトドア: コーチの打球や他のコートからのノイズが加わります。[tp−0.45, tp+0.25] 秒を検索します。該当するものがなければ tp を使用します。
• クリップに採用されるすべてのショットについて、フレームを見て実際のコンタクトフレームを確認します。

2.5 片手打ちバックハンドの検出 (プレーヤーが学習中の場合)

• バックハンドの中で、tp 後 0.7 秒以内の最大手首間距離 (胴体長で割る) を取得します。両手打ちは両手をフィニッシュまで一緒に保ちます (通常 1.5 未満)。片手打ちは非打撃腕を後ろに開きます (通常 2.0～2.5)。差は明確です。閾値は約 1.95 で機能します。
• 近いカメラアングルは誤検出を引き起こします。すべての候補を目視で確認します。
• 各片手打ちについて記録: テイクバックで手が頭の上に上がるか、テイクバックが遅いか (両手打ちのようにセットアップしてから最後の瞬間に引き上げる)、コンタクトで腕がまっすぐか、フォロースルーの高さ、結果。
• 片手打ちチェックリスト (各項目: 正しい姿 / 今回のセッション / 判定): オフハンドをスロートに置いたユニットターン、ラケットヘッドを後ろに向けた胸から肩の高さのテイクバック、ラケットが低く落ちてから低く高くスイング、前でのコンタクトとまっすぐな腕、オフ腕が後ろに開く、胸が早く回らずに高くフィニッシュを保持、膝を曲げて踏み込む。グリップは後方からは見えないので、プレーヤーにコーチと確認するよう提案します。

2.6 ネット / アウトカウント (ボールが可視の場合のみ)

• 壁打ち: ズームした壁動画でネットラインをマークします。各ショットについて、コンタクト後の 30 フレームにわたって移動する黄色いブロブ (時間とともに赤→緑でプロット) と、ネットライン上のカーテンの動きを別の色でプロットした 1 タイルを作成します。各タイルを目視で判断します: カーテンが動くかボールがラインより上に当たる = イン; ボールがボードに当たりカーテンが動かない = ネット; プレーヤーにブロックされる = 読み取り不可。完全自動判定は人間と一致するのは約 60% 程度なので、ヒントとしてのみ使用します。
• サンプリング: セッション全体から均等に分散された 100 ショットを判断し、読み取り不可のものを除外し、フォアハンド / 両手打ち / 片手打ちを別々に報告します。次に、残りの最も疑わしい 20 ショットをレビューして、エラーが 1 つの期間 (通常は疲労が現れた後) に集中しているかどうかを確認します。
• アウトドア: 背景で木々が動いたり、周りに多くのプレーヤーがいたりすると、色と動きによるボール検出はほとんど機能しません。パーセンテージは報告しないでください。レポートでその理由を述べ、代わりにテクニックでベスト/ワーストを選び、カウントを可能にするためのカメラに関するアドバイスを提供します。

2.7 テクニックメトリクス (すべてのスイングで測定)

メトリクス	方法	それが示すもの
フォアハンドの手が鼻より上	[tp−1.1, tp−0.25] のフレームで、打撃手首が鼻より上にある割合	テイクバックが高すぎる、ループスイング
両手が肩より上	同じウィンドウで両手首が肩の中心より上にある割合	バックハンドのラケットを高く持ちすぎ
最大膝の曲がり	[tp−0.6, tp+0.3] での前側脚の股関節-膝-足首の最小角度、スイング全体の中央値	脚がまっすぐすぎる (後方カメラは前方への屈曲を過小評価します。自分自身とのみ比較)
スタンス幅	tp での足首の水平距離 ÷ 胴体長	狭いスタンスはしばしばホッピングを伴う
接地と真っ直ぐ	tp 後 0.7 秒以内に一方の足首の移動が胴体長の 0.4 未満、かつその膝の角度が 155° より広い	膝への捻り負荷 (バックハンドでのピボットで一般的)
コンタクトの高さ	tp の 0.07～0.2 秒前の、打撃手の位置を腰 (0) から肩 (1) の間で評価	高いボールの数とプレーヤーが位置を調整するかどうか
ホッピング / 片足着地	フレームごとにレビューするショットで目視カウント	まだ信頼できる自動メトリクスはありません

• 長いセッションの場合、前半と後半を別々に報告して、疲労で何が崩れるかを確認します。
• カメラ、会場、または方法が変更された場合、古い動画を新しい方法で再測定するか、数値が比較できないことを明確に述べます。

2.8 ベスト 3 とワースト 3 を選ぶ

• ベスト: 良い結果 (快適にネットを越え、深く着地) と完全なストローク (テイクバックが所定の位置にあり、ラケットヘッドがボールの下に落ち、完全なフィニッシュ、両足が地面に着いている)。セッション全体に分散させます。
• ワースト: ネット、天井球、または明らかなエラー; 十分にない場合は、テクニカルな欠点が最も明確なショットを採用します。異なる原因を示すショット、または一緒に一つの共通原因を証明するショットを優先します。
• 結果タイルからショートリストを作成し、フレームごとのプレーヤーシート (コンタクトの 0.9 秒前から 0.5 秒後) から原因を確認します。ワーストバックハンドを選ぶときは、それらが片手打ちでないことを確認します。

2.9 アノテーション付きスローモーションクリップのレンダリング

• オリジナルから約 3 秒カット (コンタクトの 1.1～1.5 秒前から開始)、プレーヤーの周りを約 16:10 にクロップし、プレーヤーがフレーム高さの約 60% になるようにし、1280 幅にスケーリングします。
• すべてのフレームでポーズを実行します。手動で 4 つのフレームを選択します: テイクバックの頂点、コンタクト、描画パスの開始と終了 (レディポジションと回復は除く)。自動コンタクトフレームはしばしば間違っているので、常に目視で確認します。
• クリップ構成:
  1. 実速度 を 1 回。
  2. 1/4 速度、打撃手のパスをフレームごとに描画 (フォアハンド = 打撃手首; 両手打ち = 両手首の中点; 片手打ち = コンタクト前は中点、コンタクト後は打撃手首)、オレンジ→シアングラデーション、下部に各フェーズのキャプション付き。
  3. テイクバックの頂点で約 3 秒間停止、それを丸で囲み (緑 = 正しい、赤 = 問題)、短い見出しを付けます。
  4. コンタクトで約 3 秒間停止: コンタクトポイントに白い丸 (自動位置はボールを逃すことが多いので手動で設定)、前側の膝に黄色い丸とその角度 (片手打ちでは脚が横から重なるためスキップ)。
  5. フルパスで停止。 ワーストクリップでは、同じタイプのセッションのベストショットを、パス開始からコンタクトまで、胴体長でスケーリングし肩の中心で位置合わせし、アニメーション化された緑の破線と黒いアウトラインとして、修正方法を一文でオーバーレイします。
• H.264、yuv420p、faststart、960 幅、約 1～2.5 MB/クリップでエンコードします。各クリップから 4 フレームのコンタクトシートを作成して、キャプションが何も隠しておらず、丸が正しい位置にあることを確認します。
• キャプションでは ✓ と ✗ を避けます。多くの CJK フォントにはそれらがなく、ボックスとして表示されます。

3. レポート構成

HTML ページ (またはユーザーが要求する形式) を次の順序で生成します:

1. 評決: プレーヤーの質問に直接答えます; 最大の改善点、最大の問題、主要な数値; 以前のレビューへの修正。その下に、統計ストリップ (ストローク別スイング数、サンプルネット率または理由付きの「カウントされず」、1 つまたは 2 つの主要メトリクス)。
2. 原因: 問題を 2～3 の原因にグループ化し、それぞれにタイムスタンプ付きの例を付けます。
3. ベスト vs ワースト: 4 グループ、各グループに 3 つのクリップ、3 列の表 (テイクバック、ドロップ、コンタクト、フィニッシュ、足、膝の角度)、パターンに関する一文。
4. 前回との比較: ベストショットとワーストショットで何が変わったかを、表と並べて表示するクリップで示します。
5. 片手打ちバックハンド (練習している場合): 統計、チェックリスト、良いクリップ 3 つと悪いクリップ 3 つ、ショットごとのリスト、現在も練習を続けるべきかどうかのアドバイス。
6. 膝とフットワーク: メトリクステーブルとリスクを「優先 / 監視 / 改善中」に分類し、それぞれに修正方法を記載します。これは医学的アドバイスではないことを明確に述べ、腫れ、ロック、力が入らない、1 週間以上続く痛みについてはスポーツ医学の医師に相談するよう提案します。
7. 次に何を練習するか: セクション 5 を参照。
8. カメラに関するアドバイス (映像に不足があった場合)。
9. フッター: データソース、サンプルサイズ、測定定義、カメラの制限。

オプションのデザイン方向性: テニスパレット、ハードコートブルーをメインカラーに、ボールイエローは主要な数字とハイライトのみに、グラスグリーンを「良い」、クレーレッドを「問題」に使用。コンデンスド数字でスコアボードのような雰囲気に。ライトモードとダークモードの両方で読みやすく、スマートフォンで水平スクロールがないようにします。

4. 一般的な欠点と修正

以下の表で見られるものをまず分類し、次に具体的なショットでそれを証明します。

症状	通常の原因	動画での見え方	修正
フォアハンドがネット、下向きスイング	頭の上のテイクバック、大きなループ、ラケットが間に合わずドロップできない	打撃手が鼻より上に…

[truncated for translation]