《使用Qt Quick从零构建AI螺丝瑕疵检测系统》——5. 集成OpenCV：让程序拥有“视力”

一、概述

1.1 背景介绍：赋予应用“视力”

在此前的文章中，我们已经成功搭建了UI与逻辑之间的通信桥梁。现在，我们的应用程序拥有了美观的“面孔”和响应迅速的“神经系统”。然而，作为一个视觉检测应用，它还缺少最核心的器官——“眼睛”。

本篇文章的核心任务，就是为我们的应用安装一双强大的“眼睛”——集成全球最流行的开源计算机视觉库OpenCV (Open Source Computer Vision Library)。通过集成OpenCV，我们的程序将首次获得处理和显示真实图像的能力，这是后续实现一切AI视觉功能的前提和基础。

1.2 学习目标

通过本篇的学习，读者将能够：

在Windows环境下正确配置Qt项目以集成OpenCV库。
掌握在C++中OpenCV的图像数据结构cv::Mat与Qt的QImage之间的相互转换，这是两者协同工作的关键。
实现从本地加载一张螺丝图片，并通过我们架设好的前后端桥梁，最终在QML界面上成功显示出来。

二、集成OpenCV

2.1 安装OpenCV

首先，需要在开发环境中准备好OpenCV。

下载: 访问OpenCV官网的发布页面，下载适用于Windows的最新预编译版本（例如 4.12.0）。
解压: 运行下载的.exe文件，它实际上是一个自解压程序。将其解压到一个不含中文和空格的稳定路径并重命名为opencv4.12.0，例如 D:\toolplace\opencv4.12.0。解压后，关键的目录是 D:\toolplace\opencv4.12.0\build。

2.2 在Qt项目中配置CMake

要让我们的ScrewDetector项目能够找到并使用OpenCV，需要在CMakeLists.txt中添加配置。这是集成任何第三方C++库的标准流程。

1. 编写代码 (CMakeLists.txt)
打开项目根目录下的CMakeLists.txt文件，在find_package(Qt6 ...)之后，添加以下代码：

# --- 开始集成OpenCV ---
# 1. 设置OpenCV的根目录，请根据您的实际安装路径修改
set(OpenCV_DIR "D:/toolplace/opencv4.12.0/build")# 2. 查找OpenCV包，Core和Imgproc是我们目前需要的核心和图像处理模块
find_package(OpenCV REQUIRED COMPONENTS core imgproc)# 3. 包含OpenCV的头文件目录，以便#include指令能够找到它们
include_directories(${OpenCV_INCLUDE_DIRS})
# --- 结束集成OpenCV ---# ... (qt_add_executable等保持不变) ...# 在链接Qt库之后，链接OpenCV库
target_link_libraries(appScrewDetector PRIVATE# ... (原有的Qt6::Core, Qt6::Gui等)${OpenCV_LIBS} # 链接OpenCV库
)

关键代码分析:
(1) set(OpenCV_DIR ...): 这一行是关键，它明确告诉CMake去哪里寻找OpenCV的配置文件。路径必须指向包含OpenCVConfig.cmake文件的build目录。请务必根据自己的实际解压路径进行修改，并注意使用正斜杠/。
(2) find_package(OpenCV REQUIRED ...): CMake会根据OpenCV_DIR的路径，查找OpenCV的配置，并加载其头文件路径、库文件路径等信息到CMake变量中（如OpenCV_INCLUDE_DIRS和OpenCV_LIBS）。
(3) include_directories(...) 和 target_link_libraries(...): 这两行分别将OpenCV的头文件目录和库文件添加到了我们项目的编译和链接步骤中。

3. 验证集成
在backend.h的顶部添加以下两行：

#include <opencv2/core.hpp>
#include <opencv2/imgproc.hpp>

然后按Ctrl+B重新构建项目。如果项目能成功编译，没有任何“找不到文件”的错误，则说明OpenCV已经成功集成！

三、项目数据集介绍与准备

【核心概念：数据是AI的燃料】

无论是传统图像处理还是现代AI，一切算法都离不开数据。一个高质量、标准化的数据集是项目成功的基石。从本章开始，我们将引入一个贯穿后续所有算法章节的公开数据集。

我们将采用 MVTec Anomaly Detection Dataset (MVTec AD)。这是一个用于异常检测（在工业领域通常等同于瑕疵检测）的行业基准数据集，由德国MVTec公司发布，质量极高且下载方便。它包含了多种工业品类，我们正好可以使用其中的**“螺丝(screw)”**类别。

官方网站：https://www.mvtec.com/company/research/datasets/mvtec-ad

