5.5.2 SLAM（选装）

SLAM（同步定位与建图）模块提供地图构建、地图获取和重定位接口，支持机器人在未知环境中建立地图并基于已有地图进行精确定位。

重要

本处为选装组件, 如需使用本页面所述功能接口, 请联系售后技术支持

地图构建

使用话题控制建图流程的启停，并指定保存的地图名称。

话题名称	数据类型	描述	QoS	频率
`/integrated_command`	`std_msgs/String`	发布建图控制指令	`RELIABLE`+`TRANSIENT_LOCAL`	用户发送（按需）

指令格式：

指令	说明
`start_mapping`	开始建图
`stop_mapping:<map_name>`	停止建图并以 `<map_name>` 保存地图

注意： 发送 stop_mapping 指令后，地图保存需要一定时间。保存过程中系统可能因异常（如 SLAM 模块无响应、磁盘 I/O 慢等）导致超时失败（默认超时 120 秒）。可通过 GetStoredMapByName 服务按地图名称查询是否保存成功。

地图获取

服务名称	数据类型	描述
`/aimdk_5Fmsgs/srv/GetStoredMapByName`	`GetStoredMapByName`	按地图名称获取已存储的地图数据

GetStoredMapByName ros2-srv @ mm/srv/GetStoredMapByName.srv

# 按地图名称获取已存储的地图数据
# 服务名称: /aimdk_5Fmsgs/srv/GetStoredMapByName

# 请求
std_msgs/Header header   # 请求头
string map_name          # 地图名称

---

# 响应
uint64 code              # 返回码，0 表示成功
std_msgs/Header header   # 响应头
nav_msgs/MapMetaData map_info  # 地图信息（分辨率、宽高等）
uint64 map_version       # 地图版本号
string map_path          # 地图 PNG 文件路径
int8[] data              # 地图栅格数据（-1/0/100）
NaviPoint[] navi_points  # 导航点拓扑信息
QRPoint[] qr_points      # 二维码点拓扑信息
HRPoint[] hr_points      # 高精度点拓扑信息
Path[] paths             # 路径拓扑信息
Region[] regions         # 区域拓扑信息（含虚拟墙）
uint64 map_id            # 地图 ID

std_msgs/Header
nav_msgs/MapMetaData

NaviPoint ros2-msg @ mm/msg/NaviPoint.msg

int32 point_id                   # 点位 ID
geometry_msgs/Pose2D navi_point  # 导航点二维坐标位姿

geometry_msgs/Pose2D

QRPoint ros2-msg @ mm/msg/QRPoint.msg

int32 point_id  # 点位 ID
QRCode qr_code  # 二维码信息

QRCode ros2-msg @ common/QRCode.msg

int32 code               # 二维码值
geometry_msgs/Pose pose  # 二维码位姿

geometry_msgs/Pose

HRPoint ros2-msg @ mm/msg/HRPoint.msg

int32 point_id           # 点位 ID
geometry_msgs/Pose pose  # 高精度点的实时位姿
QRCode[] qr_list         # 关联的二维码点列表
bool use_head            # 是否使用头部相机

geometry_msgs/Pose

Path ros2-msg @ mm/msg/Path.msg

int32 path_id                    # 路径 ID
geometry_msgs/Pose2D[] points    # 路径点二维坐标位姿列表

geometry_msgs/Pose2D

Region ros2-msg @ mm/msg/Region.msg

uint8 type          # 区域类型（0: 未定义, 1: 工作区域, 2: 虚拟墙）
uint8 drawing_type  # 绘制类型（0: 未定义, 1: 封闭区域, 2: 折线）
string name                        # 区域名称
geometry_msgs/Polygon polygon      # 闭合多边形顶点（有序，首尾不重合）

geometry_msgs/Polygon

重定位

将机器人定位到已建立地图中的指定位置，需先触发重定位指令，再提供初始位姿估计，最后通过订阅定位结果话题确认重定位是否成功。

何时需要重定位

以下场景需要重新执行重定位，使机器人获取在地图中的初始位姿：

机器人开机后首次使用导航功能
切换到新的地图
定位丢失（如机器人被搬动后）

注意： 不执行重定位时，定位模块不会启动，/slam/lidar_odom 不会有数据发布。

话题名称	数据类型	描述	QoS	频率
`/integrated_command`	`std_msgs/String`	发布重定位控制指令	`RELIABLE`+`TRANSIENT_LOCAL`	用户发送（按需）
`/relocalization_pose`	`geometry_msgs/Pose`	发布机器人初始位姿估计	`BEST_EFFORT`+`VOLATILE`	用户发送（按需）
`/slam/lidar_odom`	`nav_msgs/Odometry`	订阅激光定位结果（`frame_id` 为 `map`，`child_frame_id` 为 `torso_link`，表示机器人在全局地图中的位姿）	`RELIABLE`+`TRANSIENT_LOCAL`	10Hz

重定位指令格式：

指令	说明
`start_relocalization:<map_id>`	开始重定位，`<map_id>` 为目标地图 ID（可通过手机 APP 查看，或从 `map.db` 的 `map` 表 `map_id` 字段获取）

操作流程：

向 /integrated_command 发布 start_relocalization:<map_id> 指令
延迟约 1 秒后向 /relocalization_pose 发布机器人的初始位姿估计（建议从地图构建的起始点开始）
订阅 /slam/lidar_odom，收到数据表示重定位成功

注意： /relocalization_pose 中使用的坐标为像素坐标，可从地图信息文件中获取。地图信息文件路径为： /agibot/data/var/MapManagerModule/<map_id>/grid_map_info.txt

该文件包含三行：

第一行：分辨率（1m 对应 20 个 pixel）

第二行：地图起点坐标（建图原点的像素坐标），即重定位时可使用的初始位姿

第三行：图像长宽（pixel）

地图标识与坐标的获取

调用地图获取、重定位、导航接口时常用的参数，获取方式如下：

map_id（重定位、导航必填）与 map_name（GetStoredMapByName 按名取图用）：通过手机 APP 查看，或在机器人上查询地图数据库，从结果中读取对应的 map_id / map_name 字段：
```
sqlite3 /agibot/data/var/MapManagerModule/map.db "SELECT * FROM map;"
```
坐标：
- 重定位初始位姿（/relocalization_pose）使用像素坐标，取 grid_map_info.txt（见上文「重定位」说明）第 2 行的建图原点 origin，其中 origin.u 对应 position.x、origin.v 对应 position.y。
- 导航目标点（target_pose）使用米制 Map 世界坐标，与像素坐标不同，像素到米制的换算见导航接口的坐标转换。

编程示例

详细的编程示例和代码说明请参考：

Python 示例（建图）：地图构建
Python 示例（重定位）：使用地图进行重定位
Python 示例（地图获取）：获取已存储的地图
C++ 示例（建图）：地图构建
C++ 示例（重定位）：使用地图进行重定位
C++ 示例（地图获取）：获取已存储的地图

小心

ROS的服务(service)机制在跨板通信时存在一些待优化问题, 二次开发时请参考例程添加异常处理、快速重试等保护机制

机器人处于稳定站立 / 走跑模式时, 请勿批量快速启动 ROS 节点(建议不超过 2 个/秒), 短时间内大量节点参与 DDS 发现会造成通信拥塞、影响运控实时性, 存在机器人失稳摔倒风险