diff --git a/README.md b/README.md index f7556e3..8d5da28 100644 --- a/README.md +++ b/README.md @@ -3,3 +3,65 @@ ROS Packages for Real-Time 3D LIDAR Based Localization using Normal Distribution Transform (NDT) Scan Matching Algorithm and Unscented Kalman Filter (UKF) Estimation. ![3D-LIDAR-Localization](3D-LIDAR-Localization.png) + +This localization algorithm performs Unscented Kalman Filter (UKF) based pose estimation. It first estimates the sensor pose from IMU data (IMU-based pose prediction is optional, if disabled, the system uses a constant velocity model) implemented on the LIDAR, and then performs multi-threaded NDT scan matching between a global map point cloud and input sensor point clouds to correct the estimated pose. + +## Dependencies +***hdl_localization*** requires the following libraries: +- PCL +- OpenMP + +***hdl_localization*** requires the following ROS packages: +- pcl_ros +- [ndt_omp](https://github.com/koide3/ndt_omp) +- [fast_gicp](https://github.com/SMRT-AIST/fast_gicp) +- [hdl_global_localization](https://github.com/koide3/hdl_global_localization) + +## Installation + +```bash +cd ROS1_Workspace +``` +- For nominal NDT: + ``` + catkin_make -DCMAKE_BUILD_TYPE=Release + ``` +- For CUDA-accelerated NDT: + ```bash + catkin_make -DCMAKE_BUILD_TYPE=Release -DBUILD_VGICP_CUDA=ON + ``` + +## Configuration +- All configurable parameters are listed in `launch/hdl_localization.launch`. +- The estimated pose can be set and reset using using `2D Pose Estimate` in RViz. + +## Topics +- ***/odom*** (nav_msgs/Odometry) + - Estimated sensor pose in the map frame +- ***/aligned_points*** (sensor_msgs/PointCloud2) + - Input point cloud aligned with the map +- ***/status*** (hdl_localization/ScanMatchingStatus) + - Scan matching result information (e.g., convergence, matching error, and inlier fraction) + +## Services +- ***/relocalize*** (std_srvs/Empty) + - Reset the sensor pose with the global localization result + +## Execution + +Open a terminal and launch `hdl_localization`. +```bash +roslaunch hdl_localization hdl_localization.launch +``` + +Open another terminal and play a pre-recorded `rosbag` or start streming data from sensor. +```bash +rosparam set use_sim_time true +rosbag play --clock +``` +Open another terminal and call a service to reset the sensor pose with the global localization result (if required). +```bash +rosservice call /relocalize +``` + +> **Note:** If the algorithm does not work very well or if the CPU usage is too high, change `ndt_neighbor_search_method` in `hdl_localization.launch` to `DIRECT1`. It makes the scan matching significantly fast, but is a bit unstable.