Skip to content
A fast and robust point-cloud registration library
C++ CMake MATLAB Python
Branch: master
Clone or download
Latest commit 76635a7 Feb 5, 2020
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows Add github actions for simple CI (#7) Feb 3, 2020
cmake
doc Fix documentation building error (#5) Jan 28, 2020
matlab Update references Jan 24, 2020
python Fix scaling parameter in python README example Jan 24, 2020
teaser Add checks to ensure reasonable maximum clique size (#6) Feb 3, 2020
test v1.0.0 release Jan 21, 2020
.clang-format
.gitignore v1.0.0 release Jan 21, 2020
CMakeLists.txt Update README to include CMake example (#9) Feb 5, 2020
LICENSE Add MIT license Jan 21, 2020
README.md Update README to include CMake example (#9) Feb 5, 2020
THANKS.md Add THANKS document Feb 5, 2020
package.xml Update references Jan 24, 2020

README.md

TEASER++

TEASER++ is a fast and certifiably-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:

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:

@article{Yang20arXiv-TEASER,
    title={TEASER: Fast and Certifiable Point Cloud Registration},
    author={Yang, Heng and Shi, Jingnan and Carlone, Luca},
    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.

Getting Started

Supported Platforms

TEASER++ has been tested on Ubuntu 18.04 with g++-7/9 and clang++-7/8/9.

Dependencies

Building TEASER++ requires the following libraries installed:

  1. Eigen3 >= 3.3
  2. PCL >= 1.9 (optional)
  3. Boost >= 1.58 (optional)

You may run the following to install Eigen3:

sudo apt install libeigen3-dev

Please refer to other dependencies' documentation for detailed installation instructions.

You also need a compiler that supports OpenMP. See here for a list.

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

  1. 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:

  1. MATLAB
  2. 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.

Compilation and Installation

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.

How to use TEASER++

To use TEASER++ in your CMake-based C++ project, here's an example CMake file that finds and includes TEASER++:

cmake_minimum_required(VERSION 3.10)
project(teaserpp_example)

set (CMAKE_CXX_STANDARD 14)

find_package(Eigen3 REQUIRED) 
find_package(teaserpp REQUIRED)

# Change this line to include your own executable file
add_executable(cpp_example cpp_example.cpp)

# Link to teaserpp & Eigen3 
target_link_libraries(cpp_example Eigen3::Eigen teaserpp::teaser_registration)

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

  • If you are encountering segmentation faults from PMC, try add the environmental variable OMP_NUM_THREADS=12 in your current shell. You can also just prepend OMP_NUM_THREADS=12 when running your executable.
  • 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.
You can’t perform that action at this time.