1. 下载与组织数据集

从上述官网链接进入,填写相关信息后跳转到下载页面，找到对应的Screw下载链接并下载screw.tar.xz文件。这是一个压缩包，需要使用支持.tar.xz格式的解压软件（如7-Zip）进行解压。
在我们的ScrewDetector项目根目录（与CMakeLists.txt同级）下，创建一个名为dataset的文件夹。
将解压后的screw文件夹完整地拷贝到这个dataset文件夹中。

最终的项目目录结构应如下所示：

ScrewDetector/
├── CMakeLists.txt
├── main.cpp
├── Main.qml
├── logo.rc
├── backend.h
├── backend.cpp
├── icons/
│   └── appicon.png
│   └── appicon.ico
└── dataset/      <-- 新建的数据集文件夹└── screw/    <-- 从压缩包解压出的文件夹├── train/│   └── good/│       ├── 000.png│       └── ...└── test/├── good/├── scratch_head/│   ├── 000.png│   └── ...└── ...

说明：将数据集放在项目源码目录之外，是一种良好的工程实践，可以保持代码仓库的整洁，避免将庞大的数据文件包含进版本控制系统。

数据集部分样本图片如下：
在这里插入图片描述

四、图像的桥梁：`ImageProvider`与格式转换

为了让QML能够显示由C++动态加载的图像，我们需要一个特殊的桥梁——QQuickImageProvider。您可以把QQuickImageProvider想象成一个内置在您应用中的、私有的、轻量级的“图像服务器”。

QML (客户端): 像浏览器一样，向一个特殊的URL地址发起请求，例如 image://liveImage/current_screw。
QQuickImageProvider (服务器): 它会接收到这个请求，解析出URL中的ID（current_screw），然后在C++代码中找到或生成对应的QImage对象，并将其作为响应“发回”给QML。同时，我们还需要实现cv::Mat到QImage的转换。

【例5-1】创建ImageProvider并实现格式转换。

1. 创建ImageProvider类

在Qt Creator中，右键点击项目，添加新文件... -> C++ -> C++ Class。
- 类名: ImageProvider
- 基类: 选择 QObject。
完成后，我们需要手动修改imageprovider.h和ImageProvider.cpp使其继承自QQuickImageProvider。

2. 编写代码 (imageprovider.h)

#ifndef IMAGEPROVIDER_H
#define IMAGEPROVIDER_H#include <QQuickImageProvider>
#include <QImage>// 继承自 QQuickImageProvider
class ImageProvider : public QQuickImageProvider
{
public:ImageProvider();// QML引擎会调用这个纯虚函数来请求图片QImage requestImage(const QString &id, QSize *size, const QSize &requestedSize) override;// 一个公共方法，用于从C++的Backend更新图片void updateImage(const QImage &image);private:// 用于存储当前要显示的图像QImage m_image;
};#endif // IMAGEPROVIDER_H

3. 编写代码 (imageprovider.cpp)

#include "imageprovider.h"ImageProvider::ImageProvider()// 构造函数中必须指定Provider的类型: QQuickImageProvider(QQuickImageProvider::Image)
{
}QImage ImageProvider::requestImage(const QString &id, QSize *size, const QSize &requestedSize)
{Q_UNUSED(id);Q_UNUSED(requestedSize);if (size) {*size = m_image.size();}return m_image;
}void ImageProvider::updateImage(const QImage &image)
{if (m_image != image) {m_image = image;}
}

4. cv::Mat到QImage的转换函数 (backend.cpp)

修改backend.cpp，添加图像转换函数：

// 在 backend.cpp 的顶部
#include <opencv2/core.hpp>
#include <opencv2/imgproc.hpp>static QImage matToQImage(const cv::Mat &mat) {if (mat.empty()) { return QImage(); }if (mat.type() == CV_8UC3) {return QImage(mat.data, mat.cols, mat.rows, mat.step, QImage::Format_RGB888).rgbSwapped();} else if (mat.type() == CV_8UC1) {return QImage(mat.data, mat.cols, mat.rows, mat.step, QImage::Format_Grayscale8);}return QImage();
}

五、加载、转换并显示图像

现在，我们将把Backend和ImageProvider串联起来，完成整个流程。

【例5-2】改造Backend以使用ImageProvider。

1. 注册ImageProvider (main.cpp)
QML引擎必须“知道”我们的ImageProvider的存在。

