简介基于YOLOv8与Streamlit构建的足球检测与跟踪项目面向具备一定Python与深度学习基础的计算机视觉学习者、体育数据分析爱好者及目标检测课程设计者。资源集成完整源码、预训练权重、数据集配置与演示视频覆盖球员、裁判、足球的实时检测球员球队预测球场关键点定位以及足球战术图位置估计等全流程Streamlit界面将功能组织为如何使用、团队颜色、模型超参数和检测三个标签页方便直观调参与观察结果。压缩包共67个文件含py启动脚本、pt模型权重、yaml训练配置、csv标签数据、ipynb实战案例、mp4演示视频以及jpg/png图片样本等整体约380.97MB目录结构清晰。已有422人学习下载适合需要从零搭建足球分析看板、复现运动检测流水线或深入学习YOLOv8应用开发的读者。1. 从「看比赛录像」到「出战术地图」这份YOLOv8Streamlit足球分析项目能解决什么一提起足球视频分析很多人以为训练个YOLOv8检测模型把人框出来就完事真正上手才发现把一堆检测框变成一张可读的战术地图才是整套流程里最磨人的环节。这份资源不是拿YOLOv8演示完目标检测就收工而是把球员、裁判、球的检测、球队颜色聚类、球场关键点透视变换和Streamlit三Tab页面串成一条完整链路上传一段比赛录像在页面里拉动置信度阈值就能看到检测框、跟踪轨迹和一张俯视角度的球员站位地图。适合三类人正在做CV课设或毕设的学生、想快速跑通YOLOv8Streamlit业务流的从业者以及准备用计算机视觉做体育数据采集的爱好者。整份资源自带演示视频、模型权重和配置文件省掉了从零收集数据和训练的时间。2. 环境与启动Streamlit主程序、YOLOv8环境与模型权重2.1 项目里值得先看的三类文件压缩包解压后文件不算少但绝大多数是结果输出和演示素材真正要动的是三类入口脚本、模型权重、配置与文档。先对照下面这张表能少走不少冤枉路。分类文件/目录用途入口main.py、detection.pyStreamlit三Tab页面入口YOLOv8检测与跟踪逻辑模型models/Yolo8L Players.pt、models/Yolo8M Field Keypoints.pt一个做球员/裁判/球检测一个做球场关键点检测配置config players dataset.yaml、config pitch dataset.yaml类别定义与数据集信息训练和推理共用数据pitch map labels position.json、test vid.mp4、demo_vid_1.mp4、demo_vid_2.mp4战术地图坐标基准与演示视频输出outputs/、tactical map.jpg推理结果与战术地图样例用来判断程序是否跑通models里的两个权重是这份资源的「黑匣子」你不知道内部细节也能直接加载但得知道分工后面调参数才不会懵。config目录下两个yaml是YOLOv8标准格式类别编号和数据集路径都在里面想换自己的数据集入口就在这里。pitch map labels position.json是战术地图的关键基准会在第4章展开讲。2.2 environment.yml与requirements.txt为什么两套依赖都要装这类压缩包通常同时带conda的environment.yml和pip的requirements.txt。只看pip一个图省事翻车的概率不小environment.yml会把Python解释器和conda渠道的依赖一起锁进环境requirements.txt则补上pip源里的细粒度依赖两套一起用才稳妥。# 用conda创建环境环境名以environment.yml里的命名为准这里用football_analytics举例 conda env create -f environment.yml conda activate football_analytics # 进入项目根目录后再补装pip格式的依赖避免遗漏 pip install -r requirements.txt环境名不要自己脑补装完先执行conda env list确认实际创建出来的名字activate后再跑pip否则会装进base环境。核心依赖是ultralytics、opencv-python、streamlit和scikit-learnGPU机器要额外确认PyTorch装的是CUDA版而不是CPU版CPU机器上直接按默认装就行。像GTX1660Ti这种级别跑YOLOv8L的640输入单帧推理大概几十毫秒Streamlit页面每秒刷几帧完全够用纯CPU会明显卡顿后面会讲到抽帧方案。如果模型文件损坏或缺失Ultralytics官方release里有对应的yolov8l.pt和yolov8m.pt预训练权重替换后保持文件名一致代码不用改。这就是「yolov8预训练权重下载」在这个项目里的正确打开方式权重已经放在本地了不需要每次都去下载但出了问题要知道去哪补。2.3 启动Streamlit跑通页面的最快路径依赖装完不要急着改代码先原样把页面拉起来。Streamlit的入口是main.py很多人习惯双击运行python main.py其实不行它必须由streamlit命令启动。# 在项目根目录执行默认端口8501 streamlit run main.py # 如果端口被占用换端口 streamlit run main.py --server.port 8502--server.port用来显式改端口浏览器缓存和WebSocket端口不一致时能避开不少怪问题。启动后浏览器会自动打开本地页面第一次加载模型权重会等几秒这是正常的。页面顶端有三个Tab如何使用、团队颜色、模型超参数和检测。先点「如何使用」看官方演示路径不要一上来就去调阈值。Streamlit和Gradio相比tabs加color_picker这套交互更适合做「用户自助演示」而不是「AI对话」这也是这份资源选Streamlit而不是Gradio的原因。提示CPU机器上跑YOLOv8L建议把视频处理帧率降到5fps以下或者在Streamlit里加一个抽帧开关否则页面会卡到怀疑人生。这一步能跑通就证明环境和模型文件都正常。如果页面起来了但点检测没反应问题基本在detection.py的输入输出下面第3章把它讲透。3. 检测与跟踪YOLOv8两个模型的选型理由与跟踪关键参数3.1 球员检测与球场关键点为什么要拆成两个YOLOv8模型第一次看models目录很多人会问为什么不像大多数演示那样放一个yolov8s.pt而是放Yolo8L Players和Yolo8M Field Keypoints两个原因在于任务类型不一样。球员/裁判/球检测是标准目标检测输出的是矩形框球场关键点检测是回归任务输出一组坐标。两个任务拼在同一个模型里检测头的损失和关键点回归的损失会互相抢权重训练阶段很难平衡。拆成两个模型后各自用最适合的规模球员这种小目标多、重叠多的场景用LLarge版更扛关键点只需要十来个点用MMedium版就够推理还快一截。这和做文字识别时把「文字检测」和「方向分类」拆成两个模型的思路一样职责单一出了问题也好定位。模型任务输出选型理由Yolo8L Players球员/裁判/球检测检测框类别置信度小目标多、人群密集L版容量大Yolo8M Field Keypoints球场关键点回归关键点坐标点数少M版推理速度更快3.2 detection.py的模型加载与推理参数detection.py是整套程序的推理核心main.py里的每个Tab最终都会绕到它。前半段负责加载两个模型后半段包了一层可复用的检测函数。下面这段是项目里最常改的入口from pathlib import Path from ultralytics import YOLO ROOT Path(__file__).parent # 用脚本自身所在目录避免工作目录不同导致加载失败 player_model YOLO(ROOT / models / Yolo8L Players.pt) keypoint_model YOLO(ROOT / models / Yolo8M Field Keypoints.pt) def detect_players(frame, conf0.35, iou0.5): # classes的编号顺序以config players dataset.yaml里定义的类别为准 # 常见约定是 0球员 1裁判 2球但请以yaml内容为准 results player_model(frame, confconf, iouiou, classes[0, 1, 2]) boxes results[0].boxes.xyxy.cpu().numpy() # 左上右下坐标 labels results[0].boxes.cls.cpu().numpy() # 类别编号 scores results[0].boxes.conf.cpu().numpy() # 置信度 return boxes, labels, scores用Path(file).parent拼路径而不是写死相对路径是这类项目的标配操作。Streamlit启动时的工作目录不一定在项目根目录加上模型文件名里带空格直接写models/Yolo8L Players.pt很容易FileNotFoundError。classes参数用来过滤类别漏检球的时候把球所在类别单独拿出来重检就是改这里。返回结果加.cpu().numpy()是因为ultralytics默认在GPU上输出张量直接返回给Streamlit做后续处理容易类型不匹配。conf是置信度阈值任何类别低于它的框都会被丢掉。球员目标大、特征明显0.35到0.4都行足球只有小半个巴掌大默认0.5基本会把球全滤掉控制在0.25到0.3才算合理。iou是NMS抑制阈值球场上球员互相遮挡严重iou0.5会保留更多框0.7则会压掉大量重叠框。训练时的epochs、lr影响的是权重推理时的conf、iou影响的是输出这是「yolov8模型训练参数含义」和推理参数在工程上的分工。如果你想用这份资源在自己的数据集上重新走一遍「yolov8训练自己的数据集」流程config players dataset.yaml就是入口类别名、数据集路径和nc字段都写在里面。3.3 跟踪不是玄学IoU帧间匹配与track API检测只回答「这一帧有谁、在哪里」跟踪要回答「上一帧的球员是不是这一帧的球员」。项目里的跟踪有两条路轻量方案是自己写IoU匹配重型方案是直接用ultralytics内置的ByteTrack。先看IoU匹配的简化逻辑def iou(box1, box2): 两个矩形框的交并比0代表完全不重叠1代表完全重合 # 计算相交面积与并集面积的比值这是常规实现 ... def associate(prev_tracks, dets, iou_thr0.3): matched [] for track_id, track_box in prev_tracks.items(): best_iou, best_det 0.0, None for det in dets: score iou(track_box, det[box]) if score best_iou: best_iou, best_det score, det # 交并比超过阈值才认为是同一个目标 if best_iou iou_thr and best_det is not None: matched.append((track_id, best_det)) dets.remove(best_det) return matchedIoU匹配的核心假设是相邻帧里同一目标的位置足够接近框的重叠大就是同一人。这个逻辑在机位固定的足球录像里表现很好镜头几乎不动球员移动也不会瞬间跨过大半个画面。iou_thr取0.3是常用起点低于0.2会频繁开新轨迹高于0.5会把高速跑动的球员尾巴弄丢。Ultralytics也自带track接口一行就能换ByteTrackresults player_model.track(frame, trackerbytetrack.yaml, persistTrue, conf0.35, iou0.5)persistTrue表示帧与帧之间保留轨迹ID千万别漏写否则每帧都会重新编号。ByteTrack对遮挡和短暂出镜更稳但比手写IoU匹配多花一点计算量。怎么判断跟踪质量看帧画面里轨迹号是否连续跳动就行轨迹号一帧一个样说明persist没生效或者阈值太激进。注意不管是手写匹配还是ByteTrack跟踪都是在检测之后做检测漏了目标跟踪一定跟着断。所以排查跟踪问题永远先看检测框稳不稳再查跟踪参数。4. 从检测框到战术地图球队颜色聚类与球场坐标映射4.1 球队颜色聚类HSV空间与KMeans的配合球员检测框有了但两队球员在画面里都是「人」的框怎么区分主队客队常见做法是在HSV空间对球衣像素做KMeans聚类把球员分成两类。为什么在HSV而不是RGB里做因为RGB三通道对光照太敏感同一个红色球衣在阳光直射和阴影下能差出很远HSV把色相H单独拎出来H值在光照变化时相对稳定聚类结果更可信。import cv2 import numpy as np from sklearn.cluster import KMeans def get_team_colors(frame, boxes, n_clusters2): pixels [] for (x1, y1, x2, y2) in boxes.astype(int): roi cv2.cvtColor(frame[y1:y2, x1:x2], cv2.COLOR_BGR2HSV) # 过滤草皮和短裤饱和度过低、亮度太低或太亮的像素都不要 mask (roi[..., 1] 60) (roi[..., 2] 60) (roi[..., 2] 230) pts roi[mask].reshape(-1, 3) if len(pts) 500: pts pts[:500] # 限制每框采样数防止几万像素全进内存 pixels.extend(pts) if len(pixels) 10: return None km KMeans(n_clustersn_clusters, random_state0, n_init10).fit(np.array(pixels)) return km.cluster_centers_ # 两队的HSV主色返回后转RGB给页面展示先裁出每个球员框内的区域过滤掉饱和度和亮度异常的像素这些通常是草皮、短裤和阴影。每框最多取500个像素是为了控制KMeans的输入规模一帧20个框上限也就1万像素聚类速度在可接受范围内。n_init10让KMeans跑10次选最优结果避免随机初始化把聚类带偏。返回的cluster_centers_是两队主色中心点转成RGB后能直接回显到Streamlit的颜色选择器里用户一眼就能看出颜色分对没分对。裁判球衣通常是黑色或深色在HSV里V通道很低这段代码在聚类前就把它们排除了。如果两队球衣颜色接近比如白对浅灰算法会很吃力所以「团队颜色」Tab里留了手动选主客队颜色的入口算法分不清时人工兜底这个设计很务实算法不硬扛给用户留一颗「后悔药」。4.2 战术地图球场关键点与透视变换拿到所有人的检测框后下一个问题是「他站在球场哪个位置」。比赛录像一般是斜向机位拍摄的直接画坐标会得到一堆压扁的点必须做透视变换。Yolo8M Field Keypoints输出的球场关键点对应像素坐标系下的场地线交点pitch map labels position.json里存着同一批点在俯视图中的真实位置。一组src一组dst刚好能算出单应矩阵H。import cv2 import numpy as np # src_pts来自keypoint_model输出的球场关键点像素坐标 # dst_pts来自pitch map labels position.json中对应的球场俯视坐标 H, _ cv2.findHomography(src_pts, dst_pts, cv2.RANSAC, 5.0) def map_position(box): 把检测框的底边中点映射到战术地图 x1, y1, x2, y2 box.astype(np.float32) foot_point np.array([[[(x1 x2) / 2.0, y2]]]) # 用脚底而不是框中心 mapped cv2.perspectiveTransform(foot_point, H) return mapped[0][0]findHomography用RANSAC迭代计算能容忍少量关键点误检。为什么用脚底中心而不是框中心因为人的高度在图像里随距离变化框的中点大概在地面以上一米的位置投到俯视图会往前偏移脚底永远贴在地面上坐标天然可信。这是一行代码的差别但战术地图的位置准确度全看它。RANSAC的5.0是重投影误差阈值单位是像素阈值太小会把有效点当外点剔除太大会混入噪声。比赛中球员频繁遮挡关键点导致H抖动时比较稳的方案是保留上一帧的H继续用等关键点数量恢复再更新这是静止机位场景下稳定战术地图的常规做法。有了H之后所有球员框和球框底边都能映射到同一张俯视图上这就是「足球地图上球员和球位置的估计」的核心逻辑。注意findHomography的src_pts和dst_pts顺序必须一一对应编号错一位战术地图上的位置就会整体偏移甚至出现镜像。4.3 position.json与输出目录检测结果如何沉淀Streamlit上的实时画面是给人看的position.json是给程序用的沉淀。detection.py处理完一帧视频后会把球员、球的坐标、队伍标签和跟踪ID写进position.jsonoutputs目录里的tactical map.jpg就是把这些坐标按时间轴画到俯视图上的结果。position.json的字段通常包含帧号、目标类型、队伍标签、透视后的战术坐标具体字段名以项目内代码为准。当我需要统计球员跑动距离、热区分布时会直接读这个json而不是重新跑一遍检测。十几分钟的视频重跑一遍推理太贵了提前落盘就是给后续分析留的后悔药。demo_vid_1.mp4跑完能在outputs目录看到几张图和json文件这是判断「复制代码是否成功」的第一道依据。5. 可视化交互与常见问题排查Streamlit三Tab页的设计与踩坑5.1 三个Tab页的职责与参数暴露main.py用Streamlit的st.tabs把页面划分成三个区块如何使用、团队颜色、模型超参数和检测。这个分层很有用第一个Tab解决「不会用」的问题第二个解决「颜色分不清」的问题第三个解决「检测效果不满意」的问题。用户绝大多数疑问都不用翻代码在页面上就能调到答案。import streamlit as st tab_guide, tab_team, tab_detect st.tabs([如何使用, 团队颜色, 模型超参数和检测]) with tab_guide: st.markdown(上传或选择demo视频后去第三个Tab调阈值点开始检测右侧出战术地图。) with tab_team: home_color st.color_picker(主队颜色, #e74c3c) # 默认红色 away_color st.color_picker(客队颜色, #3498db) # 默认蓝色 # 页面选出来的hex颜色转RGB后会和前面KMeans聚类结果做二次匹配 with tab_detect: conf st.slider(置信度阈值 conf, 0.10, 0.90, 0.35, 0.05) iou st.slider(NMS阈值 iou, 0.10, 0.90, 0.50, 0.05) if st.button(开始检测): # 调detection.py跑视频把结果画到帧上并更新战术地图 st.image(tactical map.jpg, caption实时战术地图)st.tabs返回三个容器对象with语句把控件各自放进去页面逻辑互不干扰。color_picker返回的是十六进制字符串比如#e74c3c送到detection.py之前要解析成RGB数组。slider的四个参数依次是label、最小值、最大值、默认值、步长步长0.05是为了让用户在微调时有足够精细度。这个页面的价值在于把「模型参数含义」变成可见可拉的东西球漏检时拉低conf两框重叠太多时拉高iou效果实时反馈在检测结果里。有人纠结Streamlit和Gradio怎么选这个项目已经给出了答案tabs、color_picker、slider这一套组合让用户在不写代码的情况下完成「选视频-调参-看结果」的闭环Gradio更擅长对话式演示做这种带状态的多页分析略吃力。5.2 五个最常见问题从依赖版本到坐标错乱这套项目我跑过不止一次也见过别人踩过各种坑。下面5条是最典型的问题每一条按「现象 → 原因 → 解决」的顺序写。第1条ImportError: cannot import name YOLO from ultralytics。现象是detection.py一执行就报导入错误。原因是当前环境里的ultralytics版本过旧或者压根没装进当前环境。解决先确认conda环境名是否激活对执行conda list ultralytics看版本不对就重装pip install -U ultralytics再跑python -c from ultralytics import YOLO验证。第2条模型文件路径找不到。现象是models目录就在项目里加载权重仍报FileNotFoundError。原因是Streamlit的工作目录和脚本所在目录不一致相对路径失效文件名里带空格在Windows上更容易出岔子。解决按3.2节的写法用Path(file).parent拼路径不要依赖os.getcwd()。这条是路径类问题的通用解法。第3条浏览器里demo视频黑屏不播放。现象是页面里的视频控件一片黑用播放器打开mp4却正常。原因是录屏工具保存的视频多是H.265编码浏览器的video标签不认。解决用ffmpeg把编码转成H.264ffmpeg -i demo_vid_1.mp4 -c:v libx264 demo_vid_1_h264.mp4转完再上传到页面。这条在高码率足球录像里几乎必踩。第4条球完全检测不到或频繁断检。现象是页面里球员框正常唯独球框一帧有、连续几帧没有。原因是足球在远摄像头视角下只有几个像素默认conf0.5把它全滤掉了。解决把球这一类单独拉低conf到0.25到0.3或者把输入尺寸imgsz从640调大到960小目标在特征图上的响应会更好。注意小目标在置信度上天然吃亏不要指望用iou去救它。第5条战术地图上的点乱飞或成镜像。现象是地图上的人位置和画面明显对不上甚至左右颠倒。原因是src_pts与dst_pts没有按顺序对应或者关键点模型把两端球门标反了。解决先在一帧上画关键点并编号把编号后的图像和pitch map的编号逐一比对确认对应关系后再进findHomography同时固定用一个排序函数对关键点排序不要手填坐标。这类问题排查起来很耗耐心我的习惯是先画图验证再算H绝不去猜。6. 验证与进阶技巧一条命令跑通demo视频与场地迁移项目拿到手别急着改代码先用最朴素的链路验证在项目根目录跑一遍detection.py处理demo_vid_1.mp4然后去outputs目录检查是否有tactical map.jpg和一帧帧带框的截图。若有再执行streamlit run main.py把demo_vid_2.mp4放进去在「团队颜色」里选好主客队颜色把conf拉到0.3点「开始检测」页面右侧出现战术地图就说明全链路通了。这个顺序的关键在于把「模型环境」和「页面交互」两层分开验证。验证步骤预期结果不通过时看哪detection.py跑demo_vid_1outputs里出现战术地图和json3.2节模型加载、5.2节第1/2条streamlit run main.py三个Tab页面正常打开2.3节启动命令、5.2节第3条页面跑demo_vid_2且调低conf球框稳定出现、地图点不飘5.2节第4/5条如果想把这套框架挪去别的场地不需要重头调整整个体系。球场关键点检测模型可以保留只换pitch map labels position.json里的dst坐标把新场地的俯视图关键点按同样顺序填入H矩阵会自动适配。把Yolo8L Players换成你用自己的数据集微调过的版本整套分析框架改做篮球、橄榄球甚至动物行为分析都没有问题用labelme标注转成YOLO格式训练出来的权重在这个项目里可以直接替换Streamlit那层完全不用动。真要把这套东西部署到RK3588这种板子上做边缘推理ultralytics的pt权重需要先转ONNX再转RKNNStreamlit的部分要换成轻量级后端那是另一条技术线。这份资源解决的是PC端研究、演示和出数据的场景边缘部署是后续话题。有一次我把demo_vid_1换成了某场正式比赛的集锦没改任何参数结果守门员背后的广告牌被当成了球员战术地图上多了几个乱跳的点。从那以后我每次跑视频分析项目都强制走一遍这个验证顺序先关掉页面用纯脚本出中间结果再开Streamlit看交互两层分开定位问题再也不在页面和终端之间瞎猜。希望帮到你。本文还有配套的精品资源点击获取