sports 开源仓库深度解读:用计算机视觉构建体育分析工具链(球追踪、球员追踪、球场关键点与雷达可视化)

原创2026-10-14 10:00:101,963 阅读
文章标签:计算机视觉人工智能深度学习机器学习图像处理视频处理

sports 开源仓库深度解读:用计算机视觉构建体育分析工具链(球追踪、球员追踪、球场关键点与雷达可视化)

本文以 sports 开源仓库(Roboflow 旗下以体育为测试场景的计算机视觉项目)为主线,系统梳理其技术定位、五大核心挑战、从源码安装的方式、配套数据集与训练资源,并结合 examples/soccer 足球示例与 sports 包源码,逐层剖析球追踪、球员追踪、球队分类与雷达可视化等完整工具链的实现原理。读完本文,你将掌握如何在 Python 3.8+ 环境中快速搭建一套可复用的体育视频分析管线,并理解其中每个组件的底层机制。

项目定位:为什么用体育来"拷问"计算机视觉

sports 是一个以体育场景为测试场、推动目标检测(object detection)、图像分割(image segmentation)、关键点检测(keypoint detection)与基础模型(foundational models)能力上限的开源仓库。其核心理念正如根目录 README.md 所描述:在体育竞技中,每一厘米、每一秒都至关重要,因此体育成为检验视觉模型极限的理想场景。仓库产出的不是单个模型,而是一系列可复用的工具(reusable tools),这些工具不仅适用于体育,也可以迁移到更广泛的视觉分析任务中。

仓库整体结构分为两个层次:

  • sports/ 包:存放可复用的核心模块,包括球场标注器(sports/annotators/soccer.py)、球场配置(sports/configs/soccer.py)以及球追踪、球队分类、视角变换等通用组件(sports/common/);
  • examples/soccer/:基于上述组件构建的端到端足球视频分析示例,提供 6 种可独立运行的处理模式(详见后文)。

配套的 Python 包元数据定义在 setup.py,版本号为 0.1.0,声明 python_requires=">=3.8",核心依赖包括 supervision、numpy、opencv-python、transformers、umap-learn、scikit-learn、tqdm、sentencepiece 与 protobuf。

五大技术挑战:仓库要解决的核心难题

根 README 明确列出了当前重点攻关的五大挑战,它们既是体育分析场景的痛点,也是整个仓库技术选型的出发点:

  1. 球追踪(Ball tracking):足球体积小、运动速度快,在高分辨率视频中追踪难度极大。仓库给出的工程解法是基于 InferenceSlicer 分块推理加轨迹缓冲(详见"球检测与球追踪"一节)。
  2. 球衣号码识别(Reading jersey numbers):视频模糊、球员转身、号码被其他物体遮挡,都会严重影响识别准确率,这也是仓库中"篮球球衣号码 OCR"数据集存在的意义。
  3. 球员追踪(Player tracking):全场比赛中球员频繁相互遮挡,如何保持跨帧身份一致是一大挑战,示例中使用 ByteTrack 追踪器应对。
  4. 球员再识别(Player re-identification):球员离场后重新入画、摄像机运动、球员外观相似,都会导致身份错乱,需要结合外观特征与时空信息综合判断。
  5. 摄像机标定(Camera calibration):要从画面中提取球员速度、跑动距离等高级统计,必须准确标定摄像机视角。仓库通过球场关键点检测加单应矩阵变换(ViewTransformer)来解决这一动态标定问题。

安装指南:从源码安装 sports

根 README 明确指出:该仓库目前没有发布独立的 Python 包,需要从源码安装。适用前提是 Python>=3.8 环境。安装命令如下:

pip install git+https://github.com/roboflow/sports.git

如果你使用的是本仓库镜像,也可直接通过 git clone 获取源码后在本地环境中配置依赖:

git clone https://gitcode.com/gh_mirrors/sp/sports
cd sports
pip install -e .

上述 pip install -e . 会依据 setup.py 中的 install_requires 自动安装 supervision、numpy、opencv-python、transformers、umap-learn、scikit-learn、tqdm、sentencepiece 与 protobuf。需要说明的是,运行完整示例还需要额外安装 ultralytics(用于加载 YOLOv8 模型)与 gdown(用于下载权重和数据),这两项在示例目录的 requirements.txt 中列出:

