Tiger AI Plateform项目中羽毛球分析模块的技术实现、依赖环境、模型权重、API 接口与使用流程

羽毛球分析模块文章目录羽毛球分析模块1. 模块概述2. 技术栈2.1 前端2.2 后端2.3 架构示意3. 分析流程3.1 端到端步骤3.2 球场映射3.3 自动球场检测3.4 球员追踪与统计3.5 视频 HUD 叠加3.6 分析产物4. 依赖与环境4.1 Python 依赖羽毛球分析相关4.2 安装与启动4.3 硬件建议4.4 存储配置5. 模型与权重5.1 姿态模型必选系统预置常见手动添加同样支持5.2 羽毛球检测模型可选5.3 RTMO 权重拉取说明6. 使用流程6.1 首次准备6.2 分析一场视频6.3 叠加层选项7. API 接口7.1 自动球场检测7.2 提取首帧可选7.3 启动分析异步7.4 查询进度7.5 下载产物8. 权限说明9. 关键代码索引10. 常见问题Q1提示「姿态模型须为 ultralytics 或 rtmlib」Q2RTMO 报错 No module named rtmlibQ3自动球场检测失败Q4没有羽毛球轨迹 / 回合数始终为 0Q5分析完成后刷新页面找不到结果Q6五种姿态模型是否都支持Q2RTMO 报错 No module named rtmlibQ3自动球场检测失败Q4没有羽毛球轨迹 / 回合数始终为 0Q5分析完成后刷新页面找不到结果Q6五种姿态模型是否都支持本文档说明 CV Python Tigerpro 项目中羽毛球比赛视频分析功能的技术实现、依赖环境、模型权重、API 接口与使用流程。1. 模块概述羽毛球分析模块位于前端菜单视觉识别 → 羽毛球分析路由/ai/badminton对比赛视频进行逐帧处理输出带标注的结果视频及统计数据。核心能力能力说明球场映射四角单应性变换将像素坐标映射到标准球场5.18 m × 13.4 m自动球场检测Hough 线段 几何约束上传视频后自动预填四角可手动修正球员姿态YOLO Poseultralytics或 RTMOrtmlibCOCO-17 骨架羽毛球追踪可选 Ultralytics YOLO 检测权重球场内最高置信度目标移动统计速度、距离、回合内/全场统计视频 HUD左侧球员数据面板 右上 HAWK-EYE 鹰眼俯视图分析产物标注 MP4、detections.jsonl、热力图、散点图、metadata.json参考思路球场检测与统计逻辑参考 Good-Badminton 类方案在本平台复用 YOLO / RTMO 推理栈。羽毛球分析页面总览分析功能 Tab、配置栏、原视频与球场标注2. 技术栈2.1 前端技术用途Vue 3 Composition API页面逻辑、双 Tab分析功能 / 分析结果Element Plus表单、进度条、统计卡片、表格、图表区Axios调用/api/ai/badminton/*Canvas球场四角点击标注左上 → 右上 → 右下 → 左下主要源文件frontend/src/views/ai/badminton/index.vue— 分析主页面frontend/src/api/ai.js—badmintonApidetectCourt / analyze / progress / artifactBlob2.2 后端技术用途Flask Blueprint/api/ai/badminton专用路由OpenCV (cv2)视频读写、单应性、球场线检测、热力图/散点图Ultralytics YOLO姿态估计、羽毛球检测rtmlib ONNX RuntimeRTMO 单阶段姿态COCO-17PIL (ImageDraw)中文 HUD 文字渲染imageio libx264输出 H.264 标注视频后台线程 内存 Job异步分析任务与进度轮询主要源文件文件说明backend/routes/badminton.pyAPI 路由、任务调度backend/services/badminton.py逐帧分析、HUD、轨迹、统计backend/services/court_detector.py自动球场四角检测无深度学习权重backend/inference.py_get_model、_get_rtmo_model、infer_pose_rtmobackend/seed.py菜单与预置姿态模型backend/config.pyBADMINTON_FOLDER等存储路径2.3 架构示意┌──────────────────┐ POST /detect-court ┌─────────────────────┐ │ badminton/index │ ───────────────────────► │ court_detector.py │ │ (Vue) │ POST /analyze │ (Hough 几何约束) │ └────────┬─────────┘ ───────────────────────► └──────────┬──────────┘ │ │ │ GET /progress/{jobId} ▼ │ ◄────────────────────────────── badminton.py (逐帧分析) │ │ │ ┌─────────────────┴─────────────────┐ │ │ ultralytics: YOLO Pose 球检测 │ │ │ rtmlib: RTMO ONNX 姿态 │ │ └─────────────────────────────────────┘ ▼ 产物analyze_output.mp4 / heatmap.png / scatter.png / detections.jsonl3. 分析流程3.1 端到端步骤选择姿态模型必选与可选羽毛球检测模型上传比赛视频→ 自动调用球场检测预填四角确认或手动修正球场四角Canvas 点击标注配置叠加层骨架、轨迹、羽毛球、统计 HUD、球场边框与 HUD 语言中/英点击开始分析→ 后端异步逐帧处理轮询进度 → 完成后切换至分析结果Tab查看统计、热力图、散点图与结果视频上传视频后自动球场检测成功四角连线 置信度标签3.2 球场映射用户标注四角顺序左上 → 右上 → 右下 → 左下坐标支持0–1 归一化或像素坐标通过cv2.getPerspectiveTransform映射到标准单打场地宽 5.18 m长 13.4 m球员脚底锚点踝部中心关键点 15/16否则取可见关键点最下端3.3 自动球场检测court_detector.py实现无需额外模型权重将首帧缩放到 1080×720 进行检测绿色场地 ROI 白线/边缘提取Hough 线段检测区分水平线与边线四线交点组合 多维度评分面积、透视、线对齐等得分 ≥ 120 时返回归一化四角及confidence检测失败时courtPoints为空需用户手动点击标注。3.4 球员追踪与统计最近邻简易追踪track_id按球场 Y 坐标分为上场slot 0/ 下场slot 1平滑轨迹图像坐标 球场坐标双通道统计项当前速度、本回合移动距离/平均/最大速度、全场总距离/平均/最大速度回合判定检测到羽毛球开始新回合连续约 1.5 秒无球则结束回合并重置回合统计3.5 视频 HUD 叠加启用「统计叠加」时每帧绘制区域内容左侧面板上场/下场球员统计标签固定、数值右对齐中部「当前回合」大号数字右上 HAWK-EYE球场俯视图、球员轨迹、羽毛球轨迹与当前位置支持languagezh/en切换 HUD 文案。分析结果视频中的 HUD左侧统计 右上鹰眼3.6 分析产物任务完成后产物保存在uploads/badminton/{jobId}/文件说明analyze_output.mp4带叠加层的标注视频detections.jsonl逐帧 JSON帧号、回合、球员球场坐标、羽毛球位置heatmap.png球员球场坐标热力图scatter.png球员落点散点图metadata.json汇总元数据帧数、回合数、球员距离/速度等分析结果 Tab — 统计摘要卡片 球员移动表格位置热力图与散点图4. 依赖与环境4.1 Python 依赖羽毛球分析相关backend/requirements.txt中与本模块直接相关的包ultralytics8.4.69 # YOLO Pose、羽毛球检测 rtmlib0.0.15 # RTMO 姿态 onnxruntime1.17.0 # RTMO ONNX 推理 torch2.11.0 # rtmlib / ultralytics 共用 torchvision0.26.0 imageio2.37.3 imageio-ffmpeg0.6.0 # H.264 视频输出 opencv-python经 ultralytics # 图像/视频处理 numpy Pillow # HUD 中文渲染球场自动检测仅依赖OpenCV NumPy无额外深度学习包。4.2 安装与启动conda activate cv_python_tigerprocdbackend pipinstall-rrequirements.txt python app.py# http://127.0.0.1:5001cdfrontendnpminstallnpmrun dev# http://127.0.0.1:51734.3 硬件建议组件CPUGPUYOLO Pose可用长视频较慢推荐RTMO (ONNX)可用CUDA 下更快球场检测仅首帧开销很小不需要视频编码libx264 CPU 编码—4.4 存储配置来自backend/config.py配置项路径说明BADMINTON_FOLDERuploads/badminton分析任务产物目录VIDEO_FOLDERuploads/videos分析时临时保存上传视频MODEL_FOLDERuploads/models姿态/检测模型权重VIDEO_ALLOWED_EXTmp4/avi/mov/mkv 等支持的视频格式MAX_CONTENT_LENGTH500 MB单文件上传上限注意分析任务状态保存在后端内存_jobs中重启后端后旧jobId失效需重新分析。5. 模型与权重5.1 姿态模型必选前端筛选条件library为ultralytics或rtmlibtaskpose-estimationstatus0且 ultralytics 须已拉取权重。系统预置model_key显示名称library来源yolo11n-poseYOLO11n 姿态估计ultralyticsUltralytics/YOLO11#yolo11n-pose.ptrtmo-sRTMO-S 姿态估计rtmlibOpenMMLab RTMO-S ONNX SDK ziprtmo-mRTMO-M 姿态估计rtmlibOpenMMLab RTMO-M ONNX SDK zip常见手动添加同样支持在模型管理中自行添加、任务类型为pose-estimation的 Ultralytics 模型均可使用例如yolo11s-pose、yolo11m-pose等 YOLO11 Pose 系列.ptyolo26n-pose等 YOLO26 Pose 系列.pt或 pose 导出的 ONNX推理库加载方式权重要求ultralyticsYOLO(path).predict()→keypoints本地.pt/ pose ONNX须先拉取rtmlibRTMO(onnx_model...)zip 自动解压为end2end.onnx也可无本地文件按 URL 下载推荐综合速度与稳定性优先RTMO-S已有 Ultralytics 环境可用YOLO11n/s Pose。模型管理 — 姿态模型列表与权重拉取5.2 羽毛球检测模型可选前端筛选libraryultralyticstaskobject-detection已拉取权重。未选择时跳过羽毛球检测无球轨迹与回合统计其余姿态/移动统计仍可用选择后每帧在球场多边形内取置信度最高的检测框中心作为羽毛球位置系统种子中无专用羽毛球预置模型可在模型管理中添加针对小球/网球的 YOLO 权重如tennis-ball等前端会优先匹配modelKey tennis-ball。羽毛球检测使用通用 YOLOpredict不限制className实际效果取决于所选权重是否适配羽毛球外观。5.3 RTMO 权重拉取说明模型管理中对rtmlib库模型点击「拉取权重」时下载 OpenMMLab ONNX SDKzip自动解压提取end2end.onnx到模型目录推理时resolve_rtmlib_onnx()解析可用 ONNX 路径若直接上传 zip 而未解压后端会在加载时自动解压已实现于inference.extract_rtmlib_onnx_from_zip。6. 使用流程6.1 首次准备启动 MySQL、后端、前端登录系统默认admin / admin123进入模型管理拉取至少一个姿态模型权重推荐 RTMO-S 或 YOLO11n Pose可选添加并拉取羽毛球检测用 YOLO 权重侧栏进入视觉识别 → 羽毛球分析6.2 分析一场视频选择姿态模型、可选羽毛球模型调整置信度点击选择比赛视频上传 MP4 等格式等待自动球场检测失败则在右侧 Canvas依次点击四角勾选需要的叠加层选择 HUD 语言点击开始分析等待进度条完成自动跳转分析结果Tab查看统计与图表播放/下载结果视频6.3 叠加层选项选项效果骨架COCO-17 骨架连线上下场球员分色球员轨迹图像坐标平滑尾迹羽毛球轨迹球飞行弧迹需羽毛球模型统计叠加左侧 HUD 右上鹰眼球场边框绘制用户标注的四边形7. API 接口基础路径/api/ai/badminton需 JWTAuthorization: Bearer token权限接口使用ai:badminton:list种子菜单ai:badminton:query为按钮权限。7.1 自动球场检测POST /api/ai/badminton/detect-court Content-Type: multipart/form-data字段说明video比赛视频文件响应示例{code:0,message:自动检测成功,data:{imageBase64:JPEG 首帧,width:1920,height:1080,autoDetected:true,courtPoints:[[0.12,0.31],[0.88,0.29],[0.95,0.82],[0.05,0.85]],confidence:0.756,score:156.2}}7.2 提取首帧可选POST /api/ai/badminton/extract-frame字段说明video视频文件autoDetect1时同时尝试自动检测默认07.3 启动分析异步POST /api/ai/badminton/analyze Content-Type: multipart/form-data字段必填说明video是比赛视频poseId是姿态模型 IDballId否羽毛球 YOLO 检测模型 IDcourtPoints是JSON 四角[[x,y],...]×40–1 归一化conf否置信度默认0.25showSkeleton否1/0默认开showTrajectories否球员轨迹showShuttle否羽毛球轨迹showStats否HUD 统计showCourt否球场边框language否zh默认或en响应{code:0,message:分析已启动,data:{jobId:a1b2c3d4...}}7.4 查询进度GET /api/ai/badminton/progress/{jobId}进行中{code:0,data:{jobId:...,status:running,processed:320,total:1500,stats:null,error:null}}完成{code:0,data:{status:done,processed:1500,total:1500,stats:{frames:1500,rallyCount:42,totalPersons:3000,shuttleDetections:890,playerDistances:{1:45.2,2:38.7},playerMaxSpeed:{1:4.5,2:5.1},outputVideo:analyze_output.mp4,heatmap:heatmap.png,scatter:scatter.png,detections:detections.jsonl,metadata:metadata.json},artifacts:{video:/api/ai/badminton/artifact/{jobId}/analyze_output.mp4,heatmap:/api/ai/badminton/artifact/{jobId}/heatmap.png,scatter:/api/ai/badminton/artifact/{jobId}/scatter.png,detections:/api/ai/badminton/artifact/{jobId}/detections.jsonl,metadata:/api/ai/badminton/artifact/{jobId}/metadata.json}}}7.5 下载产物GET /api/ai/badminton/artifact/{jobId}/{fileName}按扩展名返回video/mp4、image/png、application/json等。8. 权限说明标识类型说明ai:badminton:list菜单侧栏「羽毛球分析」入口ai:badminton:query按钮查询权限种子API 实际校验—permission_required(ai:badminton:list)9. 关键代码索引文件说明frontend/src/views/ai/badminton/index.vue分析 UI、球场 Canvas、结果展示frontend/src/api/ai.jsbadmintonApibackend/routes/badminton.py路由与异步 Workerbackend/services/badminton.pyanalyze_badminton_video、HUD、热力图backend/services/court_detector.pydetect_court_from_framebackend/inference.pyRTMO 封装、infer_pose_rtmobackend/seed.py菜单 270、姿态模型种子backend/config.pyBADMINTON_FOLDER10. 常见问题Q1提示「姿态模型须为 ultralytics 或 rtmlib」所选模型library或task不正确须为pose-estimation且库为ultralytics或rtmlib。Q2RTMO 报错No module named rtmlib执行pip install rtmlib onnxruntime后重启后端。Q3自动球场检测失败光照、视角或场地线不清晰时常见。请手动点击四角尽量使用固定机位、完整可见场地的视频。Q4没有羽毛球轨迹 / 回合数始终为 0未选择羽毛球检测模型或所选 YOLO 权重无法稳定检出羽毛球。可尝试专用小球权重并降低置信度。Q5分析完成后刷新页面找不到结果任务 ID 存于内存重启后端会丢失。请在一次会话内下载所需产物视频/JSON/图片。Q6五种姿态模型是否都支持凡满足ultralytics/rtmlibpose-estimation 已拉取权重的模型均可预置为 YOLO11n Pose、RTMO-S/M其余如 YOLO11s Pose、YOLO26 Pose ONNX 等需在模型管理中自行添加。tics或rtmlib。Q2RTMO 报错No module named rtmlib执行pip install rtmlib onnxruntime后重启后端。Q3自动球场检测失败光照、视角或场地线不清晰时常见。请手动点击四角尽量使用固定机位、完整可见场地的视频。Q4没有羽毛球轨迹 / 回合数始终为 0未选择羽毛球检测模型或所选 YOLO 权重无法稳定检出羽毛球。可尝试专用小球权重并降低置信度。Q5分析完成后刷新页面找不到结果任务 ID 存于内存重启后端会丢失。请在一次会话内下载所需产物视频/JSON/图片。Q6五种姿态模型是否都支持凡满足ultralytics/rtmlibpose-estimation 已拉取权重的模型均可预置为 YOLO11n Pose、RTMO-S/M其余如 YOLO11s Pose、YOLO26 Pose ONNX 等需在模型管理中自行添加。