# Vision Pipeline

基于 ROS2 Humble 的机器视觉识别与云台追踪系统。

## 整体架构

```
┌─────────────────────────────────────────────────────────────┐
│                        硬件层                                │
│  ┌──────────┐    ┌──────────┐    ┌────────────────────┐     │
│  │ 工业相机  │    │  Jeston  │    │  云台（UART）       │     │
│  │ (Hikrobot)│    │  (aarch64)│   │  Yaw + Pitch + 激光  │    │
│  └────┬─────┘    └────┬─────┘    └─────────┬──────────┘     │
│       │               │                    │                │
├───────┼───────────────┼────────────────────┼────────────────┤
│       ▼               ▼                    ▼                │
│  ┌─────────┐   ┌──────────┐   ┌───────────────────┐        │
│  │driver_pkg│  │algorithm_pkg│ │gimbal_control_pkg │        │
│  │         │   │           │   │                   │        │
│  │ 相机驱动  │──▶│ 视觉处理   │──▶│ 云台串口通信       │        │
│  │ MvCamera │   │ Otsu+轮廓  │   │ 0xA5/A6/A7/A8    │        │
│  └────┬─────┘   └─────┬─────┘   └───────────────────┘        │
│       │               │                                      │
│       ▼               ▼                                      │
│  ┌─────────────────────────────────────┐                     │
│  │          application_pkg            │                     │
│  │  ┌───────────────────────────────┐  │                     │
│  │  │ web_node (:8080)              │  │                     │
│  │  │  - MJPEG 预览页               │  │                     │
│  │  │  - POST /api/mode/switch      │──┼──▶ /gimbal/mode     │
│  │  └───────────────────────────────┘  │                     │
│  └─────────────────────────────────────┘                     │
│                                                              │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐    │
│  │ rosbridge   │  │web_video     │  │     Nginx :80    │    │
│  │ ws://:9090  │  │server :8081  │  │  / → 前端静态文件  │    │
│  └──────┬──────┘  └──────┬───────┘  │  /stream → :8081  │    │
│         │                │          │  /api → :8080     │    │
├─────────┼────────────────┼──────────└──────────────────┘────┤
│         ▼                ▼                                   │
│  ┌─────────────────────────────────────┐                     │
│  │          浏览器 (Vue3 前端)          │                     │
│  │  - 视频预览 / 键盘遥控 / PID 调参    │                     │
│  └─────────────────────────────────────┘                     │
└─────────────────────────────────────────────────────────────┘
```

## 数据流

| 阶段 | 话题 | 方向 | 消息类型 | 说明 |
|------|------|------|----------|------|
| 图像采集 | `/camera/image_raw` | camera_node → vision_node | `sensor_msgs/Image` | 原始相机图像 |
| 视觉结果 | `/vision/result_image` | vision_node → web_node | `sensor_msgs/Image` | 带轮廓标注的结果图 |
| 二值调试 | `/vision/binary_image` | vision_node → web_node | `sensor_msgs/Image` | 二值化调试图像 |
| 目标追踪 | `/vision/target` | vision_node → gimbal_node | `geometry_msgs/Point` | 归一化目标偏移 (x,y) |
| 模式切换 | `/gimbal/mode` | web_node → gimbal_node | `std_msgs/String` | auto/manual/debug |
| 手动控制 | `/cmd_gimbal` | 前端 → gimbal_node | `geometry_msgs/Twist` | yaw/pitch 角度 |
| PID 参数 | `/pid_config` | 前端 → gimbal_node | `std_msgs/String` | PID 参数 JSON |

## 目录结构

```
Vision/
├── README.md
├── vision_example.py          # 独立参考脚本（非 ROS2）
├── config/
│   └── nginx-aimbot.conf       # Nginx 配置
├── docs/
│   ├── 云台通信协议指南.md       # 云台 UART 串口协议
│   ├── 与前端对接文档.md         # 前后端对接规范
│   └── 使用指南.md              # 使用说明
└── workspace/                   # ROS2 workspace
    └── src/
        ├── driver_pkg/          # 工业相机驱动
        ├── algorithm_pkg/       # 视觉处理算法
        ├── application_pkg/     # HTTP 服务
        ├── gimbal_control_pkg/  # 云台串口通信
        └── bringup_pkg/         # 启动文件
```

## 快速开始

```bash
# 构建
cd workspace
colcon build --symlink-install
source install/setup.bash

# 启动全流程
ros2 launch bringup_pkg vision_pipeline.launch.py

# 浏览器预览
# http://<设备IP>:8080
```

详细使用方法见 [使用指南](docs/使用指南.md)。