# 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/
```