Introduction to PyGEL

J. Andreas Bærentzen, January 2019

This Jupyter Notebook is an introduction to the PyGEL Python library for geometry processing. PyGEL provides Python bindings for a subset of the C++ based GEL library.

PyGEL is a package consisting of two modules:

  • The gel module:
    • The Manifold class: the class that provides our halfedge mesh representation.
    • The GLManifoldViewer class: an OpenGL based viewer for Manifold.
    • The I3DTree class: a kD-tree data structure for 3D point clouds.
    • The MeshDistance class: a data structure for signed distance queries.
    • A fairly rich library of functions are available for the Manifold class, allowing users to load, save, simplify, optimize, triangulate, refine, or otherwise manipulate general polygon meshes.
  • The js module:
    • Contains only the display function which creates an HTML/WebGL plot that can be shown inside a Jupyter Notebook. This function is based on Plotly.

This text provides a brief introduction to PyGEL. If you are planning to use PyGEL, please also cast a glance at the PyGEL Reference Documentation. All features of the API are concisely described in the reference.

PyGEL Installation

PyGEL is now available on the Python Package Index (PyPI) and can be installed via pip:

$> pip install PyGEL3D

There is another package called PyGEL on the package index. To disambiguate, PyGEL from geometry processing is now called PyGEL3D in th PyPi package index.

If your prefer to install from source, you can download GEL and PyGEL from Github. In this case, you can create a wheel (Python package) and install that with pip. Please see instructions on the github repository.

Python Distribution and Required Packages

It is recommended that you either use the standard distribution from Python.org or the Anaconda distribution. Anaconda may make it a little easier to install the packages that you need and it also has the advantage that you can install everything as a user with no administrator priviliges. That being said, the regular Python distribution should also work well for PyGEL. In either case, Pip is the tool you would need to install PyGEL unless installing from source.

Regardless of distribution, you need to have NumPy and Plotly (for Python) installed and Jupyter notebook. Try to make sure that you have the most recent versions of both packages. Furthermore, to make Plotly work on Jupyter, you need the right extensions. Consult the Plotly github page for details: https://github.com/plotly/plotly.py/.

PyGEL: Rationale and Design

The GEL library was created by Andreas Bærentzen with significant contributions from colleagues at the Image Analysis and Computer Graphics Section of the Computer Science and Applied Mathematics Department at The Technical University of Denmark. The library has been used for several research projects and as the basis for exercises in a long running course on Geometry Processing. The GEL library is also the recommended platform for solving problems from our book "Guide to Computational Geometry Processing". However, GEL is a C++ library and while that has not been a big limitation in the past, we wanted to offer a geometry processing course in a more general form and to undergraduates. In this context, it seemed prudent to switch to Python. While there are several other geometry processing libraries with Python bindings, it turned out to be surprisingly straight forward to use ctypes to develop Python bindings for GEL and since none of the other options seemed to be a drop in replacement, we decided to create PyGEL.

The scope of PyGEL is a little narrower than the scope of GEL. For instance, PyGEL does not contain voxel grids or a vector matrix library for 2,3, and 4D vectors and matrices. To a large extent this is because C++ libraries often work best if they have few dependencies whereas this appears to be a bit less of a concern with Python where most of the packages we need can be installed with ease using e.g. pip. If you happen to have a strong interest in some of the choices that led to how PyGEL was developed, the process is documented here

Perhaps, the pivotal feature of GEL, and by extension PyGEL, can be said to be HMesh - the polygonal mesh representation. HMesh is halfedge based. Originally, the halfedge representation was chosen since it is more efficient than the older winged edge representation while also making connectivity information readily available. Furthermore, the halfedge representation makes it trivial to support polygons with arbitrary numbers of edges. From an implementation point of view, many operations are probably harder to implement than for simpler mesh representations, but at this point, the GEL code base seems fairly robust while offering a rich set of mesh manipulation operations.

An important concern was to be able to run PyGEL inside a Jupyter Notebook. It is probably best to use a programming editor or an IDE to develop code, but for presentation purposes, the ability provided by JN to mix code, output from code, and text is very hard to beat. One big stumbling block was that we wanted students to be able to show 3D models inside a Jupyter Notebook. Several frameworks ostensibly make this possible, but because of subtle bugs almost none of these do so in a way that allows the 3D model to survive into a static HTML page generated from the Notebook. One exception turned out to be Plotly. HTML pages generated from ipynb files using the Nbconvert program would actually retain interactive views of 3D models. Thus, the PyGEL package contains a module called js with a single function that converts a mesh into an interactive view, embedded in the notebook. One - absolutely maddening - caveat, though, is that LaTeX formulas in the Markdown text remain LaTeX code when you do that. There is some bug which causes MathJax to be unintentionally neutralized by Plotly. Hopefully, that will be resolved, but for now the bug remains.

Loading and viewing a mesh

Clearly for anything to work, the path must be correct: the working directory of your script should be where the mesh files are placed.

In [1]:
import os
os.chdir("../data")

To use PyGEL you need to import the appropriate module. The code below starts by doing that, then it loads a mesh called m, creates a GLManifoldViewer called viewer, and, finally, it displays m using viewer

In [2]:
from PyGEL3D import gel
from PyGEL3D import js
# Uncomment before exporting to HTML: 
js.set_export_mode()
m = gel.obj_load("bunnygtest.obj")
viewer = gel.GLManifoldViewer()
viewer.display(m)