Programmatic Manipulation with STL Files

Library Installation

To use the ADMesh library, you first need to install the library.

If you use Linux, you can explore your distribution’s packages; you’re interested in the devel or dev package to get header files and other things needed for compiling programs using ADMesh. In Fedora distribution you want the admesh-devel package, in Debian distribution then libadmesh-dev. In any case, you need version 0.98.x; older versions contain only the command-line program.

For macOS you can use homebrew.

For Windows operating system, there are precompiled archives available on GitHub.

On all supported systems you can compile the library yourself from source code.

Building on Linux Yourself

After downloading admesh-0.98.5.tar.gz and extracting:

$ ./configure
$ make
$ export ADMESHDIR=~/admesh
$ make install DESTDIR=$ADMESHDIR

To compile source code into a program, you need to tell the linker that we want to use the ADMesh library, and pass to the compiler the path to the header file and library:

$ export ADMESHDIR=~/admesh
$ gcc -L$ADMESHDIR/usr/local/lib/ -I$ADMESHDIR/usr/local/include/ source.c -o myapp -ladmesh

$ LD_LIBRARY_PATH=$ADMESHDIR/usr/local/lib/ ./myapp

Installing and Compiling ADMesh on macOS

For installation we’ll use Homebrew. If you don’t have it installed, install it according to instructions at https://brew.sh/

$ brew install admesh

To compile source code into a program, you need to tell the linker that we want to use the ADMesh library, and pass to the compiler the path to the header file and library:

$ gcc -L/opt/homebrew/lib/ -I/opt/homebrew/include/ source.c -o myapp -ladmesh

$ ./myapp

Basic Usage

To use the library, just include the header file admesh/stl.h:

#include <admesh/stl.h>

In the library there’s a set of structures and functions that you can use for basic manipulation with STL models.

Loading Model from File

First you need to load the file from disk into the stl_file structure.

#include <stdlib.h>
#include <admesh/stl.h>

int main(void) {
  stl_file stl; 1
  char *filename = "directory/model.stl"; 2
  stl_open(&stl, filename); 3
  stl_exit_on_error(&stl); 4

  /* ... TODO ... */

  stl_close(&stl); 5
  return EXIT_SUCCESS;
}

Compiling the Program

To compile source code into a program, you need to tell the linker that we want to use the ADMesh library:

$ gcc source.c -o myapp -ladmesh

Or, if you don’t have ADMesh installed in standard paths, you need to set absolute paths to both the library and header file:

$ export ADMESHDIR=~/admesh
$ gcc -L$ADMESHDIR/usr/local/lib/ -I$ADMESHDIR/usr/local/include/ source.c -o myapp -ladmesh

$ ./myapp

$ LD_LIBRARY_PATH=$ADMESHDIR/usr/local/lib/ ./myapp

$ DYLD_LIBRARY_PATH=$ADMESHDIR/usr/local/lib/ ./myapp

Working with the stl_file Structure

After loading the file into memory, you can work with the stl_file structure in any way. For example, view or change data. The structure is no longer data-bound to the file on disk and all data is in program memory.

To view individual facets, you can use the pointer (array) facet_start. In the array, facets are stored in the form of stl_facet structures, which contain a normal – attribute normal (structure of type stl_normal containing 3 floats (x, y, z)), three vertices – attribute vertex (array of three structures of type stl_vertex each containing 3 floats (x, y, z)) and attribute extra, which you can ignore.

float x = stl.facet_start[0].vertex[0].x; 1
float z = stl.facet_start[1000].vertex[1].z; 2

To be able to go through all facets, you first need to know how many there are. This information can be found in the stats attribute, which contains a structure with lots of useful data, mostly numbers. One of them is number_of_facets, i.e., the number of facets.

stl.facet_start[stl.stats.number_of_facets-1] 1

In statistics (stats) you’ll find more information, an overview of which is in the definition of the stl_stats structure in the stl.h file or in the not very good documentation.

Here’s a short example program that loads an STL file model.stl (binary or ASCII) and writes it as ASCII or binary STL to the same file – it makes ASCII from binary and binary from ASCII.

You can view and change data at will. If you want to enlarge the model, for example, theoretically it’s enough to perform the appropriate mathematical operation on all coordinates of all vertices of all facets.

Most basic operations are already covered by the program authors.

Functions for Manipulating the Model

For "typical" operations with 3D models, there are prepared functions. In the library you’ll find functions for rotating, scaling, moving…​

Usually it’s enough to look at their list in the header file.

Among the interesting ones are:

Functions for Writing Model to File

After finishing work with the model, it’s often necessary to write the model to disk again (export).

Functions stl_write_ascii() and stl_write_binary() serve to write the model in STL format, which differ in the resulting format: they write ASCII STL and binary STL respectively.

Both functions take three arguments:

The mesh name is not related to the file name, but is only textual information stored in the STL file. This information is not used in practice and is often replaced by the name of the program that created the mesh. For example, models from OpenSCAD are always named OpenSCAD_Model.

/* ... */
stl_write_ascii(&stl, filename, "whatever"); 1
stl_exit_on_error(&stl); 2
/* ... */
stl_close(&stl); 3

Example Program for Converting ASCII/Binary STL

As an example, a complete program for converting an ASCII STL file to binary form (or vice versa).

#include <stdlib.h>
#include <admesh/stl.h>

int main(void) {
  stl_file stl;
  char *filename = "model.stl";

  printf("Opening %s\n", filename);
  stl_open(&stl, filename); 1
  stl_exit_on_error(&stl); 2

  if (stl.stats.type == binary) { 3
    printf("Writing ASCII file %s\n", filename);
    stl_write_ascii(&stl, filename, "converted"); 4
    stl_exit_on_error(&stl); 5
  } else {
    printf("Writing binary file %s\n", filename);
    stl_write_binary(&stl, filename, "converted"); 6
    stl_exit_on_error(&stl); 7
  }

  stl_close(&stl); 8
  return EXIT_SUCCESS;
}

More Information

Individual library functions and structures can be found in the file admesh/stl.h. The library unfortunately doesn’t have much documentation, although something is emerging at admesh.readthedocs.io.