Libgwyfile

Libgwyfile is a small MIT-licensed embeddable library that provides functions for reading and writing of Gwyddion GWY files. It contains functions for both the generic GWY file format and specific data structures actually used by Gwyddion to represent scanning probe microscopy data.

The current version of libgwyfile is 1.2, released 2016-04-27. You can download it from SF.net.

GWY file format

The GWY file format, specified in Gwyddion user guide, is a self-describing hierarchical binary format. Starting from the end:

binary
Data are represented as binary, i.e. close to machine representation.
hierarchical
A GWY file is a tree, with a single object (compound data structure) as the root. An object contains some data items that may be primitive values or again objects or arrays of objects.
self-describing
All data items in the file have names and types, which permits reading a GWY file in a generic manner (and also writing it back).

Gwyddion uses the format for object serialisation. To get an idea how a GWY file is structured it is best to look at the gwydump examples.

Documentation

Gwyfile library API reference documents fully the data structures, functions, macros and conventions.

The API reference contains several moderately complex examples demonstrating how the library can be used. The examples are complete compilable programs and they are also included in the source code package.

For practical advice concerning compilation and embedding see also file README in the source code.

Version history

See file NEWS in the subversion repository for the lists of changes in individual versions, including any upcoming version.

After development versions 0.8 (alpha) and 0.9 (beta), the stable version 1.0 implemented all planned functionality for reading and writing Gwyddion and generic GWY files.

Further (post-1.0) versions will focus on:

They may also introduce additional functionality, such as:

Additional functionality will be generally considered for implementation upon request.

Frequently asked questions

Why a standalone library?

The GWY file format was originally intended as a private data format of Gwyddion. Nevertheless, over time the need to read and write GWY files in other software has arisen. In Gwyddion the files are handled by a set of libraries and modules – that are complex, depend on Gtk+ and various other stuff. If you adopt the Gwyddion data model, then using the Gwyddion libraries is highly beneficial as they provide many useful data processing functions. But if you just need to read or write Gwyddion GWY files, using the libraries can mean lots of pain for too little gain. In addition, the Gwyddion libraries are licensed under GNU GPL, requiring essentially that any program that uses them is licensed under the same license (if distributed). This is intentional and fair if you actually utilise the provided data processing functions. For a file format library, however, GPL is a less suitable license choice as the primary goal is to enable adoption of the file format.

Can I use libgwyfile in commercial software?

Yes – commercial supposedly meaning proprietary, i.e. closed-source. Unlike unlike the GPL-licensed Gwyddion libraries, libgwyfile is licensed under the MIT license which is quite permissive. This statement does not substitute the license though, you still need to read and comply with the license. Examples and tests programs included in the source package are in the public domain.

Why is libgwyfile a separate project from Gwyddion?

Primarily because of licensing. The licenses are different (MIT vs. GPL) and no code is shared. Hence the codebases are also clearly separated and no chance of inadvertent (or ‘inadvertent’) use of code under the wrong license exists. Also, Gwyddion has already too many subprojects…

What are the compilation requirements/dependencies?

A working ISO C compiler, with support for some base C99 stuff, namely the inline keyword, stdbool.h and stdint.h. And that is it. No special dependencies was one of the main libgwyfile design principles.

How portable it is?

We tested the library mainly in various Linux distributions and MS Windows. Thanks to the minimal requirements compilation in other Unix systems should not be a problem. In MS Windows the code was tested using with both MinGW and MSVC, and also cross-compilation for MS Windows from Linux. If you encounter problems compiling the library in a POSIX system please report it as a bug. Support for non-POSIX, non-Windows systems will be considered upon request.

What do you mean by small and embeddable? The thing seems complicated!

The full library is just two files: gwyfile.h (the header) and gwyfile.c (the implementation). You can easily adopt them to your software. The rest is there just for examples, testing, to build it as a shared library (should you ever wish to do so), to extract the documentation, etc. The interface may also seem complicated because of the large number of functions. However, most of them are low-level and enable detailed handling of various types of data – in case you need it. The relatively compact high-level interface is usually sufficient.

Is it thread-safe?

Libgwyfile is thread-oblivious. The library has no shared or global state that would need protecting. Hence code using libgwyfile is thread-safe as long as it does not access objects and items within a single tree from multiple threads – or uses synchronisation mechanism to ensure such access from multiple threads is serialised.

Is it safe to use libgwyfile on untrusted input?

The library has not undergone formal security audit. That said, it was created to handle untrusted input. It has also had to withstand lots of abuse, particularly by the american fuzzy lop fuzzer, from the very beginning. So it is rather resilient, probably more than Gwyddion libraries themselves.