319 lines
8.4 KiB
Markdown
319 lines
8.4 KiB
Markdown
# office_gzweb
|
||
|
||
## 项目说明
|
||
|
||
本项目用于 Ubuntu + ROS 2 Humble 下的 TurtleBot3 办公室场景自动探索与建图，包含：
|
||
|
||
- Gazebo Sim 8 (Harmonic) 仿真
|
||
- Nav2 导航栈（速度优化版）
|
||
- SLAM Toolbox 在线建图
|
||
- explore_lite 自动探索（调优版）
|
||
- **YOLOv8 CPU 视觉检测**（640×480，中文输出，带图像归档）
|
||
- **Qwen2.5-VL-3B GPU 视觉检测**（VLM 语义理解，中文 JSON 输出，场景描述）
|
||
- gzweb 网页端 3D 可视化
|
||
- 循环探索模式（永不退出，自动保存地图后重启）
|
||
- 一键停止脚本
|
||
|
||
核心目标：一条命令启动，机器人自动探索、检测、建图，循环运行直到手动停止。
|
||
支持三种视觉模式切换：**无视觉 / YOLO CPU / VLM GPU**。
|
||
|
||
---
|
||
|
||
## 环境要求
|
||
|
||
- Ubuntu 22.04
|
||
- ROS 2 Humble
|
||
- Gazebo Sim Harmonic
|
||
- Node.js / npm（用于 `gzweb-demo`）
|
||
- Python 依赖：`ultralytics`, `opencv-python`, `numpy<2`
|
||
|
||
---
|
||
|
||
## 关键目录与文件
|
||
|
||
- 仿真与模型：`turtlebot3_simulations/turtlebot3_gazebo/`
|
||
- 探索节点：`m-explore-ros2/explore/`
|
||
- 视觉检测：`src/vision_yolo/vision_yolo/detector.py`
|
||
- 一键启动脚本：`run_all.sh`
|
||
- 一键停止脚本：`run_all_stop.sh`
|
||
- 自动运行入口：`autorun.sh`
|
||
- WebSocket 配置：`websocket.sdf`
|
||
- gzweb 前端：`gzweb-demo/gzweb-demo/`
|
||
- 地图输出目录：`turtlebot3_simulations/turtlebot3_gazebo/map/`
|
||
- 视觉输出目录：`/workspace/vision_output/YYYYMMDD_HHMMSS/`
|
||
|
||
---
|
||
|
||
## 一键运行（推荐）
|
||
|
||
### 1) 启动自动流程
|
||
|
||
```bash
|
||
cd /workspace
|
||
./autorun.sh
|
||
```
|
||
|
||
等效于：
|
||
|
||
```bash
|
||
./run_all.sh mapping --explore --gzweb --no-gzweb-vite --vision
|
||
```
|
||
|
||
执行内容：
|
||
|
||
1. 启动 Gazebo Sim + ROS bridge + SLAM + RViz
|
||
2. 启动 gzweb websocket（foundation /opt/gzweb，端口 8000）
|
||
3. 启动 Nav2（快速参数：max_vel_x 0.5 m/s）
|
||
4. 启动 explore_lite 自动探索（planner_frequency 1.0，min_frontier_size 0.3）
|
||
5. 启动 YOLOv8 视觉检测（1 秒/帧，640×480，中文日志，图像归档）
|
||
6. 自动检测探索结束（带超时）
|
||
7. **自动保存地图 → 等待 30 秒 → 重新启动探索（循环模式，永不退出）**
|
||
|
||
### 2) 停止全部进程
|
||
|
||
```bash
|
||
./run_all_stop.sh
|
||
```
|
||
|
||
或通过停止信号：
|
||
|
||
```bash
|
||
touch /workspace/.run_all_stop
|
||
```
|
||
|
||
---
|
||
|
||
## 端口说明
|
||
|
||
- `5173`：gzweb 前端（Vite，仅当不使用 `--no-gzweb-vite`）
|
||
- `8000`：foundation gzweb（`--no-gzweb-vite` 时使用）
|
||
- `9002`：Gazebo WebSocket
|
||
- `3000`：后端 API（如启用）
|
||
|
||
浏览器访问：
|
||
|
||
- 本地开发：[http://localhost:5173](http://localhost:5173)
|
||
- 镜像内 foundation：[http://localhost:8000](http://localhost:8000)
|
||
|
||
---
|
||
|
||
## 地图保存结果
|
||
|
||
默认保存到：
|
||
|
||
- `turtlebot3_simulations/turtlebot3_gazebo/map/office_map.yaml`
|
||
- `turtlebot3_simulations/turtlebot3_gazebo/map/office_map.pgm`
|
||
|
||
每次循环结束时自动覆盖保存最新地图。
|
||
|
||
---
|
||
|
||
## 视觉检测
|
||
|
||
支持三种模式，通过 `VISION_BACKEND` 环境变量切换：
|
||
|
||
| 模式 | 命令 | 说明 |
|
||
|------|------|------|
|
||
| 关闭 | `./run_mapping.sh` | 不运行 detector，纯制图 |
|
||
| YOLO CPU | `./run_yolo.sh` | YOLOv8n，~80ms/帧，COCO 80 类 |
|
||
| VLM GPU | `./run_vlm.sh` | Qwen2.5-VL-3B，~6.6s/帧，语义理解 |
|
||
|
||
### YOLO 输出
|
||
|
||
保存于 `/workspace/vision_output/YYYYMMDD_HHMMSS/`：
|
||
|
||
- `frame_0001.jpg` — 原始相机图像
|
||
- `frame_0001_annotated.jpg` — 带检测框和中文标签的图像
|
||
- `/workspace/camera_latest.jpg` — 最新一帧快速查看
|
||
|
||
日志示例：
|
||
|
||
```
|
||
[vision] 第42帧 | 位置(1.23, 0.87, 0.15rad) | 检测到 3 个目标: 椅子(87%), 沙发(92%), 人(76%)
|
||
```
|
||
|
||
### VLM 输出
|
||
|
||
Qwen2.5-VL-3B 返回中文 JSON：
|
||
|
||
```json
|
||
{
|
||
"objects": [
|
||
{"label": "饮水机", "bbox": [438, 72, 521, 256], "confidence": 0.95}
|
||
],
|
||
"scene_description": "办公室茶水间"
|
||
}
|
||
```
|
||
|
||
基准性能（Tesla T4）：
|
||
|
||
| 指标 | 数值 |
|
||
|------|------|
|
||
| 模型加载 | ~4s |
|
||
| 单帧推理 | **~6.6s**（640×480） |
|
||
| VRAM 占用 | 7.5GB / 15.6GB |
|
||
| 输出 token | ~70 个 |
|
||
|
||
实时查看检测日志：
|
||
|
||
```bash
|
||
tail -f /workspace/logs/run_all_*/D_vision_yolo.log
|
||
```
|
||
|
||
---
|
||
|
||
## 常用脚本参数
|
||
|
||
### 便捷脚本
|
||
|
||
```bash
|
||
# 纯制图（无 detector）
|
||
./run_mapping.sh
|
||
|
||
# YOLO CPU 视觉巡检
|
||
./run_yolo.sh
|
||
|
||
# VLM GPU 视觉巡检（需要 GPU 实例）
|
||
./run_vlm.sh
|
||
|
||
# VLM 混合模式（YOLO 持续 + VLM 定期深度分析）
|
||
VISION_BACKEND=hybrid ./run_vlm.sh
|
||
```
|
||
|
||
### `run_all.sh`
|
||
|
||
```bash
|
||
./run_all.sh mapping [--explore] [--vision] [--gzweb] [--no-gzweb-vite] [--no-rviz] [--world PATH]
|
||
./run_all.sh localization [--gzweb] [--no-gzweb-vite] [--no-rviz] [--map PATH] [--world PATH]
|
||
```
|
||
|
||
可配置环境变量（`.env.defaults`）：
|
||
|
||
- `VISION_BACKEND`（`yolo` / `vlm` / `hybrid`）
|
||
- `VLM_INTERVAL`（默认 `5.0` 秒）
|
||
- `VLM_MODEL`（默认 `Qwen/Qwen2.5-VL-3B-Instruct`）
|
||
- `ROBOT_MODEL`（默认 `waffle`）
|
||
- `GZ_PARTITION`（默认 `tb3_office_gz`）
|
||
- `SLEEP_NAV2`（默认 `18` 秒）
|
||
- `EXPLORE_WAIT_TIMEOUT`（默认 `420` 秒）
|
||
|
||
---
|
||
|
||
## 关键实现
|
||
|
||
### 1) 仿真/导航/探索/视觉总控
|
||
|
||
- `run_all.sh`
|
||
- 统一启动 A(sim)、B(nav2)、C(explore)、D(websocket)、E(gzweb 前端)、D_vision_yolo
|
||
- 自动端口检查与冲突清理（`5173/9002`）
|
||
- 探索阶段终端计时输出（explore elapsed）
|
||
- **循环模式**：探索结束自动保存地图 → 等待 30 秒 → 重新启动 explore_lite
|
||
- 通过 `/workspace/.run_all_stop` 文件接收停止信号
|
||
|
||
### 2) Gazebo + ROS 集成启动
|
||
|
||
- `turtlebot3_simulations/turtlebot3_gazebo/launch/turtlebot3_office_gz.launch.py`
|
||
- office world 启动
|
||
- `/clock`、`/scan`、`/odom`、`/tf`、`/camera/image_raw` 等桥接
|
||
- SLAM 与 RViz 延迟启动控制
|
||
- `GZ_PARTITION` 隔离避免串到其他 Gazebo 会话
|
||
|
||
### 3) YOLO 视觉检测
|
||
|
||
- `src/vision_yolo/vision_yolo/detector.py`
|
||
- YOLOv8n 实时推理，订阅 `/camera/image_raw`
|
||
- 推理节流：1 秒/帧（降低 CPU 占用，避免影响 Nav2）
|
||
- 分辨率 640×480（比 320×240 检测效果更好）
|
||
- 订阅 `/odom` 获取机器人实时位姿
|
||
- **中文标签输出**：COCO 80 类中英文映射
|
||
- **图像归档**：每帧保存原始图 + 标注图到时间戳目录
|
||
- 发布 `/vision/detections`（Detection2DArray）和 `/vision/image_annotated`（Image）
|
||
|
||
### 4) Nav2 速度优化
|
||
|
||
- `nav2_params_fast.yaml`
|
||
- `max_vel_x: 0.5`（默认 0.26）
|
||
- `max_speed_xy: 0.5`
|
||
- 加速办公室场景探索
|
||
|
||
### 5) explore_lite 调优
|
||
|
||
- `m-explore-ros2/explore/config/params.yaml`
|
||
- `planner_frequency: 1.0`（默认 0.2，提高响应速度）
|
||
- `min_frontier_size: 0.3`（默认 0.5，更容易发现小 frontier）
|
||
|
||
### 6) gzweb 纹理与材质修复
|
||
|
||
- `gzweb/gzweb/include/ColladaLoader.js`
|
||
- 修复 `RGBFormat is not defined` 问题
|
||
- 修复 `model://` 纹理 URI 拼接错误
|
||
- 重新构建输出到 `gzweb/gzweb/dist/`
|
||
|
||
### 7) 模型颜色兜底
|
||
|
||
- `office_desk/model.sdf`
|
||
- `office_chair/model.sdf`
|
||
- `office_couch/model.sdf`
|
||
|
||
为关键家具增加 fallback 材质参数，避免网页端纹理异常时完全黑白。
|
||
|
||
---
|
||
|
||
## 典型问题与处理
|
||
|
||
- **gzweb 无法连接**：检查 `9002` 是否被占用，`run_all.sh` 会自动清理并重启
|
||
- **前端打不开**：检查 `5173`/`8000`，并查看 `logs/run_all_*/E_gzweb_frontend.log`
|
||
- **纹理丢失/颜色异常**：检查 `ColladaLoader.js` 与 `GZ_SIM_RESOURCE_PATH`
|
||
- **探索长期不结束**：`EXPLORE_WAIT_TIMEOUT` 超时后自动强制收尾并保存地图，30 秒后重启
|
||
- **YOLO 误识别多**：预训练模型基于 COCO 真实照片，Gazebo 3D 渲染场景存在 domain gap，属于正常现象
|
||
- **VLM 首次加载慢**：模型 7GB，首次加载约 4-5 秒，后续复用缓存
|
||
- **VLM 推理慢**：单帧约 6-6.5 秒，属于正常范围，设计为定期采样而非每帧
|
||
- **机器人不动**：Nav2 生命周期初始化需要 20-40 秒，请耐心等待
|
||
|
||
---
|
||
|
||
## 日志位置
|
||
|
||
每次运行会生成：
|
||
|
||
- `logs/run_all_YYYYMMDD_HHMMSS/`
|
||
- `A_sim.log`
|
||
- `B_nav2.log`
|
||
- `C_explore.log`
|
||
- `D_websocket.log`
|
||
- `E_gzweb_frontend.log`
|
||
- `D_vision_yolo.log`
|
||
|
||
---
|
||
|
||
## 快速命令参考
|
||
|
||
```bash
|
||
# 启动（推荐，默认循环制图，无 detector）
|
||
./autorun.sh
|
||
|
||
# 停止全部
|
||
./run_all_stop.sh
|
||
|
||
# 纯制图
|
||
./run_mapping.sh
|
||
|
||
# YOLO CPU 视觉巡检
|
||
./run_yolo.sh
|
||
|
||
# VLM GPU 视觉巡检
|
||
./run_vlm.sh
|
||
|
||
# 仅 A+B（不含 explore/vision/gzweb）
|
||
./run_ab.sh mapping
|
||
|
||
# 实时查看视觉检测日志
|
||
tail -f /workspace/logs/run_all_*/D_vision_yolo.log
|
||
|
||
# 查看最新相机图像
|
||
ls -lh /workspace/camera_latest.jpg
|
||
|
||
# 查看视觉归档目录
|
||
ls -la /workspace/vision_output/
|
||
```
|