pip install ultralytics gdown

配套数据集与模型训练资源

数据集一览

根 README 以表格形式列出了仓库配套的 5 个数据集(托管于 Roboflow Universe,可自行检索下载),覆盖足球与篮球两大场景:

应用场景 数据集
⚽ 足球球员检测 football-players-detection
⚽ 足球球检测 football-ball-detection
⚽ 足球场关键点检测 football-field-detection
🏀 篮球场关键点检测 basketball-court-detection
🏀 篮球球衣号码 OCR basketball-jersey-numbers-ocr

其中足球相关的原始数据来源于 DFL - Bundesliga Data Shootout 竞赛数据,经过处理形成了上述可直接用于训练的数据集。

训练笔记本:三步复现检测模型

仓库在 examples/soccer/notebooks/ 下提供了 3 个 Colab 风格的训练笔记本,分别对应球员检测、球检测与球场关键点检测,均可直接基于 YOLOv8 从头训练:

三个笔记本遵循同一套流程:配置 Roboflow API Key → 验证 GPU → 安装依赖 → 下载数据集 → 执行 YOLO 训练 → 在验证集上评估并导出权重。训练产出的 best.pt 权重即可用于下方示例管线。

足球 AI 示例:六种分析模式实战

examples/soccer/README.md 与 main.py 共同定义了足球视频分析的完整示例。示例依赖三个训练好的模型权重(存放在 examples/soccer/data/ 目录):

  • football-player-detection.pt:检测球员(PLAYER_CLASS_ID = 2)、门将(GOALKEEPER_CLASS_ID = 1)、裁判(REFEREE_CLASS_ID = 3)以及球(BALL_CLASS_ID = 0);
  • football-ball-detection.pt:专用于球的检测;
  • football-pitch-detection.pt:检测球场边界与 32 个关键点。

setup.sh 会自动创建 data/ 目录,并借助 gdown 下载上述 3 个模型权重和 5 段德甲比赛视频(如 2e57b9_0.mp4)。完整环境准备:

cd examples/soccer
pip install -r requirements.txt
./setup.sh

随后通过 main.py 运行,命令行参数如下(定义见 main.py):

参数 含义 默认值
--source_video_path 输入视频路径 必填
--target_video_path 输出视频路径 必填
--device 推理设备,如 cpu、cuda、mps cpu
--mode 运行模式(见下) PLAYER_DETECTION

模式一:PITCH_DETECTION(球场关键点检测)

该模式用球场检测模型逐帧推理,通过 sv.KeyPoints.from_ultralytics(result) 提取 32 个球场关键点,再用 VertexLabelAnnotator 绘制关键点编号标签(标签与配色来自 SoccerPitchConfiguration,见 sports/configs/soccer.py)。

python main.py --source_video_path data/2e57b9_0.mp4 \
--target_video_path data/2e57b9_0-pitch-detection.mp4 \
--device mps --mode PITCH_DETECTION

该模式的直接用途是识别和可视化球场布局,同时为 RADAR 模式提供单应变换所需的对应点。

模式二:PLAYER_DETECTION(球员检测)

对每帧以 imgsz=1280 运行球员检测模型,用 BoxAnnotator 与 LabelAnnotator 绘制检测框与类别标签:

python main.py --source_video_path data/2e57b9_0.mp4 \
--target_video_path data/2e57b9_0-player-detection.mp4 \
--device mps --mode PLAYER_DETECTION

模式三:BALL_DETECTION(球检测与球追踪)

球体积小,直接整帧推理容易漏检,因此示例采用了两级策略(实现见 main.py):

  1. 分块推理:使用 sv.InferenceSlicer 将画面切成 640×640 的切片逐块推理(overlap_filter_strategy=sv.OverlapFilter.NONE),随后对合并结果执行 with_nms(threshold=0.1);
  2. 轨迹缓冲追踪:将每帧检测结果送入 BallTracker(buffer_size=20)。
python main.py --source_video_path data/2e57b9_0.mp4 \
--target_video_path data/2e57b9_0-ball-detection.mp4 \
--device mps --mode BALL_DETECTION

