从零到二开：Good-Badminton AI 羽毛球鹰眼系统代码架构导读与自定义数据集接入完整指南-平芜编程栈

【免费下载链接】Good-Badminton

🏸 AI Badminton Hawk-Eye System

项目地址：https://gitcode.com/gh_mirrors/go/Good-Badminton

Good-Badminton 是一款基于计算机视觉的AI 羽毛球鹰眼（Hawk-Eye）视频分析系统，只需上传一段固定机位的比赛视频，它就能自动识别球员姿态、追踪羽毛球轨迹、映射标准球场坐标，并输出带骨架、轨迹、速度统计与回合编号的标注视频，以及热力图 / 散点图和结构化检测数据。本文面向想读懂代码、二次开发、接入自己数据集的新手，带你从零走通「架构 → 关键源码 → 自定义数据集」的完整路径。

一、项目速览：它能做什么？

Good-Badminton 的核心能力可以概括为「输入一段视频，输出完整分析结果」：

球员姿态检测：支持 RTMPose / RTMO / YOLO Pose 三种人体关键点模型。
羽毛球检测：使用 YOLO 模型定位羽毛球，并在视频中绘制飞行轨迹。
球场坐标映射：把图像像素坐标映射到 6.1m × 13.4m 的标准球场坐标系。
自动球场检测：基于球场线模型自动匹配四角，支持手动修正。
运动统计：移动距离、当前 / 最大速度、回合数量。
可视化输出：标注视频、球员位置热力图与散点图、detections.jsonl逐帧数据。

💡 无论是做教学、科研还是打造自己的「智能羽毛球分析工具」，读懂它的数据流是二开的第一步。

二、整体代码架构：一图看懂数据流

Good-Badminton 采用「入口层 → 主流程编排 → 功能模块」的三层结构。你几乎只需要盯住一个核心类 BadmintonAnalysisSystem 就能看懂整个流程。

main.py / webui/app.py ← 入口层：解析参数、提供界面 │ ▼ badminton_analysis/system.py ← 主编排：逐帧调度各模块 │ ├── court/ 球场标注与图像→球场坐标映射 ├── detection/ 羽毛球检测 + 姿态检测 ├── tracking/ 球员追踪与运动统计 ├── visualization/ 视频叠加层、热力图/散点图 ├── data/ JSON / JSONL 数据输出 └── media/ 视频音频处理

模块目录	职责	关键文件
badminton_analysis/court/	球场四角标注、自动检测、坐标映射	mapper.py、detector.py
badminton_analysis/detection/	羽毛球 YOLO 检测、姿态模型	shuttlecock.py、rtmpose.py
badminton_analysis/tracking/	上下半场球员追踪、速度距离统计	player.py
badminton_analysis/visualization/	骨架/轨迹绘制、位置图表	player_pose.py、player_positions_zh.py
badminton_analysis/data/	`metadata.json`与`detections.jsonl`写入	writer.py
badminton_analysis/media/	H.264 转码、音频合并	video_audio.py
webui/	基于 Gradio 的浏览器界面	app.py、pipeline.py

入口层：CLI 与 WebUI 双通道

命令行入口main.py：用argparse解析全部参数，构建BadmintonAnalysisSystem后调用process_video()。
WebUI 入口webui/app.py：基于 Gradio，上传视频与模板图、点击「检测球场」并「运行分析」。其流程编排集中在 webui/pipeline.py 的run_analysis()，最终复用的是同一个BadmintonAnalysisSystem。

主流程编排：BadmintonAnalysisSystem.process_video()

system.py 中的process_video()是整条流水线的「总指挥」，逐帧执行以下六步：

读视频 + 载入模板：cv2.VideoCapture打开视频，读取球场模板图并缩放到与帧一致。
球场标注_setup_court_annotation()：优先复用输出目录里已有的court_annotations.txt；否则调用annotate_court()自动检测 + 手动四角标注。
构建坐标映射：CourtMapper(corners)建立图像坐标 ↔ 标准球场坐标（6.1×13.4 米）的双向变换。
逐帧检测_process_frame()：
- is_court_view()用模板匹配判断当前帧是否为比赛视角，用于回合开始/结束判定；
- PlayerPoseVisualizer.detect_players()在 ROI 内做姿态检测；
- ShuttlecockTracker.detect_ball()做羽毛球检测并维护轨迹；
- PlayerTracker.update()追踪上下半场球员、写检测记录；
- 各Visualizer把骨架、轨迹、统计、球场轨迹画回帧上。
写输出：每帧追加detections.jsonl，逐帧写入临时视频。
收尾_cleanup()：关闭数据写入器，用 FFmpeg 把临时视频转码为浏览器兼容的 H.264 并合并音频。

三、关键源码导读（二开必看）

1. 球场映射 court/：像素 → 米的桥梁

court/mapper.py 的CourtMapper是整套统计的地基。它用cv2.getPerspectiveTransform算出「四角点 → 标准矩形」的透视矩阵：

image_to_court()：把球员像素位置换算成球场坐标（单位：米）。
court_to_image()：反向换算，用于把球场轨迹画回画面。
compute_expanded_roi()：由四角自动生成姿态检测 ROI，减少推理区域、提速。

自动检测则交给 court/detector.py：auto_detect_court_corners()先提取水平/侧边球场线段，再枚举「上、下、左、右」线段组合求交点，用 reference.py 的标准球场线模型打分，选出最可信的四角。

2. 检测 detection/：羽毛球 + 姿态

