136 lines
4.2 KiB
Markdown
136 lines
4.2 KiB
Markdown
# chengnan
|
||
|
||
chengnan 是一个面向 Windows 的图片查看器 / 简单图像处理应用，使用 **Qt Widgets + OpenCV + CMake + C++17** 开发。
|
||
|
||
## 项目定位
|
||
|
||
- 目标平台：Windows x64
|
||
- 应用类型：桌面图片查看器
|
||
- 构建方式：只在 Gitea Actions 工作流中构建和打包
|
||
- 仓库内容：只保留源码、CMake 配置、文档和工作流
|
||
- 仓库不包含：CMake/Ninja/Qt/OpenCV/MSYS2/vcpkg 等编译工具、SDK、第三方二进制依赖、本地构建产物
|
||
|
||
## 功能
|
||
|
||
当前已实现：
|
||
|
||
- 打开图片
|
||
- 保存图片、另存图片
|
||
- 使用 Qt QWidget 体系显示图片，不使用 `cv::imshow`
|
||
- 左右对比显示原图和处理后图片
|
||
- 图片视图支持：
|
||
- 鼠标滚轮缩放
|
||
- 双击适配窗口
|
||
- 拖拽平移视图
|
||
- 基础图像处理：
|
||
- 放大 / 缩小
|
||
- 平移
|
||
- 指定角度旋转
|
||
- 阈值分割 + 轮廓目标提取
|
||
- 基于 HSV 均值的简单规则分类
|
||
- 使用 `QThread` + 信号槽执行 OpenCV 处理任务，避免阻塞 UI
|
||
|
||
## 技术栈
|
||
|
||
- C++17
|
||
- Qt Widgets / Qt Concurrent
|
||
- OpenCV
|
||
- CMake
|
||
- Gitea Actions
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
chengnan/
|
||
├── .gitea/workflows/
|
||
│ ├── build-windows-cross-linux.yml # Linux Runner 交叉编译 Windows 发布包
|
||
│ └── build-windows-release.yml # Windows Runner 原生构建备用工作流
|
||
├── app/
|
||
│ ├── include/ # 头文件
|
||
│ └── src/ # 源文件
|
||
├── CMakeLists.txt
|
||
├── .gitignore
|
||
└── README.md
|
||
```
|
||
|
||
## 构建与发布
|
||
|
||
本项目不在仓库中保存编译工具或第三方二进制依赖。所有构建工作都在 Gitea Actions 工作流中完成。
|
||
|
||
当前优先使用 `.gitea/workflows/build-windows-cross-linux.yml`：在自建 `9950x` Linux Runner 的 Fedora 41 容器中，通过 MinGW-w64 交叉编译生成 Windows x86_64 发布包。`.gitea/workflows/build-windows-release.yml` 保留为 Windows Runner 原生构建备用工作流。
|
||
|
||
交叉编译工作流会临时完成以下步骤：
|
||
|
||
1. 拉取源码
|
||
2. 安装 Fedora / MinGW-w64 构建环境和依赖
|
||
3. 配置 CMake
|
||
4. 编译 Release 版本
|
||
5. 收集 Qt / OpenCV / MinGW 运行时依赖
|
||
6. 打包 Windows 发布包
|
||
7. 生成 SHA256 校验文件
|
||
8. 上传发布包到 Gitea Packages
|
||
|
||
## 编译工具链版本
|
||
|
||
交叉编译工作流固定使用以下环境和包版本：
|
||
|
||
| 组件 | 版本 |
|
||
| --- | --- |
|
||
| Runner 标签 | `9950x` |
|
||
| 容器镜像 | `fedora:41` |
|
||
| C++ 语言标准 | `C++17` |
|
||
| MinGW-w64 GCC C++ | `mingw64-gcc-c++ 14.2.1-3.fc41` |
|
||
| CMake | `cmake 3.28.3-7.fc41` |
|
||
| Ninja | `ninja-build 1.12.1-3.fc41` |
|
||
| Qt 6 Base | `mingw64-qt6-qtbase 6.7.2-3.fc41` |
|
||
| OpenCV | `mingw64-opencv 4.10.0-1.fc41` |
|
||
|
||
版本来源为 Fedora 41 `Everything/x86_64` 仓库元数据；构建时由工作流临时安装，不提交到源码仓库。
|
||
|
||
触发方式：
|
||
|
||
- push 到 `main`
|
||
- 创建 `v*` 标签
|
||
- Pull Request 到 `main`
|
||
- 手动触发 `workflow_dispatch`
|
||
|
||
构建产物：
|
||
|
||
```text
|
||
chengnan-windows-x86_64-cross.zip
|
||
chengnan-windows-x86_64-cross.zip.sha256
|
||
```
|
||
|
||
发布包解压后，双击 `chengnan.exe` 运行。请保留同目录 DLL 和 Qt 插件目录，不要只复制单个 exe。
|
||
|
||
## 本地开发说明
|
||
|
||
仓库不提供本地依赖安装脚本，也不保存编译工具。若需要本地开发，请自行在 Windows 上安装：
|
||
|
||
- CMake
|
||
- Ninja
|
||
- Qt 6
|
||
- OpenCV
|
||
- C++ 编译器（MSVC 或 MinGW）
|
||
|
||
然后按常规 CMake 项目方式配置和构建。正式发布以 Gitea Actions 产物为准。
|
||
|
||
## 依赖管理原则
|
||
|
||
- 不提交编译器、CMake、Ninja、Qt、OpenCV、MSYS2、vcpkg 等工具或 SDK
|
||
- 不提交 `build-*`、`dist-*`、`.exe`、`.dll` 等构建产物
|
||
- 第三方依赖只在工作流运行期间临时安装
|
||
- 发布包只作为工作流产物或 Gitea Packages 文件产出，不进入源码仓库
|
||
|
||
## 验收标准
|
||
|
||
- 可以打开常见图片格式，例如 PNG、JPG、BMP
|
||
- 可以保存当前处理后的图片
|
||
- 可以另存为指定路径
|
||
- 可以在同一界面中对比显示处理前和处理后图片
|
||
- 支持缩放、平移、旋转操作
|
||
- 至少实现目标提取或分类功能之一
|
||
- 图片显示使用 QWidget 体系，不使用 OpenCV 窗口显示函数
|
||
- 图像处理任务不会明显阻塞 UI
|
||
- Windows 发布包可直接解压运行
|