# Machine Vision Image

**Repository Path**: xzy35/machine-vision-image

## Basic Information

- **Project Name**: Machine Vision Image
- **Description**: No description available
- **Primary Language**: C++
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-05
- **Last Updated**: 2026-03-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Machine Vision Image
<div align="center">
  <p>基于 Qt5 + OpenCV + Halcon 开发的工业机器视觉图像处理软件</p>
  <img src="https://img.shields.io/badge/Qt-5.15+-blue.svg" alt="Qt Version">
  <img src="https://img.shields.io/badge/OpenCV-4.x-green.svg" alt="OpenCV Version">
  <img src="https://img.shields.io/badge/Halcon-20.11+-orange.svg" alt="Halcon Version">
  <img src="https://img.shields.io/badge/OS-Windows 10/11-yellow.svg" alt="Operating System">
</div>

## 一、项目介绍
Machine Vision Image 是面向工业场景的机器视觉处理软件，集成海康威视（GigE/USB）、Basler USB 相机驱动，提供图像采集、条码识别、形状匹配、ROI分析等核心功能，支持 TCP 网络通信、离线图像测试、配置文件管理等扩展能力，可快速适配工业视觉检测场景。

### 核心优势
- 多相机兼容：无缝对接海康威视、Basler 主流工业相机
- 轻量化架构：Qt 跨平台 GUI + OpenCV/Halcon 算法层解耦，易于扩展
- 工业级通信：TCP Socket 心跳保活 + Base64 图像传输，保障数据稳定性
- 离线调试：支持本地图像加载测试，降低现场调试成本

## 二、技术架构
### 1. 技术栈
| 模块         | 技术选型                          | 作用                     |
|--------------|-----------------------------------|--------------------------|
| GUI 框架     | Qt5 (QMainWindow/QWidget)         | 可视化界面、交互逻辑     |
| 图像处理     | OpenCV 4.x + Halcon 20.11+        | 图像算法、形状匹配、条码识别 |
| 相机驱动     | 海康威视 SDK + Basler USB 驱动    | 相机控制、图像采集       |
| 网络通信     | TCP Socket                        | 数据交互、图像传输       |
| 配置管理     | XML                               | 参数持久化、设备配置     |
| 数据格式     | JSON + Base64                     | 结构化数据、图像编码     |
| 开发环境     | Visual Studio 2019+ (x64)         | 编译、调试               |

### 2. 目录结构
```
visionPro/
├── visionPro.cpp/h         # 主程序入口（QApplication、主窗口初始化）
├── ImageTool.cpp/h         # 图像处理工具界面（条码识别、形状匹配面板）
├── ImageProcess.cpp/h      # 图像处理核心算法（OpenCV/Halcon 封装）
├── HK_Camera.cpp/h         # 海康相机驱动（打开/关闭/触发/采集）
├── baslerUSB.cpp/h         # Basler相机驱动（USB 相机控制）
├── DeviceManager.cpp/h     # 设备管理器（相机枚举、设备状态管理）
├── Task.cpp/h              # 任务执行类（视觉任务调度、结果返回）
├── socket_client.cpp/h     # Socket客户端（TCP 连接、心跳、数据收发）
├── XMLConfigOperator.cpp/h # XML配置操作（参数读写、配置解析）
├── ListImgWidge.cpp/h      # 图像列表控件（离线图像管理、预览）
├── ListImgItem.cpp/h       # 图像列表项（单张图像的显示/操作）
└── json.hpp                # JSON库（结构化数据序列化/反序列化）
```

### 3. 核心流程
```mermaid
graph TD
    A[主程序启动] --> B[设备管理器初始化]
    B --> C{相机连接？}
    C -->|是| D[相机采集图像]
    C -->|否| E[离线加载本地图像]
    D --> F[图像处理（ROI/条码/形状匹配）]
    E --> F
    F --> G{网络通信？}
    G -->|是| H[图像Base64编码 + JSON封装 → TCP发送]
    G -->|否| I[本地显示处理结果]
    F --> J[结果保存/配置更新]
```

## 三、功能特性
### 1. 相机管理
- 相机枚举：自动识别已连接的海康威视/Basler 相机
- 采集控制：支持**连续采集**、**软触发采集**、**停止采集**
- 参数调节：相机曝光、增益、分辨率等参数配置（需相机支持）
- 状态监控：实时显示相机连接状态、采集帧率

### 2. 图像处理
- 条码识别：支持一维码（Code128/Code39/EAN-13 等）识别，返回条码内容、位置
- 形状匹配：基于 Halcon 实现模板匹配，支持多模板、ROI 区域匹配，返回匹配得分、位置
- ROI 操作：支持矩形/圆形 ROI 绘制、编辑，仅处理 ROI 区域内图像
- 图像预处理：灰度化、二值化、滤波（高斯/中值）等基础操作

### 3. 网络通信
- TCP 客户端：支持连接指定服务器 IP/端口
- 心跳保活：定时发送心跳包，检测连接状态
- 数据传输：图像 Base64 编码后通过 JSON 格式传输，支持处理结果同步发送
- 断线重连：网络断开后自动重试连接

### 4. 离线模式
- 本地图像加载：支持单张/批量加载本地图像（JPG/PNG/BMP 等）
- 图像列表管理：预览、删除、切换图像，模拟相机采集流程
- 离线测试：使用本地图像验证条码识别、形状匹配算法效果

