Skip to content

Home

Jump to bottom
efifogel edited this page Jun 23, 2020 · 120 revisions

About CGAL TAU Python Bindings

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:

  1. Boost Python
  2. Pybind11
  3. 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.

Installing

Naturally, you need to install Python and CGAL before attempting to use the bindings.

Python & Pip

We use Python 3.7.

Ubuntu

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 Python via apt-get

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
Install Python 3.7 via PPA
#!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

Boost

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.

Ubuntu

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.

Install Boost via apt-get 
#!bash

> sudo apt-get install libboost-all-dev
Install Boost From Sources

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

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

cmake

cmake is used to build CGAL and applications that depends on CGAL. The minimun required version is 3.7.

Ubuntu

If cmake 3.7 or higher is the default version of you Ubuntu distribution, proceed to install cmake via the standard apt-get installation procedure. Otherwise, jump to install cmake from sources.

Install cmake via apt-get 
#!bash

# RUN apt-get install -y cmake
Install cmake from sources
#!bash

> mkdir -p ~/tmp/src/cmake
> cd ~/tmp/src
# Download
> curl -SL https://github.com/Kitware/CMake/releases/download/v3.13.2/cmake-3.13.2.tar.gz | tar -xzC cmake
> cd ~/tmp/src/cmake/cmake/cmake-3.13.2
# Build
> ./configure
> make install
# Clean
> rm -rf ~/tmp/src/cmake

CGAL Bindings

The CGAL library is huge. It consists of many function and class templates. It follows the generic programming paradigm, which implies that many decisions 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. With our system it is possible to generate, for example, a single library that contains bindings for an instance of the 2D arrangement class template and instance of the 2D triangulation class template. 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 meaningful 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 generated library is dynamically linked—it must be so. However, the library itself can be built while dynamically or statically linking its dependent libraries. If you intend to generate and use just a single library that contains the bindings, you have the freedom to choose between generating a library compiled of static libraries or dynamic libraries. However, if you intend to generate and use several libraries in a single Python module, it is recommended that you use libraries compiled of dynamic libraries. (Otherwise, different generated libraries might be compiled of conflicting static libraries.)

The content of the library and its name are governed by flags provided to cmake. There number of flags is already large, and it is expected to grow in the future. All flags have the prefix CGALPY_. In the following table this prefix is omitted.

Name Type Default Description
FIXED_LIBRARY_NAME Boolean true Determines whether the library name is fixed 'cgalpy.so' or set based on other selections
KERNEL_NAME String epic The kernel used, either epic, epec, or epecws
ARR_2D_BINDING Boolean false Determines whether to generate bindings for Arrangement_2<GeometryTraits, DCEL>
ARR_2D_DCEL_NAME String allExtended The DCEL of a 2D arrangement
ARR_2D_GEOMETRY_TRAITS_NAME String segment The geometry traits of a 2D arrangement

Benchmarks

Tests

Clone this wiki locally