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

目录结构

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

构建产物：

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 发布包可直接解压运行