# Vision — ROS2 视觉处理与通信系统

基于 ROS2 Humble 的机器视觉识别、PnP 位姿估计与串口通信系统，运行在 NVIDIA Jetson (aarch64) 平台上。

## 整体架构

```
┌──────────────────────────────────────────────────────────────┐
│  camera_node (driver_pkg)                                    │
│  MvCamera SDK → /camera/image_raw                            │
├──────────────────────────────────────────────────────────────┤
│  vision_node (algorithm_pkg)                                 │
│  缩放 → 灰度 → Otsu 二值化 → 形态学 → 轮廓层次 → PnP 位姿    │
│  → /vision/target, /vision/result_image, /vision/debug_image │
├──────────────────────────────────────────────────────────────┤
│  gimbal_node / chassis_node (UART 串口)                       │
│  二进制帧协议 (0xA5/0xA6/0xA7/0xA8/0xA9)                     │
├──────────────────────────────────────────────────────────────┤
│  web_node (application_pkg)                                  │
│  Microdot HTTP Server :8080 → REST API                       │
├──────────────────────────────────────────────────────────────┤
│  bringup_pkg                                                  │
│  rosbridge :9090 + web_video_server :8081 + launch            │
└──────────────────────────────────────────────────────────────┘
```

## 目录结构

```
vision/
├── README.md
├── config/
│   └── nginx-aimbot.conf          # Nginx 反代配置
├── docs/
│   ├── API.md                     # HTTP API 规范
│   ├── front-end_ROS.md           # ROS 话题格式 (前端对接)
│   ├── 使用指南.md                # 构建/运行/问题排查
│   ├── 云台通信协议指南.md          # 云台 UART 协议
│   └── 底盘通信协议指南.md          # 底盘 UART 协议
├── scripts/
│   ├── vision_example.py           # 独立参考 (无 ROS)
│   └── calibrate/
│       ├── calibrate.py            # 相机内参标定
│       ├── laser_calibrate.py      # 激光-相机联合标定
│       ├── pnp_solve.py            # 独立 PnP 解算
│       ├── laser_pnp.py            # 独立 PnP + 激光坐标
│       └── 标定与解算流程.md        # 标定数学说明
└── workspace/
    └── src/
        ├── driver_pkg/             # Hikrobot 相机驱动
        ├── algorithm_pkg/          # 视觉处理算法
        ├── application_pkg/        # HTTP API 服务
        ├── gimbal_control_pkg/     # 云台串口通信
        ├── chassis_control_pkg/    # 底盘串口通信
        └── bringup_pkg/            # 全流程启动
```

## ROS2 节点

| 节点 | 包 | 功能 |
|------|-----|------|
| camera_node | driver_pkg | Hikrobot MvCamera SDK → `/camera/image_raw` |
| vision_node | algorithm_pkg | 矩形检测 → PnP → 激光坐标 → `/vision/target` |
| gimbal_node | gimbal_control_pkg | 云台 UART 串口通信 (921600bps) |
| chassis_node | chassis_control_pkg | 底盘 UART 串口通信 (115200bps) |
| web_node | application_pkg | HTTP REST API (Microdot, :8080) |

## 视觉处理流水线

```
原始图像 1440×1080
  → 缩放 50% (720×540)
  → 灰度
  → 高斯模糊 5×5
  → Otsu 反二值化
  → 形态学闭运算 3×3
  → RETR_TREE 轮廓检测
  → 矩形识别 (外轮廓 + 内轮廓, 4 顶点凸包)
  → 角点排序 (短边 = 宽, 长边 = 长)
  → cv2.solvePnP (SOLVEPNP_IPPE)
  → 激光光斑世界坐标 (Z=0 平面交点)
  → 发布归一化目标偏移 [measure_x, ref_x, measure_y, ref_y]
```

**目标参数:**
- 矩形长边 (RECT_L): 305mm
- 矩形短边 (RECT_W): 215mm
- 最小轮廓面积: 图像面积的 1%

**可选 GPU 加速:** 设置 `ENABLE_CUDA = True` 启用 OpenCV CUDA (缩放/色彩转换/高斯模糊)。

## 通信协议

### 云台 UART (默认 /dev/ttyTHS1, 921600 8N1)

| 帧头 | 长度 | 方向 | 用途 |
|------|------|------|------|
| 0xA5 | 18B | PC→MCU | 自动追踪 (4×float) |
| 0xA6 | 10B | PC→MCU | 手动控制 (2×float) |
| 0xA7 | 3B | PC→MCU | 命令 (模式/激光) |
| 0xA8 | 50B | PC→MCU | PID 调参 (12×float) |
| 0xA9 | 6B | MCU→PC | 前馈角速度 |

### 底盘 UART (默认 /dev/ttyCH341USB0, 115200 8N1)

| 帧头 | 长度 | 方向 | 用途 |
|------|------|------|------|
| 0xA6 | 8B | PC→MCU | 手动控制 |
| 0xA7 | 3B | PC→MCU | 命令 |
| 0xA8 | 38B | PC→MCU | PID 调参 (9×float) |
| 0xA9 | 6B | MCU→PC | 前馈角速度 |

校验和: 全部字节累加取低 8 位。详细说明见 `docs/` 目录下协议指南。

### HTTP API

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/gimbal/mode/switch` | POST | 云台模式切换 |
| `/api/chassis/mode/switch` | POST | 底盘模式切换 |
| `/api/laser` | POST | 激光开关 |
| `/api/gimbal/pidconfig` | GET/POST | 云台 PID 配置 |
| `/api/chassis/pidconfig` | GET/POST | 底盘 PID 配置 |

详细 API 规范见 [docs/API.md](docs/API.md)。

## 标定流程

1. **相机内参标定**: 运行 `scripts/calibrate/calibrate.py`，使用 11×8 内角点、15mm 方格棋盘标定板，输出 `calibration_result.json`
2. **激光线标定**: 运行 `scripts/calibrate/laser_calibrate.py`，需加载相机内参，输出 `laser_result.json`
3. 将标定结果写入 `vision_node.py` 或独立脚本中使用

## 工作模式

| 模式 | 视觉处理 | 串口发送 | 说明 |
|------|----------|----------|------|
| AUTO | 运行 | 0xA5 帧 | 检测矩形目标，自动追踪 |
| MANUAL | 运行 (仅显示) | 0xA6 帧 | 接收手动速度指令 |
| DEBUG | 运行 (仅显示) | 0xA8 帧 | PID 参数在线调试 |

## 快速开始

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

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

# 启动 Nginx (可选, 提供 Web 前端)
sudo nginx -c $(pwd)/../config/nginx-aimbot.conf
```

## 端口分配

| 端口 | 服务 |
|------|------|
| 80 | Nginx 静态文件 + 反代 |
| 8080 | web_node HTTP API |
| 8081 | web_video_server (MJPEG) |
| 9090 | rosbridge WebSocket |

## 依赖

- **ROS2 Humble** (rclpy, sensor_msgs, std_msgs, geometry_msgs, cv_bridge)
- **OpenCV** 4.x (图像处理, PnP, 标定)
- **NumPy** (线性代数)
- **pyserial** (串口通信)
- **microdot** (HTTP 服务)
- **Hikrobot MvCamera SDK** (工业相机, 安装于 /opt/MVS/)
- **rosbridge_server** + **web_video_server** (运行时)