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

Changelog

1.0.0 - 2026-03-30

Initial repo-ready Nav2-focused release.

• added Nav2-oriented launch flows with nav2_lidar_localization.launch.py and nav2_navigation.launch.py
• added smoke and replay helpers including run_nav2_demo_smoke, run_nav2_replay_smoke, and send_nav2_goal.py
• added occupancy map generation from PCD with generate_occupancy_map_from_pcd.py
• added benchmarking and comparison helpers for rosbag-based localization evaluation
• added local-map crop, twist-based prediction, borderline seed rejection gate, diagnostics, and replay-oriented utilities
• fixed NDT_OMP runtime keep-alive issues seen in replay and fixed the shutdown-only SIGINT crash path
• set the recommended Nav2 preset to param/nav2_ndt_urban.yaml

Known limitation at this release:

• long-duration urban replay robustness is improved enough for smoke and controlled validation, but not yet solved well enough to claim fully stable long-horizon operation in all cases