# 项目架构及调用关系文档

## 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)