简介这是一套面向高校计算机相关专业课程实训与毕设场景的台球击球路线规划系统基于Python、OpenCV与YOLO目标检测实现同时含有C工程代码可供交叉参考。项目包含完整源码、部署配置与项目报告代码经过严格测试可稳定复现适合人工智能、通信工程、自动化、电子信息等专业学生用于课程设计、毕业设计或项目初期演示也适合希望通过实际项目提升视觉检测与路径规划能力的学习者。压缩包共有190个文件大小约2.58MB文件类型以34个Python脚本为核心另有C/C源文件、JavaScript/HTML/CSS前端页面、YOLO相关配置与JSON数据以及大量jpg/png图片和项目文档覆盖从目标检测、坐标定位到击球路线计算的主要环节。目前已有109人浏览学习。除可直接运行的完整工程外资源还附有项目报告能够帮助理解台球识别、球杆角度计算、路线规划等关键实现逻辑若基础稍弱还可获得远程配置指导快速完成部署并在此基础上进行二次开发。1. 课程实训里最容易被低估的一套代码Python OpenCVYOLO台球击球路线规划系统如果你在课程设计、毕业设计或者项目实训里拿到过「Python OpenCVYOLO台球击球路线规划系统」这套资源包打开后第一眼看到的通常是 src、models、report 三个文件夹。很多人的反应是直接跑主程序然后卡在环境缺失、模型权重 loading 失败、检测框乱跳这几件事上。这个标题说的是一个典型的计算机视觉综合项目用 OpenCV 做球桌和球的底层几何检测用 YOLO 做球的类别识别与位置回归最后用几何关系计算击球路线并预判下一杆的走向。它解决的是一类很现实的问题——视觉检测不只是把目标框出来还要把框出来的结果换算成可以控制的运动路线。适合的人群也清晰正在做课程实训、需要交付可演示系统的学生以及刚接触检测到空间规划这条技术链的从业者。2. 检测到规划这套系统在解决什么模块从哪几层拆2.1 OpenCV 与 YOLO 各自承担什么角色台球击球路线规划不是单一算法能完成的。球桌上的球、袋口、库边桌壁和球杆在图像里的形态差异很大。白球是光滑球体彩球有颜色库边是长直线袋口是几何开口。如果用纯 OpenCV 来做靠颜色阈值和边缘检测能稳定找到的只有库边和大色块球遇到白球贴在库边、球杆与球重叠这种场景就会误检。如果用纯 YOLO 来做检测框能给出球的类别和中心点但 YOLO 给的是像素坐标不会告诉你球与库边的相对角度更不会算反弹路径。所以这套系统的常见做法是分层OpenCV 负责底层的图像预处理、直线检测、球桌边界拟合、帧差去噪YOLO 负责语义识别——哪个是白球、哪个是目标球、哪个是袋口区域。两边的输出合并成一张「球桌状态表」再交给后续的几何规划模块。简单说OpenCV 让机器看见几何结构YOLO 让机器认得出东西规划模块让机器知道往哪打。标题里的「OpenCVYOLO」是并列关系但实现的时候一定是先 OpenCV 后 YOLO。OpenCV 的输出质量直接决定 YOLO 输入图像的干净程度。如果球桌区域都没裁出来就让 YOLO 在全图跑推理不仅速度慢还会把观众、球杆、桌面反光全部误检成球。2.2 系统模块拆解与数据流向我一般拿到这类实训项目先不看代码先画数据流。整个系统可以拆成四个模块图像采集与预处理、球桌几何重建、球体目标检测、击球路径规划。图像采集是视频流或单帧图片预处理做的是透视校正、去噪、亮度归一化几何重建用直线检测找到四条库边和六个袋口目标检测用 YOLO 对裁切后的球桌区域做推理输出每个球的类别和像素坐标路径规划将像素坐标映射到真实球桌的平面坐标系再用反射几何计算主球撞目标球之后的走向。数据流向是单向的原始帧 → 透视校正后的桌面临时图 → YOLO 检测结果表 → 坐标映射 → 路径计算 → 结果可视化。这条链路里最容易出错的是第二步到第三步的衔接因为 OpenCV 的坐标系原点在图像左上角而 YOLO 输出的是归一化中心点坐标两者如果不统一换算后面所有角度计算都是错的。2.3 规划算法选型反射镜像法还是迭代求解击球路线规划的几何核心是已知白球位置 A、目标球位置 B需要求白球的击打方向使得白球击中目标球之后目标球滚向袋口 C。这里常用的是反射镜像法。把库边当作镜面把目标球吃库后的理论路线反转镜像用几何关系求入射点。但台球不总是直球白球可能要先吃一库再击打目标球也就是路径 A → 库边点 P → B → C。实现时我的习惯是先用暴力搜索采样库边上的候选点对每个点用向量夹角和距离和做评分找出满足入射角和反射角相等的最优 P。这种迭代采样比纯解析法更稳因为图像检测出来的库边坐标本身有误差解析解对误差非常敏感而采样加评分会自然平滑掉一部分抖动。评分项一般是吃库后白球到目标球的剩余距离、撞球时白球与目标球的夹角、目标球到袋口的三点共线程度三个指标加权求和。3. 从零跑通环境依赖安装、模型准备和工程结构3.1 安装步骤与依赖版本避雷拿到源码包第一件事永远是先建环境。Python 版本建议 3.8 到 3.10 之间OpenCV 用 pip 安装即可。YOLO 部分主流实训代码用的是 ultralytics 这个库它把 YOLO 的推理和训练都封装成了 Python API不需要自己下载 darknet 源码编译对课程实训来说省掉很多时间。整套依赖安装命令如下# 创建虚拟环境避免污染系统 Python python -m venv venv # Windows 下激活venv\Scripts\activateLinux 下用 source venv/bin/activate pip install opencv-python opencv-contrib-python pip install ultralytics pip install numpy matplotlib逻辑说明opencv-python 提供基础图像处理接口opencv-contrib-python 多包含一些扩展模块比如跟踪和特征匹配实训项目里有时会用到。ultralytics 是 YOLO 的官方封装库里面自带多个预训练模型结构不需要单独写网络定义文件。numpy 和 matplotlib 是绘图和数组计算的底座。参数说明opencv-contrib-python 和 opencv-python 不能同时装两个主版本但可以同时装实际导入时以 opencv-python 为主。如果报导入错误先检查是不是两个库版本冲突卸载重装其中一个就行。如果你用的是 GPU 机器想跑 YOLO 的 CUDA 加速需要提前装好对应版本的 PyTorch再装 ultralytics否则 ultralytics 会自动装 CPU 版 PyTorch速度会慢很多。3.2 预训练模型权重没有权重文件一切推理都是空谈YOLO 不是纯 OpenCV 能跑起来的传统算法它是深度模型必须有预训练权重。标题里的源码包正常情况下会附带权重文件比如 best.pt 或者 yolov8n.pt。如果没有就要自己准备。课程实训场景里不需要从头训练一个台球检测模型直接用 YOLO 在 COCO 数据集上的预训练权重再把「球」这个类别映射到台球场景里是更快的方式。COCO 里有 sports ball 这个类对应台球、网球、足球这类球体足够完成演示。但如果你希望检测精度更高想区分白球、彩球和袋口那就得自己标注数据重新训练。一个可行的最低成本方案拍 200 到 300 张不同角度、不同光照的球桌照片用 labelimg 标注成 YOLO 格式按 8:1:1 划分训练集、验证集、测试集然后微调 YOLOv8n 模型。训练命令如下# 训练自己的台球检测模型数据标注放在 datasets/billiards/ 下 yolo detect train datadatasets/billiards/data.yaml modelyolov8n.pt epochs60 imgsz640 batch8逻辑说明data.yaml 需要写明训练集和验证集路径以及类别名列表。比如 names 定义为 white_ball、color_ball、pocket 这三类。epochs 60 对于小数据集足够再多容易过拟合尤其是只有两三百张图的情况下。参数说明imgsz640 是输入图像缩放到 640x640 分辨率这个值是大是小直接影响检测小球的精度。台球在图像里占的面积不大如果你拍摄的画面里球桌占满整个画面640 够用如果球桌只占画面一半建议改成 800 或 960。batch8 是批大小显存不够的时候减半但不要低于 2否则 BN 层统计不稳定训练收敛会变慢。3.3 工程目录结构源码包的常见组织方式实训源码包的目录结构一般长这样根目录下有 main.py 作为程序入口utils/ 放图像处理和几何计算函数models/ 放 YOLO 权重和配置文件report/ 放项目报告模板和实验结果图。如果你拿到的包和我说的不一致不要慌找到 main.py 或者 run.py它就是入口。我建议你拿到包后先做一次最小化运行验证把 main.py 里视频文件路径换成本地图片路径把模型加载路径换成实际权重文件路径先跑通单帧再跑视频。单帧跑通意味着检测链路没问题剩下的只是视频解码和显示的问题。不要一上来就跑完整视频流否则你会分不清到底是检测慢还是视频读取慢。4. 核心实现拆解YOLO 推理、OpenCV 直线检测与几何路线绘制4.1 用 YOLO 做球体检测并提取坐标YOLO 推理在 ultralytics 库下的写法非常简洁核心代码如下。这个函数接收一帧 BGR 图像返回检测到的球对象列表里面包含类别、置信度、归一化中心点和宽高from ultralytics import YOLO model YOLO(models/best.pt) # 加载训练好的台球模型 def detect_balls(frame, conf_threshold0.5): results model.predict(frame, confconf_threshold, imgsz640, verboseFalse) balls [] for r in results: boxes r.boxes for box in boxes: x1, y1, x2, y2 box.xyxy[0].tolist() # 像素坐标框 conf box.conf[0].item() # 置信度 cls_id int(box.cls[0].item()) # 类别 id cx (x1 x2) / 2 # 中心 x cy (y1 y2) / 2 # 中心 y balls.append({ cls: cls_id, conf: conf, cx: cx, cy: cy, radius: (x2 - x1) / 2 # 近似半径 }) return balls逻辑说明box.xyxy 是检测框的左上角和右下角像素坐标从里面算出中心点和半径。半径的作用后面会用到——碰撞计算里判断白球是否碰到目标球不能只看中心点距离还要减去两个球的半径。cls_id 对应模型训练时的类别索引比如 0 是白球1 是彩球2 是袋口。参数说明conf_threshold0.5 是置信度阈值低于这个值的检测结果会被丢弃。如果现场误检特别多可以提高如果漏检多就降低到 0.3 左右。imgsz640 要和训练时保持一致否则模型输出的框精度会受影响。verboseFalse 是关掉控制台打印不然跑视频流的时候终端会被刷爆。4.2 OpenCV 做库边检测与透视校正YOLO 能找出球的位置但找库边不是 YOLO 的强项。库边是长直线在图像里颜色单一用 OpenCV 的 Canny 边缘检测加霍夫直线检测是最经典、最稳定的做法。下面这段代码先对球桌区域做灰度化和高斯模糊然后提取边缘直线再筛选出四条最长的构成球桌边界import cv2 import numpy as np def detect_table_lines(frame): gray cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) blurred cv2.GaussianBlur(gray, (5, 5), 0) # 降噪避免库边纹理误检 edges cv2.Canny(blurred, 50, 150) # 边缘检测 lines cv2.HoughLinesP( edges, rho1, thetanp.pi / 180, threshold80, minLineLength150, maxLineGap10 ) if lines is None: return [] # 按长度排序取前 4 条作为球桌边界候选 lines sorted(lines, keylambda l: np.hypot( l[0][2] - l[0][0], l[0][3] - l[0][1]), reverseTrue) return lines[:4]逻辑说明Canny 的两个阈值 50 和 150 是边缘强弱的上下限小于 50 的梯度不算边缘大于 150 的一定算中间的要与强边缘连接才保留。HoughLinesP 的 rho 是距离分辨率设 1 表示按像素精度搜索theta 是角度分辨率设 pi/180 表示按 1 度精度搜索。minLineLength 过滤掉太短的线段避免把球杆、纹理误判成库边。参数说明minLineLength 和 maxLineGap 是这组参数里最需要调的。台球桌库边在图像里通常超过 200 像素设 150 可以去掉大部分噪声线。maxLineGap 控制在同一直线上断开的线段合并距离设 10 表示空隙在 10 像素以内才算同一条线。如果球桌表面纹理重比如有logo和花纹把 Canny 的高阈值从 150 提到 200减少非库边边缘的数量。4.3 几何路线规划镜像法和向量夹角计算检测到球和库边之后规划模块开始工作。最常见的直球场景是白球 A 击打目标球 B使 B 进袋 C。这里的关键是把检测得到的像素坐标转换成平面坐标然后算两个矢量白球到目标球的入射方向以及目标球到袋口的出射方向。两者夹角越接近 180 度进球成功率越高。下面这个函数计算一条击球路径是否值得推荐import numpy as np def angle_between(vec1, vec2): cos_theta np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2)) cos_theta np.clip(cos_theta, -1.0, 1.0) # 防止浮点越界 return np.degrees(np.arccos(cos_theta)) def evaluate_shot(white_pos, target_pos, pocket_pos): vec_to_target np.array(target_pos) - np.array(white_pos) vec_to_pocket np.array(pocket_pos) - np.array(target_pos) # 夹角越接近 180 度说明白球、目标球、袋口越接近一条直线 deviation abs(angle_between(vec_to_target, vec_to_pocket) - 180.0) distance np.linalg.norm(vec_to_target) # 分数越低越好距离和角度偏离度共同决定 score deviation * 0.7 distance * 0.3 return score, deviation逻辑说明angle_between 用向量点积求余弦值再反解出夹角。evaluate_shot 返回两个值deviation 是角度偏离度理想直球是 0 度实际小于 15 度就可以尝试击打。distance 是白球到目标球的像素距离权重占比低一点因为长台进球本身难度大但角度正确的话还是可以打。score 越小越好用于在多个候选目标球里选最优那一颗。参数说明偏离度权重 0.7 和距离权重 0.3 是我做演示系统时的默认值侧重「角度优先」。如果你的思路是做力量可控的短台练习可以把距离权重调高比如 0.5 对 0.5。这个分数函数只是第一层筛选还要配合白球吃库后的路径长度做第二层判断避免选出一条虽然角度正但中途要穿过其它球的路线。4.4 路径可视化在帧上画出预测路线计算完成之后要得让老师或者评委看到效果路线可视化是整个演示的加分项。在 OpenCV 里画线画圆非常简单def draw_path(frame, white_pos, target_pos, pocket_pos): overlay frame.copy() # 画白球到目标球的击球线路 cv2.line(overlay, tuple(white_pos), tuple(target_pos), (0, 255, 0), 2) # 画目标球到袋口的预计滚动脉路 cv2.line(overlay, tuple(target_pos), tuple(pocket_pos), (0, 0, 255), 2) # 画目标球进袋方向的延长线提示进球角度 vec np.array(pocket_pos) - np.array(target_pos) vec vec / np.linalg.norm(vec) * 80 tail_pos (int(target_pos[0] vec[0]), int(target_pos[1] vec[1])) cv2.line(overlay, tuple(target_pos), tail_pos, (255, 0, 0), 1) return cv2.addWeighted(overlay, 0.7, frame, 0.3, 0)逻辑说明addWeighted 将带线条的 overlay 和原始帧混合透明度设为 0.7让路线半透明地覆盖在画面上既能看到标注又不遮挡球桌细节。绿色线表示白球的击球方向红色线表示目标球进袋的预期路线蓝色是辅助延长线用来直观展示进球角度是否足够正。参数说明cv2.line 的线宽参数 2 在 640P 画面里看得清楚在 1080P 里偏细可以调整到 4 或 5。tail_pos 的延长长度 80 像素是固定值如果球桌在图像里占的面积大可以改成 150让辅助线更明显。实际演示时把这几个函数按「检测 → 规划 → 绘制」顺序串起来每处理一帧调一次 detect_balls、evaluate_shot、draw_path就能看到实时路线跟随效果。5. 部署期和高频踩坑5 个影响交付的严重问题5.1 报错 ModuleNotFoundError: No module named opencv现象代码运行到 import cv2 直接失败pip list 里已经显示安装了 opencv-python但程序还是找不到模块。原因最常见的是虚拟环境和全局环境不统一你在系统 Python 里装了包但项目用的是 venv 环境或者反之。另一个原因是 Jupyter Notebook 或 IDE 的解释器路径和终端里激活的虚拟环境不一致。解决在终端里运行 source venv/bin/activateWindows 下为 venv\Scripts\activate 然后执行 python -c import cv2; print(cv2.version) 确认当前解释器能导入。如果 IDE 还是报错手动把项目的 Python 解释器路径切换到 venv 下的 python 程序。5.2 YOLO 检测结果里白球和库边上的反光点一起被框成球现象球桌库边有塑料反光条或者灯光直射区域YOLO 把高光区域识别成球置信度还不低导致规划模块把目标球坐标选在库边上画出来的路线完全偏离桌面。原因训练数据里缺少反光负样本模型把「高光圆形亮斑」当成了和球相似的特征。解决数据集里加入低保真度的反光图片作为负样本专门标注成 background 类重新训练一轮或者在推理层加一层 OpenCV 的高光过滤把亮度超过 240 的像素区域先剔除不进 YOLO。我的经验是两者结合最稳只靠数据增强或只靠阈值过滤都会有漏网之鱼。5.3 OpenCV 检测到的库边直线是斜的透视校正后球坐标错位现象摄像头安装在球桌侧上方拍到的球桌是梯形OpenCV 算出来的库边直线延长线在图像外相交YOLO 输出的球坐标没问题但换算到平面坐标系后球的相对位置全乱。原因没做透视校正直接用原始图像的像素坐标参与几何计算。解决用检测到的四条库边交点计算透视变换矩阵 cv2.getPerspectiveTransform把球桌区域映射到一个固定尺寸的俯视平面图之后的坐标换算和角度计算全部在这个平面上做。透视变换的四个点要按同一时针顺序传入否则矩阵会错乱我在这上面翻过车症状是校正后的图像是颠倒的。5.4 库边反弹算出来的是镜面反射但显示出来的路径穿过了另一颗球现象白球需要吃一库再击打目标球的场景下系统给出的路线在视觉上会穿过中间的一颗彩球按这个路线打肯定碰球犯规。原因规划模块只做了库边反弹和进球角度计算没有做碰撞检测。解决在路径求出来后加一段线段与圆形区域的相交判断遍历所有球的位置检查白球反弹路径上是否存在距离过近的球体。如果存在要么把该路径评分大幅扣减要么直接剔除避免演示时出现明显违规路线。线段与圆的相交检测用点到直线的距离公式就能做不需要引入复杂物理引擎。5.5 项目报告里的检测精度与现场演示效果对不上现象项目报告写 mAP 达到 85%但现场运行同一模型时频繁漏检给人水分很大的感觉。原因报告里的 mAP 是在测试集上算的测试集图片和现场摄像头拍摄画面存在光照、角度、分辨率差异模型泛化能力不够强。解决报告里除了写离线测试指标还要加一段现场运行的成功率统计比如统计连续 100 次检测中正确检测到全部球的比例。这个数字虽然不华丽但更真实答辩时反而更有说服力。这个习惯我坚持了很久实训项目现场演示翻车的大多数原因是报告指标和真实环境不一致提前做现场压测能挽回很多印象分。6. 调试技巧和验证方法把单帧检测扩展成可量化的效果评估方案做完之后最需要验证的不是「图上有路径画出来」而是「路径画得准不准」。我常用的验证方法是做一个离线的批处理脚本把测试视频逐帧拆出来对每一帧记录检测到的球数、实际球数、路径规划是否命中了目标球最后统计出一个成功率。这个脚本本身很简单但价值很大——它能让你在答辩前知道自己系统的真实水平在哪里。一个更进阶的验证思路是轨迹回放对比。用同一段视频跑两次第一次关掉可视化只记录路径参数第二次把路径画在帧上人工逐帧看目标球滚动的方向和系统预测的延长线是否重合。重合度超过 70% 说明几何模型可靠达不到就检查库边直线检测的稳定性、透视矩阵是否准确以及 YOLO 框的中心点是否因为球体遮挡而偏移。调参的时候记住一条我的血泪经验不要同时调多个参数。很多人遇到误检就同时改置信度阈值、imgsz、Canny 阈值结果问题没解决连基线效果都丢了。正确做法是每次只改一个参数记录下来效果变化形成一张简单的参数-效果对照表。这种做法听起来慢但你回头查问题的时候一定感谢自己。尤其像 minLineLength 和 conf_threshold 这种参数之间有耦合同时调出来一个问题根本定位不到是哪个参数出了问题。这套 Python OpenCVYOLO 台球击球路线规划系统真正难的地方不在深度学习推理而在坐标系统一和几何容错上。把 OpenCV 的像素坐标系、YOLO 的归一化坐标、实际球桌的物理坐标三者对齐整个系统就顺了对不齐就会一直出现「检测到了但算不对」的奇怪现象。拿到了源码包不要急着改模型先跑通、再改参、最后才动结构这个顺序能帮你省下大量排查时间。希望我的这些经验帮到你少走点弯路。本文还有配套的精品资源点击获取