# 语义推理与导航

卡片名称：办公室场景下的小车语义推理与导航

描述：基于 `VLM`、`RRT*`、`Nav2` 和视觉语言模型的语义导航项目，把仿真导航、目标检测、语义记忆库和自然语言导航串成一条完整链路。

这是一个基于 `ROS 2 Humble`、`Gazebo Sim`、`Nav2` 和视觉语言模型的语义导航项目。系统把仿真导航、目标检测、语义记忆库和自然语言导航串成一条完整链路：机器人先在环境中自主移动并识别目标物体，把高置信度的语义结果保存为 JSON 记忆库；随后用户输入自然语言目标，系统从记忆库中检索最匹配的语义对象，并调用 Nav2 完成导航。

![Semantic Navigation Preview](assets/picture20.png)

## 项目能力

本项目包含以下核心能力：

- 使用 `TurtleBot3 + Gazebo Sim` 构建室内办公场景导航仿真
- 使用自定义 `RRT*` 全局规划器接入 Nav2
- 使用 `VLM` 目标检测节点进行语义目标标注
- 基于 RGB-D 与 TF 估计物体在地图中的位置并生成语义记忆库
- 将检测结果保存为 JSON 文件，支持后续复用
- 接收自然语言输入，匹配语义目标并导航到目标附近的可行接近点

## 整体流程

项目运行分为两个阶段：

1. 语义记忆构建阶段  
   机器人在仿真环境中移动，检测节点从相机图像中识别目标物体，并把标签、置信度和目标坐标写入 JSON 语义记忆库。

2. 语义导航阶段  
   用户输入自然语言目标，例如 `water dispenser`、`sofa`、`refrigerator`，系统将语义文本映射到已保存的目标条目，选取目标附近的可达点，并通过 Nav2 发送导航目标。

## 核心模块

### 1. 导航与仿真

- `src/TurtleBot-RRT-Star/`：自定义 `RRT*` 全局规划器，包名为 `nav2_rrtstar_planner`
- `src/turtlebot3_simulations/`：TurtleBot3 仿真环境、世界文件和启动资源
- `gzsim_run.sh`：一键启动 Gazebo Sim 与 websocket 服务（内含 `setup_model_cache.sh`）
- `setup_model_cache.sh` / `VENDOR_MODELS.md`：vendor 共享权重与下载、同步说明

### 2. 语义感知

- `src/vlm_perception_pkg/`：语义检测节点
- 入口命令：`ros2 run vlm_perception_pkg vlm_detection`
- 功能：读取机器人相机图像，识别候选目标，结合深度和 TF 写入语义记忆库

### 3. 语义导航

- `src/vlm_nav_pkg/`：自然语言语义导航节点
- 入口命令：`ros2 run vlm_nav_pkg semantic_nav`
- 功能：加载 JSON 语义记忆库，匹配语义标签，选择可行导航点并发送目标给 Nav2

### 4. 语义记忆库

示例语义结果文件位于：

- `src/vlm_nav_pkg/config/example_object_detection_vlm.json`
- `src/vlm_nav_pkg/config/test_vlm.json`

语义记忆库保存的是目标标签、置信度和地图坐标。系统会优先保留高分结果，以减少低质量检测对导航的影响。

## 仓库结构

```text
.
├── README.md
├── doc.md
├── gzsim_run.sh
├── bootstrap_ros2_conda_workspace.sh
├── requirements.txt
├── requirements-v100.txt
├── assets/
└── src/
    ├── TurtleBot-RRT-Star/
    ├── turtlebot3_simulations/
    ├── vlm_nav_pkg/
    ├── vlm_perception_pkg/
    └── websocket.gzlaunch
```

各目录作用如下：

- `doc.md`：完整课程说明，包含带截图的分步骤操作
- `assets/`：运行截图和展示图片
- `src/TurtleBot-RRT-Star/`：RRT* 全局规划插件与 Nav2 参数
- `src/vlm_perception_pkg/`：检测与语义标注相关代码
- `src/vlm_nav_pkg/`：语义导航相关代码与配置文件
- `gzsim_run.sh`：仿真与 websocket 启动脚本
- `requirements*.txt`：Python 依赖列表

## 相关资源

- 详细操作文档：[doc.md](doc.md)
- 语义记忆示例：[src/vlm_nav_pkg/config/example_object_detection_vlm.json](src/vlm_nav_pkg/config/example_object_detection_vlm.json)
- 更优测试样例：[src/vlm_nav_pkg/config/test_vlm.json](src/vlm_nav_pkg/config/test_vlm.json)
- RRT* 参数文件：`src/TurtleBot-RRT-Star/nav2_params.yaml`