The Geometry Conversion Library

The Geometry Conversion Library (GCV or libgcv) provides a unified API for geometry conversion capabilities under a plugin-based architecture.

The GCV public API is declared in C headers located within include/gcv/. The single include/gcv.h header includes the entire GCV public API.

The Geometry Conversion Library consists of a stream-based API for geometry conversion and associated operations. Input and output are provided by "reader" and "writer" converters (provided by plugins). Intermediate operations are provided by "filters". Readers and writers are types of filters that provide input and output support for model formats, while basic filters apply transformations to models and geometry.

Geometry is stored in an in-memory BRL-CAD database (struct db_i in include/rt/db_instance.h) during the intermediate steps of conversion. For writer filters, this database is marked read-only and its geometry should not be modified. All names within a BRL-CAD database must be unique.

Figure 1. GCV architecture

GCV can be built in a similar manner as other BRL-CAD libraries. After configuring with CMake, building the libgcv target will produce a dynamic library. For Unix-based systems, the procedure should be similar to the following:

$ cd brlcad
$ mkdir build
$ cd build
$ cmake ..
$ make libgcv

Plugins can be built under gcv_plugin_name targets, or collectively under the gcv_plugins target.

The command-line utility can be built under the gcv target. At this time, the gcv program is not installed automatically; the binary will be placed into build/src/conv/gcv/.

The following code illustrates a basic use of GCV from within an application. Note that there may be multiple filters providing import/export capabilities for a given format; the below code simply selects the first matching filter encountered.

The public API for interacting with GCV filter plugins is summarized below.

The GCV plugin API is declared in include/gcv/api.h. Plugins provide an externally-visible const struct gcv_plugin defining their filters, which are described by struct gcv_filter.

As shown in the above table, filters may initialize data structures for processing command-line style option strings via bu_opt. Please refer to include/bu/opt.h for full documentation on the bu_opt API.

The following example will leverage the filter in the above plugin example, tessellation_statistics.c, to implement a function that counts the number of faces in a model after tessellation.

GCV includes a command-line front-end utility, gcv, implemented in src/conv/gcv/gcv.c. Full documentation is available under brlman gcv and gcv --help.

$ gcv --input=a.stl --output=b.fg4
Input file format: BU_MIME_MODEL_STL
Output file format: BU_MIME_MODEL_VND_FASTGEN
Input file path: a.stl
Output file path: b.fg4
    Converting Part: all_cpu_cpw6_cw_cpubox_cpubox.a
    Using solid name: s.all_cpu_cpw6_cw_cpubox_cpubox.a
    Making region (all_cpu_cpw6_cw_cpubox_cpubox.a)
...

$ gcv --input=a.fg4 --output=b.vrml --input-and-output-opts --verbosity=1 --output-only-opts --objects=comp_0001.r

$ gcv --input=a.fg4 --output=b.obj --input-only-opts --colors=a.fg4.colors --output-only-opts --vertex-normals

$ gcv --input=infile.txt --output=outfile.obj --input-format=stl

GCV currently contains support for import and export into five model formats, detailed below.

static int
apply_filter_with_options(struct gcv_context *context, const struct gcv_filter *filter, const char *target)
{
    struct gcv_opts options;
    const char *argv[] = { "--colors=colors.dat", "--continue" };
    const size_t argc = sizeof(argv) / sizeof(argv[0]);

    gcv_opts_default(&options);
    options->debug_mode = 1;

    return gcv_execute(context, filter, &options, argc, argv, target);
}