256 lines
6.9 KiB
Markdown
256 lines
6.9 KiB
Markdown
# office_gzweb
|
||
|
||
## 项目说明
|
||
|
||
本项目用于 Ubuntu + ROS 2 Humble 下的 TurtleBot3 办公室场景自动探索与建图，包含：
|
||
|
||
- Gazebo Sim 8 (Harmonic) 仿真
|
||
- Nav2 导航栈（速度优化版）
|
||
- SLAM Toolbox 在线建图
|
||
- explore_lite 自动探索（调优版）
|
||
- YOLOv8 视觉检测（640×480，中文输出，带图像归档）
|
||
- gzweb 网页端 3D 可视化
|
||
- 循环探索模式（永不退出，自动保存地图后重启）
|
||
- 一键停止脚本
|
||
|
||
核心目标：一条命令启动，机器人自动探索、检测、建图，循环运行直到手动停止。
|
||
|
||
---
|
||
|
||
## 环境要求
|
||
|
||
- 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`
|
||
|
||
每次循环结束时自动覆盖保存最新地图。
|
||
|
||
---
|
||
|
||
## 视觉检测输出
|
||
|
||
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%)
|
||
[vision] 第43帧 | 位置(1.25, 0.89, 0.16rad) | 未检测到目标
|
||
```
|
||
|
||
实时查看检测日志：
|
||
|
||
```bash
|
||
tail -f /workspace/logs/run_all_*/D_vision_yolo.log
|
||
```
|
||
|
||
---
|
||
|
||
## 常用脚本参数
|
||
|
||
### `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]
|
||
```
|
||
|
||
可配置环境变量：
|
||
|
||
- `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，属于正常现象
|
||
- **机器人不动**：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
|
||
# 启动（推荐，循环模式）
|
||
./autorun.sh
|
||
|
||
# 停止全部
|
||
./run_all_stop.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/
|
||
```
|