Gwyddion Module Overview (HEAD)

Gwyddion Module Overview — Overview of Gwyddion modules

Module Types

Gwyddion is quite a modular application. In fact, most of its basic functionallity is provided by modules. Modules allow to easily extend Gwyddion without the need to recompile. However, it is currently impossible to load, unload and change modules while Gwyddion is running, therefore it has to be restarted when the set of modules change. Modules are then automatically detected, registered and the functions provided by modules are added to Gwyddion menus and/or toolboxes.

There are several distinct module types:

• data processing modules that provide functions for processing of two-dimensional data arrays (e.g. Fast Fourier Transform module), or changing the graphical presentation of data (e.g. shading module). Data processing modules usually get data (i.e. two-dimensional field of SPM data), possibly ask for processing options and do the requested data processing. More interactive functions are typically better implemented as tool modules.

• file loading and saving modules that handle import and export of foreign file formats, also the Gwyddion native file format is handled by a module.

• graph modules that operate on one-dimensional data (graphs), e.g. profiles obtained by Profile selection tool. An example is Function fit module.

• tool modules that provide tools operating on two-dimensional data directly in application data windows. They have typically more interactive interface than processing modules and allow to select objects on the data with mouse. Examples include Read value or Three-point leveling tools.

• layer modules that implement two-dimensional data selections as rectangular selection or line selection. Selections are mostly employed in tool modules, however several data processing modules use them too.

The above types are in fact function types, not module types. One module often provides a single function, but it can also provide a whole bunch of completely unrelated functions, even of different types. However, it is usual to group functions containing considreable amount of common code to one module (to allow sharing), and use separate modules for unrelated functions.

More precisely, a file (i.e., a shared/dynamically linked library) always corresponds to a one Gwyddion module. A module can register zero or more functions (features) of arbitrary type.

Data Representation

The object representing a data file in Gwyddion is GwyContainer. It is a general container that can hold values of mixes types: atomic, strings or objects. Its items are identified with GQuarks, that is either by strings or by integers associated with the strings.

Two-dimensional data arrays (represented with GwyDataField) or one-dimensional curve data (represented with GwyGraphModel and GwyGraphCurveModel) and auxiliary data are stored at keys resembling Unix file paths and forming a kind of hierarchical structure. For instance the data of the zeroth channel and its title can be obtained with

1
2

data_field = gwy_container_get_object_by_name(container, "/0/data");
title      = gwy_container_get_string_by_name(container, "/0/data/title");

The location of certain items is given by historical reasons and do not always make much sense. Fortunately a module author is rarely forced to resort to this low-level interface. The data browser provides high-level view of the file and means to perform all common operations.

In the high-level view, channels and graphs in a file are simply numbered by small integers (each data type has its own numbering) and to uniquely identify an object one uses the (container, id) couple. The id number an object does not change during its lifetime (however, it can change when the file is saved, closed and then opend again). There are also functions with similar interface, operating on auxiliary data.

For example to add a new data field to a container (file) we call

1

new_id = gwy_app_data_browser_add_data_field(data_field, container, TRUE);

The function gwy_app_data_browser_add_data_field() takes care of finding a free id, storing the data field at the right key and even creation of a window showing the new data field.