plCurve: Fast polygon library

by Ted Ashton, Jason Cantarella, Harrison Chapman, and Tom Eddy.

plCurve is a library for efficiently handling polygonal space curves. It allows curves to be open or closed, and to contain multiple components. In addition, curves (or sections of curves) may be constrained to lie at particular points, on particular lines, or in particular planes. To support operations on plCurves, the library provides a fully functional linear algebra package for vectors in 3-space, including vector arithmetic, dot and cross products, and higher-level operations such as taking linear combinations of vectors. The library also supports splining plCurves and reading and writing them to disk. The file format used by plCurve is the Geomview VECT format, which is a simple human-readable format for space polygons.

plCurve is written in syntax-checked ANSI C, and is valgrind-clean for memory bugs. The package is built using the GNU Autotools and installs in the standard way. The argtable2 library is required for the demonstration programs included with plCurve.

plCurve is currently supported and actively developed. The current roadmap for development is to switch the main interface to Python, and then to build new functionality into the library in Python, so the interface will shift to Python in the next version. We will be adding more topological invariants (via SnapPy) after the shift.

Programmer’s Introduction

The main data types in the plCurve library are the plc_vector and plCurve types. The plc_vector is a struct containing one field: an array c of 3 doubles giving the components of the vector in R^3. These vectors can be added, subtracted, and so forth with the functions described in plCurve.h.

The plCurve data type is much more complicated, but is essentially a wrapper for an array of pointers to individual components. Most programmers will need to know:

Users should always allocate plCurve *, rather than plCurve variables. Library functions which create plCurves also allocate memory for the main data structure and the library function to destroy plCurves, plc_free, expects to deallocate the pointer to plCurve which it is passed.

If C is of type plCurve *, then

There is a limited form of wraparound addressing in plCurves. If C->cp[i].nv = N and the component is closed, C->cp[i].vt[-1] is equal to the last vertex of the curve and C->cp[i].vt[N] is equal to the first vertex. If the component is open, then C->cp[i].vt[-1] = C->cp[i].vt[0] and C->cp[i].vt[N] = C->cp[i].vt[N-1]. These provisions make for much cleaner and nicer code, and extensive experience with geometric programming for polygons tells us that these conventions are usually what you want to happen. However, in order to implement this functionality, programmers should only modify in-range vertex addresses and they must call plc_fixwrap anytime they directly modify the vertices of a plCurve in order to make sure that wraparound addresses work properly on subsequent reads of the same plCurve.

Python module ‘libpl

If Python dependencies are met and bindings not disabled on compile, a Python module libpl is built. At this time, most functionality of pd_code_t is supported. Headers are included to call some Python-implemented procedures from C. An introduction to, and links to the documentation for, the Python wrappings can be found here.

Overview of Functionality

Download

The latest plCurve can be obtained from the subversion repository. Point releases tend to lag behind the subversion build, but are included below for convenience. Note that you’ll need the GNU Autotools in order to build from subversion.