Cartographer 安装与部署：编译、依赖与启动
二、安装与部署：编译、依赖与启动
先说一个关键前提：Cartographer 的 ROS 集成在 ROS 1（Melodic / Noetic）与 ROS 2 上是两套不同的包，配置文件的加载方式与启动文件写法都不同。ROS 1 时代用 cartographer_ros 加 Lua 配置，ROS 2 版本在参数名与 launch 写法上有调整。下面以 ROS 1 Noetic（Ubuntu 20.04）为主线说明，ROS 2 用户把 roslaunch 换成 ros2 launch、把 Lua 换成对应参数文件即可，具体差异以官方文档为准。
依赖分为编译期和运行期。编译期需要 CMake、g++、Eigen3、Google Ceres Solver、protobuf 3、Abseil（较新版本需要）、Lua 5.2 或 LuaJIT、以及 Boost。运行期的核心依赖是 cartographer_ros 与 cartographer_ros_msgs。Ceres 与 protobuf 的版本兼容是这套系统最大的坑，务必优先处理。
- 安装 ROS Noetic 基础环境。假设你已经装好 ROS，先确认环境变量可用：
source /opt/ros/noetic/setup.bash echo $ROS_DISTRO - 安装 Cartographer 的依赖。官方提供了一条 rosdep 与 apt 的组合路径：
sudo apt update sudo apt install -y cmake g++ git google-maps-geometry \ libboost-all-dev libcairo2-dev libceres-dev libeigen3-dev \ libgflags-dev libgoogle-glog-dev liblua5.2-dev libprotobuf-dev \ protobuf-compiler python3-sphinx libsuitesparse-dev libpcl-dev - 安装 cartographer 与 cartographer_ros。推荐用 ROS 包管理器直接装，版本匹配最省事：
需要改源码或追新特性时，才用sudo apt install -y ros-noetic-cartographer ros-noetic-cartographer-ros \ ros-noetic-cartographer-ros-msgswstool加rosdep从源码编译，那条路会同时编译 Ceres，耗时长且容易出现 protobuf 版本冲突。 - 验证安装。装好后应当能找到示例 launch 与 Lua 配置：
rospack find cartographer_ros ls $(rospack find cartographer_ros)/configuration_files - 跑官方示例数据集验证。示例包会订阅一个名为
bag_filename的参数：
终端里应当能看到子图完成的日志，RViz 里能看到逐渐长出来的栅格地图与实时位姿。roslaunch cartographer_ros demo_backpack_2d.launch \ bag_filename:=$HOME/Downloads/backpack_2d.bag - 保存地图。建图完成后不要直接关掉，用服务把状态序列化成 pbstream：
再把它转成 pgm 与 yaml 供导航使用：rosservice call /write_state "{filename: '$HOME/map.pbstream'}"rosrun cartographer_ros cartographer_pbstream_to_ros_map \ -pbstream_filename=$HOME/map.pbstream \ -map_filestem=$HOME/map
常见报错排查表。
| 报错现象 | 根因 | 处理方式 |
|---|---|---|
This program was compiled against version 3.x of the Protocol Buffer runtime library | 编译期 protobuf 与运行期 protobuf 版本不一致 | 统一版本；用 protoc --version 与 ldd 对比实际链接的库 |
Check failed: ... lua 或找不到 lua 文件 | Lua 配置路径不对，或 launch 里 configuration_directory 写错 | 检查 launch 中 configuration_basename 与实际文件名是否逐字一致 |
RViz 报 TF 外推错误 Lookup would require extrapolation into the future | 机器人 TF 发布时间与激光时间戳不同步 | 检查 IMU 与雷达的时间同步，或调整 TF 缓冲时长 |
| 地图整体旋转或明显错位 | 外参 tracking_frame 到 published_frame 的变换配置错误 | 核对 URDF 与 Lua 中的坐标系名称，确认旋转方向 |
| 回环检测一直不触发 | 门限过严或 optimize_every_n_nodes 太大 | 下调 constraint_builder.min_score，并减小优化间隔 |
| CPU 占用持续 100% 且地图更新卡顿 | 3D 模式体素分辨率过细，或 num_accumulated_range_data 过大 | 放大 voxel_filter_size，减少累积帧数 |
| 机器人快速旋转时地图撕裂 | 激光帧率不足，扫描匹配跟不上角速度 | 提高雷达帧率，或开启 IMU 辅助的旋转预测 |
传感器方面，2D 建图常用 RPLIDAR、Hokuyo、镭神等单线雷达，2D 模式对这些雷达的驱动兼容良好。3D 模式需要多线雷达（如 16 线、32 线），点云量与计算量按线数增长，务必先评估算力。里程计来源可以是轮式编码器，也可以是 IMU，Cartographer 会把它们作为初值喂给扫描匹配。如果两者都没有，也能跑，但在纯旋转或长直走廊里会明显变差。
