pallet_storage_detection_system/docs/project_class_interaction.md

项目功能类调用关系说明 (Project Class Interaction Documentation)

本主要介绍 image_capture 项目核心功能类之间的调用关系、数据流向以及模块划分。

1. 核心模块概览 (Core Modules Overview)

系统主要由以下几个核心模块组成：

• GUI 模块 (MainWindow): 程序的入口与界面显示，负责系统初始化。
• Vision 控制器 (VisionController): 系统的核心中枢，协调通信与任务管理。
• 任务管理 (TaskManager): 负责具体的业务逻辑执行、算法调度和结果处理。
• 设备管理 (DeviceManager): 负责相机等硬件设备的统一管理（单例模式）。
• 通信模块 (RedisCommunicator): 负责与外部系统（如 WMS）通过 Redis 交互。
• 算法模块 (DetectionBase 及其子类): 具体的图像处理算法。

2. 类调用关系图 (Class Interaction Diagram)

classDiagram
    class MainWindow {
        +VisionController vision_controller
        +init()
    }

    class VisionController {
        -shared_ptr<RedisCommunicator> redis_comm
        -shared_ptr<TaskManager> task_manager
        +start()
        +stop()
        -onTaskReceived()
    }

    class RedisCommunicator {
        +startListening()
        +writeDetectionResult()
        +setTaskCallback()
    }

    class TaskManager {
        -queue<RedisTaskData> task_queue
        -map detectors
        +handleTask()
        -executeDetectionTask()
        -getDetector(flag)
    }

    class DeviceManager {
        <<Singleton>>
        +getInstance()
        +getLatestImages()
        +startAll()
    }

    class DetectionBase {
        <<Abstract>>
        +execute(depth, color, ...)
    }

    class ConcreteDetection {
        +execute()
    }

    MainWindow --> VisionController : 拥有并管理
    VisionController --> RedisCommunicator : 管理 (监听/发送)
    VisionController --> TaskManager : 分发任务
    RedisCommunicator --> VisionController : 回调通知 (Callback)
    TaskManager ..> DeviceManager : 获取图像数据 (Dependency)
    TaskManager --> DetectionBase : 调用算法
    DetectionBase <|-- ConcreteDetection : 继承

3. 详细调用流程 (Detailed Call Flow)

3.1 系统初始化与启动 (Initialization & Startup)

1. Entry Point: main.cpp 创建 QApplication 并实例化 MainWindow。
2. MainWindow:
   • 构造函数中初始化界面。
   • 调用 DeviceManager::getInstance().initialize() 扫描并初始化相机设备。
   • 实例化 VisionController 成员变量。
   • 调用 VisionController::initialize()，配置 Redis 连接参数。
   • 调用 VisionController::start() 启动后台服务。
3. VisionController:
   • 在 start() 中调用 RedisCommunicator::startListening() 开启监听线程。

3.2 任务触发与执行 (Task Trigger & Execution)

当 Redis 中 vision_task_flag 发生变化时，流程如下：

1. RedisCommunicator:
   • 监听线程检测到 Flag 变化。
   • 通过回调函数 VisionController::onTaskReceived 通知控制器。
2. VisionController:
   • onTaskReceived 将接收到的 RedisTaskData 传递给 TaskManager::handleTask。
3. TaskManager:
   • handleTask 将任务推入内部的任务队列 task_queue_。
   • 工作线程 taskExecutionThreadFunc 从队列中取出任务。
   • 获取图像: 调用 DeviceManager::getInstance().getLatestImages(...) 获取当前最新的深度图和彩色图。
   • 选择算法: 根据任务 Flag 调用 getDetector(flag) 获取对应的算法实例（如 PalletOffsetDetection）。
   • 执行算法: 调用 detector->execute(depth_img, color_img, ...) 进行计算。
   • 结果封装: 将算法返回的数据填充到 DetectionResult 结构体中。

3.3 结果处理 (Result Handling)

算法执行完成后：

1. TaskManager:
   • 调用 processResult(result)。
   • 该函数会格式化结果为 JSON 字符串，并计算报警/警告状态。
   • 调用 redis_result_comm_->writeDetectionResult(json) 将结果写入 Redis。
2. RedisCommunicator:
   • 执行 Redis SET 命令，将 JSON 数据写入指定的 Key。

4. 关键类说明 (Key Class Descriptions)

VisionController (src/vision/vision_controller.h)

• 职责: 作为系统的外观（Facade），对外提供统一的 start/stop 接口，对内协调 Redis 和 TaskManager。
• 特点: 它是 MainWindow 唯一直接交互的非 GUI 业务类。

DeviceManager (src/device/device_manager.h)

• 职责: 屏蔽底层相机 SDK（Percipio / MVS）的差异，提供统一的图像获取接口。
• 模式: 单例模式 (Singleton)。确保系统中只有一份硬件控制实例。

TaskManager (src/task/task_manager.h)

• 职责: 真正的“大脑”。负责任务的缓冲（队列）、图像获取、算法调度和结果回传。
• 并发: 拥有独立的执行线程，避免阻塞 Redis 监听线程或 GUI 线程。

RedisCommunicator (src/redis/redis_communicator.h)

• 职责: 封装 Redis 的底层 socket 操作，提供易用的读写接口和异步监听机制。

DetectionBase (src/algorithm/core/detection_base.h)

• 职责: 定义所有检测算法的统一接口 execute。
• 扩展: 新增算法只需继承此类并在 TaskManager 中注册即可。

---

文档生成时间: 2025-12-29