lidar_localization_ros2

A ROS2 package of 3D LIDAR-based Localization.

Quick Start

From this repository in the local workspace:

source scripts/setup_local_env.sh
cd ../build_ws
colcon build --symlink-install --packages-up-to lidar_localization_ros2
cd ../repo
source scripts/setup_local_env.sh

Then choose the path that matches what you want to do:

For Nav2 use, provide a pointcloud map, matching 2D map_yaml when launching the full Nav2 stack, an odom source publishing odom -> base_link, and an initial pose on /initialpose.

Status

The repo is now packaged as v1.0.0.

• recommended Nav2 preset: param/nav2_ndt_urban.yaml
• verified flows: nav2_lidar_localization.launch.py, nav2_navigation.launch.py, run_nav2_demo_smoke, run_nav2_replay_smoke
• current boundary: long-horizon urban replay beyond the validated smoke path is still an active robustness problem, not a solved one

See CHANGELOG.md for the release summary and docs/v1_status.md for the concrete validated scope and known limits.

Green: path, Red: map
(the 5x5 grids in size of 50m × 50m)

Requirements

• ndt_omp_ros2
• small_gicp (optional, for SMALL_GICP and SMALL_VGICP)

If small_gicp is installed as a CMake package at build time, SMALL_GICP and SMALL_VGICP are enabled automatically.

local build

For the no-sudo local prefix workflow used in this workspace, see docs/local_build.md. After the first successful build, load the environment with:

source scripts/setup_local_env.sh

Experiment-First Development

Runtime code lives in src/ and include/. Competing ideas live in experiments/ and are assumed to be discardable.

For the current experiment problems, this repo keeps multiple comparable implementations behind minimal interfaces and regenerates the comparison docs from one suite entry point:

ros2 run lidar_localization_ros2 run_experiment_suite.py

Problem-specific runners are also available:

• ros2 run lidar_localization_ros2 run_imu_guard_experiments.py
• ros2 run lidar_localization_ros2 run_borderline_gate_experiments.py
• ros2 run lidar_localization_ros2 run_recovery_action_experiments.py
• ros2 run lidar_localization_ros2 run_reinit_trigger_experiments.py

The suite updates:

• docs/interfaces.md
• docs/experiments.md
• docs/decisions.md

The rule is simple: new behavior should be introduced as multiple comparable variants first, then only the winning behavior is promoted into runtime core.

For a one-command regression pass across both the short public checks and the heavier Nav2 long-replay recovery check:

ros2 run lidar_localization_ros2 run_release_regression_suite.sh

This aggregates:

• run_public_regression_suite.sh
• run_nav2_reinit_supervisor_regression.sh

and writes a combined summary under artifacts/public/release_regression_suite/.

File truncated at 100 lines see the full file