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) 启动自动流程

cd /workspace
./autorun.sh

等效于：

./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) 停止全部进程

./run_all_stop.sh

或通过停止信号：

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
• 镜像内 foundation：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：

{
  "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 个

实时查看检测日志：

tail -f /workspace/logs/run_all_*/D_vision_yolo.log

---

常用脚本参数

便捷脚本

# 纯制图（无 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

./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

---

快速命令参考

# 启动（推荐，默认循环制图，无 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/