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