TEASER++

TEASER++ is a fast and robust point cloud registration framework written in C++. It can solve the rigid body transformation problem between two point clouds in 3D. TEASER++ also has bindings for MATLAB and Python, as well as integration with ROS for easy testing and visualization.

Left: correspondences generated by 3DSmoothNet (green and red lines represent the inlier and outlier correspondences according to the ground truth respectively). Right: alignment estimated by TEASER++ (green dots represent inliers found by TEASER++).

For a short conceptual introduction, check out our video. For more information, please refer to our paper:

H. Yang, J. Shi, and L. Carlone, "TEASER: Fast and Certifiable Point-Cloud Registration,". arXiv:2001.07715 [cs, math], Jan. 2020. (pdf)

Other related publications from our group include:

H. Yang and L. Carlone, “A Polynomial-time Solution for Robust Registration with Extreme Outlier Rates,” in Robotics: Science and Systems (RSS), 2019. (pdf)
H. Yang and L. Carlone, “A quaternion-based certifiably optimal solution to the Wahba problem with outliers,” in Proceedings of the IEEE International Conference on Computer Vision (ICCV), 2019, pp. 1665–1674. (pdf)
H. Yang, P. Antonante, V. Tzoumas, and L. Carlone, “Graduated Non-Convexity for Robust Spatial Perception: From Non-Minimal Solvers to Global Outlier Rejection,” IEEE Robotics and Automation Letters (RA-L), 2020. (pdf)

If you find this library helpful or use it in your project, please consider citing:

@misc{Yang20-TEASER,
    title={TEASER: Fast and Certifiable Point Cloud Registration},
    author={Heng Yang and Jingnan Shi and Luca Carlone},
    year={2020},
    eprint={2001.07715},
    archivePrefix={arXiv},
    primaryClass={cs.RO},
    url = {https://github.com/MIT-SPARK/TEASER-plusplus},
    pdf = {https://arxiv.org/abs/2001.07715}
}

If you are interested in more works from us, please visit our lab page here.

Dependencies

Building TEASER++ requires the following libraries installed:

Eigen3 >= 3.3
PCL >= 1.9 (optional)
Boost >= 1.58 (optional)

If you want to build Python bindings, you also need:

Python 2 or 3 (make sure to include the desired interpreter in your PATH variable)

If you want to build MATLAB bindings, you also need:

MATLAB
CMake >= 3.13

TEASER++ uses the Parallel Maximum Clique (paper, code) for maximum clique calculation. It will be downloaded automatically during CMake configuration. In addition, CMake will also download Google Test and pybind11 if necessary.

Getting Started

CMake

Ensure that your CMake version is at least 3.10. Clone the repo to your local directory. Open a terminal in the repo root directory. Run the following commands:

mkdir build
cd build
cmake ..
make

If you want to install relevant headers and shared libraries, run make install after the above commands (you may need to sudo).

Available CMake Options

Option Name	Description	Default Value
`BUILD_TESTS`	Build tests	ON
`BUILD_TEASER_FPFH`	Build TEASER++ wrappers for PCL FPFH estimation	OFF
`BUILD_MATLAB_BINDINGS`	Build MATLAB bindings	OFF
`BUILD_PYTHON_BINDINGS`	Build Python bindings	ON
`BUILD_DOC`	Build documentation	ON
`BUILD_WITH_MKL`	Build Eigen with MKL	OFF
`BUILD_WITH_MARCH_NATIVE`	Build with flag `march=native`	OFF
`ENABLE_DIAGNOSTIC_PRINT`	Enable printing of diagnostic messages	OFF

Run Tests

You can run the tests by running ctest in the build directory. To generate the Doxygen documentation, run make doc, and you should be able to view the Doxygen files in build/doc folder.

By default, the library is built in release mode. If you instead choose to build it in debug mode, some tests are likely to time out.

To run benchmarks (for speed & accuracy tests), you can execute the following command:

ctest --verbose -R RegistrationBenchmark.*

The --verbose option allows you to see the output, as well as the summary tables generated by each benchmark.

The library has been tested on Ubuntu 18.04.

How to use TEASER++

To use TEASER++ in your C++ project, please refer to the source code and Doxygen documentation for details. Here's a short C++ snippet that you may find helpful for integrating TEASER++ in your code:

#include <Eigen/Core>
#include <teaser/registration.h>

Eigen::Matrix<double, 3, Eigen::Dynamic> src(3, N);
Eigen::Matrix<double, 3, Eigen::Dynamic> dst(3, N);

// Populate src & dst with your correspondences ...

// Populate solver parameters
teaser::RobustRegistrationSolver::Params params;
params.cbar2 = 1;
params.noise_bound = 0.01;
params.estimate_scaling = false;
params.rotation_estimation_algorithm = teaser::RobustRegistrationSolver::ROTATION_ESTIMATION_ALGORITHM::GNC_TLS;
params.rotation_gnc_factor = 1.4;
params.rotation_max_iterations = 100;
params.rotation_cost_threshold = 1e-6;

// Initialize solver
teaser::RobustRegistrationSolver solver(params);

// Solve
solver.solve(src, dst);

// Get solution
auto solution = solver.getSolution();

For a short example on how to use the MATLAB bindings for TEASER++, please refer to this document.

For a short example on how to use the Python bindings for TEASER++, please refer to this document.

To use TEASER++ in a ROS environment, simple clone the repo to your catkin workspace.

Known Issues

When using the MATLAB wrapper with MATLAB on terminal (-nojvm option enabled), you might encounter errors similar to this: /usr/local/MATLAB/R2019a/bin/glnxa64/MATLAB: symbol lookup error: /opt/intel/compilers_and_libraries_2019.4.243/linux/mkl/lib/intel64_lin/libmkl_vml_avx2.so: undefined symbol: mkl_serv_getenv. One way to get around this is to run the following command in the environment where you start MATLAB: export LD_PRELOAD=/opt/intel/mkl/lib/intel64/libmkl_intel_lp64.so:/opt/intel/mkl/lib/intel64/libmkl_gnu_thread.so:/opt/intel/mkl/lib/intel64/libmkl_core.so. You may need to change the paths according to your MKL installation.

feihugis / TEASER-plusplus