BallTracker 的实现位于 sports/common/ball.py:内部维护一个 deque(maxlen=buffer_size) 缓冲近期球心位置,计算缓冲位置的质心,然后选取当前帧检测中离质心最近的检测作为本帧球的输出,从而在漏检时保持轨迹连贯。绘制部分使用 BallAnnotator(radius=6, buffer_size=10),它以 deque 缓冲最近若干帧的球坐标,并按 jet 色板给不同帧的圆圈着色、根据缓冲长度插值半径,形成"轨迹拖尾"的视觉效果。

模式四:PLAYER_TRACKING(球员追踪)

在球员检测的基础上叠加 sv.ByteTrack(minimum_consecutive_frames=3) 追踪器,通过 tracker.update_with_detections(detections) 为每个检测分配跨帧稳定的 tracker_id,并以椭圆标注(EllipseAnnotator)加 ID 标签呈现:

python main.py --source_video_path data/2e57b9_0.mp4 \
--target_video_path data/2e57b9_0-player-tracking.mp4 \
--device mps --mode PLAYER_TRACKING

该模式解决的是"全场球员频繁遮挡下保持身份一致"的挑战。

模式五:TEAM_CLASSIFICATION(球队分类)

这是示例中最具"基础模型"色彩的模式。流程(实现见 main.py)分为两个阶段:

离线训练阶段:先以 STRIDE = 60 的帧步长采样视频帧,裁剪出所有球员目标(class_id == PLAYER_CLASS_ID),构成训练集 crops;随后实例化 TeamClassifier(device=device) 并调用 fit(crops) 学习两类簇中心。

在线推理阶段:对每帧执行球员检测 + ByteTrack 追踪,将球员裁剪图交给 team_classifier.predict(crops) 得到 players_team_id;门将(GOALKEEPER_CLASS_ID)不参与聚类,而是通过 resolve_goalkeepers_team_id 依据离两队球员质心(BOTTOM_CENTER 锚点均值)的欧氏距离就近归属(main.py);裁判单独成类。最终用合并后的 color_lookup 为椭圆标注着色,区分两队与裁判。

python main.py --source_video_path data/2e57b9_0.mp4 \
--target_video_path data/2e57b9_0-team-classification.mp4 \
--device mps --mode TEAM_CLASSIFICATION

TeamClassifier 的核心链路定义在 sports/common/team.py,由三个环节组成:

  • 特征提取:加载 google/siglip-base-patch16-224 的 SiglipVisionModel,将球员裁剪图(经 sv.cv2_to_pillow 转 PIL)按 batch_size=32 分批送入,取 last_hidden_state 的均值池化作为嵌入向量(默认 device='cpu');
  • 降维:umap.UMAP(n_components=3) 将高维嵌入降到 3 维;
  • 聚类:KMeans(n_clusters=2) 将球员聚成两队。

模式六:RADAR(雷达图可视化)

RADAR 模式将球场检测、球员检测、追踪与球队分类整合,实时生成球员位置雷达图并叠加到画面右下角。关键步骤(main.py):

  1. 球场模型输出关键点,过滤置信度低的点((x > 1) & (y > 1));
  2. 以球场关键点为源、SoccerPitchConfiguration.vertices 中对应点为目标,构造 ViewTransformer 求单应矩阵;
  3. 将球员 BOTTOM_CENTER 锚点坐标经 transform_points 映射到标准球场平面;
  4. 用 draw_pitch 绘制球场底图,再按队伍颜色调用 draw_points_on_pitch 绘制位置点;
  5. 雷达图缩放至半屏宽度后以 50% 透明度叠加到原画面。
python main.py --source_video_path data/2e57b9_0.mp4 \
--target_video_path data/2e57b9_0-radar.mp4 \
--device mps --mode RADAR

从源码结构看,RADAR 模式是前面五种能力的综合出口,能够以俯瞰视角直观呈现球员跑位与球队阵型。

源码级解析:sports 包中的可复用组件

球场配置与绘制:SoccerPitchConfiguration 与 annotators

