docs: add usage guide and README with architecture overview

2026-05-31 22:25:00 +08:00
parent 19d5e432a4
commit a281fd115e
2 changed files with 286 additions and 0 deletions
@@ -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)。