3、SLAM Toolbox实战：配置与启动、在线建图、地图保存与加载

说到SLAM Toolbox，我得先坦白一件事。早些年我做机器人建图，用的还是GMapping那一套老古董。后来换了SLAM Toolbox，第一次跑起来的时候，我盯着终端愣了好几秒——这玩意儿怎么这么快？

说白了，SLAM Toolbox是当前ROS2生态里最成熟的2D SLAM方案。它不像Cartographer那样配置复杂到让人想摔键盘，也不像GMapping那样在回环检测上基本靠运气。它把在线建图、定位、地图序列化这些事，打包成了一个干净利落的工具包。

3.1 核心架构与节点关系

我们先看看它的骨架长什么样。我习惯在动手配置前，先把架构图在脑子里过一遍，这样后面出问题了也知道去哪找原因。

看到这张图你就明白了。slam_toolbox节点吃进激光数据和里程计，吐出地图和位姿。它内部维护了一个位姿图（Pose Graph），每次新的激光帧进来，就做一次扫描匹配，然后更新图结构。回环检测？那是它自己后台默默干的事。

3.2 配置文件详解

配置SLAM Toolbox，核心就是搞定一个YAML文件。我见过太多人直接复制网上的配置就跑，结果地图建出来歪歪扭扭的。嗯，这里要注意，参数得根据你的传感器和场景来调。

下面是我在一个仓储AGV项目里用过的配置，经过实战检验的：

# slam_toolbox_params.yaml
slam_toolbox:
  ros__parameters:
    # 核心参数
    use_sim_time: false
    mode: mapping  # mapping | localization | localization_and_mapping
    
    # 激光雷达参数
    laser_min_distance: 0.2
    laser_max_distance: 12.0
    minimum_travel_distance: 0.1
    minimum_travel_heading: 0.2
    
    # 扫描匹配
    correlation_search_space_dimension: 0.5
    correlation_search_space_resolution: 0.01
    correlation_search_space_smear_deviation: 0.02
    
    # 回环检测
    loop_search_maximum_distance: 3.0
    loop_search_minimum_distance: 0.5
    loop_search_maximum_time: 30.0
    
    # 地图参数
    map_resolution: 0.05
    map_size: 100.0
    map_start_x: 0.0
    map_start_y: 0.0
    map_start_theta: 0.0
    
    # 可视化
    visualize_tree: true
    visualize_pose_graph: false

关键参数解读：

mode：建图阶段用 mapping，纯定位用 localization。我建议第一次跑先用 mapping。
correlation_search_space_dimension：搜索窗口大小。环境空旷可以设大点，比如0.8；走廊环境0.3就够了。
loop_search_maximum_distance：回环检测的搜索半径。仓库这种大场景我设到5.0米。
map_resolution：0.05米是平衡精度和性能的好选择。0.025米太费内存，0.1米又太粗糙。

我的经验：如果你发现建图时地图频繁抖动，先别急着调回环参数。检查一下激光雷达的安装角度和tf树是否正确。我曾经花了两天调参数，最后发现是激光的安装偏了2度——那感觉，就像修了半天电脑发现没插电源。

3.3 启动文件编写

配置写好了，怎么启动？我习惯用launch文件来管理，这样参数、节点、生命周期都一目了然。

# slam_toolbox_launch.py
import os
from ament_index_python.packages import get_package_share_directory
from launch import LaunchDescription
from launch.actions import DeclareLaunchArgument
from launch.substitutions import LaunchConfiguration
from launch_ros.actions import Node

def generate_launch_description():
    # 参数文件路径
    params_file = os.path.join(
        get_package_share_directory('my_robot_bringup'),
        'config',
        'slam_toolbox_params.yaml'
    )
    
    # 声明参数
    use_sim_time = LaunchConfiguration('use_sim_time', default='false')
    
    # SLAM Toolbox节点
    slam_toolbox_node = Node(
        package='slam_toolbox',
        executable='async_slam_toolbox_node',
        name='slam_toolbox',
        output='screen',
        parameters=[params_file, {'use_sim_time': use_sim_time}]
    )
    
    return LaunchDescription([
        DeclareLaunchArgument(
            'use_sim_time',
            default_value='false',
            description='Use simulation time'
        ),
        slam_toolbox_node
    ])

启动命令很简单：

ros2 launch my_robot_bringup slam_toolbox_launch.py

注意：启动前务必确认tf树已经完整。SLAM Toolbox需要以下变换：