// main.cpp
#include <QGuiApplication>
#include <QQmlApplicationEngine>
#include <QIcon>
#include <QQmlContext>
#include "backend.h"
#include "imageprovider.h" // 1. 包含ImageProvider头文件int main(int argc, char *argv[])
{QGuiApplication app(argc, argv);app.setWindowIcon(QIcon(":/icons/appicon.png"));QQmlApplicationEngine engine;// 2. 实例化ImageProviderImageProvider *imageProvider = new ImageProvider();// 3. 将Provider注册到QML引擎，并给它一个URL方案名，例如"liveImage"engine.addImageProvider(QLatin1String("liveImage"), imageProvider);// 4. 创建Backend实例时，将provider的指针传给它Backend backend(imageProvider);engine.rootContext()->setContextProperty("backend", &backend);// ... (后续代码不变)return app.exec();
}

2. 修改Backend (backend.h & backend.cpp)
Backend通过OpenCV读取图像，转换为QImage后更新ImageProvider，然后通知QML去刷新图像。

// backend.h
#ifndef BACKEND_H
#define BACKEND_H
#include <QObject>
#include <QString>
// 移除 #include <QImage>
class ImageProvider; // 使用前向声明class Backend : public QObject
{Q_OBJECT
public:// 构造函数需要接收ImageProvider的指针explicit Backend(ImageProvider *provider, QObject *parent = nullptr);Q_INVOKABLE void startScan();
signals:// 信号不再传递QImage，只传递一个“刷新”指令和图像IDvoid imageReady(const QString &imageId);void statusMessageChanged(const QString &message);
private:ImageProvider *m_imageProvider;
};
#endif // BACKEND_H

// backend.cpp
#include "backend.h"
#include "imageprovider.h" // 在cpp中包含完整的头文件
#include <QDebug>
#include <QDir>
#include <opencv2/imgcodecs.hpp>// ... (matToQImage辅助函数)Backend::Backend(ImageProvider *provider, QObject *parent): QObject(parent), m_imageProvider(provider) // 在构造函数中保存指针
{}void Backend::startScan()
{qDebug() << "C++: Loading image with OpenCV...";emit statusMessageChanged("正在从数据集加载图像...");// 1. 构建数据集图片的绝对路径// QDir::currentPath() 获取的是构建目录，需要向上两级到项目根目录// 我们从MVTec数据集中挑选一张带瑕疵的图片作为示例QString imagePath = QDir::currentPath() + "/../../dataset/screw/test/scratch_head/000.png";// 2. 使用OpenCV从文件系统加载图像// 注意：imread需要一个标准C++字符串cv::Mat imageMat = cv::imread(imagePath.toStdString());if (imageMat.empty()) {qDebug() << "Error: Could not load image from path:" << imagePath;emit statusMessageChanged("错误：无法从数据集加载图像！请检查路径。");return;}// 3. 将cv::Mat转换为QImageQImage imageQ = matToQImage(imageMat);if (imageQ.isNull()){emit statusMessageChanged("错误：图像格式转换失败！");return;}// 4. 更新ImageProvider中的图像m_imageProvider->updateImage(imageQ);// 5. 发射信号，只告诉QML需要刷新的图像IDemit imageReady("screw_sample");emit statusMessageChanged("图像显示成功！");
}

3. 修改QML以使用URL (Main.qml)
这是最后一步，让QML的Image组件使用我们自定义的image:// URL。

// Main.qml
import QtQuick
// ...Window {// ...Connections {target: backendfunction onStatusMessageChanged(message) {statusLabel.text = message;}function onImageReady(imageId) {// 1. 构建URL: "image://<provider_name>/<image_id>"// 2. 附加一个时间戳来强制刷新，避免QML使用缓存videoDisplay.source = "image://liveImage/" + imageId+ "?" + new Date().getTime();}}ColumnLayout {// ...Frame {id: videoFrame// ...Image {id: videoDisplayanchors.fill: parentfillMode: Image.PreserveAspectFitcache: false // 显式禁用缓存，增加刷新可靠性}}// ...}
}

4. 运行结果
现在再次运行程序，点击“开始检测”按钮。流程变为：

QML: 调用 backend.startScan()。
C++ Backend: 加载cv::Mat -> 转换为QImage -> 调用 m_imageProvider->updateImage()将新图像存入Provider -> 发射 imageReady("screw_sample") 信号。
QML Connections: 收到信号，执行 onImageReady("screw_sample")。
QML Image: source属性被设置为 "image://liveImage/screw_sample?..."。
QML引擎: 看到image://协议，将请求转发给名为liveImage的ImageProvider。
C++ ImageProvider: requestImage()被调用，它返回存储在m_image中的最新图像。
QML Image: 成功获取并显示图像。