Good-Badminton

What it is

Good-Badminton is an AI羽毛球鹰眼系统 for badminton video analysis. It is part of a family including Good-Badminton, Good-Tennis, and Good-Pickleball, focusing on player detection, shuttlecock tracking, court coordinate mapping, trajectory statistics, and annotated outputs. It provides both CLI and optional WebUI via Gradio.

How it works

The project combines: (1) player pose detection using RTMPose, RTMO, or YOLO Pose; (2) shuttlecock detection with YOLO; (3) manual/static court keypoint annotation for image-to-standard-court mapping; (4) automatic court boundary detection and ROI-based posture regions; (5) tracking of players (split halves), rally detection, and statistics (distance, speed, rallies); (6) visualization outputs including skeletons, trajectories, heatmaps, and scatter plots; (7) outputs include metadata, per-frame detections, annotated video, and visualization data. WebUI workflow allows uploading video, detecting the court, adjusting parameters, and running analysis in a browser.

Getting started

Key commands and options shown in the README:

• Default installation and usage are through the provided Python environment and requirements files. WebUI can be installed with:

  pip install -r requirements-webui.txt
  

  and started with:

  python -m webui.app
  

• First run CLI flow:

  python main.py --video-path videos/demo.mp4
  

• Pose model selection examples:

  python main.py --video-path videos/demo.mp4 --pose-family rtmpose --pose-mode balanced
  

  python main.py --video-path videos/demo.mp4 --pose-family rtmo --pose-mode lightweight
  

  python main.py --video-path videos/demo.mp4 --pose-family yolo-pose --yolo-pose-model yolo11n-pose.pt
  

• Common parameters include:

  --video-path
  --output-dir
  --ball-model
  --pose-family
  --pose-mode
  --yolo-pose-model
  --template-path
  --pose-roi true|false
  --display true|false
  --skeletons true|false
  --player-trajectories true|false
  --court-trajectory true|false
  --shuttlecock-trajectory true|false
  --player-stats true|false
  --performance-stats
  --save-images
  --visualize-positions true|false
  --audio true|false
  --language {zh,en}
  

• Output location defaults to outputs/<视频文件名>/ with files like metadata.json, detections.jsonl, detect_<视频文件名>.mp4, court_annotations.txt, and visualization folders.

Getting started (continued)

• WebUI provides an interface for uploading a video and court template, detects court boundaries, allows manual corner adjustment, configures analysis parameters, and runs analysis, with outputs including annotated video and visualizations. WebUI is optional and does not affect CLI usage.

Recent releases

• The latest release section lists none in RELEASES (latest 0); the README notes ongoing updates through 2026-06-27 to 2026-06-24, etc., including new Gradio WebUI and improvements to court boundary detection.

Traction

• Stars: 797, Forks: 226, Open issues: 5. Language: Python. License: Apache-2.0. Created: 2026-06-20, Last push: 2026-07-03.

Behind the repo

• Not provided in the README; no linked startup/company information is present.

Caveats

• License: Apache-2.0. The README notes dependencies (Python 3.8+, FFmpeg), and requires a badminton YOLO weight from Releases. Hardware guidance includes GPU considerations (6GB+ vRAM recommended) and system memory (16GB+), with SSD recommended. WebUI requires extra dependencies via requirements-webui.txt.