307 lines
11 KiB
Markdown
307 lines
11 KiB
Markdown
# 项目架构及调用关系文档
|
||
|
||
## 1. 系统概述
|
||
|
||
本系统是一个基于立体视觉的仓库巡检图像采集与处理系统。它集成了图漾(Percipio)工业相机SDK和海康(MVS)相机SDK进行多相机图像采集，使用OpenCV进行图像处理，Qt6作为用户界面框架，并通过Redis与外部系统（如机器人控制系统）进行通信和任务调度。
|
||
|
||
系统主要功能包括：
|
||
- 多相机同步采集（深度图与彩色图）
|
||
- 实时图像预览与状态监控
|
||
- 基于Redis的任务触发与结果上报
|
||
- 多种检测算法（货位占用、横梁/立柱变形、托盘偏差等）
|
||
- 系统配置管理与日志记录
|
||
|
||
## 2. 目录结构说明
|
||
|
||
```text
|
||
scripts/ # 批处理脚本 (数据库配置、模拟任务等)
|
||
image_capture/
|
||
└── src/
|
||
├── algorithm/ # 核心算法库
|
||
│ ├── core/ # 算法基类与结果定义 (DetectionBase, DetectionResult)
|
||
│ ├── detections/ # 具体检测算法实现 (SlotOccupancy, BeamRackDeflection等)
|
||
│ └── utils/ # 图像处理工具 (ImageProcessor)
|
||
├── camera/ # 相机驱动层
|
||
│ ├── ty_multi_camera_capture.cpp/h # 图漾(Percipio) 3D相机封装
|
||
│ └── mvs_multi_camera_capture.cpp/h # 海康(MVS) 2D相机封装
|
||
├── common/ # 通用设施
|
||
│ ├── config_manager.cpp/h # 配置管理单例
|
||
│ ├── log_manager.cpp/h # 日志管理
|
||
│ └── log_streambuf.h # std::cout重定向到GUI
|
||
├── device/ # 硬件设备管理
|
||
│ └── device_manager.cpp/h # 相机设备单例管理
|
||
├── gui/ # 用户界面
|
||
│ └── mainwindow.cpp/h/ui # 主窗口实现 (集成Settings Tab)
|
||
├── redis/ # 通信模块
|
||
│ └── redis_communicator.cpp/h # Redis客户端封装
|
||
├── task/ # 任务调度
|
||
│ └── task_manager.cpp/h # 任务分发与执行逻辑
|
||
├── vision/ # 系统控制
|
||
│ └── vision_controller.cpp/h # 顶层控制器，协调Redis与Task
|
||
├── common_types.h # 通用数据类型 (Point3D, CameraIntrinsics)
|
||
└── main.cpp # 程序入口
|
||
```
|
||
|
||
## 3. 核心架构设计
|
||
|
||
系统采用分层架构设计，各模块职责明确：
|
||
|
||
- **展示层 (GUI)**: `MainWindow` 负责界面显示、手动控制、参数配置及日志展示。
|
||
- **控制层 (Controller)**: `VisionController` 作为系统级控制器，负责服务的启动/停止，协调 `RedisCommunicator` 和 `TaskManager`。
|
||
- **业务逻辑层 (Task/Manager)**: `TaskManager` 解析任务指令，`DeviceManager` 管理硬件资源。
|
||
- **算法层 (Algorithm)**: 提供具体的视觉检测功能，继承自 `DetectionBase`。
|
||
- **驱动层 (Driver)**: `CameraCapture` 封装底层SDK调用。
|
||
|
||
### 系统分层架构图
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph Presentation ["展示层 (Presentation)"]
|
||
direction TB
|
||
GUI[MainWindow]
|
||
end
|
||
|
||
subgraph Control ["控制层 (Control)"]
|
||
VC[VisionController]
|
||
end
|
||
|
||
subgraph Business ["业务逻辑层 (Business Logic)"]
|
||
direction TB
|
||
TM[TaskManager]
|
||
DM[DeviceManager]
|
||
end
|
||
|
||
subgraph Algorithm ["算法层 (Algorithm)"]
|
||
direction TB
|
||
DB[DetectionBase]
|
||
Det[Concrete Detections<br/>(Slot, Beam, etc.)]
|
||
end
|
||
|
||
subgraph Infrastructure ["基础设施层 (Infrastructure)"]
|
||
direction TB
|
||
Cam[CameraCapture]
|
||
Redis[RedisCommunicator]
|
||
Conf[ConfigManager]
|
||
end
|
||
|
||
%% 层级调用关系
|
||
GUI --> VC
|
||
VC --> TM
|
||
VC --> Redis
|
||
|
||
TM --> DM
|
||
TM --> DB
|
||
DB <|-- Det
|
||
|
||
DM --> Cam
|
||
DM --> MVS[MvsMultiCameraCapture]
|
||
|
||
%% 跨层辅助调用
|
||
GUI -.-> Conf
|
||
TM -.-> Conf
|
||
|
||
style Presentation fill:#e1f5fe,stroke:#01579b
|
||
style Control fill:#e8f5e9,stroke:#2e7d32
|
||
style Business fill:#fff3e0,stroke:#ef6c00
|
||
style Algorithm fill:#f3e5f5,stroke:#7b1fa2
|
||
style Infrastructure fill:#eceff1,stroke:#455a64
|
||
```
|
||
|
||
### 系统类图
|
||
```mermaid
|
||
classDiagram
|
||
class MainWindow {
|
||
+VisionController visionController_
|
||
+updateImage()
|
||
+onSaveSettings()
|
||
}
|
||
|
||
class VisionController {
|
||
+RedisCommunicator redis_comm_
|
||
+TaskManager task_manager_
|
||
+start()
|
||
+stop()
|
||
}
|
||
|
||
class DeviceManager {
|
||
<<Singleton>>
|
||
+CameraCapture camera_capture_
|
||
+initialize()
|
||
+computePointCloud()
|
||
}
|
||
|
||
class TaskManager {
|
||
+executeTask()
|
||
-algorithms_ map
|
||
}
|
||
|
||
class CameraCapture {
|
||
+getLatestImages()
|
||
+computePointCloud()
|
||
+start()
|
||
-captureThreadFunc()
|
||
}
|
||
|
||
class RedisCommunicator {
|
||
+connect()
|
||
+listenForTasks()
|
||
+publishResult()
|
||
}
|
||
|
||
class ConfigManager {
|
||
<<Singleton>>
|
||
+loadConfig()
|
||
+saveConfig()
|
||
}
|
||
|
||
MainWindow --> VisionController : 只有与管理
|
||
VisionController --> RedisCommunicator : 使用
|
||
VisionController --> TaskManager : 使用
|
||
|
||
VisionController ..> DeviceManager : 依赖(全局)
|
||
TaskManager ..> DeviceManager : 获取图像/点云
|
||
DeviceManager --> CameraCapture : 拥有
|
||
|
||
MainWindow ..> ConfigManager : 读写配置
|
||
TaskManager ..> ConfigManager : 读取参数
|
||
```
|
||
|
||
## 4. 关键模块详解
|
||
|
||
### 4.1 GUI与主入口 (MainWindow)
|
||
- **职责**: 程序的主要入口，负责UI渲染、用户交互、参数配置及系统状态反馈。
|
||
- **调用关系**:
|
||
- 初始化时创建 `VisionController`。
|
||
- 通过 `QTimer` 定期从 `DeviceManager` 获取图像更新界面。
|
||
- **Settings Tab**: 直接在 `MainWindow` 中实现，提供 "Beam/Rack Deflection", "Pallet Offset" 等算法参数配置界面。
|
||
- 通过 `ConfigManager` 加载和保存配置项，包括ROI点坐标和各类阈值。
|
||
|
||
### 4.2 视觉控制器 (VisionController)
|
||
- **职责**: 系统的"大脑"，不依赖于GUI运行（设计上支持无头模式）。
|
||
- **流程**:
|
||
1. `initialize()`: 连接Redis。
|
||
2. `start()`: 启动Redis监听线程。
|
||
3. `onTaskReceived()`: 当Redis收到任务时，转发给 `TaskManager`。
|
||
|
||
### 4.3 任务管理 (TaskManager)
|
||
- **职责**: 解析Redis下发的JSON指令，选择合适的算法执行。
|
||
- **工作流**:
|
||
1. 接收任务ID和参数。
|
||
2. 从 `DeviceManager` 获取当前最新的一帧图像（深度+彩色）。
|
||
3. **点云生成**: 对于需要3D数据的任务（Flag 2/3），调用 `DeviceManager::computePointCloud()` 生成点云。
|
||
4. 根据任务类型实例化或调用相应的 `DetectionBase` 子类。
|
||
5. 执行 `detect()`，传入图像和点云数据。
|
||
6. 将结果打包为JSON，通过回调或直接通过 `RedisCommunicator` 返回。
|
||
|
||
### 4.4 设备管理 (DeviceManager)
|
||
- **职责**: 硬件资源的全局访问点（单例模式）。
|
||
- **封装**: 内部持有 `CameraCapture` 实例，确保相机资源全生命周期只被初始化一次。
|
||
- **功能**:
|
||
- 提供线程安全的图像获取接口 `getLatestImages()`。
|
||
- 提供点云计算接口 `computePointCloud()`，利用SDK内部参数生成高精度点云。
|
||
|
||
### 4.5 相机驱动 (CameraCapture)
|
||
- **实现**: `ty_multi_camera_capture.cpp`
|
||
- **机制**:
|
||
- 为每个相机开启独立采集线程。
|
||
- 维护内部帧缓冲区。
|
||
- 将SDK的 `TYImage` 转换为 OpenCV `cv::Mat`。
|
||
- **点云优化**: 内部集成 `TYMapDepthImageToPoint3d`，利用相机标定参数直接计算3D点云，消除畸变。
|
||
|
||
### 4.6 配置管理 (ConfigManager)
|
||
- **职责**: 管理 `config.json` 文件，集中管理系统配置。
|
||
- **管理内容**:
|
||
- Redis 连接信息。
|
||
- 算法阈值 (Beam/Rack, Pallet Offset 等)。
|
||
- ROI (Region of Interest) 坐标点。
|
||
- 系统通用参数 (最小/最大深度等)。
|
||
- **特性**: 单例模式，支持热加载（部分参数）和持久化保存。程序启动时由 `MainWindow` 加载，确保算法使用持久化的用户设置。GUI中的Settings Tab直接操作此模块。
|
||
|
||
## 5. 系统执行与数据流
|
||
|
||
### 5.1 初始化流程
|
||
1. `main()` 启动 `QApplication`。
|
||
2. `MainWindow` 构造：
|
||
- 初始化UI。
|
||
- **调用 `ConfigManager::getInstance().loadConfig()` 加载本地配置。**
|
||
- 调用 `DeviceManager::getInstance().initialize()` 初始化相机。
|
||
- 创建并初始化 `VisionController`（连接 Redis，但暂不启动监听）。
|
||
- 启动定时器调用 `updateImage()` 刷新界面显示。
|
||
3. 启动设备采集：调用 `DeviceManager::startAll()`。
|
||
4. 设备启动成功后再调用 `VisionController::start()` 开启 Redis 监听，确保任务到来时设备已就绪。
|
||
|
||
### 5.2 自动任务执行流 (Redis触发)
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Redis
|
||
participant RC as RedisCommunicator
|
||
participant VC as VisionController
|
||
participant TM as TaskManager
|
||
participant DM as DeviceManager
|
||
participant Algo as DetectionAlgorithm
|
||
|
||
Redis->>RC: Publish Task (JSON)
|
||
RC->>VC: onTaskReceived(data)
|
||
VC->>TM: executeTask(data)
|
||
|
||
activate TM
|
||
TM->>DM: getLatestImages()
|
||
DM-->>TM: depth_img, color_img
|
||
|
||
TM->>DM: computePointCloud(depth)
|
||
DM-->>TM: point_cloud (vector<Point3D>)
|
||
|
||
TM->>Algo: execute(images, point_cloud)
|
||
activate Algo
|
||
Algo-->>TM: DetectionResult
|
||
deactivate Algo
|
||
|
||
TM->>TM: processResult()
|
||
TM->>RC: writeString(key, value)
|
||
RC->>Redis: Set Key-Value
|
||
deactivate TM
|
||
```
|
||
|
||
1. **外部触发**: Redis 发布任务消息。
|
||
2. **接收**: `RedisCommunicator` 监听到消息，触发回调。
|
||
3. **调度**: `VisionController` 调用 `TaskManager::executeTask()`。
|
||
4. **获取数据**: `TaskManager` 从 `DeviceManager` 获取最新帧。
|
||
5. **算法处理**: 调用相应算法（如 `SlotOccupancyDetection::detect`）。
|
||
6. **结果反馈**: 结果封装成JSON，通过 `RedisCommunicator` 写入Redis结果队列。
|
||
7. **任务复位**: 结果写入完成后，将 `vision_task_flag` 置 `0`、`vision_task_side`/`vision_task_time` 置空，避免程序重启后被旧任务自动触发。
|
||
|
||
### 5.3 实时监控执行流 (GUI)
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Timer as QTimer
|
||
participant MainWin as MainWindow
|
||
participant DM as DeviceManager
|
||
|
||
Timer->>MainWin: timeout()
|
||
activate MainWin
|
||
MainWin->>DM: getLatestImages()
|
||
DM-->>MainWin: depth_img, color_img
|
||
|
||
MainWin->>MainWin: Convert to QImage
|
||
MainWin->>MainWin: update QLabel
|
||
deactivate MainWin
|
||
```
|
||
|
||
1. **定时刷新**: `MainWindow` 的 `QTimer` 触发 `updateImage()`。
|
||
2. **数据拉取**: 调用 `DeviceManager::getInstance().getLatestImages()`。
|
||
3. **渲染**: 将OpenCV Mat 转换为 QImage 并显示在 `QLabel` 上。
|
||
- 深度图进行伪彩色处理以便观察。
|
||
- 自适应窗口大小缩放。
|
||
|
||
## 6. 异常处理与日志
|
||
- **日志**: 使用 `LogManager` 和 `spdlog` (如果集成) 或标准输出。
|
||
- **重定向**: `LogStreamBuf` 将 `std::cout/cerr` 重定向到GUI的日志窗口，方便现场调试。
|
||
- **错误恢复**: 相机掉线重连机制（在驱动层实现或计划中）。
|
||
|
||
## 7. 编译与构建
|
||
- **工具**: CMake
|
||
- **依赖**: Qt6, OpenCV 4.x, Percipio SDK, (Redis库通常被封装或作为源码包含)
|
||
- **平台**: Windows (MSVC/MinGW)
|