### 5. 配置管理
- 参数保存：将相机参数、图像处理参数保存到 XML 配置文件
- 配置加载：启动时自动加载历史配置，无需重复设置
- 多配置切换：支持保存多个场景配置文件，快速切换

## 四、安装教程
### 1. 环境要求
| 依赖项                | 版本要求          | 备注                     |
|-----------------------|-------------------|--------------------------|
| 操作系统              | Windows 10/11 (64位) | 暂不支持 Linux/macOS     |
| 开发工具              | Visual Studio 2019+ | 需安装 C++ 开发组件      |
| Qt                    | 5.15+             | 建议使用 Qt 5.15.2 LTS   |
| OpenCV                | 4.x               | 需编译 x64 版本          |
| Halcon                | 20.11+            | 安装时选择 x64 运行时    |
| 海康威视 SDK          | V3.0+             | 对应相机型号的 SDK       |
| Basler Pylon SDK      | 7.0+              | Basler 相机驱动          |

### 2. 环境配置
#### 步骤 1：安装基础依赖
1. 安装 Visual Studio 2019+，勾选「使用 C++ 的桌面开发」组件
2. 安装 Qt5.15+，配置 Qt VS Tools 插件，关联 VS 开发环境
3. 安装 OpenCV 4.x，配置系统环境变量 `OPENCV_DIR`，并将 `bin` 目录加入 `Path`
4. 安装 Halcon 20.11+，配置系统环境变量 `HALCONROOT`
5. 安装海康威视 SDK/Basler Pylon SDK，按文档配置驱动

#### 步骤 2：项目编译
1. 下载项目源码，使用 Visual Studio 打开 `visionPro.vcxproj`
2. 在项目属性中配置：
   - Qt 包含目录、库目录（Qt5Core/Qt5Gui/Qt5Widgets 等）
   - OpenCV 包含目录、库目录
   - Halcon 包含目录、库目录
   - 海康/Basler SDK 包含目录、库目录
3. 选择「Release x64」配置，点击「生成解决方案」
4. 复制 Qt/OpenCV/Halcon/相机 SDK 的运行时库到生成目录

### 3. 常见问题
- 相机无法识别：检查相机驱动是否安装、SDK 版本是否匹配、USB/GigE 连接是否正常
- 编译报错：确认所有依赖库的包含目录/库目录配置正确，VS 平台工具集与 Qt 版本兼容
- 图像传输失败：检查网络连接、服务器端口是否开放、Base64 编码/解码逻辑是否正确

## 五、使用说明
### 1. 快速上手
#### 步骤 1：启动软件
双击 `visionPro.exe`，软件自动初始化设备管理器，检测已连接的相机。

#### 步骤 2：相机操作
1. 点击顶部菜单「相机」→「打开相机」，选择相机型号（海康/Basler）
2. 选择采集模式：
   - 连续采集：实时获取相机图像
   - 软触发采集：点击「触发」按钮单次采集图像
3. 点击「停止采集」关闭相机流

#### 步骤 3：图像处理
1. 点击「图像工具」按钮，打开工具面板
2. 条码识别：勾选「条码识别」，框选 ROI 区域，点击「执行」，结果显示在面板下方
3. 形状匹配：点击「加载模板」选择模板图像，设置匹配阈值，点击「匹配」，返回匹配结果

#### 步骤 4：离线模式
1. 勾选界面左下角「离线模式」
2. 点击「加载图像」选择本地图像文件，图像显示在预览窗口
3. 重复步骤 3，使用本地图像测试算法效果

#### 步骤 5：网络通信
1. 点击「网络设置」，输入服务器 IP 和端口
2. 点击「连接服务器」，成功后状态栏显示「已连接」
3. 勾选「自动发送结果」，图像处理结果自动通过 TCP 发送到服务器

### 2. 高级操作
- 配置保存：点击「配置」→「保存配置」，将当前参数保存到 XML 文件
- 模板管理：在形状匹配面板中，点击「保存模板」将当前 ROI 区域保存为模板文件
- 日志查看：点击「帮助」→「日志」，查看采集/处理/通信日志

## 六、参与贡献
### 1. 贡献规范
1. Fork 本仓库到个人账号
2. 新建分支：`git checkout -b Feat_xxx`（功能）/`Fix_xxx`（修复）
3. 代码规范：遵循 Qt 编码规范，函数/变量命名清晰，添加必要注释
4. 提交说明：`git commit -m "Feat: 新增XX功能"`，明确提交内容
5. 推送分支：`git push origin Feat_xxx`
6. 新建 Pull Request，描述功能/修复内容，等待审核

### 2. 开发建议
- 新增算法：在 `ImageProcess.cpp` 中封装新算法，对外提供统一接口
- 新增相机：参考 `HK_Camera.cpp` 实现相机驱动接口，接入 `DeviceManager`
- 新增通信协议：扩展 `socket_client.cpp`，添加协议解析逻辑

## 七、许可证
本项目仅供学习、研究使用，禁止用于商业用途。如需商业使用，请联系开发者获取授权。

## 八、联系方式
- 问题反馈：提交 Issue 描述问题（附日志/截图）
- 技术交流：可提交 Discussion 讨论功能优化/技术问题

---
<div align="center">
  <p>© 2025 Machine Vision Image 开发团队</p>
</div>