Home Download News Features Screenshots Documentation English guide French guide Russian guide FAQ Communicate Participate Resources Publications Applications Site Map
This document describes how is Gwyddion organized and how it works from a slightly technical standpoint, but it does not go too deep. As such it is a recommended reading before hacking Gwyddion, or even writing modules.
Overview
Libraries
Main program
Modules
Pygwy
Plug-ins
Gwyddion is written in C and builds on GTK+ and GLib libraries. It relies on the GLib utility library for portability and uses GLib object system GObject for its own objects. Graphical user interface is implemented with the GTK+ toolkit, with a fair amount of Gwyddion specific extension widgets.
The program can be divided into five main components, each discussed in more detail below:
This structure help keeping the overall complexity low despite hundreds of modules and thousands of library functions. Most functionality exists as isolated pieces of code – either in independent modules or library functions with no global state.
Furthermore, data processing (and some other) routines can be concurrently developed at two levels of stability. Code encapsulated in modules can be as experimental as necessary since modules do not provide stable interface; they can be changed and occasionally are even removed. Stable and commonly useful functions are moved to (or directly implemented in) libraries whose APIs have not changed in an incompatible manner since 2006.
Libraries form the bulk of Gwyddion code and provide most of the real functionality that modules and the main program build on. The current set of libraries has a layered structure where each next library uses all previous, lower-level ones.
In following description, they are listed from from the lowest level to the highest level.
The libgwyddion library defines some core interfaces, like GwySerializable for data-like objects; general classes not directly related to data processing or GUI (GwyContainer, GwySIUnit); and various string, maths, file and miscellaneous utilities and macros.
Of particular interest is the GwyContainer object, which serves as
a general-purpose container for data-like (i.e. serializable) objects in
the program. Both Gwyddion native .gwy files and settings file
are technically just serialized GwyContainers; this allows quite a faithful
preservation of state in saved data.
The libprocess library defines two basic objects: GwyDataField. representing two-dimensional data and GwyDataLine, representing one-dimensional data. These objects encapsulate raw floating point arrays together with basic metadata – physical dimensions and their units.
Almost all of the many libprocess routines operate on these objects – a few operate on GwyBrick volume data, GwySurface XYZ data, or raw data arrays. There are elementary operations, like value, row, and column extraction, scaling, rotation, inversion; as well as high level functions, like grain marking, wavelet transform, statistical functions, or correlation and fractal analysis.
The libdraw library is a small library which provides a few colour handling and elementary data rendering functions (and exists as a historical artefact; it should be a part of libgwydgets). It defines false colour map objects, GwyGradients, OpenGL material objects, GwyGLMaterials, and an abstract selection class GwySelection.
It also defines a GwyRGBA floating point colour type used throughout Gwyddion for colour representation.
The libgwydgets library is essentially a collection of Gwyddion-specific GTK+ widgets. There are several notable groups of widgets there.
GwyDataView and GwyDataWindow are used to display two-dimensional data. They are accompanied by a swarm of auxiliary widgets – various data view layers pluggable to the data view and false colour axis. One kind of data view layers, so called vector layers, allowing user to “draw” on data views has been modularized (to allow extensions to define their own means of interaction), so vector layers are implemented in layer modules.
Likewise, Gwy3DView and Gwy3DWindow display data in three dimensions (they are also accompanied by some auxiliary objects like Gwy3DLabels).
Then there is a group of graph widgets: GwyGraph that is used to display one-dimensional data and its components: GwyAxis, GwyGraphArea, or GwyGraphLabel.
Various constructors (for combo boxes, radio buttons and other selectors), stock icon handlers and general purpose widgets such as adjustment bars and rulers. And there are a few individual useful widgets, like a colour button or an improved status bar.
The libgwymodule library deals with module administrative, loading and act as a proxy in their usage. It defines particular module types; module and module feature registration function. In some cases it implements more convenient wrappers around primitive module functions.
The libgwyapp library contains main program related functions, some of which could be probably equally well put into the main program. Nevertheless many can be useful outside Gwyddion itself – in a Gwyddion related work. Since it's not always clear which are which, the library contains everything that can be of any interest to outside world.
The content of libgwyapp is quite diverse. There are settings loading and saving functions, an undo facility, base classes for tool modules (GwyTool, GwyPlainTool), a “Please wait” progress bar helper, functions dealing with data and graph windows in the program, etc.
The main program is kept very small and simple, as it is practically the only non-reusable (or hardly reusable) part. In fact, a few modules are comparable in size to the main program.
The function of main program is to glue the other parts together in a common GUI framework. So beside some presentation and eye candy (About, splash screen) and a few global functions (metadata browser), it just handles command line arguments, loads settings, constructs the toolbox and then lets modules and libgwyapp functions rule.
While libraries form the bulk of code, modules are what makes the program what it is. If Gwyddion is run without any module, it starts, but the only thing one can do then is to quit it again. File loading is handled by modules, all operations on data are handled by modules too.
Technically, modules are shared/dynamically loaded libraries, scanned and loaded a program start. On load time they are asked to register their functions (also called features), there can be zero or more of them, although the former does not make a particularly useful module. The program then builds menus and toolbars representing registered functions.
There are several types of function a module can registed according to its role in the program – a module can register functions of different types, but this normally makes little sense, with the notable exceptions of pygwy and the plug-in proxy module. The following types currently exist:
Since modules can use all Gwyddion libraries, including libgwyapp, it's up to them whether they present a GUI to the user, create new windows, or anything. There are actually few things they cannot do, albeit as a side-effect not corresponding to their role.
Modules store their persistent settings in a big hash table, called settings, of whose saving and loading main program takes care of.
Pygwy is the name of Gwyddion Python bindings which provide Python module called gwy. It exists in two separate forms:
The bindings are identical. Nevertheless, there are some differences. The embedding also provides the interactive Python console in Gwyddion and allows Python scripts (following certain conventions) being used as Gwyddion modules. The extension does some basic initialisation to make Gwyddion modules and other resources more easily available in the Python scripts.
Plug-ins are standalone programs, that are more or less independent of Gwyddion, both technically and legally. It runs them to perform a given task when necessary and it waits for them to finish. The plug-in mechanism is quite limited and deprecated.
Plug-in interaction with Gwyddion lies in a
simple data
format used for data exchange, and a small set of predefined program
arguments – like register, run, or
load – telling the plug-in what it should do with the data
specified as other arguments. It then performs the task, and Gwyddion reads
back the result. This simplicity limits their possible roles and
functionality, but on the other hand it enables writing plug-ins in almost
arbitrary language.
There are two kinds of plug-ins – data processing and file type, basicially corresponding to data processing and file type modules.
The main program knows practically nothing about plug-ins. The ability to use plug-ins inheres to a smart module called plug-in proxy. In its registration phase it scans plug-in directories, queries found plug-ins and registers their features as its own features. Likewise, when it is asked to perform some task, it run appropriate plug-in to handle it. Thus it transparently maps plug-ins to module features.