[WIP] feature/python_module : Adding libpointmatcher's Python bindings (#222)

CMakeLists.txt

@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 2.8.11)
+cmake_minimum_required(VERSION 2.8.12)
 
 include(CheckSymbolExists)
 
@@ -446,6 +446,14 @@ if (BUILD_TESTS)
 	add_subdirectory(utest)
 endif()
 
+# ========================= Python module =============================
+option(BUILD_PYTHON_MODULE "Build the python module for libpointmatcher" OFF)
+set(PYTHON_INSTALL_TARGET "" CACHE PATH "Target where to install the python module")
+
+if (BUILD_PYTHON_MODULE)
+	add_subdirectory(python)
+endif()
+
 #=================== allow find_package() =========================
 #
 # the following case be used in an external project requiring libpointmatcher:

doc/CompilationPython.md

@@ -0,0 +1,189 @@
+| [Tutorials Home](index.md) | [Previous](ImportExport.md) | [Next](PythonModule.md) |
+| :--- | :---: | ---: |
+
+# Compiling libpointmatcher with python
+
+This tutorial presents the different steps of compiling pypointmatcher, the libpointmatcher's python module, on Ubuntu and Mac OS X.
+
+## Prerequisites
+
+To get started, you will obviously need the same prerequisites as libpointmatcher, but also some additional dependencies as listed here :
+
+| Name | Version <br> (Tested August 2020 on Ubuntu 18.04) |
+| :--- | :---: |
+| pybind11 | 2.5.0 |
+| Python3 | 3.6.9 |
+|||
+| **Dependencies** | |
+| catch | 1.10.0 |
+| python3-dev | 3.6.7 |
+| pytest | 5.4.3 |
+
+`catch` and `python3-dev` need to be installed with the package manager :
+
+```bash
+sudo apt install catch python3-dev
+```
+
+and `pytest` with `pip` :
+
+```bash
+pip3 install pytest
+```
+
+> ***Note :*** pybind11 is also compatible with Python2.7, which means that it is also possible to generate a module for Python2.7. But, this hasn't been tested. You can refer to the pybind11 [official documentation](https://pybind11.readthedocs.io/en/latest/index.html) for more informations on what you can do with pybind11 and how to do it.
+
+The rest of this tutorial will guide you through the necessary steps to compile pypointmatcher.
+
+## pybind11
+
+In order to be able to compile pypointmatcher, you must either install pybind11 on your system or add it as a git submodule in the libpointmatcher's `/contrib` directory. You must then create a symbolic link to this git submodule in the python directory. Go [here](#installing-pybind11) for the installation steps or [here](#adding-pybind11) for the git sudmodule steps.
+
+### Installing pybind11 (recommended) <a name="installing-pybind11"></a>
+
+The very first step is to clone pybind11 [repository](https://github.com/pybind/pybind11) into a directory of your choice.
+
+ At the moment, pypointmatcher can only be compiled with **version 2.5.0** of pybind11. To install the right version, run the following commands :
+
+ ```bash
+ cd pybind11
+ git checkout v2.5.0
+ ```
+
+Once this is done, run the following commands :
+
+```bash
+mkdir build && cd build
+cmake ..
+make check -j 4
+```
+
+This will both compile and run the pybind11 tests. Next, you can install pybind11 by running this command :
+
+```bash
+sudo make install
+```
+
+Once this is done, return to libpointmatcher's `/build` directory.
+
+You're now ready to proceed to the [configuration step](#configuration).
+
+### Adding pybind11 as a `git` submodule <a name="adding-pybind11"></a>
+
+An alternative to installing pybind11 on your system is to add its repository as a git submodule and create a symbolic link into the python directory. To do this, you will first need to clone the repository as a git submodule by running the following commands in your terminal from the contrib directory.
+
+```bash
+cd contrib
+git submodule add https://github.com/pybind/pybind11.git
+```
+
+This will add pybind11 as a git submodule of libpointmatcher into the contrib directory. Then, still from the contrib directory, run this command to create a symbolic link to pybind11 in the python directory :
+
+```bash
+ln -sr pybind11 ../python/pybind11
+```
+
+At the moment, pypointmatcher can only be compiled with **version 2.5.0** of pybind11. To install the right version, run the following commands :
+
+```bash
+cd pybind11
+git checkout v2.5.0
+```
+
+Before going any further, the `CMakeLists.txt` file from the `/python` directory needs to be modified as follows :
+
+```cmake
+#find_package(pybind11 2.5.0 REQUIRED)
+add_subdirectory(pybind11) # add this line
+
+# Everything in between remains unchanged
+
+#if (pybind11_FOUND)
+#    message(STATUS "pybind11 v${pybind11_VERSION}")
+
+    pybind11_add_module(pypointmatcher ${PYBIND11_SOURCES})
+
+    target_link_libraries(pypointmatcher
+                          PRIVATE
+                          pointmatcher
+                          ${EXTERNAL_LIBS})
+
+    add_dependencies(pypointmatcher pointmatcher)
+
+    install(TARGETS pypointmatcher LIBRARY DESTINATION ${PYTHON_INSTALL_TARGET})
+#else ()
+#	message(FATAL_ERROR "pybind11 is required! Please follow the \"Compiling \
+#libpointmatcher's with python\" instructions from the official libpointmatcher's documentation.")
+#endif ()
+```
+
+> ***IMPORTANT :*** When this method is used, it is very important to checkout the version **2.5.0** of pybind11 or it will be impossible to generate the build files.
+
+Once this is done, return to libpointmatcher's `/build` directory.
+
+You're now ready to proceed to the [configuration step](#configuration).
+
+## Configuring the variables <a name="configuration"></a>
+
+> ***Note :*** *It is recommended to create a virtual python environment before proceeding with the next steps.*
+
+#### Specifying the path
+
+First, you need to specify where you want the module to be installed. To do so, you must provide the path by setting the CMake variable `PYTHON_INSTALL_TARGET` with an absolute path to your python's environment `site-packages` location. This can be achieve manually or automatically.
+
+##### The manual way :
+
+Launch the python interpreter and run the following commands to find the path to the `/site-packages` directory :
+
+```bash
+>>> import site
+>>> site.getsitepackages()
+```
+
+> ***Note :*** If you are using the system's python environment, replace the `getsitepackages()` function call by `getusersitepackages()`.
+
+This will output a list of installation's path for your current python environment. Now, choose the one that is located in the `python_env_path/lib/python3.x` directory. The command to run should looks like this :
+
+```bash
+cmake -D PYTHON_INSTALL_TARGET=python_env_path/lib/python3.x/site-packages ..
+```
+
+##### The automatic way :
+
+If you don't want to set the path manually, here's a command that should automatically pick the right one for you :
+
+```bash
+cmake -D PYTHON_INSTALL_TARGET=$(python3 -c "import site; print(site.getsitepackages()[0])") ..
+```
+
+> ***Note :*** If you are using the system's python environment, replace the `site.getsitepackages()[0]` by `site.getusersitepackages()`.
+
+> ***IMPORTANT :*** *This last example is the default behavior if no path has been set before compiling the module.* ***Please, make sure that this correspond to a valid location or this will lead to an import error.***
+
+#### Enabling the compilation
+
+By default, pypointmatcher compilation is disabled. In order to compile it, you must set the CMake variable `BUILD_PYTHON_MODULE` to `ON` :
+
+```bash
+cmake -D BUILD_PYTHON_MODULE=ON ..
+```
+
+Everything is now set up to proceed to the compilation and the installation.
+
+## Compilation
+
+Now, to compile pypointmatcher into the `/build` directory, run the following command:
+
+```bash
+make pypointmatcher -j N
+```
+
+***Note :*** *Depending on your system, the compilation can take quite some time, so consider leaving the `-j` command with no argument in order to speed up this step.*
+
+## Installation
+
+And finally, to install the module on your system, run the following command :
+
+```bash
+sudo make install
+```

examples/align_sequence.cpp

@@ -58,8 +58,8 @@ int main(int argc, char *argv[])
 {
 	validateArgs(argc, argv);
 
-	typedef PointMatcher<float> PM;
-	typedef PointMatcherIO<float> PMIO;
+	typedef PointMatcher<double> PM;
+	typedef PointMatcherIO<double> PMIO;
 	typedef PM::TransformationParameters TP;
 	typedef PM::DataPoints DP;
 

examples/build_map.cpp

@@ -61,8 +61,8 @@ int main(int argc, char *argv[])
 {
 	validateArgs(argc, argv);
 
-	typedef PointMatcher<float> PM;
-	typedef PointMatcherIO<float> PMIO;
+	typedef PointMatcher<double> PM;
+	typedef PointMatcherIO<double> PMIO;
 	typedef PM::TransformationParameters TP;
 	typedef PM::DataPoints DP;
 

examples/compute_overlap.cpp

@@ -58,8 +58,8 @@ int main(int argc, char *argv[])
 {
 	validateArgs(argc, argv);
 
-	typedef PointMatcher<float> PM;
-	typedef PointMatcherIO<float> PMIO;
+	typedef PointMatcher<double> PM;
+	typedef PointMatcherIO<double> PMIO;
 	typedef PM::Matrix Matrix;
 	typedef PM::TransformationParameters TP;
 	typedef PM::DataPoints DP;

examples/filterProfiler.cpp

@@ -15,7 +15,7 @@ using namespace PointMatcherSupport;
 using namespace std;
 using namespace boost;
 
-typedef PointMatcher<float> PM;
+typedef PointMatcher<double> PM;
 typedef PM::DataPoints DP;
 typedef PM::Parameters Parameters;
 

examples/icp.cpp

@@ -45,7 +45,7 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 using namespace std;
 
-typedef PointMatcher<float> PM;
+typedef PointMatcher<double> PM;
 typedef PM::DataPoints DP;
 typedef PM::Parameters Parameters;
 typedef PointMatcherSupport::CurrentBibliography CurrentBibliography;

examples/icp_advance_api.cpp

@@ -46,7 +46,7 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 using namespace std;
 using namespace PointMatcherSupport;
 
-typedef PointMatcher<float> PM;
+typedef PointMatcher<double> PM;
 typedef PM::DataPoints DP;
 typedef PM::Parameters Parameters;
 

examples/icp_customized.cpp

@@ -56,7 +56,7 @@ int main(int argc, char *argv[])
 	bool isCSV = true;
 	validateArgs(argc, argv, isCSV);
 
-	typedef PointMatcher<float> PM;
+	typedef PointMatcher<double> PM;
 	typedef PM::DataPoints DP;
 
 	// Load point clouds

examples/icp_simple.cpp

@@ -51,7 +51,7 @@ int main(int argc, char *argv[])
 	bool isCSV = true;
 	validateArgs(argc, argv, isCSV);
 
-	typedef PointMatcher<float> PM;
+	typedef PointMatcher<double> PM;
 	typedef PM::DataPoints DP;
 
 	// Load point clouds

examples/list_modules.cpp

@@ -40,7 +40,7 @@ using namespace std;
 using namespace PointMatcherSupport;
 
 typedef PointMatcherSupport::Parametrizable::ParametersDoc ParametersDoc;
-typedef PointMatcher<float> PM;
+typedef PointMatcher<double> PM;
 
 void printBibliographyHeader(const CurrentBibliography::Mode mode)
 {

examples/python/icp.py

@@ -0,0 +1,56 @@
+import numpy as np
+
+from pypointmatcher.pointmatcher import PointMatcher
+from examples.python.utils import parse_translation, parse_rotation
+
+PM = PointMatcher
+DP = PM.DataPoints
+
+config_file = "../data/default.yaml"
+output_base_file = "tests_output/icp/"
+is_3D = True
+init_translation = "1,1,1" if is_3D else "1,1"
+init_rotation = "1,0,0;0,1,0;0,0,1" if is_3D else "1,0;0,1"
+
+if is_3D:
+    # 3D point clouds
+    ref = DP.load('../data/car_cloud400.csv')
+    data = DP.load('../data/car_cloud401.csv')
+    test_base = "3D"
+else:
+    # 2D point clouds
+    ref = DP.load('../data/2D_twoBoxes.csv')
+    data = DP.load('../data/2D_oneBox.csv')
+    test_base = "2D"
+
+icp = PM.ICP()
+
+icp.loadFromYaml(config_file)
+# icp.setDefault()
+
+cloud_dimension = ref.getEuclideanDim()
+
+assert cloud_dimension == 2 or cloud_dimension == 3, "Invalid input point clouds dimension"
+
+translation = parse_translation(init_translation, cloud_dimension)
+rotation = parse_rotation(init_rotation, cloud_dimension)
+init_transfo = np.matmul(translation, rotation)
+
+rigid_trans = PM.get().TransformationRegistrar.create("RigidTransformation")
+
+if not rigid_trans.checkParameters(init_transfo):
+    print("Initial transformations is not rigid, identiy will be used")
+    init_transfo = np.identity(cloud_dimension + 1)
+
+initialized_data = rigid_trans.compute(data, init_transfo)
+
+T = icp(initialized_data, ref)
+
+data_out = DP(initialized_data)
+icp.transformations.apply(data_out, T)
+
+ref.save(output_base_file + f"{test_base}_test_ref.vtk")
+data.save(output_base_file + f"{test_base}_test_data_in.vtk")
+data_out.save(output_base_file + f"{test_base}_test_data_out.vtk")
+
+print(f"{test_base} ICP transformation:\n{T}".replace("[", " ").replace("]", " "))