Implement Qt OpenCV image processing app

readme.md

@@ -2,34 +2,52 @@
 
 项目链接：<https://git.luochen570.cn/luochen570/chengnan>
 
-`chengnan` 是一个轻量级 Windows 图片查看器 / 简单图片处理工具，使用 **Qt Widgets + CMake + C++17** 开发。
+`chengnan` 是一个 Windows 图像显示与处理课程项目，使用 **Qt Widgets + OpenCV + CMake + C++17** 开发。
+
+## 作业要求对应情况
+
+- 使用 Qt 设计界面：已使用 Qt Widgets 实现菜单栏、工具栏和双栏图像显示界面。
+- 打开图片、保存图片、另存图片：已实现。
+- 缩放、平移、旋转：
+  - 缩放：工具栏滑块、放大、缩小、原始大小、双击适配窗口。
+  - 平移：图片位于 `QScrollArea` 中，放大后可通过滚动条平移查看。
+  - 旋转：左旋 90°、右旋 90°。
+- 图片处理：灰度化、反色、目标提取、简单分类。
+- 处理前后对比：主界面左右两个 `QWidget` 区域分别显示处理前和处理后图像。
+- 显示方式：使用 Qt Widgets 显示图片，未使用 `cv::imshow`。
+- OpenCV 处理线程：灰度化、反色、目标提取、简单分类通过 Qt 线程执行，避免处理时阻塞界面。
+- Windows 应用构建发布：`.gitea/workflows/build-windows-release.yml` 会在 Gitea Actions 的 Linux Runner 中交叉构建 Windows x64 程序并上传 Release 附件。
 
 ## 功能
 
 当前实现：
 
 - 打开图片：PNG、JPG、JPEG、BMP、GIF、WebP 等 Qt 支持的格式
-- 保存当前图片
+- 保存当前处理后图片
 - 另存为 PNG / JPG / BMP 等格式
-- 图片显示：使用 Qt Widgets，不使用 OpenCV 窗口
+- 处理前 / 处理后双栏对比显示
 - 缩放：工具栏滑块、放大、缩小、原始大小
+- 平移：放大后使用滚动条移动查看区域
 - 双击图片适配窗口
 - 旋转：左旋 90°、右旋 90°
 - 翻转：水平翻转、垂直翻转
-- 简单处理：灰度化、反色
+- OpenCV 图片处理：灰度化、目标提取、简单分类
+- 其它处理：反色
 
 ## 文件结构
 
 ```text
 chengnan/
+├── .gitea/workflows/build-windows-release.yml
 ├── CMakeLists.txt
 ├── MainWindow.cpp
 ├── MainWindow.h
-├── build-windows.ps1
 ├── main.cpp
 └── readme.md
 ```
 
+除工作流和 `readme.md` 外，工程根目录只保留 `CMakeLists.txt`、`main.cpp`、`MainWindow.h`、`MainWindow.cpp` 四个文件。
+
 ## Windows 编译需要的工具
 
 推荐环境：Windows 10 / Windows 11 x64。
@@ -47,18 +65,16 @@ chengnan/
 3. **Qt 6 或 Qt 5，包含 Widgets 模块**
    - 下载：<https://www.qt.io/download-qt-installer-oss>
    - 推荐安装 Qt 6.x 的 MSVC 64-bit 套件，例如 `msvc2019_64` 或 `msvc2022_64`。
-   - 项目不依赖 OpenCV。
 
-4. **Visual Studio 2022 Build Tools 或 Visual Studio 2022**
+4. **OpenCV 4.x Windows 预编译包**
+   - 下载：<https://opencv.org/releases/>
+   - 解压后 CMake 需要能找到 OpenCV 的 `build` 目录，例如 `C:\opencv\build`。
+
+5. **Visual Studio 2022 Build Tools 或 Visual Studio 2022**
    - 下载：<https://visualstudio.microsoft.com/zh-hans/downloads/>
    - 需要安装组件：`使用 C++ 的桌面开发`。
    - 提供 MSVC 编译器和 Windows SDK。
 
-可选工具：
-
-- **Ninja**：<https://github.com/ninja-build/ninja/releases>
-- 如果使用 Ninja，可以把 `build-windows.ps1` 的 `-Generator` 参数改成 `Ninja`。
-
 ## 获取源码
 
 ```powershell
@@ -66,63 +82,43 @@ git clone https://git.luochen570.cn/luochen570/chengnan.git
 cd chengnan
 ```
 
-如果仓库主分支已切换到当前版本，直接构建即可；否则可手动切换：
-
-```powershell
-git checkout main
-```
-
-## 一键构建（推荐）
-
-在 Windows PowerShell 中进入项目目录，然后执行：
-
-```powershell
-powershell -ExecutionPolicy Bypass -File .\build-windows.ps1 -QtPrefix "C:\Qt\6.7.2\msvc2019_64"
-```
-
-请把 `-QtPrefix` 改成你本机实际 Qt 安装目录。例如：
-
-```powershell
-powershell -ExecutionPolicy Bypass -File .\build-windows.ps1 -QtPrefix "C:\Qt\6.8.0\msvc2022_64"
-```
-
-脚本会完成：
-
-1. 检查 Qt、CMake、编译器环境
-2. 生成 CMake 构建目录
-3. 编译 Release 版本
-4. 调用 `windeployqt` 收集 Qt 运行库
-5. 把发布文件放到 `dist-windows\chengnan`
-
-构建成功后，运行：
-
-```powershell
-.\dist-windows\chengnan\chengnan.exe
-```
-
 ## 手动构建
 