map → odom（由SLAM节点发布）
odom → base_link（由里程计提供）
base_link → laser_frame（由机器人模型提供）

缺一个变换，节点就会报"Waiting for transform..."然后卡住不动。我刚开始用的时候被这个坑了整整一个下午。

3.4 在线建图实战

启动之后，你会看到终端里刷刷刷地打印信息。这时候打开RViz，添加Map和LaserScan显示，就能看到地图在慢慢生长了。

在线建图的核心操作就三步：

遥控机器人走一遍环境——速度别太快，0.3-0.5 m/s比较合适。太快了扫描匹配容易跟丢。
注意回环——走到之前去过的地方时，放慢速度，让算法有时间检测回环。你会看到地图突然"咔"一下对齐了，那感觉挺爽的。
观察地图质量——如果出现重影或者错位，说明回环检测没做好。可以手动触发一次回环优化。

手动触发回环优化的命令：

ros2 service call /slam_toolbox/manual_loop_closure slam_toolbox/srv/LoopClosure "{}"

一个小技巧：建图时把RViz的显示频率调低一点，比如5Hz。不然地图更新太快，你的眼睛跟不上，反而觉得地图在闪。我一般建图时只看scan和map两个topic，其他都关掉，保持界面清爽。

3.5 地图保存与加载

地图建好了，得存下来。SLAM Toolbox提供了两种保存方式，我分别说说。

3.5.1 保存地图

方式一：通过服务调用（推荐）

ros2 service call /slam_toolbox/save_map slam_toolbox/srv/SaveMap "{name: {data: 'my_map'}}"

这会在当前目录生成两个文件：my_map.yaml 和 my_map.pgm。YAML文件里记录了地图的元信息，PGM是灰度图。

方式二：通过命令行工具

ros2 run nav2_map_server map_saver_cli -f my_map

这个方式不依赖SLAM Toolbox的服务，直接从/map话题保存。但有个缺点——它保存的是当前发布的地图快照，如果地图还在更新中，可能不是最终版本。

3.5.2 加载地图

加载地图用于后续的定位或导航。有两种场景：

场景一：加载到SLAM Toolbox继续建图

ros2 service call /slam_toolbox/deserialize_map slam_toolbox/srv/DeserializeMap "{filename: 'my_map'}"

这个操作会把之前保存的地图加载回SLAM Toolbox，你可以继续在上面建图。注意，加载后之前的地图会被覆盖，所以操作前确认一下。

场景二：加载到map_server用于导航

ros2 run nav2_map_server map_server my_map.yaml

然后在另一个终端启动生命周期：

ros2 lifecycle set /map_server configure
ros2 lifecycle set /map_server activate

地图文件结构示例（my_map.yaml）：

image: my_map.pgm
resolution: 0.050000
origin: [-10.000000, -10.000000, 0.000000]
negate: 0
occupied_thresh: 0.65
free_thresh: 0.196

参数说明：

image：PGM图片路径，可以是相对路径或路径
resolution：每像素代表的米数
origin：地图左下角在map坐标系下的位置 [x, y, yaw]
occupied_thresh：像素值高于此阈值视为障碍物
free_thresh：像素值低于此阈值视为自由空间

避坑指南：我曾经在保存地图时犯过一个低级错误——工作目录不对。服务调用保存地图时，文件会保存在你执行命令的那个目录下。如果你在根目录执行，地图就存到根目录去了。下次加载时路径对不上，就会报"Failed to open file"。所以，养成好习惯：先cd到你的地图目录，再执行保存命令。

3.6 常见问题与调试

问题现象	可能原因	解决方案
地图出现重影	回环检测未触发或参数不合适	增大 loop_search_maximum_distance，或手动触发回环
建图时地图抖动	激光数据噪声大或里程计不准	检查激光雷达，增加 minimum_travel_distance
保存地图失败	目录权限或路径问题	检查当前目录是否有写入权限，使用路径
加载地图后定位不准	初始位姿偏差太大	使用2D Pose Estimate设置初始位姿

嗯，说到调试，我还有一个心得。如果你发现地图建出来边界不清晰，可以试试把激光的laser_max_distance设小一点。比如室内环境设到8米就够了，太远的点噪声大，反而影响匹配精度。

SLAM Toolbox其实是个很成熟的工具，只要你把参数调对了，它很少出幺蛾子。我个人的建议是：第一次用的时候，先拿仿真环境跑一遍，把每个参数的效果都摸清楚。这样真车上手的时候，心里就有底了。