羽毛球detection/shuttlecock.py：ShuttlecockTracker在整帧上跑 YOLO 检测，再经过「面积比 / 长宽比 / ROI 范围 / 跳变门限 / 轨迹外点」多重过滤，用deque维护最近 30 帧轨迹，抗抖动效果稳定。
姿态支持三族：detection/rtmpose.py（RTMPose/RTMO，ONNX Runtime 推理，自动选 GPU/CPU）与 detection/yolo_pose.py（Ultralytics YOLO Pose）。两者统一输出 COCO 17 关键点，便于上层无差别使用。

3. 追踪与统计 tracking/

tracking/player.py 的PlayerTracker按「中线高度」把球员分成upper/lower两区，维护各自的图像历史与球场坐标历史，并计算当前速度、回合平均/最大速度、总距离。write_detection_record()负责把每帧结构化数据交给数据写入器。

4. 可视化 visualization/

visualization/player_pose.py 负责绘制骨架、球员轨迹并用球场坐标过滤场外人员；visualization/court_trajectory.py 绘制球场坐标系轨迹；visualization/stats.py 渲染统计信息。player_positions_zh.py/player_positions_en.py则在分析结束后读取detections.jsonl，生成球员位置热力图与散点图。

5. 数据输出 data/

data/writer.py 提供write_json()与JsonlDetectionWriter，前者写metadata.json（视频参数、模型、球场标注、坐标系），后者逐帧追加detections.jsonl。这份 JSONL 是所有下游分析（热力图、自定义指标、导出表格）的数据源，也是二开最重要的抓手。

四、自定义数据集接入完整指南

想分析自己的比赛视频、训练自己的检测模型，只需按下述四步走，无需改动框架代码。

第 1 步：准备输入视频与球场模板

视频：建议固定机位、球场线清晰。仓库自带示例 videos/demo.mp4。
模板图：从视频里挑一帧「视角稳定、球场线完整」的画面，保存为 PNG。可参考 templates/demo1.png 的形态。

# 最简命令：使用仓库自带示例视频 python main.py --video-path videos/demo.mp4

第 2 步：标注球场四角（关键点）

模板图决定了整套坐标映射的精度，务必认真标注：

不传--template-path时程序会弹出选框；传了则直接读取。
程序先尝试自动检测并保存auto_court_preview.png，窗口按Enter/Y接受，按M/R/Esc进入手动标注。
手动标注时依次点击左上、右上、右下、左下四个角点（如下方示例）。
标注结果缓存到outputs/<视频名>/court_annotations.txt，同目录再次运行会自动复用。

⚠️ 换了拍摄视角 / 裁切方式 / 模板图后，记得删除对应输出目录里的court_annotations.txt重新标注，否则映射会错位。

第 3 步：接入 / 训练你自己的 YOLO 羽毛球检测模型

框架默认使用weights/yolo11s-ball.pt。要换成自己数据集训练的模型，流程是标准的 Ultralytics YOLO 单类目标检测：

整理数据集：按 YOLO 格式组织images/（视频抽帧）与labels/（每帧一个.txt，格式class x_center y_center width height，均为归一化值）。
编写配置data.yaml：

path: ./datasets/badminton train: images/train val: images/val nc: 1 names: [shuttlecock]

训练模型（示例，按需调整）：

yolo detect train data=data.yaml model=yolo11s.pt epochs=50 imgsz=640

接入系统：把导出的.pt权重放到weights/下，通过参数指定即可，无需改代码：

python main.py --video-path 你的视频.mp4 --ball-model weights/你的模型.pt

同理，姿态模型也可替换：--pose-family yolo-pose --yolo-pose-model 你的姿态模型.pt。

第 4 步：运行分析并查看输出

python main.py \ --video-path 你的视频.mp4 \ --template-path 你的模板.png \ --ball-model weights/你的模型.pt \ --language zh

运行结束后，在outputs/<视频名>/下会得到：

文件	说明
`detect_<视频名>.mp4`	带骨架、轨迹、统计、回合编号的标注视频
`detections.jsonl`	逐帧检测记录（球员/手部/球场坐标/速度/羽毛球）
`metadata.json`	视频、模型、球场标注与坐标系元数据
`court_annotations.txt`	球场标注坐标缓存
`position_visualizations/`	球员位置热力图与散点图

也完全可以用 WebUI（pip install -r requirements-webui.txt后python -m webui.app）在浏览器里上传、检测球场、配置参数、查看结果，无需命令行。

五、二次开发路线与常见问题

常见二开切入点：

新增统计指标：基于 data/writer.py 产出的detections.jsonl自行聚合，或在 tracking/player.py 的get_player_movement_stats()里扩展字段。
换检测模型 / 加过滤逻辑：在 detection/shuttlecock.py 与 detection/rtmpose.py 中调整阈值、门限。
改坐标 / 球场模型：调整 court/reference.py 的标准尺寸常量与 court/mapper.py 的映射逻辑。
做批量视频分析：以 webui/pipeline.py 的run_analysis()为蓝本，写一个遍历目录的脚本（README 中标注为开发计划项）。

FAQ：

CPU 能跑吗？能，但姿态与羽毛球检测会明显变慢，更适合短视频或功能验证；GPU（建议 6GB+ 显存）体验最佳。
为什么检测总是「出界」？大概率是模板图 / 四角标错，导致球场坐标映射偏移，请重新标注四角。
如何换语言？--language en切换中英文可视化文字，分别对应player_positions_en.py与player_positions_zh.py。
击球点 / 技术动作统计？目前仍是实验功能，适合研究与二次开发，analyze_shuttlecock()预留了扩展位。