Release 2.0 (#46)

Added certification, added readthedocs documentation, various bug fixes

.gitignore

@@ -30,3 +30,4 @@ TAGS
 /cmake-*
 *.m~
 python/*.egg-info/
+/doc/_build/

.readthedocs.yml

@@ -0,0 +1,9 @@
+version: 2
+
+sphinx:
+  configuration: doc/conf.py
+
+python:
+  version: 3.6
+  install:
+    - requirements: doc/requirements.txt

CMakeLists.txt

@@ -6,11 +6,11 @@ set(CMAKE_CXX_STANDARD 14)
 set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules/" ${CMAKE_MODULE_PATH})
 
 # Check build types
-if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+if (NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
     message(STATUS "Setting build type to 'Release' as none was specified.")
     set(CMAKE_BUILD_TYPE "Release" CACHE
             STRING "Choose the type of build." FORCE)
-endif()
+endif ()
 
 # Options
 option(BUILD_TESTS "Build tests" ON)
@@ -19,7 +19,8 @@ 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_MARCH_NATIVE "Build with flag march=native" OFF)
-option(ENABLE_DIAGNOSTIC_PRINT "Enable printing of diagnostic messages" OFF)
+option(ENABLE_MKL "Try to use Eigen with MKL" OFF)
+option(ENABLE_DIAGNOSTIC_PRINT "Enable printing of diagnostic messages" ON)
 
 if (ENABLE_DIAGNOSTIC_PRINT)
     message(STATUS "Enable printing of diagnostic messages.")
@@ -34,6 +35,17 @@ endif ()
 # Find dependencies
 # Eigen3
 find_package(Eigen3 3.2 QUIET REQUIRED NO_MODULE)
+if (ENABLE_MKL)
+    find_package(MKL)
+    if (MKL_FOUND)
+        message(STATUS "MKL found at: ${MKL_LIBRARIES}")
+        include_directories(${MKL_INCLUDE_DIR})
+        add_definitions(-DEIGEN_USE_MKL_ALL)
+        list(APPEND TEASERPP_BLAS_LAPACK_LIBS ${MKL_LIBRARIES})
+    else ()
+        message(STATUS "MKL not found.")
+    endif ()
+endif ()
 
 if (BUILD_TEASER_FPFH)
     # Boost
@@ -73,6 +85,14 @@ add_subdirectory("${CMAKE_BINARY_DIR}/tinyply-src"
 target_include_directories(tinyply PUBLIC
         $<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/tinyply-src/source>)
 
+# spectra
+configure_file(cmake/spectra.CMakeLists.txt.in spectra-download/CMakeLists.txt)
+execute_process(COMMAND "${CMAKE_COMMAND}" -G "${CMAKE_GENERATOR}" .
+        WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/spectra-download")
+execute_process(COMMAND "${CMAKE_COMMAND}" --build .
+        WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/spectra-download")
+set(SPECTRA_INCLUDE_DIRS "${CMAKE_BINARY_DIR}/spectra-src/include")
+
 # Building Targets
 set(TEASERPP_ROOT ${CMAKE_CURRENT_LIST_DIR})
 add_subdirectory(teaser)
@@ -111,5 +131,5 @@ endif ()
 export(TARGETS ${TEASERPP_EXPORTED_TARGETS} FILE teaserpp-exports.cmake)
 
 install(FILES cmake/teaserppConfig.cmake
-    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/teaserpp
-)
+        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/teaserpp
+        )

README.md

@@ -1,5 +1,6 @@
 # TEASER++: fast & certifiable 3D registration 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Documentation Status](https://readthedocs.org/projects/teaser/badge/?version=latest)](https://teaser.readthedocs.io/en/latest/?badge=latest)
 [<img src="https://github.com/MIT-SPARK/TEASER-plusplus/workflows/build/badge.svg">](https://github.com/MIT-SPARK/TEASER-plusplus/actions)
 
 ![TEASER++ 3DSmooth](examples/teaser_python_3dsmooth/3dsmooth_example.gif)
@@ -144,152 +145,22 @@ You should be able to see Open3D windows showing registration results:
 ![TEASER++ 3DSmooth](examples/teaser_python_3dsmooth/3dsmooth_example.gif)
 
 ## Getting Started
-### Supported Platforms
-TEASER++ has been tested on Ubuntu 18.04 with g++-7/9 and clang++-7/8/9.  
-
-### Installing Dependencies
-Building TEASER++ requires the following libraries installed: 
-1. A compiler that supports OpenMP. See [here](https://www.openmp.org/resources/openmp-compilers-tools/) for a list. 
-2. CMake >= 3.10
-3. Eigen3 >= 3.3
-4. PCL >= 1.9 (optional)
-5. Boost >= 1.58 (optional)
-
-Run the following script to install all required dependencies:
-```shell script
-sudo apt install cmake libeigen3-dev libboost-all-dev
-```
-
-Run the following script to install PCL from source:
-```shell script
-# Compile and install PCL 1.91 from source
-PCL_PACKAGE_DIR="$HOME/pcl"
-mkdir "$PCL_PACKAGE_DIR"
-cd "$PCL_PACKAGE_DIR"
-wget "https://github.com/PointCloudLibrary/pcl/archive/pcl-1.9.1.zip"
-unzip pcl-*.zip
-rm pcl-*.zip
-cd pcl-* && mkdir build && cd build
-cmake ..
-make -j $(python3 -c 'import multiprocessing as mp; print(int(mp.cpu_count() * 1.5))')
-sudo make install
-```
-Notice that PCL is not required for the TEASER++ registration library. Installing it merely allows you to build example tests that uses PCL's FPFH features for registration. 
-
-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](https://arxiv.org/abs/1302.6256), [code](https://github.com/ryanrossi/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.
-
-### Compilation and Installation
-Clone the repo to your local directory. Open a terminal in the repo root directory. Run the following commands:
-```shell
-# Clone the repo
-git clone https://github.com/MIT-SPARK/TEASER-plusplus.git
-
-# Configure and compile
-cd TEASER-plusplus && mkdir build
-cd build
-cmake ..
-make
-
-# Generate doxygen documentation in doc/
-make doc 
-
-# Run tests
-ctest
-
-# Install shared libraries and headers
-sudo make install
-```
-
-### Available CMake Options
-Here are the available CMake options you can turn on/off during configuration:
-
-| 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_MARCH_NATIVE`| Build with flag `march=native` | OFF |
-|`ENABLE_DIAGNOSTIC_PRINT`| Enable printing of diagnostic messages | OFF |
-
-For example, if you want to build with the `march=native` flag (potentially faster at a loss of binary portability), run the following script for compilation:
-```shell script
-cmake -DBUILD_WITH_MARCH_NATIVE=ON ..
-make
-```
-Notice that by default the library is built in release mode. To build with debug symbols enabled, use the following commands:
-```shell script
-cmake -DCMAKE_BUILD_TYPE=Debug ..
-make
-```
-
-### Run Tests
-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 tests and benchmarks (for speed & accuracy tests), you can execute the following command:
-```shell
-# Run all tests
-ctest 
-
-# Run benchmarks
-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++ 
-### In CMake-based C++ Projects
-When installing TEASER++, CMake will export the following targets that can be included in other CMake projects using `find_package()`:
-- `teaserpp::teaser_registration`: the core registration library
-- `teaserpp::teaser_io`: library for importing `.ply` files
-- `teaserpp::teaser_features`: convenience wrappers around the PCL FPFH library, and simple feature matching functions
-
-A minimally-working `CMakeList.txt` looks something like this:
-```cmake
-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 teaserpp::teaser_io)
-```
-
-In the `examples/` folder, you can find two C++ examples that can be compiled with CMake:
-- [`teaser_cpp_ply`](/examples/teaser_cpp_ply): showing how to import `.ply` files and perform registration with TEASER++
-- [`teaser_cpp_fpfh`](/examples/teaser_cpp_fpfh): showing how to use TEASER++ with FPFH features
-
-### In Python
-In the `examples/` folder, you can find two C++ examples that can be compiled with CMake:
-- [`teaser_python_ply`](/examples/teaser_python_ply): showing how to import `.ply` files and perform registration with TEASER++ and Open3D
-- [`teaser_python_3dsmooth`](/examples/teaser_python_3dsmooth): showing how to use TEASER++ on descriptors generated by [3DSmoothNet](https://github.com/zgojcic/3DSmoothNet) on the 3DMatch dataset, with Open3D visualization
-
-For a short documentation on how to use the Python bindings for TEASER++, please refer to [this](python/README.md) document.
-
-### In MATLAB
-For a short documentation on how to use the MATLAB bindings for TEASER++, please refer to [this](matlab/README.md) document.
-
-### In ROS
-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=${MAX_THREADS}` (replace ${MAX_THREADS} with the maximum number of threads available on your machine) in your current shell. You can also just prepend `OMP_NUM_THREADS=${MAX_THREADS}` 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.
+- Installation
+  - [Dependencies](https://teaser.readthedocs.io/en/latest/installation.html#installing-dependencies)
+  - [Compilation](https://teaser.readthedocs.io/en/latest/installation.html#compilation-and-installation)
+  - [Install C++ Libraries](https://teaser.readthedocs.io/en/latest/installation.html#installing-c-libraries-and-headers)
+  - [Install Python Bindings](https://teaser.readthedocs.io/en/latest/installation.html#installing-python-bindings)
+  - [Install MATLAB Bindings](https://teaser.readthedocs.io/en/latest/installation.html#installing-matlab-bindings)
+  - [Run Tests](https://teaser.readthedocs.io/en/latest/installation.html#run-tests)
+- Usage
+  - [In C++](https://teaser.readthedocs.io/en/latest/quickstart.html#usage-in-c-projects)
+  - [In Python](https://teaser.readthedocs.io/en/latest/quickstart.html#usage-in-python-projects)
+  - [In MATLAB](https://teaser.readthedocs.io/en/latest/quickstart.html#usage-in-matlab-projects)
+  - [In ROS](https://teaser.readthedocs.io/en/latest/quickstart.html#usage-in-ros-projects)
+- API Documentation
+  - [C++](https://teaser.readthedocs.io/en/latest/api-cpp.html)
+  - [Python](https://teaser.readthedocs.io/en/latest/api-python.html)
+  - [MATLAB](https://teaser.readthedocs.io/en/latest/api-matlab.html)
 
 ## Other Publications
 Other publications related to TEASER include: