lidar_localization_ros2

Map-based 3D LiDAR localization for ROS 2 and Nav2.

Explore the complete Koide indoor/outdoor GIF gallery →

Features

• NDT/GICP localization against .pcd and .ply maps
• standalone, Nav2, and Livox MID-360 launch configurations
• odometry/IMU prediction, scan deskew, diagnostics, and guarded recovery
• rosbag demo and regression tools

ROS 2 Jazzy with NDT_OMP is the recommended starting point. Continuous-time deskew is enabled by default and safely leaves scans unchanged until point timing and motion data are ready. Guarded global initialization is enabled automatically when quickstart is given a matching occupancy map. See v1 status for validated scope and limitations.

Install

mkdir -p ~/lidarloc_ws/src
cd ~/lidarloc_ws/src
git clone https://github.com/rsasaki0109/lidar_localization_ros2.git
cd lidar_localization_ros2
scripts/bootstrap_colcon_workspace.sh --build
source ~/lidarloc_ws/install/setup.bash

For manual builds and no-sudo setup, see local build.

Quick Start

Start localization and RViz with one command:

ros2 run lidar_localization_ros2 quickstart.py \
  --profile standalone \
  --map /absolute/path/to/map.pcd

Quickstart detects unambiguous sensor topics, generates a reusable configuration, restores only a pose saved against the same map, and verifies tracking. Add the matching occupancy map or a mapping-run reference CSV for guarded global initialization with 3D NDT scoring:

ros2 run lidar_localization_ros2 quickstart.py \
  --profile mid360 \
  --map /absolute/path/to/map.pcd \
  --occupancy-map /absolute/path/to/map.yaml

Known routes (avoids map-wide BBS corridor aliases):

ros2 run lidar_localization_ros2 quickstart.py \
  --profile mid360 \
  --map /absolute/path/to/map.pcd \
  --reference-csv /absolute/path/to/mapping_run/reference.csv

If no safe candidate is available, it asks for 2D Pose Estimate in RViz; it never guesses the origin. See quickstart and automatic initialization and the repeat-route site setup guide. Use --no-auto-initialize to disable saved-pose restoration and global initialization, or launch with use_continuous_time_deskew:=false to disable deskew.

Common launches:

# Standalone localization
ros2 launch lidar_localization_ros2 nav2_lidar_localization.launch.py

# Nav2
ros2 launch lidar_localization_ros2 nav2_navigation.launch.py \
  map_yaml:=/absolute/path/to/map.yaml

# Livox MID-360
ros2 launch lidar_localization_ros2 mid360_legged_localization.launch.py \
  map_path:=/absolute/path/to/map.pcd \
  cloud_topic:=/livox/points imu_topic:=/livox/imu

Check topics, TF, pose output, and diagnostics with:

ros2 run lidar_localization_ros2 check_lidar_localization_bringup.py \
  --profile standalone

Runtime Contract

The default frames are map, odom, and base_link.

• /initialpose is expressed in map.
• Standalone mode publishes map -> base_link.
• Nav2 mode publishes map -> odom and requires an external odom -> base_link.
• use_odom: true consumes /odom; it does not publish odometry TF.
• Static LiDAR and IMU transforms must have only one publisher.

Main inputs are /cloud, /initialpose, /odom, and /imu. Main outputs are /pcl_pose, /path, /alignment_status, and /reinitialization_requested. All topic names are configurable. See frame contract and troubleshooting for details.

Nav2 additionally requires a 2D occupancy map and an odom -> base_link source.

Public Demo

The Autoware Istanbul demo downloads its public assets, builds when needed, replays 60 seconds, and writes a trajectory report:

source scripts/setup_local_env.sh
scripts/run_public_demo.sh

First-time setup may take 15–30 minutes. For datasets, metrics, and regression commands, see benchmarking.

Documentation

• Validated scope
• Frames and troubleshooting
• Benchmarking
• MID-360 bringup
• IMU estimation and pose covariance
• Global localization
• Quickstart and automatic initialization
• Koide demo gallery
• Release notes

Support

ROS 2 Jazzy is the primary target; Humble remains supported for existing deployments. ndt_omp_ros2 is required and small_gicp is optional.