-
Notifications
You must be signed in to change notification settings - Fork 0
Home
This repository contains software for binding CGAL TAU components (written in C++) with Python. It also contains examples, tests, and benchmarks.
We have compared three different products to create Python bindings, namely:
- Boost Python
- Pybind11
- **Swig **
We have concluded that **Boost Python ** has an advantage over its rivals. First, CGAL depends on Boost, so the latter is already a requirement. *Swig ** uses a proprietary dedicated language to describe the bindings. It supports bindings to many scripting languages. However, this profusion is not an advantage for us, as we are only interested in Python. Pybind11 and *Boost Python ** use C++ generic programming to describe the bindings. They have the same interface. While Pybind11 exploits more generic-programming features, it is less efficient space and time wise. Pybind11 is headers only, and does not depend on anything, while Boost Python depends on, well, Boost. However, CGAL already depends on Boost; thus, this dependency cannot be lifted.
Naturally, you need to install Python and CGAL before attempting to use the bindings.
We use Python 3.7.
If Python 3.7 is the default version for you Ubuntu distribution, proceed to install Python via the standard apt-get installation procedure. Otherwise, jump to install Python from a PPA.
Install Pip once via a dedicated procedure and then upgrade via Pip. Install Python modules via Pip.
#!bash
# Install Python 3
> sudo apt-get install -y python3 python3-dev
# Verify
> python3 --version
# Set up your system to build binary Python packages
# Install Pip
> curl -LO https://bootstrap.pypa.io/get-pip.py
> python3 get-pip.py --user
# Upgrade (not really necessary---already up-to-date)
> pip3 install -U pip --user
# Verify
> pip3 --version
> which pip3
# Install popular Python packages
> pip3 install --user numpy
> pip3 install --user pipenv
> pip3 install --user pytest
> pip3 install --user pybind11
#!bash
> add-apt-repository ppa:deadsnakes/ppa
> apt-get update
> apt-get install -y python3.7 python3.7-dev
> curl -LO https://bootstrap.pypa.io/get-pip.py
> python3.7 get-pip.py
> pip3.7 install -U pip
> pip3.7 install --user numpy
> pip3.7 install --user pipenv
> pip3.7 install --user pytest
> pip3.7 install --user pybind11
As aformentioned Boost is a dependency of CGAL. When you install CGAL, it is recommended installing all Boost components. If not installed already though, install the Python component python37.
Python bindings requires Boost version 1.71 or higher. If Boost 1.72 or higher is the default version of you Ubuntu distribution, proceed to install Boost via the standard apt-get installation procedure. Otherwise, jump to install Boost from sources.
#!bash
> sudo apt-get install libboost-all-dev
The following installs version 1.72 to /usr/local. While only the Boost libraries bellow are required, it is recommended that you install all.
#!bash
# Install Boost
> mkdir -p ~/tmp/src/boost
> cd ~/tmp/src
> curl -SL boost_1_72_0.tar.gz https://sourceforge.net/projects/boost/files/boost/1.72.0/boost_1_72_0.tar.gz | tar -xzC boost
> cd ~/tmp/src/boost/boost_1_72_0
> ./bootstrap.sh --with-python=python3.7 --with-python-version=3.7
> ./b2 --with=all -j4
# Install to /usr/local
> sudo ./b2 install
# Clean
> rm -rf ~/tmp/src/boost
Pybind11 is used only by the benchmark to compare the performance of the various binding methods. It is not needed if you are only interested in the CGAL bindings themselves. Pybind11 is a header-only product.
The PYBIND11_DIR environment variable is used by the CMakeLists.txt file to build the Pybind11 bindings.
#!bash
# Obtain the pybind11 sources
> git clone https://github.com/pybind/pybind11.git
# Set the PYBIND11_DIR environment variable to point at the header directory
> export PYBIND11_DIR <pybind11-root-directory>/include
The CGAL library is huge. It consists of many function and class templates. It follows the generic programming paradigm, which implies that many decision the programmer has to take are resolved during compile time. Bindings occur at run time, and the C++ objects that are bound, must be known ahead. Specifically, they must be instances (instantiated types) of C++ function and class templates. This makes the set of potential objects to bind enormous. Our objective is to enable bindings, of a great portion of this set, concurrently in a convenient way. It is possible to generate, for example, a single library that realizes bindings for 2D arrangements and 2D triangulations. If several instances of the same template must be bound, several corresponding libraries must be generated. By default, the name of the generated library is cgalpy.so. However, the user can override the name with a string that indicates the instances bound. This is useful when more then one instance of the same template must be bound. Each execution of cmake followed by make generates a single library. The content of the library and its name are governed by flags provided to cmake.