v1.0.0 release

.clang-format

@@ -0,0 +1,7 @@
+---
+Language:        Cpp
+ColumnLimit: 100
+DerivePointerAlignment: false
+PointerAlignment: Left
+SortIncludes: false
+...

.gitignore

@@ -1,32 +1,32 @@
-# Prerequisites
-*.d
-
-# Compiled Object files
-*.slo
-*.lo
-*.o
-*.obj
-
-# Precompiled Headers
-*.gch
-*.pch
-
-# Compiled Dynamic libraries
-*.so
-*.dylib
-*.dll
-
-# Fortran module files
-*.mod
-*.smod
-
-# Compiled Static libraries
-*.lai
-*.la
-*.a
-*.lib
-
-# Executables
-*.exe
-*.out
-*.app
+/bazel-*
+BROWSE
+/build*
+*.bzlc
+.cache
+.classpath
+.clwb/
+/ci/bazel-*
+compile_commands.json
+cscope.*
+.deps
+/docs/landing_source/.bundle
+/generated
+.idea/
+.project
+*.pyc
+**/pyformat
+SOURCE_VERSION
+.settings/
+*.sw*
+tags
+TAGS
+/test/coverage/BUILD
+/tools/.aspell.en.pws
+.vimrc
+.vs
+.vscode
+.ccls-cache
+.clangd
+/cmake-*
+*.m~
+python/*.egg-info/

CMakeLists.txt

@@ -0,0 +1,114 @@
+cmake_minimum_required(VERSION 3.10)
+project(TEASERPP VERSION 1.0.0)
+
+set(CMAKE_CXX_STANDARD 17)
+
+set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules/" ${CMAKE_MODULE_PATH})
+
+# Options
+option(BUILD_TESTS "Build tests" ON)
+option(BUILD_TEASER_FPFH "Build TEASER++ wrappers for PCL FPFH estimation." OFF)
+option(BUILD_MATLAB_BINDINGS "Build MATLAB bindings" OFF)
+option(BUILD_PYTHON_BINDINGS "Build Python bindings" ON)
+option(BUILD_DOC "Build documentation" ON)
+option(BUILD_WITH_MKL "Build Eigen with MKL." OFF)
+option(BUILD_WITH_MARCH_NATIVE "Build with flag march=native" OFF)
+option(ENABLE_DIAGNOSTIC_PRINT "Enable printing of diagnostic messages" OFF)
+
+if (ENABLE_DIAGNOSTIC_PRINT)
+    message(STATUS "Enable printing of diagnostic messages.")
+    add_definitions(-DTEASER_DIAG_PRINT)
+endif ()
+
+# Cache Variables
+if (NOT TEASERPP_PYTHON_VERSION)
+    set(TEASERPP_PYTHON_VERSION "" CACHE STRING "Python version to use for TEASER++ bindings.")
+endif ()
+
+# Find dependencies
+# Eigen3
+find_package(Eigen3 3.3 QUIET REQUIRED NO_MODULE)
+
+# MKL
+if (BUILD_WITH_MKL)
+    add_definitions(-DEIGEN_USE_MKL_ALL)
+endif ()
+
+if (BUILD_TEASER_FPFH)
+    # Boost
+    find_package(Boost 1.58 QUIET REQUIRED)
+
+    # PCL
+    find_package(PCL 1.8 QUIET REQUIRED COMPONENTS common io features kdtree)
+endif ()
+
+# googletest
+configure_file(cmake/GoogleTest.CMakeLists.txt.in googletest-download/CMakeLists.txt)
+execute_process(COMMAND "${CMAKE_COMMAND}" -G "${CMAKE_GENERATOR}" .
+        WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/googletest-download")
+execute_process(COMMAND "${CMAKE_COMMAND}" --build .
+        WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/googletest-download")
+set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+add_subdirectory("${CMAKE_BINARY_DIR}/googletest-src"
+        "${CMAKE_BINARY_DIR}/googletest-build")
+
+# pmc (Parallel Maximum Clique)
+configure_file(cmake/pmc.CMakeLists.txt.in pmc-download/CMakeLists.txt)
+execute_process(COMMAND "${CMAKE_COMMAND}" -G "${CMAKE_GENERATOR}" .
+        WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/pmc-download")
+execute_process(COMMAND "${CMAKE_COMMAND}" --build .
+        WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/pmc-download")
+add_subdirectory("${CMAKE_BINARY_DIR}/pmc-src"
+        "${CMAKE_BINARY_DIR}/pmc-build")
+
+# tinyply
+configure_file(cmake/tinyply.CMakeLists.txt.in tinyply-download/CMakeLists.txt)
+execute_process(COMMAND "${CMAKE_COMMAND}" -G "${CMAKE_GENERATOR}" .
+        WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/tinyply-download")
+execute_process(COMMAND "${CMAKE_COMMAND}" --build .
+        WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/tinyply-download")
+add_subdirectory("${CMAKE_BINARY_DIR}/tinyply-src"
+        "${CMAKE_BINARY_DIR}/tinyply-build")
+target_include_directories(tinyply PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/tinyply-src/source>)
+
+# Building Targets
+set(TEASER_ROOT ${CMAKE_CURRENT_LIST_DIR})
+add_subdirectory(teaser)
+
+if (BUILD_TESTS)
+    enable_testing()
+    add_subdirectory(test)
+endif ()
+
+if (BUILD_DOC)
+    add_subdirectory(doc EXCLUDE_FROM_ALL)
+endif ()
+
+if (BUILD_MATLAB_BINDINGS)
+    message(STATUS "Will build MATLAB bindings.")
+    add_subdirectory(matlab)
+endif ()
+
+if (BUILD_PYTHON_BINDINGS)
+    set(PYBIND11_PYTHON_VERSION ${TEASERPP_PYTHON_VERSION})
+
+    # download the pybind11 repo
+    configure_file(cmake/pybind11.CMakeLists.txt.in pybind11-download/CMakeLists.txt)
+    execute_process(COMMAND "${CMAKE_COMMAND}" -G "${CMAKE_GENERATOR}" .
+            WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/pybind11-download")
+    execute_process(COMMAND "${CMAKE_COMMAND}" --build .
+            WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/pybind11-download")
+    add_subdirectory("${CMAKE_BINARY_DIR}/pybind11-src"
+            "${CMAKE_BINARY_DIR}/pybind11-build")
+
+    message(STATUS "TEASER++ Python binding will be built.")
+    add_subdirectory(python)
+endif ()
+
+# export targets
+export(TARGETS ${TEASERPP_EXPORTED_TARGETS} FILE TEASERPP-exports.cmake)
+
+install(FILES cmake/TEASERPPConfig.cmake
+    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/TEASERPP
+)

README.md

@@ -1,2 +1,111 @@
-# TEASER
-C++ implementation for TEASER and related
+# 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.   
+
+For more information, please refer to:
+- H. Yang, J. Shi and L. Carlone. TEASER: Fast and Certifiable Point-Cloud Registration. Unpublished.
+
+If you find this library helpful or use it in your project, please consider citing:
+```bibtex
+ @unpublished{Yang2020-TEASER,
+   title = {TEASER: Fast and Certifiable Point-Cloud Registration},
+   author = {Yang, Heng and Shi, Jingnan and Carlone, Luca},
+   year = {2020},
+ }
+```
+
+## Dependencies
+Building TEASER++ requires the following libraries installed: 
+1. Eigen3 >= 3.3
+2. PCL >= 1.9 (optional)
+3. Boost >= 1.58 (optional)
+
+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 (PMC) 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:
+```shell
+mkdir build
+cd build
+cmake ..
+make
+```
+If you want to install relevant headers and binaries, 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 debug mode. If you run the tests, some of the tests might time out. Try build the tests in release mode (`cmake -DCMAKE_BUILD_TYPE=Release ..`) and run them again.
+
+To run benchmarks (for speed & accuracy tests), you can execute the following command:
+```shell
+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:
+```c++
+#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](matlab/README.md) document.
+
+For a short example on how to use the Python bindings for TEASER++, please refer to [this](python/README.md) 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.
+
+
+

cmake/GoogleTest.CMakeLists.txt.in

@@ -0,0 +1,14 @@
+cmake_minimum_required(VERSION 3.10)
+
+project(googletest-download NONE)
+
+include(ExternalProject)
+ExternalProject_Add(googletest
+        URL                https://github.com/google/googletest/archive/release-1.8.1.zip
+        SOURCE_DIR        "${CMAKE_CURRENT_BINARY_DIR}/googletest-src"
+        BINARY_DIR        "${CMAKE_CURRENT_BINARY_DIR}/googletest-build"
+        CONFIGURE_COMMAND ""
+        BUILD_COMMAND     ""
+        INSTALL_COMMAND   ""
+        TEST_COMMAND      ""
+        )

cmake/TEASERPPConfig.cmake

@@ -0,0 +1,8 @@
+get_filename_component(TEASERPP_CMAKE_DIR "${CMAKE_CURRENT_LIST_FILE}" PATH)
+include(CMakeFindDependencyMacro)
+
+find_dependency(Eigen3 3.3 REQUIRED)
+find_dependency(OpenMP REQUIRED)
+
+include("${TEASERPP_CMAKE_DIR}/TEASERPPTargets.cmake")
+

cmake/pmc.CMakeLists.txt.in

@@ -0,0 +1,15 @@
+cmake_minimum_required(VERSION 3.10)
+
+project(pmc-download NONE)
+
+include(ExternalProject)
+# Notice that this project uses a forked version of PMC with minor fixes & changes
+ExternalProject_Add(pmc
+        GIT_REPOSITORY    https://github.com/jingnanshi/pmc.git
+        SOURCE_DIR        "${CMAKE_CURRENT_BINARY_DIR}/pmc-src"
+        BINARY_DIR        "${CMAKE_CURRENT_BINARY_DIR}/pmc-build"
+        CONFIGURE_COMMAND ""
+        BUILD_COMMAND     ""
+        INSTALL_COMMAND   ""
+        TEST_COMMAND      ""
+        )

cmake/pybind11.CMakeLists.txt.in

@@ -0,0 +1,15 @@
+cmake_minimum_required(VERSION 3.10)
+
+project(pybind11-download NONE)
+
+include(ExternalProject)
+ExternalProject_Add(pmc
+        GIT_REPOSITORY    https://github.com/pybind/pybind11.git
+        GIT_TAG           v2.4.3
+        SOURCE_DIR        "${CMAKE_CURRENT_BINARY_DIR}/pybind11-src"
+        BINARY_DIR        "${CMAKE_CURRENT_BINARY_DIR}/pybind11-build"
+        CONFIGURE_COMMAND ""
+        BUILD_COMMAND     ""
+        INSTALL_COMMAND   ""
+        TEST_COMMAND      ""
+        )

cmake/tinyply.CMakeLists.txt.in

@@ -0,0 +1,15 @@
+cmake_minimum_required(VERSION 3.10)
+
+project(tinyply-download NONE)
+
+include(ExternalProject)
+ExternalProject_Add(pmc
+        GIT_REPOSITORY    https://github.com/jingnanshi/tinyply.git
+        GIT_TAG           0b9fff8e8bd4d37256554fe40cf76b2f3134377b
+        SOURCE_DIR        "${CMAKE_CURRENT_BINARY_DIR}/tinyply-src"
+        BINARY_DIR        "${CMAKE_CURRENT_BINARY_DIR}/tinyply-build"
+        CONFIGURE_COMMAND ""
+        BUILD_COMMAND     ""
+        INSTALL_COMMAND   ""
+        TEST_COMMAND      ""
+        )

doc/CMakeLists.txt

@@ -0,0 +1,15 @@
+project(teaser_doc)
+
+set_directory_properties(PROPERTIES EXCLUDE_FROM_ALL TRUE)
+
+set(TEASER_DOXY_PROJECT_NAME             "TEASER")
+set(TEASER_DOXY_INPUT                    "\"${TEASER_SOURCE_DIR}/teaser\" \"${TEASER_SOURCE_DIR}/doc\"")
+
+configure_file(
+        ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
+        ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+)
+
+add_custom_target(doc ALL
+        COMMAND doxygen
+        WORKING_DIRECTORY ${TEASER_BINARY_DIR}/doc)