diff --git a/README.md b/README.md index 65dbb81..78dfc79 100644 --- a/README.md +++ b/README.md @@ -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** (运行时)