-
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. 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 your 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 aforementioned 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.72 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
cmake is used to build CGAL and applications that depends on CGAL. The minimun required version is 3.7.
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.
#!bash
# RUN apt-get install -y cmake
#!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
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 CGALPY_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. The 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 2D triangulation instances |
TRIANGULATION_3_BINDING |
Boolean | false |
Determines whether to generate bindings for 3D triangulation instances |
| Name | Type | Default | Description |
|---|---|---|---|
KERNEL_NAME |
String | epic |
The kernel used, either epic, epec, or epecws
|
2D Arrangement Arguments
| Name | Type | Default | Description |
|---|---|---|---|
ARR2_GEOMETRY_TRAITS_NAME |
String | segment |
The geometry traits of a 2D arrangement. Options are: linear, segment, nonCachingSegment, conic, algebraic, or circleSegment
|
ARR2_DCEL_NAME |
String | allExtended |
The DCEL of a 2D arrangement. Options are: plain, faceExtended, halfedgeExtended, vertexExtended, allExtended
|
ARR2_POINT_LOCATION_BINDINGS |
Boolean | true |
Determines whether to generate bindings for point location and vertical ray shoot queries |
3D Triangulation Arguments
| Name | Type | Default | Description |
|---|---|---|---|
TRI3_NAME |
String | regular |
The 3D triangulation type; options are: plain, regular, delaunay, or periodic3Delaunay
|
TRI3_VERTEX_BASE_NAME |
String | plain |
Options are: plain, plainWithInfo, regular, regualrWithInfo alphaShape, alphaShapeWithInfo, alphaShapeRegular, alphaShapeRegularWithInfo, fixedAlphaShape, fixedAlphaShapeWithInfo, fixedAlphaShapeRegular, or fixedAlphaShapeRegularWithInfo
|
TRI3_CELL_BASE_NAME |
String | plain |
Options are: plain, plainWithInfo, regular, regualrWithInfo alphaShape, alphaShapeWithInfo, alphaShapeRegular, alphaShapeRegularWithInfo, fixedAlphaShape, fixedAlphaShapeWithInfo, fixedAlphaShapeRegular, or fixedAlphaShapeRegularWithInfo
|
| `TRI3_TRAITS_NAME | String | kernel |
The geometry traits of a 2D triangulation, either kernel or periodic3Delaunay
|
| `TRI3_CONCURRENCY_NAME | String | sequential |
The concurrency method, either sequential or parallel
|
| `TRI3_LOCATION_POLICY_NAME | String | compact |
The location policy, either fast or compact
|
3D Alpha Shape Arguments
| Name | Type | Default | Description |
|---|---|---|---|
AS3_NAME |
String | plain |
The 3D Alpha shape type, either plain or fixed
|
AS3_EXACT_COMPARISON |
Boolean | true |
Determines whether to apply exact comparisons |
Spatial Searching Arguments
| Name | Type | Default | Description |
|---|---|---|---|
SPATIAL_SEARCHING_DIMENSION |
Integer | 2 |
The dimension of spatial searching related classes |