LIO-SAM Documentation

To run LIO-SAM with a launch file and play back a ROS bag:

1. Launch the package:

roslaunch lio_sam run.launch

2. Play your bag file (using a playback speed of 3x as an example):

rosbag play your-bag.bag -r 3

Lidar data must be formatted correctly for cloud deskewing (handled in imageProjection.cpp). The following two requirements must be met:

• Point Timestamp: You must provide a relative point timestamp within a scan. LIO-SAM uses this to perform deskewing via IMU data. For a 10Hz lidar, the timestamp should vary between 0 and 0.1 seconds. If your sensor uses a different channel name, you must update the code to match. The default expected channel name is time.
• Point Ring Number: You must provide a ring number indicating the sensor channel for each point. This is used to organize points in a matrix.

Note: Currently, only mechanical lidars are supported.

To enable GPS functionality using the Park dataset or similar GPS-enabled data:

1. In params.yaml, set gpsTopic to odometry/gps.
2. In Rviz, uncheck Map (cloud) and check Map (global) and Odom GPS to visualize the GPS odometry.
3. Adjust gpsCovThreshold to filter out poor GPS readings.
4. Adjust poseCovThreshold to control the frequency of adding GPS factors to the graph (e.g., setting it to 1.0 will cause frequent trajectory corrections).

Note: Due to heavy iSAM optimization, it is recommended to use a playback speed of -r 1.

To use Ouster lidar, follow these hardware and software requirements:

Hardware

• External IMU Required: LIO-SAM does not work with the internal 6-axis IMU of Ouster lidars. You must attach a 9-axis IMU to the lidar.

Software/Driver

• Timestamp Mode: In your Ouster launch file, set timestamp_mode to TIME_FROM_PTP_1588 to ensure ROS-compatible timestamps for point clouds.

LIO-SAM Configuration (params.yaml)

• Set sensor to ouster.
• Set N_SCAN and Horizon_SCAN according to your specific model (e.g., N_SCAN=128, Horizon_SCAN=1024).

LIO-SAM includes a proof-of-concept loop closure function adapted from LeGO-LOAM. To use it:

1. Set loopClosureEnableFlag to true in params.yaml.
2. In Rviz, uncheck Map (cloud) and check Map (global) to see the updated map after pose correction (the Map (cloud) visualization is a simple stack of point clouds and does not update after correction).

Note: Because the ICP-based loop closure is computationally expensive, it is recommended to set the rosbag playback speed to -r 1.

For more advanced implementations, consider using ScanContext.

To install LIO-SAM, ensure you have ROS (tested with Kinetic and Melodic) and the GTSAM library installed. Follow these steps to download and compile the package in your catkin workspace:

1. Install ROS navigation and localization dependencies:

sudo apt-get install -y ros-kinetic-navigation
sudo apt-get install -y ros-kinetic-robot-localization
sudo apt-get install -y ros-kinetic-robot-state-publisher

2. Install GTSAM (Georgia Tech Smoothing and Mapping library):

sudo add-apt-repository ppa:borglab/gtsam-release-4.0
sudo apt install libgtsam-dev libgtsam-unstable-dev

3. Clone and build the package:

cd ~/catkin_ws/src
git clone https://github.com/TixiaoShan/LIO-SAM.git
cd ..
catkin_make

LIO-SAM requires a 9-axis IMU (providing roll, pitch, and yaw) for optimal performance. A minimum output rate of 200Hz is recommended.

IMU Alignment and Extrinsics

LIO-SAM transforms IMU data to the Lidar frame following the ROS REP-105 convention (x-forward, y-left, z-up). You must configure the following in config/params.yaml:

• extrinsicRot: The rotation required to transform IMU acceleration and attitude to the lidar frame.
• extrinsicRPY: The rotation from lidar to IMU (q_lb). Note that if acceleration and attitude have the same coordinate system, this may be the same as extrinsicRot.

Debugging

To verify your IMU transformation, it is highly recommended to uncomment the debug lines in imuHandler() within imageProjection.cpp. Rotate the sensor suite and ensure the transformed readings correspond correctly to the physical movement.

If you prefer using Docker, you can build and run a container based on ROS1 Kinetic.

1. Build the image:

docker build -t liosam-kinetic-xenial .

2. Run the container with X11 forwarding and local time synchronization:

docker run --init -it -d \
  -v /etc/localtime:/etc/localtime:ro \
  -v /etc/timezone:/etc/timezone:ro \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -e DISPLAY=$DISPLAY \
  liosam-kinetic-xenial \
  bash

LIO-SAM support for solid-state lidars like Livox Horizon is based on minimal codebase changes and requires an external IMU.

Requirements

• External IMU: Do not use the internal IMU.
• Driver: Use a customized livox_ros_driver to publish point clouds in a format LIO-SAM can process.

LIO-SAM Configuration (params.yaml)

• sensor: livox
• N_SCAN: 6
• Horizon_SCAN: 4000
• edgeFeatureMinValidNum: 1

LIO-SAM requires a high-frequency IMU. When using KITTI raw data, you must update params.yaml with the following specific values to account for unknown IMU intrinsics:

• 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 or 4
• loopClosureEnableFlag: true or false

Common Issues

• Zigzag or jerking behavior: Likely caused by un-synced timestamps between lidar and IMU data.
• Jumping up and down: Likely caused by incorrect IMU extrinsics (e.g., gravity acceleration has a negative value).
• mapOptimization crash: Usually caused by GTSAM. Ensure you have installed the specific GTSAM version mentioned in the main README.
• gps odometry unavailable: Likely due to missing transforms between message frame_ids and the robot frame_id. Ensure transforms exist from imu_frame_id and gps_frame_id to base_link.