Taiwan-built, self-hosted AI agent harness in a single Go binary — writes its own tools, sandbox-tests them, and shares them over MCP with Claude Code and Codex.
Give it a point cloud map (.pcd or .ply) and a LiDAR stream; it publishes the
robot pose in the map. It finds the starting pose by itself, uses odometry and IMU when
you have them, and works standalone or as the localization source for Nav2.
ROS 2 Jazzy is the main target; Humble is supported.
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
This builds ndt_omp_ros2 and this
package, about 30 minutes on an 8-core machine.
small_gicp is optional (SMALL_GICP and
SMALL_VGICP backends): on Jazzy, sudo apt install ros-jazzy-small-gicp-vendor
before building is enough. For Humble, a manual or no-sudo build, see
local build.
No ROS install? Build the Docker image and check it in one command:
Start the LiDAR driver, and odometry if you have it.
Run quickstart with your map:
ros2 run lidar_localization_ros2 quickstart.py --map /absolute/path/to/map.pcd
Check that it is tracking:
ros2 run lidar_localization_ros2 check_lidar_localization_bringup.py --profile standalone
Quickstart finds the cloud and IMU topics, /clock, an odom -> base TF and the
LiDAR frame, and prints what it picked on its Discovery: line. Then it starts the
localizer and RViz. On the first run it searches the whole map for the robot; next time
it restores the pose saved for the same map. If the search finds no safe match, it asks
you for 2D Pose Estimate in RViz (press P, click the robot, drag along its
heading) instead of guessing.
While it runs, the terminal prints one line whenever tracking starts, weakens, is lost
or comes back, with what to do about it, and RViz shows the same status above the
robot:
[localization_status]: Tracking.
[localization_status]: Tracking lost: no scan has matched the map for 4 s. If it does not recover, set 2D Pose Estimate in RViz.
Startup finds a first pose; then every scan is matched against the map near the
predicted pose. When matching keeps failing, recovery searches the map again.
flowchart TD
odom[/"optional: external odometry<br/>e.g. RKO-LIO from lidar_slam_ros2,<br/>wheel or leg odometry"/]
scan["LiDAR scan"] --> prep["range crop, voxel filter,<br/>deskew"]
prep --> seed["seed pose: last pose,<br/>moved by odometry or IMU if given"]
seed --> reg["NDT or GICP against the map<br/>cropped around the seed"]
reg --> gate{"converged, score under<br/>threshold, guards pass?"}
gate -- yes --> pub["publish pose and TF,<br/>/alignment_status OK"]
gate -- no --> bridge["keep the predicted pose<br/>(odometry bridge)"]
bridge -- "rejected for long" --> reinit["/reinitialization_requested"]
odom -. "odom -> base TF" .-> seed
odom -. "carries the pose" .-> bridge
Map matching is always NDT (default) or GICP. External odometry is optional: it only
predicts the motion between scans and carries the pose where scans do not match the
map. It helps with fast or handheld motion; quickstart uses it when it sees an
odom -> base TF.
Nav2 mode publishes map -> odom and needs an external odom -> base_link.
use_odom: true reads /odom; it does not publish odometry TF.
publish_tf: false turns off every TF the localizer broadcasts; use it when another
node (for example robot_localization fusing /pcl_pose) owns map -> odom.
Each static LiDAR and IMU transform must have exactly one publisher.
/map_switch (std_msgs/String holding a .pcd or .ply path) replaces the map at
runtime and keeps the current pose; a map that fails to load leaves the current one.
If the new map has a different origin, publish /initialpose right after the switch.
The global localization node keeps the map it was started with.
Benchmark
Public datasets replayed through the same commands as above (odometry plus
quickstart.py --map). Each run starts with no initial pose, so the localizer has to
find the robot itself. Errors are measured in the map frame with no trajectory
alignment, so a wrong start shows up as error.
Measured 2026-10-06 and 2026-10-11 on Jazzy at 1x. Ranges are over sequences.
What this does not cover:
In the kidnap runs the error is large while the sensor is carried, until recovery.
On wide Go2 maps, the default search can stay ambiguous and ask for a manual pose
(Outdoor1). The low-sensor settings started every run in the table correctly; in six
later replays, one Outdoor2 run stayed ambiguous and asked for a manual pose.
No long multi-hour runs and no physical-hardware validation.
Per-sequence tables, how to rerun, and dataset links: docs/benchmark.md.
ros2 run lidar_localization_ros2 run_koide_public_bag.py --download
It downloads the Koide data, runs odometry and localization, and reports the error
against the ground truth. Playback takes about five minutes. Data is cached in
./koide-data and results go to ./koide-run-*. See the
public-bag guide.
