# office_gzweb

## 项目说明

本项目用于 Ubuntu + ROS 2 Humble 下的 TurtleBot3 办公室场景自动探索与建图，包含：

- Gazebo Sim 8 (Harmonic) 仿真
- Nav2 导航栈
- SLAM Toolbox 在线建图
- explore_lite 自动探索
- gzweb 网页端 3D 可视化
- 自动保存地图并输出路径

核心目标：一条命令启动，探索结束后自动保存地图并退出。

---

## 环境要求

- Ubuntu 22.04
- ROS 2 Humble
- Gazebo Sim Harmonic
- Node.js / npm（用于 `gzweb-demo`）

---

## 关键目录与文件

- 仿真与模型：`turtlebot3_simulations/turtlebot3_gazebo/`
- 探索节点：`m-explore-ros2/explore/`
- 一键启动脚本：`run_all.sh`
- 一键停止脚本：`run_all_stop.sh`
- A+B 启动脚本：`run_ab.sh`
- WebSocket 配置：`websocket.sdf`
- gzweb 前端：`gzweb-demo/gzweb-demo/`
- 地图输出目录：`turtlebot3_simulations/turtlebot3_gazebo/map/`

---

## 一键运行（推荐）

### 1) 启动自动流程

```bash
cd /home/xh2204/office_gzweb/vlm_office-main
./run_all.sh mapping --explore --gzweb
```

执行内容：

1. 启动 Gazebo Sim + ROS bridge + SLAM + RViz  
2. 启动 gzweb websocket 与前端  
3. 启动 Nav2  
4. 启动 explore_lite 自动探索  
5. 自动检测探索结束（带超时）  
6. 自动保存地图并打印路径  
7. 自动停止全部进程并退出

### 2) 停止全部进程

```bash
./run_all_stop.sh
```

---

## 端口说明

- `5173`：gzweb 前端（Vite）
- `9002`：Gazebo WebSocket

浏览器访问：

- [http://localhost:5173](http://localhost:5173)

---

## 地图保存结果

默认保存到：

- `turtlebot3_simulations/turtlebot3_gazebo/map/office_map.yaml`
- `turtlebot3_simulations/turtlebot3_gazebo/map/office_map.pgm`

`run_all.sh` 保存完成后会在终端打印绝对路径。

---

## 常用脚本参数

### `run_all.sh`

```bash
./run_all.sh mapping [--explore] [--gzweb] [--no-rviz] [--world PATH]
./run_all.sh localization [--gzweb] [--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 前端)
  - 自动端口检查与冲突清理（`5173/9002`）
  - 探索阶段终端计时输出（explore elapsed）
  - 探索结束自动保存地图并退出

### 2) Gazebo + ROS 集成启动

- `turtlebot3_simulations/turtlebot3_gazebo/launch/turtlebot3_office_gz.launch.py`
  - office world 启动
  - `/clock`、`/scan`、`/odom`、`/tf` 等桥接
  - SLAM 与 RViz 延迟启动控制
  - `GZ_PARTITION` 隔离避免串到其他 Gazebo 会话

### 3) gzweb 纹理与材质修复

- `gzweb/gzweb/include/ColladaLoader.js`
  - 修复 `RGBFormat is not defined` 问题
  - 修复 `model://` 纹理 URI 拼接错误（绝对 URI 不再错误拼接）
  - 重新构建输出到 `gzweb/gzweb/dist/`

### 4) 模型颜色兜底

- `office_desk/model.sdf`
- `office_chair/model.sdf`
- `office_couch/model.sdf`

为关键家具增加 fallback 材质参数，避免网页端纹理异常时完全黑白。

---

## 典型问题与处理

- gzweb 无法连接：检查 `9002` 是否被占用，`run_all.sh` 会自动清理并重启
- 前端打不开：检查 `5173`，并查看 `logs/run_all_*/E_gzweb_frontend.log`
- 纹理丢失/颜色异常：检查 `ColladaLoader.js` 与 `GZ_SIM_RESOURCE_PATH`
- 探索长期不结束：`EXPLORE_WAIT_TIMEOUT` 超时后自动强制收尾并保存地图

---

## 日志位置

每次运行会生成：

- `logs/run_all_YYYYMMDD_HHMMSS/`
  - `A_sim.log`
  - `B_nav2.log`
  - `C_explore.log`
  - `D_websocket.log`
  - `E_gzweb_frontend.log`

---

## 快速命令参考

```bash
# 启动（推荐）
./run_all.sh mapping --explore --gzweb

# 强制停止全部
./run_all_stop.sh

# 仅 A+B（不含 explore/gzweb）
./run_ab.sh mapping
```