2D 建图

2D 地图与导航总览

2D 地图与导航分成两个阶段：

1. 建图：使用 Gmapping 或 Cartographer，让 UGV 在环境中移动，并生成 2D 占据栅格地图。
2. 导航：加载已经保存的地图，让 UGV 在地图中定位、规划路径并移动到目标点。

建图阶段不会自动完成导航；Navigation 阶段也不是重新建图。保存后的 map.pgm 和 map.yaml 会在 Navigation 中被加载，用于定位和路径规划。

建图 launch
-> 键盘控制低速移动
-> RViz 中地图逐步出现
-> 保存 map.pgm + map.yaml
-> 打开 map.pgm 快速检查
-> 启动 Navigation
-> 设置 2D Pose Estimate
-> 设置 Nav2 Goal

2D 建图

Gmapping 和 Cartographer 都用于生成 2D 地图。第一轮实车 2D 建图优先使用 Gmapping，先把雷达、里程计、TF、RViz 地图显示和地图保存流程跑完整；熟悉 Gmapping 后，再测试 Cartographer。

建图质量要求与保存前检查

2D 地图会被后续 Navigation、保存导航点和自动探索继续使用。地图文件能保存成功，不代表地图适合导航。如果地图存在重影、错位、断墙、大片未知区域，或与当前测试场地不一致，后续会影响 AMCL、costmap、Nav2 Goal 和导航点任务。

建图时保持测试环境稳定：

• 不要在人、宠物、椅子、箱子频繁移动的环境中建图；
• 建图路线中的门、桌椅、障碍物位置应和后续 Navigation 测试时一致；
• 透明玻璃、镜面、黑色吸光物体、细桌脚和低矮线缆可能影响雷达扫描；
• 雷达前方不要被外壳、手、线缆或桌边遮挡；
• 地面应平整，避免轮子打滑；
• 建图过程中不要手动搬起或拖动 UGV。

建图路线不要只原地转圈，也不要快速移动。建议按下面方式采集：

1. 启动 SLAM 后先原地小幅左右转动，让地图开始出现；
2. 沿主要通道低速前进；
3. 在每个拐角处慢速转向；
4. 尽量走一个小闭环，最后回到起点附近；
5. 对后续要导航的区域至少扫描一遍；
6. 保存地图前让 UGV 停止，观察地图是否稳定。

注意

移动太快、频繁急转或轮子打滑时，地图容易出现重影、错位或墙体弯曲。这样的地图即使能保存，也不适合直接用于 Navigation。

保存地图前，先在 RViz 中检查：

• Map 显示项不再持续提示 No map received；
• 地图中主要墙体、桌边、通道边界轮廓连续；
• 没有明显双层墙、重影、弯曲走廊或整体错位；
• 后续要导航的区域不是大片灰色未知区域；
• LaserScan 彩色点段大致落在地图墙体或障碍物边缘附近；
• UGV 停止不动时，地图不会明显抖动或跳变。

如果以上观察点不满足，不要急着保存地图。先继续低速补扫，或停止当前 SLAM 后重新建图。

Gmapping 建图

1. 启动前准备。

   gmapping.launch.py 会启动底盘、雷达、里程计、robot_pose_publisher、slam_gmapping 和 RViz。使用 use_rviz:=true 时，会加载 2D 建图视图。

   启动前停止其它 ROS 2 终端

   启动 Gmapping 前，先停止之前用于底盘 bringup、RViz、键盘控制、手柄控制或其它 SLAM 测试的终端。Gmapping launch 会重新启动底盘、雷达、里程计、slam_gmapping 和 RViz。

   如果前面已经运行 bringup_lidar.launch.py use_rviz:=false，请先在对应终端按 Ctrl + C 停止，再启动 Gmapping，避免重复占用底盘串口、雷达或产生重复节点。

   启动 SLAM 前按 检查并释放底盘串口 检查底盘串口，并确认雷达连接和供电正常。

