建图开发示例

强制： 请使用DR02 Pro机器人执行本指南操作，DR02机器人不支持本指南中的操作。

概述

建图是指机器人在行走过程中，通过激光雷达等传感器实时采集周围环境数据，确定自身当前位姿并构建周围环境的地图。构建的地图可能有多种形式，如点云、栅格等，将会用于定位、路径规划等下游模块。

当前建图功能仅支持构建小面积（50m×50m）场景的点云和栅格地图。

建图路线规划

用户需提前规划好机器人的建图路线，确保路线：

构成回环，即在建图过程中重复访问已扫描过的区域，与历史轨迹形成交点或重合路段；
尽量先走小回环，后走大回环；
覆盖到整个任务区域。

推荐路线	不推荐路线
路线有交错，可构成回环覆盖到所有区域	路线没有交错，没有回环没有覆盖到所有区域

建图步骤

注意： 建图过程中避免大量人员来回走动或存在大体积的临时物体。

注意： 建图过程中请勿遮挡激光雷达，否则可能导致建图失败。

注意： 提前清理建图路线上的杂物并打开任务区域中的所有门。

启动建图程序前确保机器人静止站立；
SSH连接到导航主机NOS（或通过导航主机NOS的VNC远程桌面打开终端），并初始化ros2环境：
Terminal window
```
source /opt/robot/scripts/setup_ros2.sh
```
根据需要选择并输入对应的建图启动指令：
- 默认建图：采用小面积建图模式，地图默认命名为”map-[日期]-[时间]“，默认建图过程中开启RViz，建图完成后默认激活该地图使其用于定位导航：
  Terminal window
```
drmap mapping
```
- 指定地图名称：使用-n指令，并在-n后携带地图名称：
  Terminal window
```
drmap mapping -n xxx    # 通过-n指令，指定地图名为xxx
```
- 不开启Rviz：使用-s指令：
  Terminal window
```
drmap mapping -s
```
- 不立即激活地图：使用-B指令：
  Terminal window
```
drmap mapping -b
```
等待约3~5秒，出现提示”正在建图，Building map”时表示已经完成建图程序启动和初始化过程，并开始建图；
遥控机器人按预定建图路线平稳行走，请避免急加减速、急转弯或剧烈运动；
全程行走完毕后，打开终端输入指令 drmap stop_mapping，即可结束建图程序并开始后续处理，待终端打印内容提示建图结束后，即可关闭终端。

注意： 结束建图过程中出现卡顿现象，可多执行几次结束建图指令，使建图程序关闭，以顺利进行后续处理步骤。

地图文件夹和地图包

每次建图生成的地图包均为一个单独的文件夹，命名为[指定名称]-[日期]-[时间]，所有的地图包统一存放在地图文件夹/var/opt/robot/data/maps路径下。

地图文件夹下存在名为active的软链接，它指向的地图包处于激活状态，即该地图包会被用于定位导航规划。仅会有一个地图包处于激活状态。

注意： 每个地图包中均包含必要的所有数据，请参考**“地图包操作”**，通过drmap指令对地图包整体进行转移、备份、替换等操作，切勿单独修改替换其中的部分文件。

查看点云地图

打开终端输入下面的命令打开PCD viewer，查看建好的三维点云地图：

cd /var/opt/robot/data/maps/XXXX-XX-XXXXX #XXXX-XX-XXXXX为需要查看点云地图的所在文件夹
pcl_viewer full_cloud.pcd

PCD viewer基础操作：

滑动滚轮控制点云模型的缩放
拖拽左键控制点云模型的旋转
拖拽滑轮控制点云模型的平移
数字按键(1~5)选择点云模型的显示模式

栅格地图修改

若栅格地图不完全符合实际环境或需要人为划定可通行区域，可以使用GNU Image Manipulation Program（GIMP）对.pgm文件进行修图：

