简介这是一套基于 OpenCV 与 Qt 开发的通用机器视觉软件框架源码仿照 easyvision 的设计思路实现面向具备一定 C 与视觉算法基础、希望快速搭建自有视觉平台的开发者与工程人员。框架基于 Qt5.12.12、VS2019 与 OpenCV 构建支持多相机多线程运行每个工具以独立 DLL 形式存在主程序通过公用接口完成加载与调用工具可自由扩展所有算法均未封装便于按需补充自定义工具。资源包共约 2000 个文件以 1213 个 cpp 源文件、612 个 h 头文件为主另含 172 个 txt 说明与 3 个 pdf 文档压缩包约 607.66MB涵盖图像算法工具、逻辑工具、通讯工具与系统工具等模块。目前已有 1955 人学习参考读者可借此理解视觉框架的模块划分、工具接口设计与多线程调度机制并在此基础上略作修改用于实际项目。1. 仿 EasyVision 的通用视觉框架为什么一线工程师都在自己攒一套产线上新来一台相机老板下午就要看检测效果你打开某商业视觉软件加密狗没带、授权到期、算子还锁着——这种场景干过三年以上的自动化工程师基本都遇到过。所谓通用视觉框架本质就是把「取图 → 预处理 → 算子处理 → 结果判定 → 界面展示」这条链路做成可配置、可扩展的壳子让新项目不用从零写 MFC 对话框。EasyVision 这类商业软件之所以被反复提及是因为它把相机管理、流程编排、参数面板、结果渲染这几件事做得足够顺手。而基于 OpenCV Qt 开发一套自己的框架核心动机就三个算子库免费且够用、界面跨平台、源码在自己手里想怎么改就怎么改。这套东西适合谁适合已经会用cv::Mat做基本图像处理、但每次做新项目都要重写一遍相机采集和参数界面的工控/机器视觉从业者。它不解决算法精度问题它解决的是「同样的事不要做第二遍」。2. 框架骨架怎么搭从 Qt 工程结构到 OpenCV 接入2.1 为什么选 Qt Widgets 而不是 QML 做视觉框架视觉框架的界面有个特点大量参数控件SpinBox、Slider、ComboBox和图像显示窗口混排而且参数面板往往需要根据算子动态生成。QML 做动画和触屏交互确实漂亮但在工控场景里参数面板的布局密度极高一个算子可能带十几个参数用 QML 手写每个算子的参数面板工作量会失控。Qt Widgets 配合QFormLayout和自定义的ParamWidget基类可以用工厂模式批量生成参数界面这是我在实际项目里验证过的做法。另一个现实原因是部署环境。很多产线工控机还跑着 Windows 7 或者精简版 LinuxQt Widgets 对老系统的兼容性比 QML 的 OpenGL 渲染管线稳得多。Qt 5.15.2 是最后一个提供离线安装包的 LTS 版本qt-opensource-windows-x86-5.15.2.exe装完直接能用不需要在线账号这对不能联外网的车间环境很关键。工程结构上我一般这样分VisionFramework/ ├── core/ # 框架核心流程引擎、算子基类、数据总线 │ ├── OperatorBase.h/cpp │ ├── FlowEngine.h/cpp │ └── DataBus.h/cpp ├── operators/ # 具体算子实现 │ ├── BlurOp.h/cpp │ ├── ThresholdOp.h/cpp │ ├── FindLineOp.h/cpp │ └── ... ├── ui/ # 界面层 │ ├── MainWindow.h/cpp │ ├── ImageView.h/cpp │ └── ParamPanel.h/cpp ├── camera/ # 相机采集抽象层 │ ├── CameraBase.h │ ├── USBCamera.h/cpp │ └── FileCamera.h/cpp └── third_party/ # OpenCV 等第三方库这个结构的核心思想是core不依赖ui算子不依赖具体界面。这样后面想把框架从桌面端搬到嵌入式 Linux 上跑只需要换ui层core和operators原封不动。2.2 OpenCV 的接入方式与 CMake 配置OpenCV 接入 Qt 工程有两种常见做法一种是直接下载预编译包配好环境变量后在.pro或CMakeLists.txt里链接另一种是自己用 CMake 编译只保留需要的模块。预编译包省事但体积大完整包解压后 2GB 以上而且默认不带 CUDA。自己编译可以裁掉dnn、gapi这些用不上的模块编译产物能压到 200MB 以内。我一般用 CMake 管理工程因为 Qt 6 已经全面转向 CMake早点切换省得后面迁移。一个最小可用的CMakeLists.txt长这样cmake_minimum_required(VERSION 3.16) project(VisionFramework LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTOUIC ON) set(CMAKE_AUTORCC ON) # Qt 组件Widgets 做界面Concurrent 做多线程流程 find_package(Qt5 REQUIRED COMPONENTS Widgets Concurrent) # OpenCV指定安装路径避免和系统里其他版本冲突 set(OpenCV_DIR D:/libs/opencv-4.8.0/build) find_package(OpenCV REQUIRED) include_directories( ${CMAKE_CURRENT_SOURCE_DIR}/core ${CMAKE_CURRENT_SOURCE_DIR}/operators ${OpenCV_INCLUDE_DIRS} ) # 把 core 和 operators 编成静态库方便单独测试 add_library(vision_core STATIC core/OperatorBase.cpp core/FlowEngine.cpp core/DataBus.cpp ) target_link_libraries(vision_core ${OpenCV_LIBS}) add_executable(VisionFramework ui/MainWindow.cpp ui/ImageView.cpp ui/ParamPanel.cpp main.cpp ) target_link_libraries(VisionFramework vision_core Qt5::Widgets Qt5::Concurrent ${OpenCV_LIBS} )这里有几个参数值得说明。OpenCV_DIR指向的是 OpenCV 编译目录下的build文件夹里面要有OpenCVConfig.cmakeCMake 靠这个文件找到头文件和库。如果报Could NOT find OpenCV九成是路径写错了或者没编译。CMAKE_AUTOMOC ON是 Qt 的元对象编译开关只要类里用了Q_OBJECT宏就必须开否则信号槽连不上编译能过但运行时报undefined reference to vtable这个坑我踩过不止一次。提示OpenCV 和 Qt 的版本要匹配编译器。Qt 5.15.2 的 MSVC 版本是 2019OpenCV 预编译包也要选vc16或vc17混用 MinGW 和 MSVC 会导致链接期一堆符号找不到。2.3 算子基类设计让每个视觉算子都能被流程引擎调度框架能不能扩展全看算子基类设计得好不好。我的做法是定义一个纯虚基类OperatorBase所有算子继承它流程引擎只认基类指针。// core/OperatorBase.h #pragma once #include QString #include QVariantMap #include opencv2/core.hpp class OperatorBase { public: virtual ~OperatorBase() default; // 算子名称用于界面显示和日志 virtual QString name() const 0; // 参数定义返回参数名、类型、默认值、范围 // 界面层根据这个动态生成控件 virtual QVariantMap paramDefs() const 0; // 核心执行函数输入图像 参数输出图像 结果 // 返回 false 表示执行失败errorMsg 带出原因 virtual bool execute(const cv::Mat input, cv::Mat output, const QVariantMap params, QString errorMsg) 0; // 是否需要在界面上显示结果叠加比如画线、画框 virtual bool hasOverlay() const { return false; } virtual void drawOverlay(cv::Mat image, const QVariantMap params) {} };paramDefs()返回一个QVariantMap里面描述每个参数的元信息。比如一个高斯模糊算子QVariantMap BlurOp::paramDefs() const { QVariantMap defs; // key: 参数名value: 另一个 map 描述类型和范围 defs[kernel_size] QVariantMap{ {type, int}, {min, 1}, {max, 31}, {step, 2}, {default, 5}, {label, 核大小} }; defs[sigma] QVariantMap{ {type, double}, {min, 0.0}, {max, 10.0}, {step, 0.1}, {default, 1.5}, {label, Sigma} }; return defs; }界面层的ParamPanel遍历这个 map遇到type int就生成QSpinBox遇到double就生成QDoubleSpinBox遇到enum就生成QComboBox。这样新增一个算子只要实现paramDefs()和execute()界面自动就有了不用手写任何控件代码。这是整套框架里最省事的设计也是我建议新手优先吃透的部分。execute()的签名里input和output分开而不是原地修改是为了支持流程分支——同一个输入可以喂给多个算子各自输出不同结果。errorMsg用引用传出避免异常在 Qt 事件循环里乱飞。3. 流程引擎与图像显示把算子串起来跑通3.1 用有向无环图组织算子执行顺序单个算子跑通不难难的是把十几个算子按依赖关系串起来还要支持分支和合并。常见做法是用有向无环图DAG每个节点是一个算子实例边表示数据流向。流程引擎的执行逻辑就是拓扑排序先算入度为 0 的节点算完把输出传给下游下游入度减一直到所有节点执行完。数据结构上我用QVectorOperatorNode存节点每个节点记录算子指针、参数、输入源列表、输出缓存。执行时用一个队列维护当前可执行的节点// core/FlowEngine.cpp 核心执行循环 bool FlowEngine::run(const cv::Mat source, QString errorMsg) { // 重置所有节点的入度计数 for (auto node : m_nodes) { node.pendingInputs node.inputSources.size(); node.output cv::Mat(); } QQueueint ready; for (int i 0; i m_nodes.size(); i) { if (m_nodes[i].pendingInputs 0) { // 无输入源的节点直接喂原始图像 m_nodes[i].output source.clone(); ready.enqueue(i); } } while (!ready.isEmpty()) { int idx ready.dequeue(); auto node m_nodes[idx]; // 执行算子 cv::Mat out; if (!node.op-execute(node.output, out, node.params, errorMsg)) { errorMsg QString(节点[%1]执行失败: %2) .arg(node.op-name()).arg(errorMsg); return false; } node.output out; // 通知下游节点 for (int downstream : node.downstream) { auto d m_nodes[downstream]; // 多输入节点把上游输出拼成 vector 传入 d.inputBuffers.append(out); if (--d.pendingInputs 0) { ready.enqueue(downstream); } } } return true; }这段代码里pendingInputs是关键状态它保证一个节点只有在所有上游都算完后才执行。inputBuffers存上游传来的图像多输入算子比如图像拼接、模板匹配从这里面取。实际项目中流程引擎还要处理循环检测——如果用户连出一个环拓扑排序会死循环所以建图的时候就要用 DFS 检测环并拒绝。注意流程引擎跑在 UI 线程会卡界面。我一般把run()放到QThread或者用QtConcurrent::run异步执行通过信号槽把中间结果发回界面刷新。但cv::Mat跨线程传递要注意引用计数clone()一下最保险否则可能出现图像数据被提前释放的花屏。3.2 图像显示控件缩放、拖拽与叠加绘制视觉框架的图像显示不是简单QLabel::setPixmap就完事。产线调试时工程师需要放大看边缘、拖拽看局部、在图上画 ROI 框选区域。这些都要在ImageView里自己实现。核心思路是重写paintEvent维护一个QTransform记录当前的缩放和平移把cv::Mat转成QImage后按变换绘制。cv::Mat转QImage有个经典坑OpenCV 默认 BGRQt 要 RGB通道顺序不对颜色就偏了。// ui/ImageView.cpp QImage ImageView::matToQImage(const cv::Mat mat) { if (mat.empty()) return QImage(); switch (mat.type()) { case CV_8UC1: { // 灰度图直接构造注意 QImage 不拷贝数据时要保证 mat 生命周期 QImage img(mat.data, mat.cols, mat.rows, static_castint(mat.step), QImage::Format_Grayscale8); return img.copy(); // copy 一份避免 mat 释放后悬空 } case CV_8UC3: { cv::Mat rgb; cv::cvtColor(mat, rgb, cv::COLOR_BGR2RGB); // BGR - RGB QImage img(rgb.data, rgb.cols, rgb.rows, static_castint(rgb.step), QImage::Format_RGB888); return img.copy(); } default: return QImage(); } }copy()这一步不能省。QImage 构造函数如果直接引用mat.data它不管理这块内存mat析构后 QImage 就指向野指针界面刷新时随机崩溃这种 bug 查起来非常痛苦。mat.step是行字节数不是cols * channels因为 OpenCV 会对齐内存用错了图像会斜。缩放拖拽用QTransform实现void ImageView::wheelEvent(QWheelEvent* event) { double factor event-angleDelta().y() 0 ? 1.15 : 1.0 / 1.15; // 以鼠标位置为中心缩放 QPointF cursorPos event-position(); m_transform.translate(cursorPos.x(), cursorPos.y()); m_transform.scale(factor, factor); m_transform.translate(-cursorPos.x(), -cursorPos.y()); update(); // 触发重绘 }wheelEvent里先平移到鼠标位置再缩放再平移回去这样缩放中心就是鼠标所在点符合直觉。如果直接scale不处理平移缩放会以控件左上角为中心用起来很别扭。叠加绘制画检测框、十字线、ROI在paintEvent里用QPainter在图像之上画。算子的drawOverlay()负责把结果画到cv::Mat上或者返回几何信息让ImageView用QPainter画。我倾向于后者因为QPainter的抗锯齿和线宽控制比 OpenCV 的cv::line好看而且不破坏原始图像数据。3.3 相机采集抽象层一套接口对接多种相机框架要通用相机层必须抽象。我定义一个CameraBase接口open()、close()、grab()三个纯虚函数USB 相机、网口相机、文件回放各自实现。这样流程引擎和界面层只依赖接口换相机不用改上层代码。// camera/CameraBase.h class CameraBase : public QObject { Q_OBJECT public: virtual bool open(const QString config) 0; virtual void close() 0; // 抓一帧成功返回 true图像写入 frame virtual bool grab(cv::Mat frame) 0; virtual QString lastError() const 0; signals: void frameReady(const cv::Mat frame); // 连续采集模式用信号通知 };文件回放相机实现最简单从磁盘读图序列适合调试算法时反复跑同一组图。USB 相机用 OpenCV 的VideoCapture就能接但要注意cap.set(CAP_PROP_FRAME_WIDTH, ...)之后要read一次确认实际分辨率有些相机不支持任意分辨率会静默改成最接近的值。网口工业相机一般有厂商 SDK封装一层适配到CameraBase即可。采集线程和流程线程分开采集线程只管往缓冲区写最新帧流程线程取最新帧处理中间用QMutex保护。这样即使算法处理慢也不会丢帧导致相机卡死。4. 避坑与排查那些让框架跑不起来的典型问题4.1 现象程序启动报could not find the Qt platform plugin原因Qt 运行时找不到平台插件通常是部署时没把platforms/qwindows.dllWindows或platforms/libqxcb.soLinux放到可执行文件旁边或者QT_QPA_PLATFORM_PLUGIN_PATH环境变量指向了错误版本。解决用windeployqtWindows或linuxdeployqtLinux自动拷贝依赖。如果手动部署确保platforms文件夹和 exe 同级。Linux 上如果报linuxfb找不到检查是否装了qt5-qpa-plugins包嵌入式环境还要确认 framebuffer 设备权限。4.2 现象链接期报fatal: cannot mix incompatible Qt library原因工程里混用了两个不同版本或不同编译器构建的 Qt 库。比如系统里装了 Qt 5.15.2 和 Qt 6.xCMake 的find_package找到了一个但运行时加载了另一个。解决在CMakeLists.txt里显式指定Qt5_DIR或Qt6_DIR锁定版本。运行时用lddLinux或DependenciesWindows检查实际加载的 Qt 库路径。最彻底的办法是把 Qt 库随程序一起打包不依赖系统安装。4.3 现象ModuleNotFoundError: No module named opencv或 C 里contourArea 未定义标识符原因Python 环境是没装opencv-pythonC 是没包含对应头文件。contourArea在opencv2/imgproc.hpp里只包含core.hpp是不够的。解决Python 用pip install opencv-python注意别和opencv-contrib-python混装。C 里按模块包含头文件图像处理加#include opencv2/imgproc.hpp视频 IO 加#include opencv2/videoio.hpp。CMake 里链接opencv_imgproc、opencv_core等具体模块别只链opencv_world否则换环境容易出问题。4.4 现象图像显示颜色偏蓝或偏红原因OpenCV 的cv::Mat默认 BGR 通道顺序Qt 的QImage::Format_RGB888期望 RGB直接转换通道就反了。解决转换前先cv::cvtColor(mat, rgb, cv::COLOR_BGR2RGB)。如果图像来自相机 SDK先确认 SDK 输出的是 BGR 还是 RGB有些工业相机默认输出 Bayer 格式还要先做去马赛克。4.5 现象流程跑几轮后内存持续上涨原因cv::Mat在流程节点间传递时如果每个节点都clone()一份中间结果没及时释放内存就堆积。或者QImage构造时引用了cv::Mat的数据但没copy()导致cv::Mat无法释放。解决流程引擎每轮结束后清空所有节点的output和inputBuffers。cv::Mat本身是引用计数赋值不拷贝数据但clone()会。检查代码里有没有不必要的clone()。用valgrind或 Visual Studio 的内存分析工具定位泄漏点。5. 进阶技巧用参数预设和算子热加载把调试效率提上去框架跑通之后真正影响日常效率的是两件事参数调好后能不能存下来复用以及新增算子要不要重新编译整个工程。参数预设我用 JSON 存。每个流程节点导出成{算子名, 参数map, 输入源}整个流程存成一个.vflow文件。下次打开直接加载参数面板自动回填。这样同一套检测逻辑换个产品只需要改几个参数值不用重新连线。实现上QVariantMap和QJsonObject互转有现成 APIQJsonDocument::fromVariant()一行搞定。// 保存流程 QJsonObject flowJson; QJsonArray nodesArray; for (const auto node : m_nodes) { QJsonObject n; n[op] node.op-name(); n[params] QJsonObject::fromVariantMap(node.params); n[inputs] QJsonArray::fromStringList(node.inputNames); nodesArray.append(n); } flowJson[nodes] nodesArray; QFile file(path); file.open(QIODevice::WriteOnly); file.write(QJsonDocument(flowJson).toJson());算子热加载稍微复杂但收益很大。做法是把每个算子编成独立的动态库.dll/.so框架启动时扫描plugins目录用QLibrary加载通过一个导出函数创建算子实例。这样新增算子只要编译那一个库扔进目录重启即可不用动主程序。// 算子插件导出宏 extern C Q_DECL_EXPORT OperatorBase* createOperator() { return new FindLineOp(); }主程序加载QLibrary lib(pluginPath); if (lib.load()) { auto create reinterpret_castOperatorBase*(*)()( lib.resolve(createOperator)); if (create) { OperatorBase* op create(); // 注册到算子工厂 OperatorFactory::instance().registerOp(op-name(), create); } }这里有个血泪经验插件和主程序必须用同一套 Qt 和 OpenCV 编译ABI 不匹配时load()成功但resolve()返回空或者调用时直接崩溃。我一般把 Qt 和 OpenCV 的版本号写进插件元数据加载时校验不匹配就拒绝并提示。验证框架是否真的通用我的习惯是拿三个不同场景跑一遍一个尺寸测量找边、拟合直线、一个缺陷检测阈值、轮廓分析、一个定位引导模板匹配、坐标输出。如果这三个场景都能在不改框架代码的前提下、只靠配置算子和参数完成那这套框架就算立住了。我自己的经验是第一版别追求算子多先把采集、流程、显示、参数这四件事做扎实后面加算子就是体力活。希望帮到你。本文还有配套的精品资源点击获取