2. 启动 Gmapping。

   在新的 Docker ROS 2 终端中执行。

   cd /home/ws/ugv_ws
   source /opt/ros/humble/setup.bash
   source install/setup.bash
   
   export UGV_MODEL=ugv_rover
   export LDLIDAR_MODEL=ld19
   ros2 launch ugv_slam gmapping.launch.py use_rviz:=true

   该命令会启动底盘、雷达、里程计、Gmapping 和 RViz。启动后不要关闭这个 Gmapping 终端。

   

   终端会输出 ldlidar communication is normal、Got first Laser Scan、slam_gmapping 的 Initialization complete 和 Registering Scans:Done。这些日志表示雷达数据已经进入 Gmapping，建图节点正在处理扫描数据。

   提示

   RViz 刚打开时，Map 可能显示 Status: Warn 和 No map received。这表示 RViz 还没有收到 Gmapping 发布的 /map 地图数据，不代表雷达或 Gmapping 已经停止。

   启动后先等待 10 ~ 30 秒。Gmapping 完成初始化后，地图有时会自动出现。如果等待后仍然只看到 LaserScan 彩色点段，没有灰、白、黑的栅格地图，再使用键盘控制让 UGV 低速转向或短距离移动。

   

3. 用键盘控制低速建图。

   保持 Gmapping 终端运行。另开一个 Docker ROS 2 终端运行键盘控制。

   cd /home/ws/ugv_ws
   source /opt/ros/humble/setup.bash
   source install/setup.bash
   
   ros2 run ugv_tools keyboard_ctrl

   按键如下。

   按键	动作
   I	前进
   ,	后退
   J	左转
   L	右转
   K 或空格	停止
   Ctrl + C	退出键盘控制

   先原地小幅转向，再短距离前进或后退，让雷达扫描覆盖周围环境。每次移动后按 K 或空格停止。不要长时间持续按方向键。

4. 保存地图。

   保存地图前，先按 建图质量要求与保存前检查 检查 RViz 中的地图质量，并确认已经出现灰、白、黑的栅格地图，Map 显示项不再提示 No map received。

   1. 保持 Gmapping launch 继续运行。
   2. 在键盘控制终端按 K 或空格停止底盘，再按 Ctrl + C 退出键盘控制。
   3. 新开一个保存终端，执行保存脚本。

   cd /home/ws/ugv_ws
   chmod +x ./save_2d_gmapping_map.sh
   ./save_2d_gmapping_map.sh

   如果提示 Permission denied，表示脚本没有执行权限，不表示 Gmapping 建图失败，也不表示地图数据错误。已经执行过 chmod +x 后仍无法运行时，可以改用下面命令。

   bash ./save_2d_gmapping_map.sh

   4. 看到 Writing map occupancy data、Writing map metadata、Map saved successfully 后，确认 map.pgm 和 map.yaml 已生成。
   5. 回到 Gmapping 终端按 Ctrl + C 退出。

   

   日志中出现 Received a 384 X 384 map @ 0.05 m/pix 时，表示保存到的地图尺寸为 384 x 384 像素，分辨率为 0.05 m/pix，也就是每个像素约 5 cm。地图像素尺寸不等于实际场地尺寸。

Cartographer 建图

1. Cartographer 和 Gmapping 的区别。

   Gmapping 和 Cartographer 都是 2D 建图方法，目的都是让 UGV 利用雷达、里程计和 TF 生成环境地图。对常规使用流程来说，最终重点是得到可用于 Navigation 的 map.pgm 和 map.yaml。

   先使用 Gmapping 完成第一轮实车建图。Gmapping 流程更直接，适合先确认雷达、里程计、TF、地图保存和 Navigation 是否能跑通。Cartographer 可作为进阶建图方案；它除了导出 map.pgm 和 map.yaml，保存脚本还会生成 Cartographer 内部状态文件，例如 map.pbstream。

   对比项	Gmapping	Cartographer
   主要用途	快速完成第一张 2D 地图，验证雷达、里程计、TF 和地图保存流程	作为另一种 2D 建图方案，适合在熟悉基础流程后进一步测试
   建图结果	主要得到 map.pgm 和 map.yaml	通常也会得到 map.pgm 和 map.yaml，并生成 map.pbstream
   文件怎么理解	map.pgm 是地图图片，map.yaml 是地图参数；后续 Navigation 主要加载这两个文件	map.pgm 和 map.yaml 同样可用于 Navigation；map.pbstream 是 Cartographer 的内部状态文件，用于 Cartographer 相关流程
   学习顺序	第一轮实车建图优先使用	跑通 Gmapping 和 Navigation 后再测试
   使用建议	适合写成主线流程	适合作为进阶建图方案，不需要一开始就使用

