refactor: 使用 OpenCV 统一 ONNX 分类预处理并更新 CI

Author: Mq-b

.github/workflows/cpp-cmake-ci.yml

@@ -96,17 +96,21 @@ jobs:
           restore-keys: |
             vcpkg-${{ runner.os }}-${{ matrix.vcpkg_triplet }}-
 
-      - name: Install ONNX Runtime on Windows
+      - name: Install C++ dependencies on Windows
         if: runner.os == 'Windows'
         shell: pwsh
         run: |
-          & "$env:VCPKG_ROOT\vcpkg.exe" install "onnxruntime:${{ matrix.vcpkg_triplet }}"
+          & "$env:VCPKG_ROOT\vcpkg.exe" install `
+            "onnxruntime:${{ matrix.vcpkg_triplet }}" `
+            "opencv4:${{ matrix.vcpkg_triplet }}"
 
-      - name: Install ONNX Runtime on Linux
+      - name: Install C++ dependencies on Linux
         if: runner.os == 'Linux'
         shell: bash
         run: |
-          "$VCPKG_ROOT/vcpkg" install "onnxruntime:${{ matrix.vcpkg_triplet }}"
+          "$VCPKG_ROOT/vcpkg" install \
+            "onnxruntime:${{ matrix.vcpkg_triplet }}" \
+            "opencv4:${{ matrix.vcpkg_triplet }}"
 
       - name: Configure on Windows
         if: runner.os == 'Windows'

CMakeLists.txt

@@ -13,13 +13,16 @@ set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
 
 find_package(Qt5 REQUIRED COMPONENTS Core Gui Widgets)
 find_package(onnxruntime CONFIG REQUIRED)
