pallet_storage_detection_system/docs/project_architecture.md

项目架构及调用关系文档

1. 系统概述

本系统是一个基于立体视觉的仓库巡检图像采集与处理系统。它集成了图漾(Percipio)工业相机SDK和海康(MVS)相机SDK进行多相机图像采集，使用OpenCV进行图像处理，Qt6作为用户界面框架，并通过Redis与外部系统（如机器人控制系统）进行通信和任务调度。

系统主要功能包括：

• 多相机同步采集（深度图与彩色图）
• 实时图像预览与状态监控
• 基于Redis的任务触发与结果上报
• 多种检测算法（货位占用、横梁/立柱变形、托盘偏差等）
• 系统配置管理与日志记录

2. 目录结构说明

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调用。

系统分层架构图

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

系统类图

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触发)

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)

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)