羽毛球为什么飞得又快又飘？Good-Badminton ShuttlecockTracker 轨迹平滑与离群点剔除实战

羽毛球是 AI 眼里最难抓的"移动靶"之一：小、快、带拖影、还随拍形变轨迹。Good-Badminton是一个基于计算机视觉的羽毛球鹰眼分析系统，其核心模块ShuttlecockTracker每帧完成"YOLO 检测 → 候选筛选 → 轨迹平滑 → 离群点剔除"，最终在视频上画出平滑可靠的羽毛球轨迹。这篇文章以 badminton_analysis/detection/shuttlecock.py 的真实实现为主线，讲清这套"四道关卡"是如何工作的。

为什么羽毛球这么难检测？

• 目标小：1080p 全景镜头里，羽毛球往往只有几十个像素
• 速度快：顶级比赛杀球接近 400 km/h，单帧位移可达上百像素
• 检测抖：YOLO 置信度逐帧波动，偶尔把白色广告板、网绳误检成球
• 会消失：过网瞬间、与球员身体重叠时会连续丢检几帧

结果就是原始检测点像"撒了一把碎珠子"，直接连成线会出现明显的跳变和折角。

上图为项目自带示例视频videos/demo.mp4的一帧：羽毛球在画面中只有几个像素，检测模型很难"每帧都稳住"。

四道关卡：ShuttlecockTracker 全貌

追踪器的设计非常直白：每个候选点要闯过四道关，才能被写进轨迹。所有阈值都有默认值，开箱即用：

第一关：候选预过滤，先拦住不合理的框

detect_ball以conf=0.18跑 YOLO 推理，随后_extract_candidates做三重硬性过滤：

1. 面积过滤：框面积占整帧比例超过 0.4% 直接丢弃——真羽毛球不可能这么大；
2. 长宽比过滤：长宽比超过 4.0 的细长框丢弃，排除拖影状误检；
3. ROI 过滤：点必须落在球场区域（按roi_padding_ratio=0.08外扩）内，挡掉观众席、场外的误检。

球场角点来自四角标注（结果缓存在输出目录的court_annotations.txt），ROI 由程序自动生成，无需手动配置。

第二关：多候选评分，用"它该出现在哪"做选择

当一帧返回多个候选框时，追踪器用轨迹线性预测位置打分（shuttlecock.py）：

得分 = 置信度 × 1000 − 与预测位置距离 × 1.4 − 框大小惩罚

"预测位置"来自_predict_next_position：用轨迹最后两点做一步线性外推（末点 + 末速度）。轨迹为空时退化为选置信度最高的候选。效果是：越贴近预测路径的候选得分越高，飘在远处的误检自然落选。

第三关：离群点双门，220 像素和 260 像素各挡一刀

这是轨迹平滑的心脏。update_trajectory中的 _is_outlier 依次做两项检查：

• 跳变门：新点与最近有效点距离 > 220 像素 → 拒绝。真实羽毛球不可能在相邻帧之间"瞬移"；
• 预测门：新点与预测位置距离 > 260 像素 → 拒绝。即使上一个有效点偏旧，也能靠预测兜底。

还有一个细节：两个门只在"连续丢失帧数 ≤ 5"时执行严格判断。也就是说，如果球已经丢失了一段时间，追踪器会放宽门槛、接受"重新落地"的点，避免"一旦错过就永远错过"的死锁。

第四关：短时丢失宽限，5 帧缓冲期

某一帧真的没检测到（或检测被拒）时，追踪器不会立刻清空轨迹，而是让missing_frames加 1；超过 5 帧才把last_valid_position置空。一旦收到有效点，计数立即归零。配合 30 帧的deque轨迹缓冲，得到既有韧性又不会"越拉越长"的平滑曲线。

回合结束时轨迹也会自动清零：在 badminton_analysis/system.py 中，连续 5 帧判定为非球场画面就调用clear_trajectory()，防止上一分的轨迹残留接到新的一分上。

平滑后的轨迹效果：30 帧缓冲 + 渐变大圆点

轨迹以"渐隐点列"绘制：缓冲 30 个历史点，圆点半径从 3 像素渐增到 7 像素，最新一点用橙色高亮（shuttlecock.py）。视觉上越旧越小、越新越大，球的"来路与去向"一目了然。

下面是 WebUI 的真实分析结果：橙色线条即平滑后的羽毛球轨迹，左侧面板是球员的速度、移动距离与回合统计。

快速上手：三步跑通羽毛球鹰眼

git clone https://gitcode.com/gh_mirrors/go/Good-Badminton cd Good-Badminton pip install -r requirements.txt

仓库自带示例视频，一条命令即可运行：

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

分析完成后，outputs/demo/目录下会生成带标注视频、逐帧的detections.jsonl（含羽毛球图像坐标）以及热力图/散点图。完整演示效果如下：

💡 提示：不想敲命令的话，安装 requirements-webui.txt 依赖后运行python -m webui.app，在浏览器里上传视频、点击"运行分析"即可，界面见 webui/app.py。

总结：轨迹为什么能这么稳

ShuttlecockTracker没有依赖单独的高斯滤波之类，而是靠四道关卡在点进入轨迹之前把关：

1. 预过滤：面积 / 长宽比 / ROI 硬筛选，先淘汰"不可能"的检测框；
2. 评分选优：一步线性外推 + 置信度打分，挑最可靠的候选；
3. 离群双门：220 像素跳变门 + 260 预测门，拦住跳变式误检；
4. 丢帧宽限：5 帧缓冲 + 30 帧轨迹，容忍短暂丢失，回合切换时清空轨迹。

这套"先检测、预测辅助、双门拦截"的做法，是不引入额外平滑模型前提下的轻量工程化实现，所有逻辑都集中在 badminton_analysis/detection/shuttlecock.py，方便按自己的视频源调整阈值做二次开发。