mcl_3dl

[!NOTE]
After official ROS 1 EOL, this package is released to Alpine ROS.

Package summary

mcl_3dl is a ROS node to perform a probabilistic 3-D/6-DOF localization system for mobile robots with 3-D LIDAR(s). It implements pointcloud based Monte Carlo localization that uses a reference pointcloud as a map.

The node receives the reference pointcloud as an environment map and localizes 6-DOF (x, y, z, yaw, pitch, roll) pose of measured pointclouds assisted by a motion prediction using odometry.

Currently, the supported motion model is differential-wheeled-robot. The node provides classic MCL; currently, it doesn’t implement adaptive feature like KDL-sampling and etc.

Algorithms

A fundamental algorithm of mcl_3dl node is Monte Carlo localization (MCL), aka particle filter localization. MCL represents a probabilistic distribution of estimated pose as density and weight of particles and estimates the pose from the distribution.

• Algorithm details
• Parameters

Node I/O

Install

from source

Note: mcl_3dl_msgs package is required to build mcl_3dl package.

# clone
cd /path/to/your/catkin_ws/src
git clone https://github.com/at-wat/mcl_3dl.git
git clone https://github.com/at-wat/mcl_3dl_msgs.git

# build
cd /path/to/your/catkin_ws
rosdep install --from-paths src --ignore-src -y  # Install dependencies
catkin_make -DCMAKE_BUILD_TYPE=Release  # Release build is recommended

from apt repository (for ROS Indigo/Kinetic/Lunar on Ubuntu)

sudo apt-get install ros-${ROS_DISTRO}-mcl-3dl

Running the demo

The example bag file of 2+4-DOF tracked vehicle with two Hokuyo YVT-X002 3-D LIDAR is available online. Pre-processed (filtered) 3-D pointcloud, IMU pose, odometry, and map data are packed in the bag.

# Download the example bag (230M)
wget -P ~/Downloads https://openspur.org/~atsushi.w/dataset/mcl_3dl/short_test3.bag

# Running the demo
roslaunch mcl_3dl test.launch use_pointcloud_map:=false use_cad_map:=false \
  use_bag_file:=true bag_file:=${HOME}/Downloads/short_test3.bag

The map data in the bag was generated by using the cartographer_ros and filtered by using pcl_outlier_removal and pcl_voxel_grid utilities.

MarkerArray shows several mcl_3dl internal information.

• Purple spheres: sampled points used in the likelihood-model calculation
• Red lines: casted rays in the beam-model calculation
• Red boxes: detected collisions in raycasting

To try global localization, call /global_localization by the following command.

rosservice call /global_localization

Demos without odometry and without IMU are also available.

Contributing

mcl_3dl package is developed under GitHub flow. Feel free to open new Issue and/or Pull Request.

The code in this repository is following ROS C++ Style Guide. A configuration file for clang-format is available at https://github.com/seqsense/ros_style/.

License

• mcl_3dl is provided under the BSD license.
• Backport codes of Point Cloud Library (PCL) is provided under the BSD license.

Changelog for package mcl_3dl

0.6.5 (2025-07-04)

• Subscribe latency sensitive topics by tcpNoDelay (#430)
• Fix MCL_3DL_EXTRA_TESTS environment variable check in if condition (#429)
• Fix CI job names (#428)
• Remove old post-release script (#427)
• Migrate to Alpine ROS 1 (#426)
• Contributors: Atsushi Watanabe, f-fl0

0.6.4 (2024-10-10)

• Fix angular part of covariance matrix (#417)
• Contributors: f-fl0

0.6.3 (2024-07-22)

• Explicitly handle zero sigma (#414)
• Update assets to v0.6.4 (#413)
• Update assets to v0.6.3 (#412)
• Update assets to v0.6.2 (#411)
• Contributors: Atsushi Watanabe

0.6.2 (2023-11-14)

• Fix reported entropy (#408)
• Update assets to v0.6.1 (#407)
• Update assets to v0.6.0 (#406)
• Update assets to v0.5.2 (#405)
• Update assets to v0.5.1 (#404)
• Update assets to v0.4.2 (#402)
• Contributors: Atsushi Watanabe, f-fl0

0.6.1 (2023-01-04)

• Update assets to v0.4.1 (#400)
• Support PCL 1.11 and later (#397)
• Update assets to v0.4.0 (#395)
• Update assets to v0.3.4 (#392)
• Remove old workarounds for PCL<1.8 (#389)
• Update assets to v0.3.3 (#388)
• Update assets to v0.3.2 (#387)
• Update code format (#386)
• Contributors: Atsushi Watanabe

0.6.0 (2021-05-12)

• Add option to load cloud through "load_pcd" service (#381)
• Update assets to v0.3.1 (#382)
• Update assets to v0.3.0 (#380)
• Update assets to v0.2.0 (#379)
• Contributors: Atsushi Watanabe, Remco

0.5.4 (2021-03-07)

• Add odom/imu/cloud_queue_size params (#375)
• Fix flaky tests (#376)
• Contributors: Atsushi Watanabe

0.5.3 (2021-02-26)

• Fix cloud accum reset on map update (#371)
• Contributors: Atsushi Watanabe

0.5.2 (2021-01-15)

• Fix potential "Time is out of dual 32-bit range" error (#367)

File truncated at 100 lines see the full file