Cartographer 核心功能与关键配置项
三、核心功能与关键配置项
Cartographer 的能力集中在配置文件的参数体系里。Lua 配置文件是一个可执行的 Lua 脚本，最终 return 一个 options 表，所以可以在里面写条件分支和引用其他文件（例如 include "map_builder.lua"）。这是它比纯 YAML 灵活的地方，也是新手容易看不懂的原因。
| 配置分组 | 关键参数 | 作用 |
|---|---|---|
| map_builder | MAP_BUILDER.use_trajectory_builder_2d | 选择 2D 还是 3D 前端 |
| map_builder | MAP_BUILDER.num_background_threads | 后台线程数，影响回环与优化的吞吐 |
| 2D 前端 | TRAJECTORY_BUILDER_2D.min_range / max_range | 雷达有效距离，超出范围的读数被丢弃 |
| 2D 前端 | missing_data_ray_length | 超过 max_range 的读数按这个长度当成空闲处理 |
| 2D 前端 | num_accumulated_range_data | 累积多少帧才做一次匹配，多则稳但延迟大 |
| 2D 前端 | submaps.num_range_data | 一个子图包含多少帧，决定子图粒度 |
| 2D 前端 | voxel_filter_size | 点云降采样体素边长，直接影响计算量 |
| 运动滤波 | motion_filter.max_time_seconds / max_distance_meters / max_angle_radians | 满足任一条件才插入新节点，控制位姿图规模 |
| 扫描匹配 | real_time_correlative_scan_matcher.* | 快速粗匹配，给精配准提供初值 |
| 扫描匹配 | ceres_scan_matcher.occupied_space_weight 等 | 精配准中各残差项权重，调不好会过拟合 |
| 后端 | POSE_GRAPH.optimize_every_n_nodes | 每插入多少节点做一次全局优化 |
| 后端 | POSE_GRAPH.constraint_builder.min_score | 回环候选的最低匹配分，调低召回高误检多 |
| 后端 | constraint_builder.global_localization_min_score | 纯定位模式下的匹配门限 |
| 3D 前端 | TRAJECTORY_BUILDER_3D.voxel_filter_size / high_resolution_max_range | 3D 模式的体素与有效距离 |
调参的优先级建议按这个顺序。首先确认 min_range 与 max_range 与雷达实际指标一致，这是所有几何关系的基础，配错了后面怎么调都没用。其次调 motion_filter 三个门限：如果机器人跑得快，max_distance_meters 要调小否则节点太稀；如果在原地缓慢调整，max_angle_radians 要调小否则旋转丢失。第三是 submaps.num_range_data，室内小场景可以在几十的量级，大场景可以到上百。最后才是扫描匹配权重与回环门限，这两个改动影响面大，要一次只动一个并对比结果。
关于实时相关扫描匹配与 Ceres 精配准的分工，值得单独说明。前者是在一个搜索窗口内穷举候选位姿，找一个粗略最优解；后者是在这个初值附近做连续优化，把误差压到最小。所以 real_time_correlative_scan_matcher 的搜索窗口大小决定了系统能容忍多快的运动，如果机器人经常跑得比这个窗口覆盖的速度还快，就会出现跟踪丢失，表现为地图上出现一段错位的轨迹。
