# CLAUDE.md

## 项目概述

这是一个 ROS 2 Humble 工作空间，用于 Ackermann 转向小车的 Gazebo 仿真、SLAM 建图和 Nav2 导航。

## 工作空间结构

```
test_ws/
├── src/
│   ├── gc_navigation2_slamtoolbox/   # 导航+SLAM 启动文件和配置
│   │   ├── launch/                   # Python launch 文件
│   │   ├── config/                   # slam_toolbox 参数
│   │   ├── params/                   # Nav2 参数
│   │   ├── maps/                     # 地图文件 (.pgm, .yaml, .posegraph)
│   │   └── world/                    # Gazebo 模型 (zhihui/)
│   └── origincar_description/        # 机器人 URDF 和 Gazebo world
│       ├── urdf/                     # origincar.urdf
│       ├── world/                    # .world 文件
│       ├── meshes/                   # 3D 模型
│       ├── launch/                   # display.launch.py
│       └── rviz/                     # RViz 配置
├── build/                            # colcon build 输出
├── install/                          # colcon install 输出 (含符号链接)
└── log/                              # 构建日志
```

## 构建命令

```bash
cd /home/guoch/test_ws
source /opt/ros/humble/setup.bash
colcon build --symlink-install
source install/setup.bash
```

## 常用 Launch 文件

| 文件 | 功能 |
|------|------|
| `gc_slam_mapping.launch.py` | Gazebo + SLAM 建图模式 |
| `gc_nav2_with_slam_online.launch.py` | 已知地图 + SLAM 在线更新 + Nav2 导航 |

## 机器人参数 (origincar)

- **类型**: Ackermann 转向小车
- **尺寸**: 0.276 × 0.214 × 0.211 m (长×宽×高)
- **轴距**: 0.168 m，**轮距**: 0.189 m
- **轮子**: 半径 0.03 m，厚 0.025 m
- **激光雷达**: 360°, 0.12~3.5 m, 5 Hz
- **IMU**: 100 Hz, 含高斯噪声
- **Gazebo 插件**: `gazebo_ros_ackermann_drive`, `gazebo_ros_ray_sensor`, `gazebo_ros_imu_sensor`

## 关键设计

1. **map_server** 提供全量静态底图（`/map`）
2. **slam_toolbox** 负责定位和增量建图，重映射 `/map` → `/slam_map` 避免冲突
3. **Nav2** 使用 `global_costmap/static_layer ← /map` + `local_costmap/obstacle_layer ← /scan`
4. 保存地图: `ros2 service call /slam_toolbox/serialize_map ...`

## 地图文件

地图放在 `src/gc_navigation2_slamtoolbox/maps/`，包含:
- `xxx.pgm` — 地图图像
- `xxx.yaml` — 地图元数据 (resolution, origin, thresholds)
- `xxx.posegraph` — 序列化的位姿图

## Gazebo World

World 文件在 `src/origincar_description/world/`:
- `zhihui.world` — 智慧楼墙体环境（内联模型）
- `test.world` — 测试环境
- `fishbot.world` / `gc_world.world` — 其他场景

## 注意事项

- 使用 `--symlink-install` 构建，Python launch 文件修改后无需重新编译
- `.world` 文件不应使用 `model://` 外部引用，应将模型内联定义
- `robot_base_frame` 在 ackermann plugin 中应设为 `base_footprint`