将DR02 导航主机（NOS）中需要修改的.pgm文件传输至开发者的开发主机上；
在开发者的开发主机上下载并安装GIMP；
右击传输至开发主机的 .pgm 文件，选择open with Other Application，然后选中GNU Image Manipulation Program，并点击Select键；
- 若GNU Image Manipulation Program未显示两侧的工具栏，可单击Tab键显示工具栏。
- 工具栏提供了前景色与背景色工具，前景色设置画笔工具的颜色，背景色设置橡皮擦工具的颜色。栅格地图中规定黑色为障碍物，即不可通行区域，白色为可通行区域，灰色为未知区域。您可以使用画笔工具或橡皮擦工具添加或擦除黑色区域。按住shift键后单击鼠标左键可画直线，按住ctrl键后单击鼠标左键可吸取颜色。
修改完成后在上方菜单栏选择File - Overwrite occ_grid.pgm对原文件进行覆盖（请勿选择 File - Save 保存），关闭该软件时会再次出现保存提示，此时点击Discard Changes即可；

注意： 如果有多张栅格地图，栅格地图的名称符合occ_grid__XXX_.pgm格式（其中_XXX_为地图编号），例如：occ_grid_3.pgm。请依次修改并保存多张栅格地图文件。
将修改完成的 .pgm 文件重新传输至导航主机（NOS）中对应的原始 .pgm 文件目录，并覆盖原有 .pgm 文件。

地图包操作

用户可在终端中执行drmap相关命令来对地图包整体进行打包、备份、复用等操作。命令输入支持TAB补全，也可通过命令加 -h选项查看命令基础用法。

压缩打包：将当前地图包压缩为zip包并备份至/home/user/Downloads文件夹下。
Terminal window
```
drmap pack
```

解压：将压缩打包后的地图包解压到/var/opt/robot/data/maps路径下。

drmap unpack [path_to_map_package]     # [path_to_map_package] 指要解压的地图zip包文件路径

激活：将需要使用的地图激活用于定位导航（地图默认存放在 /var/opt/robot/data/maps 路径下，激活后需重启生效）。
Terminal window
```
drmap apply [path_to_map_folder]     # [path_to_map_folder] 指要激活的地图包文件夹路径
```

初始化定位

初始化定位是指在机器人执行导航前或定位意外丢失后，确认机器人定位是否正确，并对机器人定位校正重置的过程。

打开终端运行下述指令，以打开RViz：

su
source /opt/ros/jazzy/setup.bash
export XAUTHORITY=/home/user/.Xauthority
rviz2

点击左上角”File-Open Config”，在弹窗中选择 /opt/robot/share/localization/conf 路径下的RViz 配置文件localization.rviz，以加载定位所需的数据；
检查实时点云与地图是否重合，如果不重合，需要参考下一步初始化机器人定位；
初始化或重置机器人定位：
- 点击顶部工具栏中的 2D Pose Estimate
- 确定机器人的实际位置和朝向，将鼠标移动到地图中的对应位置，按住左键并依照实际朝向拖拽出箭头，然后松开鼠标左键
- 若定位初始化成功，实时点云与地图会重合；若定位初始化失败，从第1步开始重新操作即可

地图坐标系与像素坐标系的转换

地图坐标系	像素坐标系

地图包中的配置文件occ_grid.yaml内包含了地图图像信息，用户可据此对地图坐标系和像素坐标系下的坐标信息进行换算：

image: /var/opt/robot/data/maps//map-20250802-151130/occ_grid.pgm
resolution: 0.1                   # 表示地图图像像素在实际地图中的物理长度Res(m)
origin: [-8.6, -11.2, 0.0]        # 前两个参数表示地图图像左下角在地图坐标系下的坐标[X0,Y0](m)
negate: 0
occupied_thresh: 0.65
free_thresh: 0.196

机器人在地图坐标系和像素坐标系中的位置坐标换算公式如下：

x_p = \frac{\text{Pos} X - X_0}{\text{Res}}

y_p = H - \frac{\text{Pos} Y - Y_0}{\text{Res}}

其中 $(x_p, y_p)$ 取整。

公式涉及的参数如下：

参数名称	参数含义
$(\operatorname{Pos} X, \operatorname{Pos} Y)$	地图坐标系下的坐标值
$(x_{p},y_{p})$	像素坐标系下的坐标值
$Res$	地图图像像素在实际地图中的物理长度，单位：米
$(X0,Y0)$	地图图像左下角在地图坐标系下的坐标，单位：米
$H$	地图图像高度包含的像素数（查看文件属性可获得）