2. 启动 Cartographer。 Cartographer launch 也会占用底盘、雷达和相关 SLAM 资源。启动前先停止其它 bringup、Gmapping、Navigation 或键盘控制终端。

   cd /home/ws/ugv_ws
   source /opt/ros/humble/setup.bash
   source install/setup.bash
   
   export UGV_MODEL=ugv_rover
   export LDLIDAR_MODEL=ld19
   ros2 launch ugv_slam cartographer.launch.py use_rviz:=true

   启动后不要关闭当前 Cartographer 终端。

3. 用键盘控制低速建图。 保持 Cartographer 终端运行。另开 Docker ROS 2 终端运行键盘控制。

   cd /home/ws/ugv_ws
   source /opt/ros/humble/setup.bash
   source install/setup.bash
   
   ros2 run ugv_tools keyboard_ctrl

   按 J / L 小幅转向，再用 I / , 短距离移动。每次动作后按 K 或空格停止。

4. 保存地图。 保存前先按 建图质量要求与保存前检查 检查 RViz 中的地图质量，再停止键盘控制底盘运动，但保持 Cartographer launch 运行。

   cd /home/ws/ugv_ws
   chmod +x ./save_2d_cartographer_map.sh
   ./save_2d_cartographer_map.sh

   如果提示 Permission denied，可以用 bash 执行。

   cd /home/ws/ugv_ws
   bash ./save_2d_cartographer_map.sh

   地图会保存到以下目录。

   /home/ws/ugv_ws/src/ugv_main/ugv_nav/maps/

   保存完成后再回到 Cartographer 终端按 Ctrl + C 退出。

   RViz 中可以看到地图逐步更新。使用键盘控制移动时，地图范围会逐步扩展。保存后会生成或更新 map.pgm、map.yaml 和 map.pbstream。Cartographer 建图完成后仍需进入 Navigation 才能使用地图导航。

查看保存的地图文件

Gmapping 和 Cartographer 保存后的地图默认位于以下路径：

/home/ws/ugv_ws/src/ugv_main/ugv_nav/maps/map.pgm
/home/ws/ugv_ws/src/ugv_main/ugv_nav/maps/map.yaml

在 Docker ROS 2 终端中执行下面命令检查文件。

cd /home/ws/ugv_ws

ls -lh src/ugv_main/ugv_nav/maps/map.pgm \
       src/ugv_main/ugv_nav/maps/map.yaml

cat src/ugv_main/ugv_nav/maps/map.yaml

map.pgm 是地图图片，map.yaml 是地图参数文件。后续 Navigation 会根据 map.yaml 找到 map.pgm，并按照其中的分辨率、原点和阈值解释地图。如果 ls 能看到 map.pgm 和 map.yaml，且文件大小不是 0，说明地图文件已经生成。cat map.yaml 用于确认地图图片路径、分辨率和原点等信息是否存在。

保存地图后，不只检查 map.pgm 和 map.yaml 是否存在，还要打开 map.pgm 快速查看地图质量。文件能保存成功，不等于地图可以用于 Navigation。

在 MobaXterm 左侧文件栏中进入以下目录。

/home/ws/ugv_ws/src/ugv_main/ugv_nav/maps/

下载 map.pgm 和 map.yaml。如果左侧文件栏没有立即显示新文件，点击刷新按钮，或重新勾选 Follow terminal folder 后进入上述目录。

打开 map.pgm 快速检查。 map.pgm 可以作为图片直接打开，用于快速检查地图轮廓。

PGM 地图不是照片，也不是 RViz 截图，而是 2D 占据栅格地图。它通常由灰、白、黑三类颜色组成。

颜色	含义
灰色	未知区域，机器人还没有可靠扫描到
白色	可通行区域，雷达认为这里没有障碍
黑色	障碍物边缘，例如墙、桌脚、箱子或其它物体轮廓

判断地图是否适合进入 Navigation 时，重点看以下内容：

检查项	可用于 Navigation 的表现	不建议用于 Navigation 的表现
墙体轮廓	连续、清楚	双层墙、断裂、明显重影
通道区域	白色区域连贯	通道中间大片黑色或灰色
未知区域	不影响计划导航路线	目标点附近大片灰色未知区域
地图比例	与实际场地大致一致	房间、走廊或障碍轮廓被拉伸、旋转或错位
起点附近	清楚可辨认	起点附近混乱或被障碍覆盖

如果更换了测试房间、桌椅位置变化较大、门的开闭状态不同，或地图与当前环境明显不一致，应重新建图。