+find_package(OpenCV CONFIG REQUIRED COMPONENTS core imgcodecs imgproc)
 
 set(CMAKE_AUTOMOC ON)
 set(CMAKE_AUTORCC ON)
 set(CMAKE_AUTOUIC ON)
 
 add_executable(${PROJECT_NAME}
     src/main.cpp
+    src/ImageUtils.h
+    src/ImageUtils.cpp
     src/MainWindow.h
     src/MainWindow.cpp
     src/OnnxClassifier.h
@@ -30,6 +33,9 @@ target_link_libraries(${PROJECT_NAME} PRIVATE
     Qt5::Core
     Qt5::Gui
     Qt5::Widgets
+    opencv_core
+    opencv_imgcodecs
+    opencv_imgproc
     onnxruntime::onnxruntime
 )
 

README.md

@@ -1,6 +1,6 @@
-# YOLO 图像分类推理工具 (C++ / Qt5 / ONNX Runtime)
+# YOLO 图像分类推理工具 (C++ / Qt5 / OpenCV / ONNX Runtime)
 
-基于 ONNX Runtime 的跨平台图像分类推理程序Demo，使用 Qt5 构建图形界面。
+基于 ONNX Runtime 的跨平台图像分类推理程序 Demo，使用 Qt5 构建图形界面，并通过 OpenCV 统一图片解码与预处理。
 
 当前界面支持：
 
@@ -36,16 +36,17 @@ cpp_inference/
 
 | 模块 | 职责 |
 |------|------|
-| `OnnxClassifier` | 封装 ONNX Runtime，负责模型加载、图像预处理、推理执行 |
+| `OnnxClassifier` | 封装 ONNX Runtime，负责模型加载、基于 OpenCV 的图像预处理、推理执行 |
 | `MainWindow` | Qt 图形界面，负责用户交互、图片显示、单张/批量结果展示 |
+| `ImageUtils` | 使用 OpenCV 统一图片解码，并在 OpenCV / Qt 之间转换图像格式 |
 | `main.cpp` | 程序入口，初始化 QApplication |
 
 ### 推理流程
 
 ```txt
 用户选择图片 → MainWindow::classify()
                   ↓
-            QImage 传入 OnnxClassifier
+            OpenCV 解码原图
                   ↓
             preprocess() → 短边缩放到输入尺寸 → 中心裁剪到输入尺寸 → RGB转换 → /255
                   ↓
@@ -62,6 +63,7 @@ cpp_inference/
 |------|------|------|
 | CMake | ≥ 3.16 | 构建系统 |
 | Qt5 | 5.12+ | GUI 框架 |
+| OpenCV | 4.x | 图像解码、缩放、裁剪 |
 | ONNX Runtime | 1.23+ | 推理引擎 |
 | 编译器 | MSVC / Clang / GCC | C++17 支持 |
 
@@ -77,7 +79,7 @@ cmake --build build
 
 ## CI
 
-仓库已提供一套仅覆盖 **纯 C++ / Qt / ONNX Runtime** 的 GitHub Actions 流水线：
+仓库已提供一套覆盖 **C++ / Qt / OpenCV / ONNX Runtime** 的 GitHub Actions 流水线：
 
 - Windows：Qt `5.12.12` + MSVC + CMake/Ninja 构建
 - Linux：Qt `5.12.12` + GCC + CMake/Ninja 构建
@@ -145,11 +147,12 @@ cmake --build build
 当前 `cpp_inference` 调用这份 Ultralytics 导出的分类 ONNX 之前，按下面的顺序做预处理：
 
 ```txt
-1. 读取原图并转成 RGB888
+1. 用 OpenCV 解码原图
 2. 按比例缩放，使“短边”刚好等于模型输入尺寸
 3. 从缩放后的图像中心裁出 HxW（本项目里是 224x224）
-4. 将像素从 0~255 转成 0~1 的 float
-5. 按 NCHW 布局喂给 ONNX Runtime
+4. 转成 RGB
+5. 将像素从 0~255 转成 0~1 的 float
+6. 按 NCHW 布局喂给 ONNX Runtime
 ```
 
 也就是：
@@ -167,19 +170,34 @@ cmake --build build
 
 ## 与 Python 结果的差异说明
 
-当前版本的目标是让 **预测类别** 与 Python 侧测试结果保持一致。
+当前版本的目标是让 **预测类别** 与 Python 侧测试结果保持一致，并把置信度差异尽量收敛。
+
+需要先明确一点：当前仓库中的 [`py/predict_gui.py`](./py/predict_gui.py) 并不是“手写 OpenCV + ONNX Runtime”的对照脚本，而是通过 Ultralytics 的 `YOLO(...)` 封装来加载模型并执行推理。
+
+这意味着：
+
+- C++ 侧是当前工程自己实现的 `OpenCV 解码 + 预处理 + ONNX Runtime 推理`
+- Python 侧是 `Ultralytics 封装 + 其内部推理流程`
+
+即使 Python 最终对 `.onnx` 也可能落到 ONNX Runtime 后端，前处理、批处理组织、结果封装和显示逻辑仍然不一定与当前 C++ 代码完全一致。
 
 在这个前提下，C++ / Qt / ONNX Runtime 的推理结果可能会出现下面这种情况：
 
 - 最终类别一致
 - 置信度数值与 Python 脚本不是完全相同
 
-这在当前阶段是正常现象，主要原因通常不是模型变了，而是推理前处理还没有做到和 Python 侧 **像素级完全一致**。常见差异来源包括：
+这在当前阶段是正常现象，主要原因通常不是模型变了，而是两边的推理链路没有做到 **完全同一实现**。常见差异来源包括：
+
+1. Python 脚本不是直接调用你自己写的 `onnxruntime.InferenceSession(...)`，而是走 Ultralytics 的模型封装
+2. 图像解码库不同：Python 侧通常使用 PIL / OpenCV，旧版 C++ 侧使用 Qt 的 `QImageReader`
+3. 缩放插值实现不同：即使都是双线性插值，不同库的边界和取整策略也可能不同
+4. 中心裁剪取整细节不同：奇偶尺寸下，中心点可能相差 1 个像素
+5. EXIF、颜色通道读取、内部像素格式处理存在实现差异
+6. 输出结果的封装方式不同：Python 侧展示的是 Ultralytics `result.probs.top1conf`，C++ 侧直接读取模型输出 tensor
+
+当前仓库已经改为在 C++ 侧使用 OpenCV 统一图片解码、缩放和裁剪，这会明显缩小和 Python 常见 OpenCV 链路之间的差异。
 
-1. 图像解码库不同：Python 侧通常使用 PIL / OpenCV，C++ 侧这里使用 Qt 的 `QImageReader`
-2. 缩放插值实现不同：即使都是双线性插值，不同库的边界和取整策略也可能不同
-3. 中心裁剪取整细节不同：奇偶尺寸下，中心点可能相差 1 个像素
-4. EXIF 自动旋转、颜色通道读取、内部像素格式处理存在实现差异
+如果这份分类 ONNX 本身已经输出概率分布，那么 C++ 直接读取输出 tensor 是合理的；但如果你想做“严格对齐”，仍然不能只拿 `predict_gui.py` 的显示结果来判断，需要让 Python 侧也改成同一套 `OpenCV + ONNX Runtime` 推理流程后再比较。
 
 因此，当前项目对“结果正常”的判定标准是：
 
@@ -190,9 +208,10 @@ cmake --build build
 
 如果后续需要把置信度进一步对齐到非常接近 Python，推荐做法是：
 
-1. Python 导出同一张图片的预处理后输入 tensor
-2. C++ 导出同一张图片的预处理后输入 tensor
-3. 对两边 tensor 做逐元素比对，再继续调整缩放、裁剪和读图细节
+1. Python 侧单独写一个 `OpenCV + ONNX Runtime` 的最小推理脚本
+2. Python 导出同一张图片的预处理后输入 tensor
+3. C++ 导出同一张图片的预处理后输入 tensor
+4. 对两边 tensor 做逐元素比对，再继续调整缩放、裁剪和读图细节
 
 ## 扩展
 

scripts/package-windows.ps1

@@ -77,6 +77,15 @@ foreach ($dllName in $requiredRuntimeDlls) {
     Copy-Item -LiteralPath $sourcePath -Destination $packageRoot
 }
 
+$opencvDlls = @(Get-ChildItem -LiteralPath $runtimeBinDir -Filter "opencv*.dll")
+if ($opencvDlls.Count -eq 0) {
+    throw "OpenCV runtime DLLs not found in: $runtimeBinDir"
+}
+
+foreach ($dll in $opencvDlls) {
+    Copy-Item -LiteralPath $dll.FullName -Destination $packageRoot
+}
+
 $windeployqt = Get-Command windeployqt.exe -ErrorAction Stop
 & $windeployqt.Source `
     --release `

src/ImageUtils.cpp

@@ -0,0 +1,78 @@
+/**
+ * @file ImageUtils.cpp
+ * @brief 基于 OpenCV 的图片读取与 Qt 图像转换。
+ */
+#include "ImageUtils.h"
+
+#include <QFile>
+
+#include <opencv2/imgcodecs.hpp>
+#include <opencv2/imgproc.hpp>
+
+#include <vector>
+
+namespace ImageUtils {
+
+cv::Mat loadColorImage(const QString &imagePath) {
+    // 先用 Qt 读取文件字节，避免直接把 QString 路径传给 OpenCV 时
+    // 在 Windows/非 ASCII 路径场景下出现兼容性问题。
+    QFile file(imagePath);
+    if (!file.open(QIODevice::ReadOnly)) {
+        return {};
+    }
+
+    const QByteArray encoded = file.readAll();
+    if (encoded.isEmpty()) {
+        return {};
+    }
+
+    // OpenCV 解码统一返回 BGR 排列的彩色图，供后续推理前处理复用。
+    std::vector<uchar> buffer(encoded.begin(), encoded.end());
+    return cv::imdecode(buffer, cv::IMREAD_COLOR);
+}
+
+QImage toQImage(const cv::Mat &image) {
+    if (image.empty()) {
+        return {};
+    }
+
+    if (image.type() == CV_8UC1) {
+        return QImage(
+            image.data,
+            image.cols,
+            image.rows,
+            static_cast<int>(image.step),
+            QImage::Format_Grayscale8
+        ).copy();
+    }
+
+    if (image.type() == CV_8UC3) {
+        cv::Mat rgb;
+        // Qt 的 RGB888 与 OpenCV 的 BGR 三通道内存顺序不同，需要显式转换。
+        cv::cvtColor(image, rgb, cv::COLOR_BGR2RGB);
+        return QImage(
+            rgb.data,
+            rgb.cols,
+            rgb.rows,
+            static_cast<int>(rgb.step),
+            QImage::Format_RGB888
+        ).copy();
+    }
+
+    if (image.type() == CV_8UC4) {
+        cv::Mat rgba;
+        // 四通道场景同理，需要从 BGRA 转成 Qt 侧期望的 RGBA。
+        cv::cvtColor(image, rgba, cv::COLOR_BGRA2RGBA);
+        return QImage(
+            rgba.data,
+            rgba.cols,
+            rgba.rows,
+            static_cast<int>(rgba.step),
+            QImage::Format_RGBA8888
+        ).copy();
+    }
+
+    return {};
+}
+
+} // namespace ImageUtils

src/ImageUtils.h

@@ -0,0 +1,42 @@
+/**
+ * @file ImageUtils.h
+ * @brief 使用 OpenCV 统一图片解码与格式转换。
+ */
+#pragma once
+
+#include <QImage>
+#include <QString>
+
+#include <opencv2/core/mat.hpp>
+
+namespace ImageUtils {
+
+/**
+ * @brief 从磁盘读取图片并解码为 BGR 三通道 Mat。
+ *
+ * 这里先使用 Qt 的 QFile 读取原始字节，再交给 OpenCV `imdecode()`，
+ * 这样可以同时兼顾：
+ *   - Qt 对 QString/中文路径的处理能力
+ *   - OpenCV 的统一图像解码行为
+ *
+ * @param imagePath 图片路径
+ * @return 成功时返回 `CV_8UC3` 的 BGR 图像；失败时返回空 Mat
+ */
+cv::Mat loadColorImage(const QString &imagePath);
+
+/**
+ * @brief 将 OpenCV Mat 转成可供 Qt UI 展示的 QImage。
+ *
+ * 当前仅处理常见的 8-bit 图像类型：
+ *   - `CV_8UC1` -> `QImage::Format_Grayscale8`
+ *   - `CV_8UC3` -> `QImage::Format_RGB888`
+ *   - `CV_8UC4` -> `QImage::Format_RGBA8888`
+ *
+ * 对三通道和四通道输入会先做 BGR/BGRA 到 RGB/RGBA 的颜色顺序转换。
+ *
+ * @param image OpenCV 图像
+ * @return 转换后的 QImage；不支持的类型返回空 QImage
+ */
+QImage toQImage(const cv::Mat &image);
+
+} // namespace ImageUtils

src/MainWindow.cpp

@@ -9,9 +9,9 @@
  *   - 执行推理并显示结果
  */
 #include "MainWindow.h"
+#include "ImageUtils.h"
 #include <QApplication>
 #include <QPixmap>
-#include <QImageReader>
 #include <QDir>
 #include <QDirIterator>
 #include <QFileInfo>
@@ -20,10 +20,8 @@
 
 namespace {
 
-QImage readImageWithAutoTransform(const QString &path) {
-    QImageReader reader(path);
-    reader.setAutoTransform(true);
-    return reader.read();
+QImage readImageWithOpenCV(const QString &path) {
+    return ImageUtils::toQImage(ImageUtils::loadColorImage(path));
 }
 
 constexpr int kImageIndexRole = Qt::UserRole;
@@ -159,7 +157,7 @@ void MainWindow::selectModel() {
 
 void MainWindow::loadImage() {
     QString path = QFileDialog::getOpenFileName(
-        this, "选择图片", "", "Images (*.png *.jpg *.jpeg *.bmp)"
+        this, "选择图片", "", "Images (*.png *.jpg *.jpeg *.bmp *.webp)"
     );
     if (path.isEmpty()) return;
 
@@ -207,16 +205,16 @@ void MainWindow::runInference() {
         return;
     }
 
-    QImage image = readImageWithAutoTransform(m_imagePaths[m_currentIndex]);
-    if (image.isNull()) {
+    const QString &imagePath = m_imagePaths[m_currentIndex];
+    OnnxClassifier::Result result = m_classifier.classify(imagePath);
+    if (result.allScores.empty()) {
         QMessageBox::warning(this, "警告", "图片格式不支持: " + m_imagePaths[m_currentIndex]);
         return;
     }
 
-    OnnxClassifier::Result result = m_classifier.classify(image);
     displayResult(result);
     setStatusText(QString("状态: 当前图片推理完成 (%1)")
-        .arg(QFileInfo(m_imagePaths[m_currentIndex]).fileName()));
+        .arg(QFileInfo(imagePath).fileName()));
 }
 
 void MainWindow::runBatchInference() {
@@ -242,8 +240,8 @@ void MainWindow::runBatchInference() {
             .arg(m_imagePaths.size())
             .arg(QFileInfo(path).fileName()));
 
-        QImage image = readImageWithAutoTransform(path);
-        if (image.isNull()) {
+        OnnxClassifier::Result result = m_classifier.classify(path);
+        if (result.allScores.empty()) {
             auto *item = new QListWidgetItem(
                 QString("第%1张 | %2 | 读取失败").arg(i + 1).arg(QFileInfo(path).fileName())
             );
@@ -253,7 +251,6 @@ void MainWindow::runBatchInference() {
             continue;
         }
 
-        OnnxClassifier::Result result = m_classifier.classify(image);
         addBatchResultItem(i, path, result);
         okCount++;
 
@@ -294,11 +291,14 @@ void MainWindow::nextImage() {
 void MainWindow::showCurrentImage() {
     if (m_currentIndex < 0 || m_currentIndex >= m_imagePaths.size()) return;
 
-    QPixmap pixmap = QPixmap::fromImage(readImageWithAutoTransform(m_imagePaths[m_currentIndex]));
+    QPixmap pixmap = QPixmap::fromImage(readImageWithOpenCV(m_imagePaths[m_currentIndex]));
     if (!pixmap.isNull()) {
         m_imageLabel->setPixmap(pixmap.scaled(
             m_imageLabel->size(), Qt::KeepAspectRatio, Qt::SmoothTransformation
         ));
+    } else {
+        m_imageLabel->clear();
+        m_imageLabel->setText("图片读取失败");
     }
 
     // 更新图片信息