简介资源整合了Python、OpenCV与YOLO的台球击球路线规划完整源码及部署教程面向人工智能、计算机视觉方向的毕业设计者与台球运动AI研究者。系统基于实时视频流识别母球与目标球位置结合动量守恒等物理模型计算最佳击球角度与力度帮助理解目标检测到路线规划的完整工程链路。压缩包共10个文件主体为1个Python脚本、8张结果展示图片与1份Markdown教程整体大小7.64MB结构紧凑便于直接阅读代码、对照运行效果并快速上手部署。目前已有362人浏览学习属于轻量级但涵盖关键环节的实践项目。通过该资源可获取完整的源码逻辑、设备环境配置说明、模型检测可视化效果以及击球路线规划的实现思路。图片素材直观呈现了台球桌与球体识别结果Python文件演示核心算法流程配套文档辅助理解设计与部署细节适合作为毕业设计参考或视觉目标检测与物理模拟结合的学习起点。1. 台球路线不是靠手感而是靠 OpenCV 加 YOLO 一步步算出来的多数人第一次看台球击球路线规划的代码都会下意识去找“力度公式”或者“角度计算”实际上整个系统的骨架是OpenCV 把视频帧变成干净图片YOLO 把每颗球的位置框出来最后才轮到几何和物理模型回答“往哪打、打多重”。这个 Python 项目正好把这条链路完整串了一遍不是零散的 demo 拼接而是一套能跑的击球辅助系统既能接摄像头实时检测也能读视频文件离线分析。对正在做人工智能毕业设计、想接触目标检测落地流程的同学来说它把推理、坐标提取、路线规划、可视化每一步都摊开在代码里适合作为第一个“完整视觉项目”来拆。2. 项目全貌与运行逻辑拆解从文件结构到一条主流程2.1 代码包里都有什么文件结构先看懂打开压缩包第一眼内容不复杂核心脚本加运行截图加教程文档。我看到的文件里README.md 是部署教程和数据说明一堆 PNG 截图是各个阶段的运行效果。比较关键的是get_hole.py这个脚本名字里的 “hole” 指的就是台球桌的袋口。它的作用是标定球洞坐标拿到六个袋口的位置。这个脚本是整个路线规划的地基因为后面所有几何求解都依赖袋口坐标作为目标点。如果袋口标偏了后面算出来的击球线路再漂亮也是错的。从常见实现来看代码包里一般还会包含检测模块、路线规划模块和工具模块职责划分大致如下模块/文件职责输入输出get_hole.py手动或半自动标定六个袋口坐标视频帧或静态图袋口坐标列表检测模块YOLO 推理封装视频帧球类别、置信度、边界框路线规划模块碰撞点/瞄准点/力度计算球心坐标、袋口坐标瞄准点、力度、路线工具模块图像预处理、坐标换算、绘制原始帧、检测结果干净帧、统一坐标、标注帧2.2 一帧画面如何变成一条击球线主流程拆成五步把整个链路拆开每一步对应到代码里一个明确的环节。第一步是读帧。用cv2.VideoCapture打开摄像头或者视频文件逐帧拿画面。这个环节看着简单但后面避坑章节里会提到返回值的检查不做就会黑屏。第二步是图像预处理。YOLO 对输入图片有尺寸要求常见做法是缩放到 640×640 或 416×416再做归一化。同时 OpenCV 把 BGR 转成 RGB因为 YOLO 训练时用的颜色通道顺序是 RGB。第三步是 YOLO 推理。输入预处理后的帧输出每个球的边界框、类别和置信度。台球场景里目标小、数量多YOLO 的优势是单阶段直接回归速度比两阶段检测快一个量级。第四步是坐标提取。YOLO 输出的是框的左上角坐标加宽高要换算成球心坐标。这一步还要做一件事把同一个球的重复检测框用 NMS 合并掉避免一颗球出两个中心点。第五步是路线计算与绘制。拿到母球、目标球、袋口的坐标后进路线规划模块算出瞄准点和力度再把线路用cv2.line画到原帧上最后用imshow显示。2.3 数据流谁给谁喂数据这条链路里各模块之间的数据格式必须对齐否则特别容易翻车。我按数据流向列一下OpenCV 预处理模块输出处理后的帧给检测模块检测模块输出检测结果(x, y, w, h, class, conf)给坐标提取坐标提取把边界框转成球心坐标(cx, cy)球心坐标和袋口坐标一起进入路线规划路线规划输出瞄准点坐标和力度值可视化模块把原始帧、球框、路线叠加显示这里面最容易出问题的是坐标口径。YOLO 有的版本输出归一化坐标有的输出像素坐标如果球心坐标和袋口坐标不在同一个坐标系里后面算出来的碰撞点会偏到离谱。我一般会在工具模块里统一做一个to_pixel或to_norm的换算函数所有坐标都先过一遍再进几何计算。3. 环境搭建与数据集准备先把依赖和输入数据定住3.1 依赖清单与版本选择这个项目的依赖不算多核心是 OpenCV、YOLO 推理框架、NumPy 和 SciPy。版本选择上我有一个血泪经验opencv-python和opencv-contrib-python二选一千万别同时装后者包含前者的全部功能还额外带了一些扩展算法。依赖建议版本用途Python3.8 ~ 3.10主语言3.10 以下兼容性最稳opencv-contrib-python4.5 以上图像预处理、视频读取、绘制numpy1.21 左右坐标运算、数组操作scipy1.7 以上物理模型里的优化求解matplotlib3.5 左右离线可视化、路线图展示torch按 CUDA 版本选YOLO 模型推理3.2 从零跑到第一次出图安装步骤我用 conda 建虚拟环境避免把系统 Python 搞乱。下面这份命令是多数项目最常见的启动方式。# 1. 创建虚拟环境Python 版本选 3.9 conda create -n billiard python3.9 -y conda activate billiard # 2. 安装基础视觉与科学计算依赖 pip install opencv-contrib-python numpy scipy matplotlib # 3. 安装 PyTorchCPU 版先跑通流程后续再换 CUDA 版 pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu第一段命令创建并激活独立环境避免依赖冲突。第二段装的是视觉和数值计算基础库其中opencv-contrib-python包含了图像处理需要的核心模块。第三段装 PyTorch先用 CPU 版验证代码流程能跑通再根据自己显卡的情况换对应 CUDA 版本这样排错时更容易定位问题。装完依赖后先用项目自带的权重文件跑一次检测不要急着训练自己的模型。把摄像头对准球桌或者随便放一段录好的球桌视频看能否正常输出检测框和路线。这一步过了环境基本就没问题了。3.3 准备自己的数据录一段球桌视频就能开始如果后续想重新训练 YOLO 模型需要准备带标注的数据。台球场景的数据集不需要从零攒常见做法是把自己打球的视频抽帧抽个几百张就够起步再配合公开的球类数据集做预训练。标注格式用 YOLO 的 txt 格式每一行对应一个目标0 0.42 0.53 0.08 0.08 1 0.61 0.47 0.09 0.09每行五个值第一个是类别编号后面四个是归一化后的中心坐标和宽高。比如0 0.42 0.53 0.08 0.08表示类别 0 的球中心在图片横向 42%、纵向 53% 的位置宽和高各占图片的 8%。台球是典型的小目标球在整幅画面里的占比很小。标注时框要贴紧球边缘别留太多背景否则模型学到的特征里会混入桌面纹理导致检测框偏大或者出现误检。4. 避坑指南环境、检测与部署的五个常见问题4.1 cv2 装完却没有想要的算法现象跑预处理代码时抛AttributeError: module cv2.cv2 has no attribute xfeatures2d或者找不到 SIFT、SURF 这类特征算子。原因特征算子属于 OpenCV 的扩展模块基础版opencv-python里不带这些接口需要opencv-contrib-python才能用。不少同学先装了一个基础包发现问题后又直接装扩展包两个版本同时在环境里冲突就来了。解决统一用opencv-contrib-python并且保证环境里只有一个 OpenCV 包。# 先卸载所有 OpenCV 相关包 pip uninstall opencv-python opencv-contrib-python -y # 只装扩展版 pip install opencv-contrib-python4.2 YOLO 权重文件不完整导致推理崩溃现象检测脚本跑到一半报KeyError: model或者IndexError: list index out of range还有的是加载权重后推理结果全是空框。原因权重文件下载过程中网络中断或者从网盘转存时文件被截断。YOLO 模型文件有几百兆下载不完整时不会立刻报错但在加载或推理时就会露出马脚。有时候.names类别文件里的类别数和模型输出的类别数对不上也会触发类似的越界错误。解决先看文件大小是否和 README 里标注的体积一致特别小的一律重新下载。同时把.weights、.cfg、.names三个文件放在同一个目录下类别编号必须从 0 开始连续编号。加载代码里加上文件存在性校验让问题在一开始就暴露。import os for f in [yolov4.weights, yolov4.cfg, coco.names]: if not os.path.exists(f): raise FileNotFoundError(f缺少模型文件: {f})4.3 摄像头黑屏但程序不报错现象cv2.VideoCapture(0)打开成功但cap.read()返回的帧一直是空的窗口弹出来是黑屏控制台也没有任何报错。原因摄像头被其他程序占用或者 OpenCV 默认用的后端和当前摄像头驱动不兼容。最常见的是笔记本自带摄像头在 Windows 上 OpenCV 默认后端经常抢不到权限。解决read 返回值必须检查不能假设每一帧都能成功读取。读取失败时跳过当前帧连续失败多次就重新初始化摄像头。cap cv2.VideoCapture(0, cv2.CAP_DSHOW) # Windows 下指定 DirectShow 后端 n_fail 0 while True: ret, frame cap.read() if not ret: n_fail 1 if n_fail 30: cap.release() cap cv2.VideoCapture(0, cv2.CAP_DSHOW) n_fail 0 continue n_fail 0 # 正常处理帧4.4 检测框抖动球心每帧跳变现象一颗静止的球在连续几帧里检测框位置跳来跳去算出来的击球路线也跟着左右摇摆没法稳定显示。原因置信度阈值设得太低背景区域被误检成球导致同一颗球在相邻帧里选了不同的候选框。另一个原因是检测框没有做 NMS 合并YOLO 本身会输出多个重叠框。解决把置信度阈值从默认的 0.25 提到 0.5 左右看效果再微调。球心输出前加一个轻量级的平滑处理最常见的做法是一阶指数平滑。def smooth_center(prev, curr, alpha0.4): if prev is None: return curr return (alpha * curr[0] (1 - alpha) * prev[0], alpha * curr[1] (1 - alpha) * prev[1])alpha越大跟随越快但越容易受到抖动影响alpha越小轨迹越平滑但延迟越大。我这里取 0.4 是折中值实际调的时候看线路稳定性就行不需要特别精确。4.5 推理速度太慢GPU 显存不够用现象用默认模型在 CPU 上跑一帧要 1 到 2 秒根本谈不上实时想切 GPU又提示显存不足。原因YOLO 的常规模型参数量不小输入分辨率默认可能是 640×640CPU 扛不住。显存不够通常是 batch size 设置过高或者模型输入图尺寸太大。解决换轻量模型比如 YOLOv5s 或 YOLOv5n输入尺寸降到 416×416推理帧率能翻几倍。半精度推理也能省接近一半显存。# 半精度推理PyTorch 版本 model model.half() # 推理时输入帧同样转成半精度 frame frame.half()5. 击球路线规划从几何解算到力度模型5.1 坐标体系先标定再规划路线规划的第一步不是写公式而是统一坐标口径。YOLO 输出的球心坐标是像素坐标袋口坐标一般来自get_hole.py的标定结果两者必须都换算到同一张图的像素坐标系里。我一般会在工具模块里定义scale_coords函数把归一化坐标或缩放前后的坐标统一映射好。袋口标定有一个细节台球桌六个袋口角袋四个边袋两个。get_hole.py里常见做法是打开第一帧画面用鼠标点击每个袋口中心把点击坐标存成列表。这个操作只需要做一次后续所有帧都复用这组坐标。5.2 碰撞点目标球进袋的几何条件要让目标球进袋目标球被撞击瞬间的运动方向必须指向袋口中心。所以碰撞点在目标球球心和袋口的连线上并且离目标球球心正好一个球半径。import numpy as np BALL_RADIUS 14.5 # 像素口径需要根据实际标定结果调整 def calc_collision_point(ball, pocket): 计算目标球被母球撞击时两球的接触点位置 接触点位于目标球球心与袋口连线上 距离目标球球心一个球半径。 dx pocket[0] - ball[0] dy pocket[1] - ball[1] dist np.hypot(dx, dy) if dist 0: return None # 球心与袋口重合违背常理做保护 dx / dist dy / dist return (ball[0] dx * BALL_RADIUS, ball[1] dy * BALL_RADIUS)这个函数里的dist是目标球球心到袋口的直线距离当距离为 0 时直接返回None防止除零。除以距离后再乘半径得到的是方向向量乘以球半径确保接触点落在正确方向上。BALL_RADIUS是像素值需要根据当前画面的实际球径来标定直接决定整条路线的精度。5.3 瞄准点母球往哪个位置打碰撞点算出来后母球要瞄准的位置就明确了母球中心到碰撞点的连线方向就是母球的前进方向。实际击球时杆的方向就是这条连线的方向。def calc_aim_point(cue_ball, collision_point): 母球中心瞄准碰撞点方向 返回瞄准点的坐标实际击球方向由 cue_ball 与 aim_point 的连线决定。 aim_x collision_point[0] - cue_ball[0] aim_y collision_point[1] - cue_ball[1] return (cue_ball[0] aim_x, cue_ball[1] aim_y)这个函数逻辑很简单但有一个坑返回的是“方向向量加上母球中心坐标”而不是方向向量本身。后续绘制路线和计算力度时用的都是这个完整坐标。5.4 力度简化动量模型与参数修正完整求解台球碰撞要算动量守恒、角动量守恒、摩擦和旋转正常做下来是一组微分方程不是不能做而是对毕设规模的系统来说容易喧宾夺主。常见实现里会做简化两球质量相同目标球初速度为零碰撞视为正碰。在这样的前提下力度主要和母球到目标球的距离、目标球到袋口的距离相关。def calc_power(cue_ball, target_ball, pocket, base_power0.6): 根据距离估算击球力度 母球或目标球离袋口越远需要的力度越大。 返回 0 ~ 1 之间的力度系数。 dist_cue np.hypot(cue_ball[0] - target_ball[0], cue_ball[1] - target_ball[1]) dist_pocket np.hypot(target_ball[0] - pocket[0], target_ball[1] - pocket[1]) max_dist 800.0 # 按实际画面尺寸调整 power base_power * (0.6 0.4 * dist_cue / max_dist) power * (0.7 0.3 * dist_pocket / max_dist) return float(np.clip(power, 0.15, 0.95))这里的逻辑是母球离目标球远需要的基本力量大目标球离袋口远也需要额外加力。base_power是一个基础系数可以根据球桌材质、球的大小做经验修正。如果在木地板的练习台上打0.6 左右起步比较稳换成正式比赛台橡胶库边弹性好力度可以往下压一点。5.5 把整条路线画到画面上有了瞄准点和碰撞点绘制就顺手了。一般画三条线母球到瞄准点的黄色线表示出杆方向瞄准点到目标球的绿色线表示母球撞击后的走向目标球到袋口的红色虚线表示目标球进袋轨迹。def draw_route(frame, cue_ball, aim_point, target_ball, pocket): 在视频帧上叠加击球路线 - 黄色母球出杆方向 - 绿色母球撞击目标球后的方向 - 红色目标球进袋方向 cv2.line(frame, cue_ball, aim_point, (0, 255, 255), 2) cv2.line(frame, aim_point, target_ball, (0, 255, 0), 2) cv2.line(frame, target_ball, pocket, (0, 0, 255), 2) cv2.circle(frame, pocket, 6, (0, 0, 255), -1) return frame颜色用的是 BGR 顺序千万别写反。(0, 255, 255)是黄色(0, 255, 0)是绿色(0, 0, 255)是红色。线宽 2 在 640×480 的画面里看起来比较清楚分辨率更高时建议调到 3。6. 实战验证线路准不准、参数怎么调6.1 固定机位录一段视频当测试基准验证这套系统不要拿摄像头对着球桌现场调那样变量太多。我一般先固定机位录一段 30 秒左右的视频横拍、光线均匀、避免反光然后离线跑检测和路线规划。同一视频反复调参参数改没改好一眼就能对比出来。6.2 三个最影响结果的参数第一个是BALL_RADIUS。这个值直接决定碰撞点位置差几个像素线路就会偏。标定时拿一颗真实球放在球桌上在画面里量它的像素直径多量几次取平均值。第二个是置信度阈值conf_thres。低了误检多线路乱跳高了漏检多球都找不到。我通常从 0.4 起步逐档往上加直到画面里所有球都能稳定框出。第三个是输入分辨率。YOLO 的输入分辨率越高检测越准但速度越慢。台球这种小目标分辨率太低会漏检我一般不低于 416×416。6.3 从 demo 到真实球桌的差异如果有条件把系统搬到真实球桌上跑一次会发现最大的问题不是检测也不是路线计算而是相机畸变。手机广角镜头拍出来的球桌边缘是弯的像素坐标和真实台面坐标对不上线路画出来是直的但不指向真实袋口。常见做法是先用棋盘格标定相机内参做一次去畸变处理线路线条会更贴近现实。从那以后我每次接触视觉引导类项目都强制先过一遍“标定、检测、规划”的流程坐标口径没统一就急着调算法最后基本都是白忙。希望帮到你。本文还有配套的精品资源点击获取