SoccerPitchConfiguration(sports/configs/soccer.py)以 dataclass 定义了标准足球场的全部几何参数(单位:厘米):

参数 默认值 含义
width 7000 球场宽度
length 12000 球场长度
penalty_box_width 4100 禁区宽度
penalty_box_length 2015 禁区纵深
goal_box_width 1832 小禁区宽度
goal_box_length 550 小禁区纵深
centre_circle_radius 915 中圈半径
penalty_spot_distance 1100 点球点距球门距离

该配置类通过 vertices 属性(@property)推导出 32 个关键点坐标(含边线、禁区、中圈、点球点),edges 属性给出 32 条连线关系,labels 提供与关键点检测模型一致的 32 个标签编号("01"–"32",顺序与顶点编号对应),colors 定义了分组配色(粉红 #FF1493、深蓝 #00BFFF、橙红 #FF6347)。

sports/annotators/soccer.py 在此基础上提供 4 个绘制函数,全部以 scale=0.1、padding=50 为默认值(即把 12000×7000 cm 的球场缩放到约 1200×700 像素的画布):

  • draw_pitch(config, ...):绘制球场底图——填充草地绿背景 sv.Color(34, 139, 34),用 cv2.line 按 edges 连线,用 cv2.circle 绘制中圈与两个点球点;
  • draw_points_on_pitch(config, xy, ...):在底图上按坐标绘制位置点(默认红心黑边、半径 10px),xy 为已映射到球场坐标系的点集;
  • draw_paths_on_pitch(config, paths, ...):按轨迹点序列绘制折线,用于展示球员跑动路径;
  • draw_pitch_voronoi_diagram(config, team_1_xy, team_2_xy, ...):为两支球队分别计算每个像素到各队球员的最近距离,生成"控制区域"掩码(min_distances_team_1 < min_distances_team_2),再以 cv2.addWeighted 按 opacity=0.5 叠加,直观展示场上空间控制权。

视角变换:ViewTransformer

ViewTransformer 是摄像机标定与雷达映射的核心。其构造函数接收源点与目标点(均须为相同形状的二维坐标),通过 cv2.findHomography(source, target) 计算单应矩阵;transform_points 用 cv2.perspectiveTransform 把图像平面坐标映射到球场平面坐标;transform_image 则用 cv2.warpPerspective 做整图透视变换。它在 RADAR 模式中承担"画面坐标 → 标准球场坐标"的关键转换,也是未来提取速度、跑动距离等高级统计的基础设施。

从挑战到能力:示例与仓库的对应关系

将根 README 的挑战声明与源码实现对照,可以清晰地看到仓库的技术闭环:

挑战 对应解法 依据
球追踪 切片推理 + BallTracker 质心缓冲 main.py、ball.py
球员追踪 ByteTrack 跨帧 ID 关联 main.py
球员再识别 SigLIP 外观嵌入 + UMAP + KMeans team.py
摄像机标定 球场关键点 + ViewTransformer 单应变换 view.py、main.py

路线图与开源许可

根 README 与示例 README 均表达了欢迎社区贡献的态度,感兴趣的开发者可以围绕仓库列出的挑战方向参与共建。当前示例明确记录的后续规划包括:为 RADAR 模式添加平滑以消除闪烁、新增"保存数据并离线分析"的笔记本演示。

许可方面,仓库本身由 setup.py 声明为 MIT 协议;但示例中集成的 YOLOv8(ultralytics)遵循 AGPL-3.0 协议,二者在商业使用时需分别遵守对应许可条款。

小结

sports 仓库的价值不在于提供开箱即用的"最强模型",而在于它系统展示了如何把目标检测、关键点检测、追踪、聚类与几何变换组装成一条完整的体育视频分析管线:从 SoccerPitchConfiguration 的标准球场建模,到 annotators 的多样化可视化,再到 BallTracker、TeamClassifier 与 ViewTransformer 三个通用组件,以及 examples/soccer/main.py 中六种模式的端到端示例,每一层都有清晰的职责边界和可复用的接口。无论你是想快速跑通一个足球分析 Demo,还是想借鉴其组件设计思路搭建自己的体育分析系统,这个仓库都提供了完整且可验证的参照实现。

登录后查看全文
sports