-如果不使用脚本，也可以手动执行：
+在已配置 Visual Studio C++ 编译环境的 PowerShell 或 “x64 Native Tools Command Prompt for VS 2022” 中执行：
 
 ```powershell
-cmake -S . -B build-windows -G "Visual Studio 17 2022" -A x64 -DCMAKE_PREFIX_PATH="C:\Qt\6.7.2\msvc2019_64"
+cmake -S . -B build-windows -G "Visual Studio 17 2022" -A x64 -DCMAKE_PREFIX_PATH="C:\Qt\6.7.3\msvc2022_64;C:\opencv\build"
 cmake --build build-windows --config Release
 ```
 
 打包 Qt 运行库：
 
 ```powershell
-C:\Qt\6.7.2\msvc2019_64\bin\windeployqt.exe --release --no-translations build-windows\Release\chengnan.exe
+C:\Qt\6.7.3\msvc2022_64\bin\windeployqt.exe --release --no-translations build-windows\Release\chengnan.exe
 ```
 
+还需要把 OpenCV 的运行库 DLL（例如 `opencv_world4100.dll`）复制到 `chengnan.exe` 同目录。
+
+## Gitea Actions / GitHub Actions 风格工作流
+
+仓库中的 `.gitea/workflows/build-windows-release.yml` 使用 Linux Runner 的 Fedora 容器交叉构建 Windows x64 应用并发布 Release 附件：
+
+- 安装 MinGW-w64、Qt MinGW、OpenCV MinGW 依赖
+- 使用 `x86_64-w64-mingw32-cmake` 配置 Windows 目标程序
+- 使用 Ninja 在 Linux 上交叉编译生成 `chengnan.exe`
+- 打包 `chengnan.exe`、Qt DLL、OpenCV DLL、Qt 插件目录
+- 上传 `.zip` 和 `.sha256` 到仓库 Release
+
+发布上传使用仓库 Secret：`RELEASE_TOKEN`。如果没有配置该 Secret，工作流会尝试使用运行环境提供的 `GITHUB_TOKEN`。
+
 ## 常见问题
 
 ### 找不到 Qt
 
-确认 `-QtPrefix` 指向 Qt 套件目录，而不是 Qt 根目录。例如应使用：
+确认 CMake 的 `CMAKE_PREFIX_PATH` 包含 Qt 套件目录，而不是 Qt 根目录。例如应使用：
 
 ```text
-C:\Qt\6.7.2\msvc2019_64
+C:\Qt\6.7.3\msvc2022_64
 ```
 
 不要写成：
@@ -131,19 +127,28 @@ C:\Qt\6.7.2\msvc2019_64
 C:\Qt
 ```
 
+### 找不到 OpenCV
+
+确认 CMake 的 `CMAKE_PREFIX_PATH` 包含 OpenCV 的 `build` 目录。例如：
+
+```text
+C:\opencv\build
+```
+
+该目录下通常能找到 `OpenCVConfig.cmake`。
+
 ### 找不到 MSVC 编译器
 
-请安装 Visual Studio 2022 的 `使用 C++ 的桌面开发`，然后在 “x64 Native Tools Command Prompt for VS 2022” 或已配置 VS 环境的 PowerShell 里运行构建脚本。
+请安装 Visual Studio 2022 的 `使用 C++ 的桌面开发`，然后在 “x64 Native Tools Command Prompt for VS 2022” 或已配置 VS 环境的 PowerShell 里运行构建命令。
 
 ### exe 复制到其它电脑无法运行
 
-请运行 `build-windows.ps1`，并整体复制 `dist-windows\chengnan` 文件夹，不要只复制单个 `chengnan.exe`。
+不要只复制单个 `chengnan.exe`。需要同时复制 Qt / OpenCV DLL 和 Qt 插件目录，或直接使用 Gitea Actions 发布的 zip 附件。
 
 ## 开发说明
 
 - `main.cpp`：应用入口，创建并显示主窗口
 - `MainWindow.h`：主窗口和图片标签类声明
-- `MainWindow.cpp`：菜单、工具栏、图片显示和处理逻辑
-- `CMakeLists.txt`：Qt Widgets CMake 构建配置
-- `build-windows.ps1`：Windows 一键构建与打包脚本
+- `MainWindow.cpp`：菜单、工具栏、图片显示、OpenCV 图像处理和 Qt 线程逻辑
+- `CMakeLists.txt`：Qt Widgets + OpenCV CMake 构建配置
 - `readme.md`：项目说明文档