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 need the same prerequisites as libpointmatcher, but also some additional dependencies as listed here:
Name |
Version |
|---|---|
pybind11 |
2.5.0 |
Python3 |
3.10.12 |
python3-dev |
3.10.6 |
catch |
1.12.1 |
pytest |
7.4.2 |
Note: This guide assumes you’re using a virtual python environment. For this, you can use the virtualenv tool. If you are not familiar with Python virtual environments, you can read this tutorial, which explains very well the reasons for using a virtual environment, or watch this video tutorial
Install pytest with pip:
pip3 install pytest wheel build
And catch and python3-dev with your package manager:
=== “Ubuntu”
bash sudo apt install catch python3-dev
=== “MacOS”
bash brew install catch2
Case-sensitivity
Note that to build pypointmatcher, your filesystem must be case-sensitive.
This applies especially to MacOS, where the APFS is case-insensitive for legacy reasons.
To overcome this, open Disk Utility and add a new case-sensitive APFS volume to your container.
Then, move libpointmatcher to the new volume.
The rest of this tutorial will guide you through the necessary steps to compile pypointmatcher.
pybind11
pybind11 is a library used to create Python bindings of existing C++ code and vice versa. So, 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 for the installation steps or here for the git sudmodule steps.
Installing pybind11
The very first step is to clone pybind11 into a directory of your choice.
At the moment, pypointmatcher is only tested for compilation with version 2.5.0 of pybind11. To install the right version, run the following commands:
cd pybind11
git checkout v2.5.0
Once this is done, run the following commands:
mkdir build && cd build
cmake ..
# With multiple versions of python3
# cmake -DPYTHON_EXECUTABLE=$(python3.6 -c "import sys; print(sys.executable)") ..
make check -j 4
This will both compile and run pybind11 tests. Next, you can install pybind11 by running this command:
sudo make install
Once this is done, return to libpointmatcher’s build/ directory.
You’re now ready to proceed to the configuration step.
Configuring the variables
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:
cmake -DBUILD_PYTHON_MODULE=ON ..
Everything is now set up to proceed to the compilation and the installation.
Note If you want to compile boost with static linkage, then make sure that it was compiled with position independent code. pybind compiles dynamic library. Static linking in dynamic library can be done if the static library was compiled with position independent code.
Compilation
Now, to compile pypointmatcher into the build/ directory, run the following command:
make -j 4
sudo make install
Installation
To install the module on your system, first open the python directory:
cd <my-project-folder>/libpointmatcher/python
and install the bindings through pip:
python3 -m build --wheel --no-isolation --outdir /tmp/libpointmatcher
pip3 install /tmp/libpointmatcher/pypointmatcher-*.whl
Finally, verify that pypointmatcher can be imported as a regular Python package:
python -c "from pypointmatcher import *"