Libgwyfile LibgwyfileLibgwyfile 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.6, released 2023-04-24. You can download it from SF.net.
The GWY file format, specified in Gwyddion user guide, is a self-describing hierarchical binary format. Starting from the end:
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.
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.
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.
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.
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.
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…
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.
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.
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.
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.
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.