AimBot/Vision
14
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add usage guide and README with architecture overview

Browse Source
This commit is contained in:
dev01
2026-05-31 22:25:00 +08:00
parent 19d5e432a4
commit a281fd115e
2 changed files with 286 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+96
View File
@@ -0,0 +1,96 @@
# 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)。
docs/使用指南.md
+190
View File
@@ -0,0 +1,190 @@
# 使用指南
## 开发环境
- ROS2 Humble + colcon
- Python 3.8+
- OpenCV、NumPy
- Hikrobot MvCamera SDK（`/opt/MVS/`）
- pyserial
## 1. 构建
```bash
cd workspace
colcon build --symlink-install
source install/setup.bash
```
`--symlink-install` 使 Python 修改无需重新构建即可生效。
## 2. 启动全流程
```bash
ros2 launch bringup_pkg vision_pipeline.launch.py
```
启动后包含四个节点：
| 节点 | 包 | 功能 |
|------|-----|------|
| camera_node | driver_pkg | 工业相机图像采集 |
| vision_node | algorithm_pkg | 图像处理 + 目标检测 |
| web_node | application_pkg | HTTP 服务、预览 + API |
| gimbal_node | gimbal_control_pkg | 云台串口通信 |
## 3. 分别启动
```bash
# 相机驱动
ros2 run driver_pkg camera_node
# 视觉处理
ros2 run algorithm_pkg vision_node
# Web 服务
ros2 run application_pkg web_node
# 云台通信（默认串口 /dev/ttyTHS1）
ros2 run gimbal_control_pkg gimbal_node
```
gimbal_node 支持串口参数覆盖：
```bash
ros2 run gimbal_control_pkg gimbal_node --ros-args -p serial_port:=/dev/ttyUSB0
```
## 4. 接入前端（可选）
前端需要 rosbridge 和 web_video_server：
```bash
# 安装依赖
sudo apt install ros-${ROS_DISTRO}-rosbridge-server
sudo apt install ros-${ROS_DISTRO}-web-video-server
# 启动 rosbridge WebSocket（默认 ws://0.0.0.0:9090）
ros2 run rosbridge_server rosbridge_websocket &
# 启动 MJPEG 视频推流（默认 http://0.0.0.0:8081）
ros2 run web_video_server web_video_server &
```
### Nginx 部署
```bash
sudo cp config/nginx-aimbot.conf /etc/nginx/sites-available/aimbot
sudo ln -s /etc/nginx/sites-available/aimbot /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
```
Nginx 负责三件事：
- 托管前端静态文件（`/var/www/aimbot/`）
- 反代 MJPEG 视频流（`/stream` → `web_video_server :8081`）
- 反代模式切换 API（`/api/` → `web_node :8080`）
### 启动顺序
1. 启动 ROS2 节点（launch 或分别启动）
2. 启动 rosbridge + web_video_server
3. 启动/重载 Nginx
## 5. 模式切换
通过 HTTP API 切换云台工作模式：
```bash
# 自动追踪模式
curl -X POST http://localhost:8080/api/mode/switch \
-H "Content-Type: application/json" \
-d '{"mode": "auto"}'
# 手动控制模式
curl -X POST http://localhost:8080/api/mode/switch \
-H "Content-Type: application/json" \
-d '{"mode": "manual"}'
# 调试模式
curl -X POST http://localhost:8080/api/mode/switch \
-H "Content-Type: application/json" \
-d '{"mode": "debug"}'
# 激光开关
curl -X POST http://localhost:8080/api/mode/switch \
-H "Content-Type: application/json" \
-d '{"mode": "laser_on"}'
```
也可直接通过 ROS2 话题发送：
```bash
ros2 topic pub /gimbal/mode std_msgs/String "data: 'auto'"
```
## 6. 手动控制云台
```bash
# angular.y = pitch 角速度, angular.z = yaw 角速度
ros2 topic pub /cmd_gimbal geometry_msgs/Twist \
"{angular: {y: 0.0, z: 0.0}}"
```
## 7. PID 调参（调试模式）
先切换到 debug 模式，然后通过 `/pid_config` 话题发送参数：
```bash
ros2 topic pub /pid_config std_msgs/String \
'{"vision_yaw": {"kp": 1.0, "ki": 0.0, "kd": 0.0},
"vision_pitch": {"kp": 1.0, "ki": 0.0, "kd": 0.0},
"motor_yaw": {"kp": 1.0, "ki": 0.0, "kd": 0.0},
"motor_pitch": {"kp": 1.0, "ki": 0.0, "kd": 0.0}}'
```
参数立即生效，调试完毕后切回 auto 或 manual 模式。
## 8. 查看视觉结果
浏览器打开 `http://<设备IP>:8080`，可看到：
- 原始图像 + 轮廓标注（result）
- Otsu 二值化 + 闭运算结果（binary）
## 9. 查看话题
```bash
# 列出所有活跃话题
ros2 topic list
# 查看话题频率
ros2 topic hz /camera/image_raw
ros2 topic hz /vision/target
# 查看话题内容
ros2 topic echo /vision/target
```
## 10. 测试
```bash
cd workspace
# 测试全部包
colcon test
# 测试单个包
colcon test --packages-select gimbal_control_pkg
# 查看测试结果
colcon test-result --all
```
## 11. 故障排查
| 现象 | 检查项 |
|------|--------|
| 相机打不开 | SDK 是否安装、相机是否连接、`/opt/MVS/` 路径是否正确 |
| 视觉画面无结果 | `/camera/image_raw` 是否有数据 |
| 云台无反应 | 串口 `/dev/ttyTHS1` 是否存在、波特率 115200 是否匹配 |
| 模式切换报错 | web_node 是否在 :8080 端口运行 |
| MJPEG 不出画面 | web_video_server 是否运行、proxy_buffering 是否设为 off |