# LIO-SAM
**Repository Path**: john_robert/LIO-SAM
## Basic Information
- **Project Name**: LIO-SAM
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: BSD-3-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-30
- **Last Updated**: 2026-07-30
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# LIO-SAM
**实时激光雷达-惯性里程计软件包。强烈建议用户仔细阅读本文档，并先使用提供的数据集进行测试。方法演示视频见 [YouTube](https://www.youtube.com/watch?v=A0H8CoORZJU)。**
[English](./README.md) | 中文
## 目录
- [**系统架构**](#系统架构)
- [**ROS2 分支说明**](#ros2-分支说明)
- [**依赖项**](#依赖项)
- [**安装**](#安装)
- [**使用 Docker**](#使用-docker)
- [**准备激光雷达数据**](#准备激光雷达数据)（必读）
- [**准备 IMU 数据**](#准备-imu-数据)（必读）
- [**示例数据集**](#示例数据集)
- [**运行软件包**](#运行软件包)
- [**其他说明**](#其他说明)
- [**常见问题**](#常见问题)
- [**论文**](#论文)
- [**待办事项**](#待办事项)
- [**相关软件包**](#相关软件包)
- [**致谢**](#致谢)
## 系统架构
我们设计了一套维护两张因子图的系统，运行速度最高可达实时的 10 倍。
- `mapOptimization.cpp` 中的因子图用于优化激光雷达里程计因子和 GPS 因子。该因子图在整个测试过程中持续维护。
- `imuPreintegration.cpp` 中的因子图用于优化 IMU 与激光雷达里程计因子，并估计 IMU 偏差。该因子图会周期性重置，以保证以 IMU 频率进行实时里程计估计。
## ROS2 分支说明
原版 ROS1 版本中的部分功能目前在本 ROS2 版本中尚不可用，包括：
- 使用 Velodyne、Livox 激光雷达以及 Microstrain IMU 的测试
- navsat 模块 / GPS 因子的 launch 文件
- rviz2 配置缺少许多元素
本分支已使用 Ouster 激光雷达、Xsens IMU 以及 SBG-Systems IMU，配合以下 ROS2 驱动进行测试：
- [ros2_ouster_drivers](https://github.com/ros-drivers/ros2_ouster_drivers)
- [bluespace_ai_xsens_ros_mti_driver](https://github.com/bluespace-ai/bluespace_ai_xsens_ros_mti_driver)
- [sbg_ros2_driver](https://github.com/SBG-Systems/sbg_ros2_driver)
在这些测试中，IMU 安装在激光雷达底部，使二者的 x 轴指向同一方向。`params.yaml` 中的参数 `extrinsicRot` 和 `extrinsicRPY` 对应这种安装配置。
## 依赖项
已在 Ubuntu 20.04 的 ROS2 foxy、galactic，以及 Ubuntu 22.04 的 humble 上测试通过。
- [ROS2](https://docs.ros.org/en/humble/Installation.html)
```
sudo apt install ros--perception-pcl \
ros--pcl-msgs \
ros--vision-opencv \
ros--xacro
```
- [gtsam](https://gtsam.org/get_started)（Georgia Tech Smoothing and Mapping 库）
```
# 添加 GTSAM-PPA
sudo add-apt-repository ppa:borglab/gtsam-release-4.1
sudo apt install libgtsam-dev libgtsam-unstable-dev
```
## 安装
使用以下命令下载并编译本软件包。
```
cd ~/ros2_ws/src
git clone https://github.com/TixiaoShan/LIO-SAM.git
cd LIO-SAM
git checkout ros2
cd ..
colcon build
```
## 使用 Docker
构建镜像（基于 ROS2 Humble）：
```
docker build -t liosam-humble-jammy .
```
镜像构建完成后，可通过以下任一方式启动容器：
1. `docker run`
```
docker run --init -it -d \
--name liosam-humble-jammy-container \
-v /etc/localtime:/etc/localtime:ro \
-v /etc/timezone:/etc/timezone:ro \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-e DISPLAY=$DISPLAY \
--runtime=nvidia --gpus all \
liosam-humble-jammy \
bash
```
2. `docker compose`
启动 docker compose 容器：
```
docker compose up -d
```
停止 docker compose 容器：
```
docker compose down
```
进入正在运行的容器：
```
docker exec -it liosam-humble-jammy-container bash
```
## 准备激光雷达数据
用户需要按正确格式准备点云数据，以便进行点云去畸变（主要在 `imageProjection.cpp` 中完成）。有两项要求：
- **提供点的时间戳**。LIO-SAM 使用 IMU 数据对点云进行去畸变，因此需要知道一帧扫描中各点的相对时间。最新的 Velodyne ROS 驱动应能直接输出该信息。此处假设点时间通道名为 `time`。点类型定义位于 `imageProjection.cpp` 文件顶部。`deskewPoint()` 函数利用该相对时间，得到该点相对于扫描起始时刻的变换。当激光雷达以 10Hz 旋转时，点的时间戳应在 0 到 0.1 秒之间变化。若使用其他激光雷达，可能需要修改该时间通道名称，并确保其为扫描内的相对时间。
- **提供点的 ring 编号**。LIO-SAM 用该信息将点正确组织到矩阵中。ring 编号表示该点所属传感器通道。点类型定义同样位于 `imageProjection.cpp` 文件顶部。最新的 Velodyne ROS 驱动应能直接输出该信息。若使用其他激光雷达，可能需要重命名该字段。注意：目前本软件包仅支持机械式激光雷达。
## 准备 IMU 数据
- **IMU 要求**。与原始 LOAM 实现类似，LIO-SAM 仅支持 9 轴 IMU（可提供 roll、pitch、yaw 估计）。roll 与 pitch 估计主要用于以正确姿态初始化系统；yaw 估计在使用 GPS 数据时用于以正确航向初始化系统。理论上，若采用类似 VINS-Mono 的初始化流程，LIO-SAM 也可配合 6 轴 IMU 工作。系统性能很大程度上取决于 IMU 测量质量。IMU 数据频率越高，系统精度越好。我们使用 Microstrain 3DM-GX5-25，输出频率为 500Hz。建议使用输出频率至少为 200Hz 的 IMU。注意：Ouster 激光雷达内置 IMU 为 6 轴 IMU。
- **IMU 对齐**。LIO-SAM 将 IMU 原始数据从 IMU 坐标系变换到激光雷达坐标系，后者遵循 ROS REP-105 约定（x 向前，y 向左，z 向上）。为使系统正常工作，需在 `params.yaml` 中提供正确的外参变换。**之所以有两个外参，是因为作者所用 IMU（Microstrain 3DM-GX5-25）的加速度与姿态使用了不同的坐标系。根据 IMU 厂商不同，你的两个外参可能相同，也可能不同。**
- `params.yaml` 中的 `extrinsicRot` 是将 IMU 陀螺仪与加速度计测量变换到激光雷达坐标系的旋转矩阵。
- `params.yaml` 中的 `extrinsicRPY` 是将 IMU 姿态变换到激光雷达坐标系的旋转矩阵。
- **IMU 调试**。强烈建议用户取消注释 `imageProjection.cpp` 中 `imuHandler()` 内的调试代码，并检查变换后的 IMU 数据输出。可通过旋转传感器套件，检查读数是否与传感器运动一致。展示校正后 IMU 数据的 YouTube 视频见[此处](https://youtu.be/BOUK8LYQhHs)。
## 示例数据集
出于隐私原因，目前无法提供适用于 ROS2 的数据集。
master 分支的 README.md 中包含一些 ROS1 rosbag 的链接。可通过 [ros1_bridge](https://github.com/ros2/ros1_bridge) 使用这些 rosbag，但请先验证时间行为（ROS2 中的消息频率）。同时请注意 [DDS 调优](https://docs.ros.org/en/humble/How-To-Guides/DDS-tuning.html)。
## 运行软件包
1. 运行 launch 文件：
```
ros2 launch lio_sam run.launch.py
```
2. 播放已有 bag 文件：
```
ros2 bag play your-bag.bag
```
## 保存地图
```
ros2 service call /lio_sam/save_map lio_sam/srv/SaveMap
```
```
ros2 service call /lio_sam/save_map lio_sam/srv/SaveMap "{resolution: 0.2, destination: /Downloads/service_LOAM}"
```
## 其他说明
- **回环检测：** 此处的回环功能为概念验证示例，直接改编自 LeGO-LOAM 的回环检测。更先进的回环检测实现请参考 [ScanContext](https://github.com/irapkaist/SC-LeGO-LOAM)。在 `params.yaml` 中将 `loopClosureEnableFlag` 设为 `true` 即可测试回环功能。在 Rviz 中取消勾选 "Map (cloud)"，勾选 "Map (global)"。因为可视化的 "Map (cloud)" 只是 Rviz 中点云的简单堆叠，位姿校正后其位置不会更新。此处回环功能改编自 LeGO-LOAM，是一种基于 ICP 的方法。由于 ICP 运行较慢，建议将回放速度设为 `-r 1`。可使用 Garden 数据集进行测试。
- **使用 GPS：** park 数据集用于测试 LIO-SAM 与 GPS 数据的配合，由 [Yewei Huang](https://robustfieldautonomylab.github.io/people.html) 采集。启用 GPS 功能时，将 `params.yaml` 中的 `gpsTopic` 改为 `odometry/gps`。在 Rviz 中取消勾选 "Map (cloud)"，勾选 "Map (global)"，并勾选 "Odom GPS" 以可视化 GPS 里程计。可通过 `gpsCovThreshold` 过滤较差的 GPS 读数；`poseCovThreshold` 用于调节向图中添加 GPS 因子的频率。例如，将 `poseCovThreshold` 设为 1.0 时，会看到轨迹被 GPS 持续校正。由于 iSAM 优化较重，建议回放速度为 `-r 1`。
- **KITTI：** 由于 LIO-SAM 需要高频 IMU 才能正常工作，测试需使用 KITTI raw 数据。一个尚未解决的问题是 IMU 内参未知，这对 LIO-SAM 精度有较大影响。下载提供的示例数据后，在 `params.yaml` 中做如下修改：
- extrinsicTrans: [-8.086759e-01, 3.195559e-01, -7.997231e-01]
- extrinsicRot: [9.999976e-01, 7.553071e-04, -2.035826e-03, -7.854027e-04, 9.998898e-01, -1.482298e-02, 2.024406e-03, 1.482454e-02, 9.998881e-01]
- extrinsicRPY: [9.999976e-01, 7.553071e-04, -2.035826e-03, -7.854027e-04, 9.998898e-01, -1.482298e-02, 2.024406e-03, 1.482454e-02, 9.998881e-01]
- N_SCAN: 64
- downsampleRate: 2 或 4
- loopClosureEnableFlag: true 或 false
- **Ouster 激光雷达：** 要使 LIO-SAM 配合 Ouster 激光雷达工作，需要在硬件和软件层面做一些准备。
- 硬件：
- 使用外部 IMU。LIO-SAM 无法配合 Ouster 激光雷达内置的 6 轴 IMU 工作。需要在激光雷达上外接 9 轴 IMU 并采集数据。
- 配置驱动。将 Ouster launch 文件中的 `timestamp_mode` 改为 `TIME_FROM_PTP_1588`，以便点云使用 ROS 格式时间戳。
- 配置：
- 将 `params.yaml` 中的 `sensor` 改为 `ouster`。
- 根据你的激光雷达修改 `params.yaml` 中的 `N_SCAN` 和 `Horizon_SCAN`，例如 N_SCAN=128，Horizon_SCAN=1024。
- 第一代与第二代 Ouster：
不同代际的点坐标定义可能不同。调试请参考 [Issue #94](https://github.com/TixiaoShan/LIO-SAM/issues/94)。
## 常见问题
- **锯齿或抖动行为**：若激光雷达与 IMU 数据格式符合 LIO-SAM 要求，该问题很可能由激光雷达与 IMU 时间戳不同步引起。
- **上下跳动**：若开始测试 bag 文件后 `base_link` 立即上下跳动，很可能是 IMU 外参错误。例如，重力加速度出现负值。
- **mapOptimization 崩溃**：通常由 GTSAM 引起。请安装 README.md 中指定的 GTSAM 版本。更多类似问题见[此处](https://github.com/TixiaoShan/LIO-SAM/issues)。
- **GPS 里程计不可用**：通常是因为消息 `frame_id` 与机器人 `frame_id` 之间缺少可用变换（例如：应从 `imu_frame_id`、`gps_frame_id` 到 `base_link` 有可用变换）。请阅读 Robot Localization 文档：[此处](http://docs.ros.org/en/melodic/api/robot_localization/html/preparing_sensor_data.html)。
## 论文
若使用本代码的任何部分，请引用 [LIO-SAM (IROS-2020)](./config/doc/paper.pdf)，谢谢。
```
@inproceedings{liosam2020shan,
title={LIO-SAM: Tightly-coupled Lidar Inertial Odometry via Smoothing and Mapping},
author={Shan, Tixiao and Englot, Brendan and Meyers, Drew and Wang, Wei and Ratti, Carlo and Rus Daniela},
booktitle={IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},
pages={5135-5142},
year={2020},
organization={IEEE}
}
```
部分代码改编自 [LeGO-LOAM](https://github.com/RobustFieldAutonomyLab/LeGO-LOAM)。
```
@inproceedings{legoloam2018shan,
title={LeGO-LOAM: Lightweight and Ground-Optimized Lidar Odometry and Mapping on Variable Terrain},
author={Shan, Tixiao and Englot, Brendan},
booktitle={IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},
pages={4758-4765},
year={2018},
organization={IEEE}
}
```
## 待办事项
- [ ] [imuPreintegration 中的 Bug](https://github.com/TixiaoShan/LIO-SAM/issues/104)
## 相关软件包
- [激光雷达-IMU 标定](https://github.com/chennuo0125-HIT/lidar_imu_calib)
- [带 Scan Context 的 LIO-SAM](https://github.com/gisbi-kim/SC-LIO-SAM)
## 致谢
- LIO-SAM 基于 LOAM（J. Zhang and S. Singh. LOAM: Lidar Odometry and Mapping in Real-time）。