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 can be installed with autotools, using the usual

./configure
make
make check
make install

but the preferred method of installation is to use Homebrew. You’ll need to use our Tap to get the formula, so the commands are:

brew tap designbynumbers/cantarellalab
brew install libplcurve

This will allow you to get updated versions of the library as they become available without any further work on your part.

plCurve is currently supported and actively developed.

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.

Overview of Functionality

Download

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