The first commit

2026-01-04 16:51:58 +08:00
parent 684a923cda
commit 9b2a6bf423
107 changed files with 35063 additions and 0 deletions
--- a/docs/cmake_configuration_summary.md
+++ b/docs/cmake_configuration_summary.md
@@ -0,0 +1,221 @@
+# CMake 配置文档
+
+本文档总结了 `image_capture` 项目的 CMake 构建系统配置。
+
+---
+
+## 目录结构
+
+```
+image_capture/
+├── CMakeLists.txt              # 主构建配置文件
+└── cmake/                      # CMake 模块目录
+    ├── CompilerOptions.cmake   # 编译器选项配置
+    ├── Dependencies.cmake      # 外部依赖管理
+    └── PercipioSDK.cmake       # 相机 SDK 配置
+```
+
+---
+
+## 主配置文件：[CMakeLists.txt](file:///d:/Git/stereo_warehouse_inspection/image_capture/CMakeLists.txt)
+
+### 基本信息
+- **CMake 最低版本**: 3.10
+- **项目名称**: `image_capture`
+- **编程语言**: C++
+- **构建生成器**: Visual Studio 17 2022 (MSVC)
+
+### 输出目录
+```cmake
+CMAKE_RUNTIME_OUTPUT_DIRECTORY = ${CMAKE_BINARY_DIR}/bin/Release  # 可执行文件
+CMAKE_LIBRARY_OUTPUT_DIRECTORY = ${CMAKE_BINARY_DIR}/lib/Release  # 动态库
+CMAKE_ARCHIVE_OUTPUT_DIRECTORY = ${CMAKE_BINARY_DIR}/lib/Release  # 静态库
+```
+
+### 模块化设计
+项目采用模块化的 CMake 配置，通过 `cmake/` 目录下的三个模块文件组织：
+
+1. **CompilerOptions.cmake** - 编译器和全局设置
+2. **Dependencies.cmake** - Qt6、OpenCV、Open3D 依赖
+3. **PercipioSDK.cmake** - 图漾相机 SDK 配置
+
+### 库和可执行文件
+
+#### 1. Algorithm Library (`algorithm_lib`)
+**类型**: 静态库
+
+**源文件**:
+- `src/algorithm/core/detection_base.cpp`
+- `src/algorithm/core/detection_result.cpp`
+- `src/algorithm/utils/image_processor.cpp`
+- `src/algorithm/detections/slot_occupancy_detection.cpp`
+- `src/algorithm/detections/pallet_offset_detection.cpp`
+- `src/algorithm/detections/beam_rack_deflection_detection.cpp`
+- `src/algorithm/detections/visual_inventory_detection.cpp`
+- `src/algorithm/detections/visual_inventory_end_detection.cpp`
+
+**包含路径**:
+- `src`
+- `third_party/percipio/common` (修复 json11.hpp 引用)
+
+**依赖**: OpenCV, Open3D
+
+#### 2. Main Executable (`image_capture`)
+**类型**: 可执行文件
+
+**主要源文件**:
+- `src/main.cpp`
+- `src/camera/ty_multi_camera_capture.cpp`
+- `src/camera/mvs_multi_camera_capture.cpp`
+- `src/device/device_manager.cpp`
+- `src/redis/redis_communicator.cpp`
+- `src/task/task_manager.cpp`
+- `src/vision/vision_controller.cpp`
+- `src/common/log_manager.cpp`
+- `src/common/config_manager.cpp`
+- `src/gui/mainwindow.cpp` / `.h` / `.ui`
+
+**链接的库**:
+- `algorithm_lib` (项目内部算法库)
+- `cpp_api_lib` (相机 SDK C++ API 封装)
+- `tycam` (相机 SDK 动态库)
+- `${OpenCV_LIBS}` (OpenCV 库)
+- `Open3D::Open3D` (Open3D 库)
+- `Qt6::Core` 和 `Qt6::Widgets` (Qt 框架)
+- `MvCameraControl.lib` (海康 MVS SDK)
+
+### 测试配置
+- **选项**: `BUILD_TESTS` (默认 ON)
+- **测试目录**: `tests/` (通过 `add_subdirectory` 添加)
+
+---
+
+## CMake 模块详解
+
+### 1. [CompilerOptions.cmake](file:///d:/Git/stereo_warehouse_inspection/image_capture/cmake/CompilerOptions.cmake)
+
+#### C++ 标准
+- **标准**: C++17
+- **要求**: 必须支持
+
+#### Qt 自动化工具
+```cmake
+CMAKE_AUTOMOC ON    # 自动 Meta-Object Compiler
+CMAKE_AUTORCC ON    # 自动 Resource Compiler
+CMAKE_AUTOUIC ON    # 自动 UI Compiler
+```
+
+#### 编译器优化选项 (MSVC)
+
+**Release 模式** (默认):
+```cmake
+/O2        # 优化速度
+/Ob2       # 内联任何合适的函数
+/Oi        # 启用内建函数
+/Ot        # 代码速度优先
+/Oy        # 省略帧指针
+/GL        # 全局程序优化
+```
+
+**Debug 模式**:
+```cmake
+/Od        # 禁用优化
+/Zi        # 生成完整调试信息
+```
+
+#### 其他设置
+- **定义**: `OPENCV_DEPENDENCIES`
+- **compile_commands.json**: 自动生成（用于 IDE 智能提示）
+
+---
+
+### 2. [Dependencies.cmake](file:///d:/Git/stereo_warehouse_inspection/image_capture/cmake/Dependencies.cmake)
+
+#### Qt6 配置
+```cmake
+find_package(Qt6 REQUIRED COMPONENTS Widgets)
+```
+
+#### OpenCV 配置
+```cmake
+find_package(OpenCV REQUIRED)
+```
+
+#### Open3D 配置
+```cmake
+find_package(Open3D REQUIRED)
+```
+用于点云处理和算法运算。
+
+---
+
+### 3. [PercipioSDK.cmake](file:///d:/Git/stereo_warehouse_inspection/image_capture/cmake/PercipioSDK.cmake)
+
+#### 相机 SDK 路径配置
+```cmake
+CAMPORT3_ROOT     = ${CMAKE_CURRENT_SOURCE_DIR}/camera_sdk
+CAMPORT3_LIB_DIR  = ${CAMPORT3_ROOT}/lib/win/x64
+```
+
+#### 导入 tycam 动态库
+```cmake
+add_library(tycam SHARED IMPORTED)
+```
+
+#### C++ API 封装库 (`cpp_api_lib`)
+**类型**: 静态库
+
+**源文件**:
+`camera_sdk/sample_v2/cpp/*`, `camera_sdk/common/*`
+
+**依赖**: OpenCV
+
+---
+
+## 构建流程
+
+### 配置项目
+```bash
+cd image_capture/build
+cmake ..
+```
+
+可选参数:
+```bash
+-DOpenCV_DIR=<path>             # 指定 OpenCV 路径
+-DQt6_DIR=<path>                # 指定 Qt6 路径
+-DOpen3D_DIR=<path>             # 指定 Open3D 路径
+```
+
+### 编译项目
+```bash
+cmake --build . --config Release
+# 或
+cmake --build . --config Debug
+```
+
+---
+
+## 依赖项总结
+
+| 依赖项 | 版本要求 | 用途 |
+|--------|---------|------|
+| CMake | ≥ 3.10 | 构建系统 |
+| C++ | C++17 | 编程语言标准 |
+| Qt6 | Widgets 组件 | GUI 框架 |
+| OpenCV | 4.x | 图像处理 |
+| Open3D | 0.17+ | 3D点云处理 |
+| Percipio SDK | tycam.dll | 相机驱动 |
+| MSVC | VS2022 (v143) | 编译器 |
+
+---
+
+## 维护建议
+
+1. **环境一致性**: 确保所有依赖项（Qt, OpenCV, Open3D）都是使用 MSVC 编译的 x64 版本。
+2. **DLL 管理**: 运行时确保所有必要的 DLL 都在可执行文件目录下。
+3. **版本检测**: 保持 Open3D 和 OpenCV 版本的一致性，避免 ABI 冲突。
+
+---
+
+*文档更新时间: 2025-12-19*
--- a/docs/project_architecture.md
+++ b/docs/project_architecture.md
@@ -0,0 +1,306 @@
+# 项目架构及调用关系文档
+
+## 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)
--- a/docs/project_class_interaction.md
+++ b/docs/project_class_interaction.md
@@ -0,0 +1,133 @@
+# 项目功能类调用关系说明 (Project Class Interaction Documentation)
+
+本主要介绍 `image_capture` 项目核心功能类之间的调用关系、数据流向以及模块划分。
+
+## 1. 核心模块概览 (Core Modules Overview)
+
+系统主要由以下几个核心模块组成：
+
+*   **GUI 模块 (`MainWindow`)**: 程序的入口与界面显示，负责系统初始化。
+*   **Vision 控制器 (`VisionController`)**: 系统的核心中枢，协调通信与任务管理。
+*   **任务管理 (`TaskManager`)**: 负责具体的业务逻辑执行、算法调度和结果处理。
+*   **设备管理 (`DeviceManager`)**: 负责相机等硬件设备的统一管理（单例模式）。
+*   **通信模块 (`RedisCommunicator`)**: 负责与外部系统（如 WMS）通过 Redis 交互。
+*   **算法模块 (`DetectionBase` 及其子类)**: 具体的图像处理算法。
+
+## 2. 类调用关系图 (Class Interaction Diagram)
+
+```mermaid
+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*