Initial Linux Qt OpenCV project

README.md

@@ -0,0 +1,407 @@
+# chengnan
+
+## 项目名称
+
+chengnan：基于 Qt 与 OpenCV 的图像显示与处理系统
+
+## 当前实现状态
+
+本项目已初始化为一个 Qt Widgets + OpenCV + CMake 的 C++ 图像处理应用。当前构建策略已调整为：**在 Linux 中编译，不使用 Windows 编译工具链；所有构建项目所需工具和依赖均采用项目目录内的二进制安装方式，不使用源码编译安装依赖。**
+
+已实现功能：
+
+- 打开图片
+- 保存图片
+- 另存图片
+- 使用 QWidget 体系显示图像，不使用 `cv::imshow`
+- 左右对比显示处理前 / 处理后图像
+- 图像视图支持鼠标滚轮缩放、双击适配窗口、拖拽平移视图
+- 图像处理功能：
+  - 放大 / 缩小
+  - 平移
+  - 指定角度旋转
+  - 阈值分割 + 轮廓目标提取
+  - 基于 HSV 均值的简单规则分类
+- 使用 `QThread` + 信号槽执行 OpenCV 处理任务，避免阻塞 UI
+
+## Linux 二进制构建原则
+
+本项目后续构建以 Linux 环境为准，要求如下：
+
+- 在 Linux 中编译本项目
+- 不使用 Windows 编译工具链
+- 不使用 `cl.exe`、`windeployqt.exe`、Windows `cmake.exe`、Windows `ninja.exe` 构建本项目
+- 不使用当前系统上的 GCC / G++ 作为项目构建工具链
+- 不全局安装 Qt、OpenCV、CMake、Ninja、Python 包等依赖
+- 不污染系统 `/usr`、`/usr/local`、系统 Python site-packages 或全局环境变量
+- 所有构建项目所需工具和依赖必须放在项目目录内
+- 所有构建项目所需依赖必须优先使用官方或可信来源的二进制包
+- 不使用源码编译安装 Qt / OpenCV 等依赖
+- Python 使用项目目录内虚拟环境，不使用 uv 安装或管理环境
+- 构建脚本只能临时设置当前进程环境变量，不能修改系统环境变量
+
+推荐目录约定：
+
+```text
+chengnan/
+├── tools/
+│   ├── cmake-linux/       # Linux 版 CMake 二进制
+│   ├── ninja-linux/       # Linux 版 Ninja 二进制
+│   ├── compiler-linux/    # Linux 版二进制编译器工具链，如 LLVM/Clang
+│   ├── python-bin/        # Python 二进制包
+│   └── python-venv/       # Python 虚拟环境
+├── third_party/
+│   ├── qt-linux/          # Linux 版 Qt 二进制包
+│   └── opencv-linux/      # Linux 版 OpenCV 二进制包
+└── build-linux/           # Linux 构建输出目录
+```
+
+> 注意：如果 OpenCV 没有适配当前 Linux 发行版的官方二进制包，不应退回源码编译安装。应改为寻找可信的预编译包、容器化二进制 SDK、发行版无污染解包方案，或更换依赖来源。
+
+## 已清理的历史依赖
+
+之前为了尝试构建曾产生过源码编译或非目标平台相关内容，目前已删除：
+
+```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 方案准备的二进制包和脚本，作为历史记录和可选参考，但**后续 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 里面编译，不使用 Windows 编译工具链”的新要求，因此 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. 环境与依赖安装要求
+
+所有安装的依赖不得污染本地系统环境，必须采用项目文件夹内二进制安装或指定路径解压的方式。
+
+要求：
+
+- 在 Linux 中编译本项目
+- 不使用 Windows 编译工具链
+- 不使用系统 GCC / G++ 作为项目构建工具链
+- 不使用源码编译安装 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 依赖说明和脚本，仅作参考，不参与 Linux 构建
+├── 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
+- 依赖安装和构建必须限制在项目目录内，不污染系统环境
+- 在 Linux 中编译，不使用 Windows 编译工具链
+- 所有工具和依赖使用二进制包或解压式安装，不使用源码编译安装
+
+## 注意事项
+
+- QWidget 只能在主线程中创建和更新
+- 工作线程只处理数据，不直接改 UI
+- 大图处理时应避免频繁深拷贝，可合理使用 `cv::Mat::clone()` 控制生命周期
+- `QImage` 与 `cv::Mat` 共享内存时要注意对象生命周期
+- 保存图片时应保存处理后的图像，而不是原图
+- 若使用 OpenCV DNN 模型，模型文件应放入项目目录，例如 `models/`
+- 所有脚本应避免执行破坏性系统操作