514 lines
17 KiB
Markdown
514 lines
17 KiB
Markdown
# chengnan
|
||
|
||
## 项目名称
|
||
|
||
chengnan：基于 Qt 与 OpenCV 的图像显示与处理系统
|
||
|
||
## 当前实现状态
|
||
|
||
本项目已初始化为一个 Qt Widgets + OpenCV + CMake 的 C++ 图像处理应用。当前发布目标为：**Windows x64 桌面应用**，使用 MSVC、Qt Windows 运行时、OpenCV Windows 预编译 DLL 构建并打包；Linux 构建仅作为代码验证用途。
|
||
|
||
已实现功能：
|
||
|
||
- 打开图片
|
||
- 保存图片
|
||
- 另存图片
|
||
- 使用 QWidget 体系显示图像，不使用 `cv::imshow`
|
||
- 左右对比显示处理前 / 处理后图像
|
||
- 图像视图支持鼠标滚轮缩放、双击适配窗口、拖拽平移视图
|
||
- 图像处理功能：
|
||
- 放大 / 缩小
|
||
- 平移
|
||
- 指定角度旋转
|
||
- 阈值分割 + 轮廓目标提取
|
||
- 基于 HSV 均值的简单规则分类
|
||
- 使用 `QThread` + 信号槽执行 OpenCV 处理任务，避免阻塞 UI
|
||
|
||
## Windows 发布与隔离依赖原则
|
||
|
||
本项目发布目标为 Windows x64 桌面应用，要求如下：
|
||
|
||
- 在 Windows x64 + Visual Studio MSVC 环境中构建发布包
|
||
- 使用 `cl.exe`、Windows `cmake.exe`、Windows `ninja.exe`、`windeployqt.exe` 构建和部署
|
||
- Qt、OpenCV、CMake、Ninja 等依赖优先使用项目目录内二进制包或 CI 缓存中的可信二进制包
|
||
- 不把 Qt/OpenCV 安装到系统目录，不修改系统全局环境变量
|
||
- 发布包必须包含 `chengnan.exe`、Qt 运行时、Qt plugins、OpenCV DLL 和校验文件
|
||
- Linux 构建脚本仅用于代码验证，不作为最终发布制品来源
|
||
|
||
推荐 Windows 依赖目录约定：
|
||
|
||
```text
|
||
chengnan/
|
||
├── tools/
|
||
│ ├── cmake-current-windows/ # Windows 版 CMake
|
||
│ └── python-bin/ # 可选：项目内 Python 二进制
|
||
├── third_party/
|
||
│ ├── qt-windows-msvc/ # Windows 版 Qt MSVC
|
||
│ ├── opencv-windows/ # Windows 版 OpenCV 预编译包
|
||
│ └── qt-tools/ # Ninja 等 Qt 工具
|
||
├── build-windows/ # Windows 构建输出目录
|
||
└── dist-windows/ # Windows 发布包输出目录
|
||
```
|
||
|
||
> 注意：Windows 发布包依赖 Qt 与 OpenCV Windows 预编译二进制。CI Runner 必须能访问这些依赖，或仓库/缓存中已经准备好对应目录。
|
||
|
||
## 编译工具链与版本声明
|
||
|
||
本项目发布目标为 Windows x64，推荐工具链如下：
|
||
|
||
| 工具 / 依赖 | 项目内路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| Visual Studio Build Tools / MSVC | Runner 系统环境 | 提供 `cl.exe`，需通过 x64 Native Tools 或 `msvc-dev-cmd` 初始化 |
|
||
| CMake | `tools/cmake-current-windows/bin/cmake.exe` | CMake 最低要求 3.21 |
|
||
| Ninja | `third_party/qt-tools/Tools/Ninja/ninja.exe` | CMake 使用 `-G Ninja` 生成构建系统 |
|
||
| Qt | `third_party/qt-windows-msvc` | 使用 Qt Widgets / Qt Concurrent，部署时调用 `windeployqt.exe` |
|
||
| OpenCV | `third_party/opencv-windows/x64/vc16` | 使用 `core`、`imgproc`、`imgcodecs` 组件，发布时复制 DLL |
|
||
| C++ 标准 | `CMakeLists.txt` | `CMAKE_CXX_STANDARD 17` |
|
||
|
||
Linux 二进制工具链仍可用于代码验证，但不作为发布包来源。
|
||
|
||
## 如何构建
|
||
|
||
### Windows 发布构建
|
||
|
||
本项目目标是 Windows 桌面应用。推荐在 Windows x64 + Visual Studio MSVC 环境中构建，仓库内 Windows 依赖约定如下：
|
||
|
||
```text
|
||
third_party/qt-windows-msvc/
|
||
third_party/opencv-windows/x64/vc16/
|
||
third_party/qt-tools/Tools/Ninja/ninja.exe
|
||
tools/cmake-current-windows/bin/cmake.exe
|
||
```
|
||
|
||
在 Windows Runner 或 “x64 Native Tools Command Prompt for VS” 中执行：
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File .\scripts\package-windows-release.ps1 -Toolchain msvc
|
||
```
|
||
|
||
生成的发布包：
|
||
|
||
```text
|
||
dist-windows/chengnan-windows-x86_64.zip
|
||
dist-windows/chengnan-windows-x86_64.zip.sha256
|
||
```
|
||
|
||
发布包内包含 `chengnan.exe`、Qt 运行时、Qt plugins 和 OpenCV DLL。解压后双击 `chengnan.exe` 运行。
|
||
|
||
### Linux 本地验证构建
|
||
|
||
Linux 构建仅用于本地验证 Qt/OpenCV 代码，不作为最终 Windows 发布包。
|
||
|
||
在 Linux 中进入项目目录执行：
|
||
|
||
```bash
|
||
cd /root/chengnan
|
||
./scripts/build-linux-binary.sh
|
||
```
|
||
|
||
脚本会自动完成：
|
||
|
||
1. 检查项目内 Linux 二进制构建环境是否存在
|
||
2. 如不存在，则下载项目内 `micromamba` 二进制工具
|
||
3. 在 `tools/linux-build-env/` 内安装 CMake、Ninja、Clang、Qt、OpenCV 等二进制依赖
|
||
4. 使用项目内 Clang / CMake / Ninja 配置并构建项目
|
||
5. 输出 Linux 可执行文件：
|
||
|
||
```text
|
||
build-linux/chengnan
|
||
```
|
||
|
||
### 分步构建
|
||
|
||
如果希望先准备依赖，再单独构建：
|
||
|
||
```bash
|
||
cd /root/chengnan
|
||
./scripts/setup-linux-binary-deps.sh
|
||
./scripts/build-linux-binary.sh
|
||
```
|
||
|
||
### 手动等价构建命令
|
||
|
||
以下命令等价于脚本中的核心构建逻辑，适合调试 CMake 参数：
|
||
|
||
```bash
|
||
cd /root/chengnan
|
||
|
||
export PATH="$PWD/tools/linux-build-env/bin:$PATH"
|
||
export CMAKE_PREFIX_PATH="$PWD/tools/linux-build-env"
|
||
export PKG_CONFIG_PATH="$PWD/tools/linux-build-env/lib/pkgconfig:$PWD/tools/linux-build-env/share/pkgconfig:${PKG_CONFIG_PATH:-}"
|
||
export LD_LIBRARY_PATH="$PWD/tools/linux-build-env/lib:${LD_LIBRARY_PATH:-}"
|
||
export CC="$PWD/tools/linux-build-env/bin/clang"
|
||
export CXX="$PWD/tools/linux-build-env/bin/clang++"
|
||
|
||
cmake -S . -B build-linux \
|
||
-G Ninja \
|
||
-DCMAKE_BUILD_TYPE=Release \
|
||
-DCMAKE_PREFIX_PATH="$CMAKE_PREFIX_PATH" \
|
||
-DCMAKE_C_COMPILER="$CC" \
|
||
-DCMAKE_CXX_COMPILER="$CXX" \
|
||
-DCMAKE_INSTALL_PREFIX="$PWD/dist-linux"
|
||
|
||
cmake --build build-linux --parallel "$(nproc)"
|
||
```
|
||
|
||
### 运行程序
|
||
|
||
构建完成后运行：
|
||
|
||
```bash
|
||
cd /root/chengnan
|
||
export LD_LIBRARY_PATH="$PWD/tools/linux-build-env/lib:${LD_LIBRARY_PATH:-}"
|
||
./build-linux/chengnan
|
||
```
|
||
|
||
如果在无桌面环境或 SSH 终端中运行，Qt 图形界面可能无法显示，需要在有 X11 / Wayland 图形会话的 Linux 桌面环境中运行。
|
||
|
||
## 已清理的历史依赖
|
||
|
||
之前为了尝试构建曾产生过源码编译或非目标平台相关内容，目前已删除：
|
||
|
||
```text
|
||
third_party/opencv-src
|
||
third_party/opencv-build
|
||
third_party/opencv
|
||
third_party/qt-sdk
|
||
third_party/qt
|
||
third_party/opengl-stub
|
||
tools/uv
|
||
tools/pyenv
|
||
tools/cmake
|
||
tools/cmake.tar.gz
|
||
```
|
||
|
||
这些内容被删除的原因：
|
||
|
||
- `opencv-src` / `opencv-build` / `opencv` 属于源码编译安装路径，不符合“只使用二进制安装”的要求
|
||
- `qt-sdk` / `qt` 是 Linux 本地尝试阶段的旧 Qt 目录，需要按新的 Linux 二进制依赖规范重新放置
|
||
- `opengl-stub` 是临时构建验证用内容，不属于正式项目依赖
|
||
- `tools/uv` / `tools/pyenv` 是 uv 相关环境，不符合“Python 使用虚拟环境，不使用 uv 安装”的要求
|
||
- `tools/cmake` 是旧 Linux CMake 工具目录，后续应按 `tools/cmake-linux/` 重新放置二进制工具
|
||
|
||
## 当前项目内已有的二进制依赖记录
|
||
|
||
当前目录中准备或约定了 Windows 方案所需的二进制依赖和脚本：
|
||
|
||
```text
|
||
third_party/qt-windows-msvc-sdk/
|
||
third_party/qt-windows-msvc
|
||
third_party/opencv-windows-extract/
|
||
third_party/opencv-windows
|
||
third_party/qt-tools/
|
||
tools/cmake-windows/
|
||
tools/cmake-current-windows
|
||
tools/python-bin/
|
||
scripts/build-windows.ps1
|
||
scripts/setup-python-venv-windows.ps1
|
||
DEPENDENCIES.md
|
||
```
|
||
|
||
已验证这些文件曾存在：
|
||
|
||
```text
|
||
third_party/qt-windows-msvc/bin/qmake.exe
|
||
third_party/qt-windows-msvc/bin/windeployqt.exe
|
||
third_party/opencv-windows/x64/vc16/lib/OpenCVConfig.cmake
|
||
third_party/opencv-windows/x64/vc16/lib/opencv_world4100.lib
|
||
third_party/opencv-windows/x64/vc16/bin/opencv_world4100.dll
|
||
third_party/qt-tools/Tools/Ninja/ninja.exe
|
||
tools/cmake-current-windows/bin/cmake.exe
|
||
tools/python-bin/python.exe
|
||
```
|
||
|
||
这些 Windows 二进制内容是发布包构建所需依赖；Linux 验证构建不会引用它们。
|
||
|
||
## Linux 验证构建说明
|
||
|
||
如需在 Linux 上做代码验证，可使用项目内 Linux 二进制依赖：
|
||
|
||
- Linux 版 CMake 二进制包
|
||
- Linux 版 Ninja 二进制包
|
||
- Linux 版二进制 C++ 编译器工具链，例如 LLVM/Clang 预编译包
|
||
- Linux 版 Qt 二进制包
|
||
- Linux 版 OpenCV 二进制包
|
||
- 项目内 Python 二进制包和虚拟环境
|
||
|
||
构建脚本建议命名为：
|
||
|
||
```text
|
||
scripts/setup-python-venv-linux.sh
|
||
scripts/build-linux-binary.sh
|
||
```
|
||
|
||
示例构建命令应类似：
|
||
|
||
```bash
|
||
./scripts/build-linux-binary.sh
|
||
```
|
||
|
||
该脚本应只使用项目内路径，例如：
|
||
|
||
```bash
|
||
export PATH="$PWD/tools/cmake-linux/bin:$PWD/tools/ninja-linux:$PWD/tools/compiler-linux/bin:$PATH"
|
||
export CMAKE_PREFIX_PATH="$PWD/third_party/qt-linux;$PWD/third_party/opencv-linux"
|
||
```
|
||
|
||
但脚本不得写入系统环境，也不得调用系统 GCC/G++ 作为项目编译器。
|
||
|
||
## 项目目标
|
||
|
||
使用 Qt 设计图形化界面，结合 OpenCV 实现图像的读取、显示、保存、基础几何处理，以及分类或目标提取功能。程序需要支持处理前后图像对比显示，并在图像处理流程中尽量使用 Qt 线程，避免阻塞界面。
|
||
|
||
## 技术要求
|
||
|
||
### 1. 开发框架
|
||
|
||
- GUI 框架：Qt（建议 Qt 6.x，使用 Qt Widgets）
|
||
- 图像处理库：OpenCV
|
||
- 构建系统：CMake
|
||
- 编程语言：C++17 或更高版本
|
||
- 图像显示：必须使用 Qt 的 QWidget / QLabel / QGraphicsView 等控件显示图像
|
||
- 禁止使用：`cv::imshow`、`cv::waitKey` 等 OpenCV 窗口显示方式
|
||
|
||
### 2. 界面功能要求
|
||
|
||
界面由 Qt 设计实现，至少应包含以下基础功能：
|
||
|
||
- 打开图片
|
||
- 保存图片
|
||
- 另存图片
|
||
- 显示原始图片
|
||
- 显示处理后的图片
|
||
- 支持处理前、处理后图像的对比观看
|
||
- 显示当前操作状态或处理结果提示
|
||
|
||
建议界面布局：
|
||
|
||
- 左侧显示原始图片
|
||
- 右侧显示处理后图片
|
||
- 顶部或侧边栏放置操作按钮
|
||
- 底部状态栏显示当前文件路径、处理状态、图片尺寸等信息
|
||
|
||
### 3. 图像基础处理要求
|
||
|
||
图片处理应包含以下简单操作：
|
||
|
||
- 缩放
|
||
- 放大
|
||
- 缩小
|
||
- 按比例缩放
|
||
- 平移
|
||
- 向上、下、左、右移动图像显示区域或图像内容
|
||
- 旋转
|
||
- 顺时针旋转
|
||
- 逆时针旋转
|
||
- 指定角度旋转
|
||
|
||
可选增强功能：
|
||
|
||
- 灰度化
|
||
- 二值化
|
||
- 亮度 / 对比度调节
|
||
- 滤波 / 模糊
|
||
- 边缘检测
|
||
- 撤销 / 重做
|
||
|
||
### 4. 分类或目标提取功能要求
|
||
|
||
程序应至少实现以下两项功能之一，两者皆有最佳：
|
||
|
||
#### 方案 A：图像分类
|
||
|
||
可实现简单图像分类，例如：
|
||
|
||
- 根据颜色占比进行分类
|
||
- 根据亮度、纹理、边缘数量进行规则分类
|
||
- 使用 OpenCV DNN 加载轻量模型进行分类
|
||
|
||
分类结果应显示在界面中，例如：
|
||
|
||
- 图片类型
|
||
- 置信度或规则判断依据
|
||
- 分类耗时
|
||
|
||
#### 方案 B：目标提取
|
||
|
||
可实现目标提取，例如：
|
||
|
||
- 阈值分割
|
||
- 颜色区域提取
|
||
- 轮廓检测
|
||
- 边缘检测
|
||
- 前景目标提取
|
||
|
||
目标提取结果应显示在处理后图像窗口中，并可叠加以下信息：
|
||
|
||
- 目标轮廓
|
||
- 外接矩形
|
||
- 目标数量
|
||
- 面积、中心点等简单特征
|
||
|
||
建议优先实现目标提取，再扩展简单分类功能。
|
||
|
||
### 5. 显示要求
|
||
|
||
- 必须具有图像显示功能
|
||
- 必须显示处理前、处理后的图像对比
|
||
- 显示控件必须基于 QWidget 体系
|
||
- 不允许使用 OpenCV 的 `cv::imshow` 显示图片
|
||
- OpenCV 的 `cv::Mat` 与 Qt 的 `QImage` / `QPixmap` 之间应封装转换函数
|
||
|
||
### 6. 线程要求
|
||
|
||
考虑图像处理使用 Qt 线程，避免大图像处理时卡住主界面。
|
||
|
||
建议设计：
|
||
|
||
- 主线程：负责 UI 显示、按钮响应、用户交互
|
||
- 工作线程：负责 OpenCV 图像处理、分类、目标提取
|
||
- 线程通信：使用 Qt 信号与槽
|
||
- 禁止在工作线程中直接操作 QWidget 控件
|
||
|
||
建议类设计：
|
||
|
||
- `MainWindow`：主窗口，负责 UI 和用户操作
|
||
- `ImageProcessor`：图像处理逻辑类
|
||
- `ImageWorker`：运行在 QThread 中的图像处理工作对象
|
||
- `ImageConverter`：负责 `cv::Mat` 与 `QImage` 转换
|
||
|
||
### 7. 环境与依赖安装要求
|
||
|
||
所有安装的依赖不得污染本地系统环境，必须采用项目文件夹内二进制安装或指定路径解压的方式。
|
||
|
||
要求：
|
||
|
||
- Windows 发布包在 Windows x64 + MSVC 环境中构建
|
||
- Linux 构建仅用于本地代码验证
|
||
- 不使用源码编译安装 Qt / OpenCV 等依赖
|
||
- 不建议直接全局安装 Qt 或 OpenCV
|
||
- 不建议污染系统 `/usr`、`/usr/local` 等全局路径
|
||
- 建议将依赖安装到项目目录下，例如：
|
||
- `chengnan/third_party/qt-linux/`
|
||
- `chengnan/third_party/opencv-linux/`
|
||
- `chengnan/tools/cmake-linux/`
|
||
- `chengnan/tools/ninja-linux/`
|
||
- `chengnan/tools/compiler-linux/`
|
||
- `chengnan/tools/python-venv/`
|
||
- CMake 通过 `CMAKE_PREFIX_PATH` 指向项目内依赖路径
|
||
- 构建目录使用 `chengnan/build-linux/`
|
||
- 可使用脚本统一配置环境变量，但只能影响当前进程，不修改系统环境变量
|
||
|
||
示例目录：
|
||
|
||
```text
|
||
chengnan/
|
||
├── README.md
|
||
├── CMakeLists.txt
|
||
├── .gitignore
|
||
├── app/
|
||
│ ├── include/
|
||
│ │ ├── MainWindow.h
|
||
│ │ ├── ImageView.h
|
||
│ │ ├── ImageProcessor.h
|
||
│ │ ├── ImageWorker.h
|
||
│ │ └── ImageConverter.h
|
||
│ └── src/
|
||
│ ├── main.cpp
|
||
│ ├── MainWindow.cpp
|
||
│ ├── ImageView.cpp
|
||
│ ├── ImageProcessor.cpp
|
||
│ ├── ImageWorker.cpp
|
||
│ └── ImageConverter.cpp
|
||
├── docs/
|
||
│ └── windows/ # Windows 依赖说明和构建脚本
|
||
├── scripts/
|
||
│ ├── setup-linux-binary-deps.sh
|
||
│ ├── setup-python-venv-linux.sh
|
||
│ └── build-linux-binary.sh
|
||
├── tools/
|
||
│ ├── linux-build-env/ # 项目内 Linux 二进制构建环境，Git 忽略
|
||
│ ├── cmake-linux -> linux-build-env
|
||
│ ├── ninja-linux -> linux-build-env
|
||
│ ├── compiler-linux -> linux-build-env
|
||
│ ├── python-bin -> linux-build-env
|
||
│ └── python-venv -> linux-build-env
|
||
├── third_party/
|
||
│ ├── qt-linux -> ../tools/linux-build-env
|
||
│ └── opencv-linux -> ../tools/linux-build-env
|
||
└── build-linux/ # Linux 构建输出目录，Git 忽略
|
||
```
|
||
|
||
示例 CMake 配置方式应写入脚本中统一执行，不能依赖系统工具链：
|
||
|
||
```bash
|
||
./scripts/setup-linux-binary-deps.sh
|
||
./scripts/build-linux-binary.sh
|
||
```
|
||
|
||
脚本会在项目目录内使用 Linux 二进制包创建隔离环境，并只在当前进程内设置环境变量。核心等价配置如下：
|
||
|
||
```bash
|
||
export PATH="$PWD/tools/linux-build-env/bin:$PATH"
|
||
export CMAKE_PREFIX_PATH="$PWD/tools/linux-build-env"
|
||
export PKG_CONFIG_PATH="$PWD/tools/linux-build-env/lib/pkgconfig:$PWD/tools/linux-build-env/share/pkgconfig:$PKG_CONFIG_PATH"
|
||
export LD_LIBRARY_PATH="$PWD/tools/linux-build-env/lib:$LD_LIBRARY_PATH"
|
||
export CC="$PWD/tools/linux-build-env/bin/clang"
|
||
export CXX="$PWD/tools/linux-build-env/bin/clang++"
|
||
|
||
cmake -S . -B build-linux \
|
||
-G Ninja \
|
||
-DCMAKE_BUILD_TYPE=Release \
|
||
-DCMAKE_PREFIX_PATH="$CMAKE_PREFIX_PATH" \
|
||
-DCMAKE_C_COMPILER="$CC" \
|
||
-DCMAKE_CXX_COMPILER="$CXX"
|
||
|
||
cmake --build build-linux -j$(nproc)
|
||
```
|
||
|
||
如需临时设置运行环境，建议写入脚本，不写入系统全局配置：
|
||
|
||
```bash
|
||
export PATH="$PWD/third_party/qt-linux/bin:$PWD/tools/cmake-linux/bin:$PWD/tools/ninja-linux:$PWD/tools/compiler-linux/bin:$PATH"
|
||
export LD_LIBRARY_PATH="$PWD/third_party/qt-linux/lib:$PWD/third_party/opencv-linux/lib:$LD_LIBRARY_PATH"
|
||
```
|
||
|
||
## 推荐实现步骤
|
||
|
||
1. 创建 Qt Widgets + CMake 项目结构
|
||
2. 实现主窗口和基本按钮：打开、保存、另存
|
||
3. 实现图片显示控件，完成原图和处理图对比显示
|
||
4. 封装 `cv::Mat` 与 `QImage` 的转换工具
|
||
5. 实现缩放、平移、旋转等基础处理
|
||
6. 将图像处理逻辑迁移到 `QThread` 工作线程
|
||
7. 实现目标提取功能，例如阈值分割 + 轮廓检测
|
||
8. 可选实现简单分类功能
|
||
9. 完成保存处理结果图片
|
||
10. 编写 Linux 本地二进制工具链构建脚本，确保 Qt、OpenCV、CMake、Ninja、编译器等工具均放在项目目录内
|
||
11. 测试大图处理时界面是否保持响应
|
||
12. 完善 README、运行说明和截图
|
||
|
||
## 验收标准
|
||
|
||
- 可以打开常见图片格式，例如 PNG、JPG、BMP
|
||
- 可以保存当前处理后的图片
|
||
- 可以另存为指定路径
|
||
- 可以在同一界面中对比显示处理前和处理后图像
|
||
- 支持缩放、平移、旋转操作
|
||
- 至少实现分类或目标提取功能之一
|
||
- 图像显示使用 QWidget 体系，不使用 `cv::imshow`
|
||
- 图像处理任务不会明显阻塞 UI
|
||
- 依赖安装和构建必须限制在项目目录内，不污染系统环境
|
||
- Windows 发布包可通过 Windows x64 + MSVC 构建生成
|
||
- 所有工具和依赖使用二进制包或解压式安装，不使用源码编译安装
|
||
|
||
## 注意事项
|
||
|
||
- QWidget 只能在主线程中创建和更新
|
||
- 工作线程只处理数据，不直接改 UI
|
||
- 大图处理时应避免频繁深拷贝，可合理使用 `cv::Mat::clone()` 控制生命周期
|
||
- `QImage` 与 `cv::Mat` 共享内存时要注意对象生命周期
|
||
- 保存图片时应保存处理后的图像，而不是原图
|
||
- 若使用 OpenCV DNN 模型，模型文件应放入项目目录，例如 `models/`
|
||
- 所有脚本应避免执行破坏性系统操作
|