docs: 完善 README.md，补充视觉处理流水线和标定流程说明

2026-06-07 21:01:28 +08:00
parent b7591f7b31
commit ebe3c54818
1 changed files with 145 additions and 63 deletions
@@ -1,81 +1,143 @@
-# Vision Pipeline
+# Vision — ROS2 视觉处理与通信系统

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

 ## 整体架构

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

-## 数据流
-
-| 阶段 | 话题 | 方向 | 消息类型 | 说明 |
-|------|------|------|----------|------|
-| 图像采集 | `/camera/image_raw` | camera_node → vision_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 参数 | `/web/gimbal_pid_config` | 前端 → gimbal_node | `std_msgs/String` | PID 参数 JSON |
-
 ## 目录结构

 ```
-Vision/
+vision/
 ├── README.md
-├── vision_example.py          # 独立参考脚本（非 ROS2）
 ├── config/
-│   └── nginx-aimbot.conf       # Nginx 配置
+│   └── nginx-aimbot.conf          # Nginx 反代配置
 ├── docs/
-│   ├── 云台通信协议指南.md       # 云台 UART 串口协议
-│   ├── 与前端对接文档.md         # 前后端对接规范
-│   └── 使用指南.md              # 使用说明
-└── workspace/                   # ROS2 workspace
+│   ├── 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/          # 工业相机驱动
-        ├── algorithm_pkg/       # 视觉处理算法
-        ├── application_pkg/     # HTTP 服务
-        ├── gimbal_control_pkg/  # 云台串口通信
-        └── bringup_pkg/         # 启动文件
+        ├── 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
@@ -86,6 +148,26 @@ source install/setup.bash

 # 启动全流程
 ros2 launch bringup_pkg vision_pipeline.launch.py
+
+# 启动 Nginx (可选, 提供 Web 前端)
+sudo nginx -c $(pwd)/../config/nginx-aimbot.conf
 ```

-详细使用方法见 [使用指南](docs/使用指南.md)。
+## 端口分配
+
+| 端口 | 服务 |
+|------|------|
+| 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** (运行时)