Skip to content

Home

Jump to bottom
efifogel edited this page Jun 25, 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 compiled of either static or dynamic (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 cmake flag USE_SHARED_LIBS indicates whether the generated library is compiled of static or dynamic libraries; it is true by default.

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 tables this prefix is omitted.

General arguments

Name Type Default Description
USE_SHARED_LIBS Boolean true Determines whether to compile shared libraries
BUILD_SHARED_LIBS Boolean true Determines whether to generate shared libraries
FIXED_LIBRARY_NAME Boolean true Determines whether the library name is fixed 'cgalpy.so' or set based on other selections

Binding selection

Name Type Default Description
ARRANGEMENT_2_BINDING Boolean false Determines whether to generate bindings for 2D arrangement instances
ALPHA_SHAPE_3_BINDING Boolean false Determines whether to generate bindings for 3D Alpha shape instances
BOOLEAN_SET_OPERATIONS_2_BINDING Boolean false Determines whether to generate bindings for 2D Boolean set operation instances
BOUNDING_VOLUMES_BINDINGS Boolean false Determines whether to generate bindings for bounding volume instances
CONVEX_HULL_2_BINDINGS Boolean false Determines whether to generate bindings for 2D convex hull instances
CONVEX_HULL_3_BINDINGS Boolean false Determines whether to generate bindings for 3D convex hull instances
POLYGON_2_BINDINGS Boolean false Determines whether to generate bindings for 2D polygon instances
POLYGON_PARTITIONING_BINDINGS Boolean false Determines whether to generate bindings for 2D polygon partitioning instances
MINKOWSKI_SUM_2_BINDINGS Boolean false Determines whether to generate bindings for 2D Minkowski sum instances
SPATIAL_SEARCHING_BINDINGS Boolean false Determines whether to generate bindings for spatial searching instances
TRIANGULATION_2_BINDING Boolean false Determines whether to generate bindings for Triangulation_2<Traits, DS>
TRIANGULATION_3_BINDING Boolean false Determines whether to generate bindings for Triangulation_3<Traits, DS>
Name Type Default Description
KERNEL_NAME String epic The kernel used, either epic, epec, or epecws

2D Arrangement Arguments

Name Type Default Description
ARR_2_DCEL_NAME String allExtended The DCEL of a 2D arrangement
ARR_2_GEOMETRY_TRAITS_NAME String segment The geometry traits of a 2D arrangement

3D Triangulation Arguments

Name Type Default Description
TRI_3_NAME String regular Options are: plain, regular, delaunay, or periodic3Delaunay
TRI_3_VERTEX_BASE_NAME String plain Options are: plain, plainWithInfo, regular, regualrWithInfo alphaShape, alphaShapeWithInfo, alphaShapeRegular, alphaShapeRegularWithInfo, fixedAlphaShape, fixedAlphaShapeWithInfo, fixedAlphaShapeRegular, or fixedAlphaShapeRegularWithInfo
TRI_3_CELL_BASE_NAME String plain Options are: plain, plainWithInfo, regular, regualrWithInfo alphaShape, alphaShapeWithInfo, alphaShapeRegular, alphaShapeRegularWithInfo, fixedAlphaShape, fixedAlphaShapeWithInfo, fixedAlphaShapeRegular, or fixedAlphaShapeRegularWithInfo

3D Alpha Shape Arguments

Name Type Default Description
EXACT_COMPARISON Boolean Determines

Benchmarks

Tests

Clone this wiki locally