Installation¶

Docker¶

The easiest way of using PyMesh is through docker, where one can simply pull a prebuild image of PyMesh from dockerhub:

$ docker run -it pymesh/pymesh
Python 3.6.4 (default, Dec 21 2017, 01:35:12)
[GCC 4.9.2] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import pymesh
>>>

Download the Source¶

The source code can be checked out from GitHub:

git clone https://github.com/PyMesh/PyMesh.git
cd PyMesh
git submodule update --init
export PYMESH_PATH=`pwd`

The rest of the document assumes PyMesh is located at $PYMESH_PATH.

Dependencies¶

PyMesh is based on the design philosophy that one should not reinvent the wheel. It depends a number of state-of-the-art open source libraries:

System dependencies¶

Python: v2.7 or higher
NumPy: v1.8 or higher
SciPy: v0.13 or higher
Eigen: v3.2 or higher
TBB: 2018 Update 1 or later
GMP: v6.1 or higher
MPFR: v4.0 or higher
Boost: 1.6 or higher (thread, system)

On Linux, the system dependencies can be installed with apt-get:

apt-get install \
    libeigen3-dev \
    libgmp-dev \
    libgmpxx4ldbl \
    libmpfr-dev \
    libboost-dev \
    libboost-thread-dev \
    libtbb-dev \
    python3-dev

On MacOS, the system dependencies can be installed with MacPorts:

port install
    python36 \
    eigen3 \
    gmp \
    mpfr \
    tbb \
    boost

Python dependencies such as NumPy and SciPy can be installed using pip:

pip install -r $PYMESH_PATH/python/requirements.txt

Third party dependencies¶

The following third-party libraries are not required, but highly recommended in order to use the full power of Pymesh. PyMesh provides a thin wrapper to these libraries, and without them certain functionalities would be disabled. Most of these packages can be easily installed using package management softwares for your OS. A copy of these libraries are also included in the third_party direcgtory.

SparseHash: is used to speed up hash grid.
CGAL: is needed for self-intersection, convex hull, outer hull and boolean computations.
tetgen: is needed by tetrahedronization and wire inflation.
libigl: is needed by outer hull, boolean computations and wire inflation.
cork: is used by boolean computation.
triangle: is used by triangulation and 2D wire inflation.
qhull: is used for computing convex hull.
Clipper: is used for 2D boolean operations.
Carve: is used for 3D boolean operations. Minor modification is added by me for linux/mac compilation.
GeoGram: is used as a 2D triangle and 3D tetrahedron generation engine.
Quartet: is used as a 3D tetrahedralization engine.
MMG3D: is used as a 3D tetrahedralizaiton optimization engine.

All third party libraries are attached to the repo as submodules. They are built as part of PyMesh automatically. See Building PyMesh section for more instructions.

Environment Variables¶

If any dependent libraries are not installed in the default locations, e.g. /usr/local and opt/local, one needs to set certain environment variables that help PyMesh locate the libraries. PyMesh check the following environment variables:

EIGEN_INC: directory containing the Eigen library.
GOOGLEHASH_INCLUDES: directory containing sparse hash.
CGAL_PATH: path to CGAL library.
BOOST_INC: directory containing boost.
LIBIGL_PATH: path to libigl.
CORK_PATH: path to cork.
TETGEN_PATH: path to tetgen.
TRIANGLE_PATH: path to triangle.
QHULL_PATH: path to qhull.
CLIPPER_PATH: path to clipper.
CARVE_PATH: path to carve.
GEOGRAM_PATH: path to GeoGram.
QUARTET_PATH: path to Quartet.

Building PyMesh¶

Build with Setuptools¶

Setuptools builds both the main PyMesh module as well as all third party dependencies. To build PyMesh:

./setup.py build

Build with CMake¶

If you are familar with C++ and CMake, there is an alternative way of building PyMesh. First compile and install all of the third party dependencies:

cd $PYMESH_PATH/third_party
mkdir build
cd build
cmake ..
make
make install

Third party dependencies will be installed in $PYMESH_PATH/python/pymesh/third_party directory.

It is recommended to build out of source, use the following commands setup building environment:

cd $PYMESH_PATH
mkdir build
cd build
cmake ..

PyMesh consists of several modules. To build all modules and their corresponding unit tests:

make
make tests

PyMesh libraries are all located in $PYMESH_PATH/python/pymesh/lib directory.

Install PyMesh¶

To install PyMesh in your system:

./setup.py install  # May require root privilege

Alternatively, one can install PyMesh locally:

./setup.py intall --user

Post-installation check¶

To check PyMesh is installed correctly, one can run the unit tests:

python -c "import pymesh; pymesh.test()"

Please make sure all unit tests are passed, and report any unit test failures.