Gwyddion – Free SPM (AFM, SNOM/NSOM, STM, MFM, …) data analysis software

Frequently Asked Questions

General:
Why Gwyddion?
I found a bug, what should I do?
How to cite/refer to Gwyddion?
What systems and architectures Gwyddion runs on?
Can we use proprietary plug-ins?
Why I cannot make data view selections or rotate 3D view in KDE?
I am trying to run Gwyddion remotely on Unix and it takes forever to start
I closed a data window, the file was completely closed and I lost valuable changes. How do I prevent that?

Versions and releases:
When it will be finished?
When a new version will be released?
How can I get notified of new releases?
What new features will be in the next version?
What are the quirky names attached to each version number?
What is version 2.xx.20yyyyyy and where can I get it?
What is a development snapshot/nightly build?
How do I apply a patch?

Files and file formats:
I am suddenly unable to open/save files. It worked mere moments ago!
My microscope files load wrong or I get an error message while opening them, what should I do?
Why I cannot load my microscope files?
How do I send large data files to you, do you have an FTP upload area?
What is the best method to automatically load my raw data?
My program will write data that should be consumed by Gwyddion. What format should I use?
How do I write a GSF file in Python?

Data processing:
What the strange PSDF values mean?
How can I export an image of the data?
How can I process all images in a file using pygwy?
Where is the list of functions usable with gwy_process_func_run()?

Extending and developing:
Why C programming language?
Why to use Gtk+ library?
Can I use my own routines with this software?
Can I use other graphical library (Qt, MFC) with the program
Will my plug-ins work with future versions of Gwyddion?
Will my modules work with future versions of Gwyddion?
I linked Gwyddion with --as-needed and it broke. How to fix it?
How do I write a module in C++?
Can I speed up make install when working on a single module?
How can I expedite integration of my module/patch?

Why Gwyddion?

See the explanation.

I found a bug, what should I do?

Please report it to Petr, the mailing list or the web forum at SourceForge.

Be as specific as possible. This means listing the operating system and environment, what exactly you were doing, and the exact error message (if any) or how the program crashed (if it crashed).

Also please check the problem is still present in the latest stable version. You will be likely asked to upgrade if you report a bug in an old version.

For file loading-related bugs please provide the file that causes problems to make reproducing the bug possible. If you experience crashes on a Unix-based system a gdb trace or valgrind output will also be helpful for locating the bug.

How to cite/refer to Gwyddion?

A paper about Gwyddion has been published in Central European Journal of Physics. It can be cited as follows:

David Nečas, Petr Klapetek, Gwyddion: an open-source software for SPM data analysis, Cent. Eur. J. Phys. 10(1) (2012) 181-188

BibTeX record:

@Article{Necas2012,
author = {Nečas, David and Klapetek, Petr},
affiliation = {CEITEC — Central European Institute of Technology, Masaryk University Kamenice 753/5, 625 00 Brno, Czech Republic},
title = {Gwyddion: an open-source software for {SPM} data analysis},
journal = {Central European Journal of Physics},
publisher = {Versita, co-published with Springer-Verlag GmbH},
issn = {1895-1082},
keyword = {Physics and Astronomy},
pages = {181-188},
volume = {10},
issue = {1},
year = {2012},
doi = {10.2478/s11534-011-0096-2},
}

If you refer to Gwyddion in a software context it is also useful to give the URL http://gwyddion.net/.

Many Gwyddion related algorithms are also described in book on Quantitative Data Processing in Scanning Probe Microscopy published by Elsevier (ISBN: 9781455730582). It includes description of many ideas in (and behind) Gwyddion, as well as basics of different physical quantities measurements and interpretation using Scanning Probe Microscopy techniques, like AFM, FFM, STM, EFM, MFM, SThM, SNOM, etc.

What systems and architectures Gwyddion runs on?

Operating systew-wise, Gwyddion is known to work on GNU/Linux, Microsoft Windows, Mac OS X, and FreeBSD. Architecture-wise, it has been tested on i386, AMD64, and PowerPC. It should work on any Unix-like system where Gtk+ and other dependencies work.

The core developers do not prepare executables for all these systems, but a number of people maintain packages for various platforms and systems. The known packages are listed at the download page.

Can we use proprietary plug-ins?

Yes you can. You can use a plug-in with other than open source license. However, such a plug-in can't be a part of the program, but can be distributed separately. Also note the difference between plug-ins, i.e. standalone programs reading/writing/processing some data, that can be independent works, and modules that are always derived works of Gwyddion.

Why I cannot make data view selections or rotate 3D view in KDE?

Most likely you use the Oxygen theme of KDE. Unfortunately, its creators decided to enable moving windows by clicking in any inactive area by default, despite not being able to detect inactive areas reliably. And they refuse to change this default.

Run oxygen-settings and disable the odd behaviour by selecting Drag windows from titlebar only in Widget Style → General → Windows' drag mode.

I am trying to run Gwyddion remotely on Unix and it takes forever to start

This is often caused by DRI3. Try running Gwyddion as follows:

LIBGL_DRI3_DISABLE=1 gwyddion

If it does not help or you get errors on startup the last resort is disabling 3D completely, including any attempts to check whether it is even available:

gwyddion --disable-gl

Of course, the 3D view will not be available in such case.

I closed a data window, the file was completely closed and I lost valuable changes. How do I prevent that?

By saving valuable changes after you make them. Files can be saved (to the GWY format) by pressing Ctrl-S.

When all windows (image, graph, volume) of a file are closed the entire file is closed. There is no Do you want to save… prompt.

This has the advantage that if you use the program to view various data and experiment with them you will not be pestered with questions when you want to discard the experiments.

The disadvantage is, of course, that changes can be indeed lost. Save the data explicitly when you make changes you want to preserve.

The developers are not in principle against some Do you want to save… prompt but they are not much interested in such thing and are unlikely to implement it themselves. Patches that add such prompt and also preserve the current operation mode will be considered for inclusion.

When it will be finished?

Since Gwyddion is intended as a framework the for development and sharing of new analytical methods, everlasting continuous development is expected.

Furthermore, there seems to be no shortage of new or changed SPM data formats. As part of the Gwyddion mission is enabling SPM users to analyse data acquired all kinds of instruments the same way, this also requires an ongoing development.

When a new version will be released?

When the amount of changes warrants a new release.

Assuming a reasonable development pace this policy means a new version is typically released every few months (see the version statistics). Sometimes the development is slower so it takes longer.

As many other projects have realized, waiting until features are finished leads to excessive delays. Hence features that are not ready yet are simply omitted from the release. Do not take it personally if you have a personal interest in something left out – since we do not wait, another release, meaning another chance, will occur soon.

How can I get notified of new releases?

If you are subscribed to either gwyddion-users or gwyddion-devel mailing list you will receive notifications by e-mail.

If you are a SourceForge.net user, you can subscribe to project Gwyddion, see the big button Subscribe to Updates. The service sends information about updates to the project and it is configurable to some degree using ‘Subscriptions’ settings in your SourceForge account. However, setting it up to only get notifications of new releases does not seem possible at this moment.

SourceForge also offers a RSS feed for project activity, see the top right corner of the Files tab.

We also send notifications using some software release aggregation services du jour. Currently you can watch new releases at Freshcode.

What new features will be in the next version?

See the NEWS file in the subversion repository.

This file reflects the state of current development snapshots, more or less. It is often updated with some delay. On the other hand it can also mention features that have been added to the program but are not complete yet. But if something appeared in the NEWS file it is almost certain it will be present in the next stable version.

What are the quirky names attached to each version number?

Version numbers are nicely structured and algorithmically comparable. But it is difficult to associate anything with a version number, especially for software with so many versions as Gwyddion. Hence Yeti started to nickname the releases. The first release bearing a name was 2.8, called “Freedom for Fourier”. And with a few exceptions, all versions released since then also carry a name.

The names characterise important features or development process of each version for easier recalling so what it was about. But they often do so in a peculiar, cryptic, whimsical, tangential or arcane manner. While “The TIFF Toll” only poorly masks the developers' opinion on TIFF libraries, “Too Technical Tears” may be more difficult to decipher. There are no formal naming rules – Yeti evidently likes alliteration though.

What is version 2.xx.20yyyyyy and where can I get it?

Each night (if you live in a time zone around GMT, as most Gwyddion developers do), an automated build and packaging of Gwyddion is performed. This results in so-called nightly snapshot that consists of whatever is in the code repository at that moment. Its version number is constructed by appending the current date to the previous stable version number. Hence it appears between the stable versions by the usual sorting rules:

  2.29 < 2.29.20120902 < 2.30
stable   snapshot        stable

You can download the latest snapshot from the Download page here. Note that the package file is always called Gwyddion-head, i.e. the actual version number can be only seen after unpacking, but you can also see the build date displayed in the download table. Since the automated build can fail and sometimes the source code is not properly updated from SourceForge please always check the date inside the program when testing the development snapshots (and if unsure then ask).

The snapshots contain all the latest features – and bugs. If you are told to try a nightly build (namely because it contains a feature or bugfix you requested) then the developer telling you this thinks it should be usable now. But the scary warnings on the download page still apply.

Also, the snapshot to try is typically the next one which will be available for download the following day.

What is a development snapshot/nightly build?

Development snapshot and nightly build refer to the same thing, automatically created Gwyddion packages capturing the current state of its development. They are described in detail in another entry.

How do I apply a patch?

Patches are applied by running the patch program (see patch(1) for details):

patch -p1 <gwyddion-patch-name.patch

in the unpacked source code before executing ./configure. Occasionally, patches may also need -p0 instead of -p1. Admittedly, we are not completely consistent in the patch level.

All patches we publish are source code patches (which is the classical meaning of patch, even though you can find all kinds of updates being called ‘patches’ nowadays). Any binary package updates, that are much rarer than patches, are released as complete packages.

I am suddenly unable to open/save files. It worked mere moments ago!

Please check that the file type is set to ‘Automatically detected’ (for file opening) or ‘Automatic by extension’ (for saving/exporting) in the file dialogue. The file type selector is in the lower part of the window, below the file list.

Selecting a specific file type means Gwyddion will not perform any automatic detection and simply assume this file type. When it does not match the actual format you will get an error message (for file opening) or the file is saved in an unexpected format (for saving/exporting).

My microscope files load wrong or I get an error message while opening them, what should I do?

Report it as a bug – preferably in the mailing list or web forum. Since microscope producers frequently update their file formats, it may happen that Gwyddion loads your data incorrectly even if the file format is supported in general.

In order to improve the import and fix the problem, the developers need:

On the other hand, sending Gwyddion screenshots is usually pointless as the developers can try to open the files in Gwyddion themselves and see what happens. What they cannot do is opening the files in your original microscope software for comparison.

So, do not send Gwyddion screenshots unless it is clear that other people are not able to observe the same Gwyddion behaviour. But do send screenshots of correctly loaded data (in other software).

Why I cannot load my microscope files?

If you have microscopy data in a format Gwyddion cannot open please contact us and send file format documentation, sample data files, information what kind of data these files contain and what they should look like when loaded correctly, and generally any available information that can be helpful for adding support for the file format to Gwyddion.

We would like to support as many SPM file formats as feasible. Nevertheless, mere knowledge that someone somewhere in the world has some files that Gwyddion cannot open, however saddening, is not sufficient to actually implement support for the file format. And if we do not even know about it, the import module for your file format is unlikely to miraculously appear.

So do not just wait. If you want to open your files in Gwyddion then do something about it.

Of course, you can also write a file import module yourself (and you are encouraged to do so) and submit it for inclusion to Gwyddion. There is page describing the file format situation in details.

How do I send large data files to you, do you have an FTP upload area?

Unfortunately, we do not have any public FTP upload space.

The preferred method of sending large files is to upload them to a file hosting service/file deposit of your choice and send the link.

When you post a message to the SourceForge discussion you can attach files to the post using the ‘Add attachments’ button.

Not preferred, but also possible is to send files by e-mail. In such case compress the files with 7zip, xz or zip because:

Please do not send large files directly to the mailing lists; messages exceeding certain size are rejected as most people do not appreciate receiving unsolicited huge files.

What is the best method to automatically load my raw data?

Generally, we try to implement automatic loading of all kinds of file formats, however rarely used, using file import modules. Please always contact the developers about the support for your file format directly in Gwyddion if there is at least a slight chance it will help also other people.

Sometimes your raw data may be too raw though.

In this case complement the data file with a standalone NRRD (Nearly Raw Raster Data) header referring to the raw file using data file: and specifying the dimensions and other properties. Loading this header into Gwyddion will then load the raw data.

The biggest advantage of this method is that no modification of the raw file is necessary. You just add a small text header and Gwyddion will load the data file fine.

NRRD is supported since Gwyddion version 2.25.

My program will write data that should be consumed by Gwyddion. What format should I use?

For single-channel data, there are several good choices:

The last option also applies to complex data as the effort required to save complex data files depends on many factors and no single format fits all uses. Of course, the ultimate Gwyddion format is GWY but it is among the most complex.

The ultimate format is of course GWY. A small standalone library for reading and writing of Gwyddion files, libgwyfile, is now available under a very permissive license, i.e. you can generally use it also in closed-source software.

How do I write a GSF file in Python?

For instance using this function:

import array, sys, math

def write_gsf(filename, imagedata, xres, yres,
              xreal=None, yreal=None, xyunits=None, zunits=None, title=None):
    """Write a Gwyddion GSF file.

    filename -- Name of the output file.
    imagedata -- Image data.
    xres -- Horizontal image resolution.
    yres -- Vertical image resolution.
    xreal -- Horizontal physical dimension (optional).
    yreal -- Vertical physical dimension (optional).
    xyunits -- Unit of physical dimensions (optional).
    zunits -- Unit of values (optional).
    title -- Image title (optional).

    Image data may be passed as any listable object that can be used to form
    a floating point array.array().  This includes tuples, lists, arrays,
    numpy arrays and other stuff.
    """
    data = array.array('f', imagedata)
    if len(data) != xres*yres:
        raise ValueError, "imagedata does not have xres*yres items"
    isinf = math.isinf
    isnan = math.isnan
    for z in data:
        if isinf(z) or isnan(z):
            raise ValueError, "GSF files may not contain NaNs and infinities"
    if sys.byteorder == 'big':
        data.byteswap()
    header = ['Gwyddion Simple Field 1.0']
    header.append('XRes = %u' % xres)
    header.append('YRes = %u' % yres)
    if xreal is not None:
        header.append('XReal = %.12g' % xreal)
    if yreal is not None:
        header.append('YReal = %.12g' % yreal)
    if xyunits is not None:
        header.append('XYUnits = %s' % xyunits.encode('utf-8'))
    if zunits is not None:
        header.append('ZUnits = %s' % zunits.encode('utf-8'))
    if title is not None:
        header.append('Title = %s' % title.encode('utf-8'))

    header = ''.join(x + '\n' for x in header)
    l = len(header)
    sentinel = bytearray()
    for j in range(4 - l % 4):
        sentinel.append(0)

    fh = file(filename, 'wb')
    fh.write(header)
    fh.write(sentinel)
    fh.write(data)
    fh.close()

What the strange PSDF values mean?

Most probably you are looking at the PSDF method of fractal dimension estimation. It uses a log-log plot with arbitrary shifts and scale. Use the statistical functions tool to obtain PSDF in absolute units.

The x axis units are then lateral_unit-1 and y axis units lateral_unit × value_unit2. The normalization corresponds to the PSDF expressions for various surfaces that can be used to fit rms and autocorrelation length of rough surfaces in graph fitting.

The spatial frequencies used in Gwyddion are circular, corresponding to exponentials in the Fourier transform of form exp(iKx), not exp(2πiKx).

Many different PSDF normalizations can be found in the literature, together with reasons why they are better than others. PSDF in Gwyddion is based on the concept of an infinite rough surface (two-dimensional random signal if you want to get mathematical). The measured data is a finite-resolution measurement on a finite area which is assumed to have the same statistical properties as the entire surface.

The total energy of an infinite signal is infinite. Hence a meaningful quantity is the energy per unit area. The PSDF displayed in Gwyddion is exactly that. It is sampled in certain points given by the discrete nature of the calculation, nevertheless, the values should be approximations of W₁(k) that results from continuous Fourier transform of the autocorrelation function of the entire infinite surface.

This has the following nice consequences:

Finally, note that the square of a density of some quantity is not the density of the same quantity squared. Normalizations of PSDF and Fourier coefficients need to be considered separately for continuous distributions.

Some of these points are also illustrated in the roughness evaluation talk by David Nečas.

How can I export an image of the data?

Using FileSave As and choosing an image format such as PNG or TIFF (or just giving the file the corresponding extension). Recent versions can also export PDF, SVG or EPS images. Please see the user guide for a detailed description.

For a plain export without rulers, false colour bars, etc. you can also press Ctrl-C in an image window to copy it to the clipboard and then paste it to another program.

If you want to represent the data in an image format but not to lose too much information then save it as PNG, TIFF or PPM and select 16bit grayscale for a larger bit depth. Gwyddion also can save and load OpenEXR HDR images that offer even higher bit depths and dynamic ranges.

How can I process all images in a file using pygwy?

This is, in fact, two questions because there are two different methods how to do something with the data. Either you can obtain the DataField object representing each channel and call its methods directly (or evne modify the pixels directly), or you can apply existing data processing modules. The following script demonstrates both:

# This pygwy script shows how an operation can be preformed with
# all channels in the current file.
c = gwy.gwy_app_data_browser_get_current(gwy.APP_CONTAINER)

#########################################
# Directly calling a DataField method
for i in gwy.gwy_app_data_browser_get_data_ids(c):
    # Get the DataField from the container
    f = c['/%u/data' % i]
    planecoeffs = f.fit_plane()
    f.plane_level(*planecoeffs)

    # Notify Gwyddion we directly modified the data
    f.data_changed()

#########################################
# Using a data processing module function
# Remember what was the current channel.
current = gwy.gwy_app_data_browser_get_current(gwy.APP_DATA_FIELD_ID)

# Set module options in the settings
settings = gwy.gwy_app_settings_get()
settings['/module/linematch/method'] = 1
settings['/module/linematch/masking'] = int(gwy.MASK_EXCLUDE)

# Execute
for i in gwy.gwy_app_data_browser_get_data_ids(c):
    # Make the data field (image) current for data processing functions
    gwy.gwy_app_data_browser_select_data_field(c, i)

    # Run the function
    gwy_process_func_run('align_rows', c, gwy.RUN_IMMEDIATE)

# It's best to select again what was selected when we started
gwy.gwy_app_data_browser_select_data_field(c, current)

You can, of course, process only some data based on their properties. Running interactive module functions in a loop is not a good idea in general.

Where is the list of functions usable with gwy_process_func_run()?

The function names are names of high-level (or at least higher-level) functions provided by data processing modules. Each corresponds to some action available in the Data Process menu. If you extend Gwyddion with a module, the functions it defines will be available the same way as functions of built-in modules.

The list of functions can be obtained by several ways:

Why C programming language?

The core and modules is written in the C language.

This language was chosen as it is well known, standardised and widely spread, there are many important libraries that could be used (Gtk+), and it is relatively easy to bind C functions to other languages. At present Python bindings are available.

Modules can be written in C, C++ or Python.

Plugins can be written in C, C++, Perl, Python and maybe more. The simplest ones can be written in almost any language.

Why to use Gtk+ library?

The Gtk+ graphical library is used because of its licensing, portability and capabilities. And also because it is a C library.

Can I use my own routines with this software?

Yes, certainly, this is one of the main goals.

There are three basic ways you can extend Gwyddion:

A better alternative to plug-ins may be writing a two-part extension. One part would be a wrapper C module that passes data to and from the other part, which can be an arbitrary external tool or service. This essentially means writing a new small and specialised plug-in proxy module. The advantage is that you can use whatever communication means you want, as opposed to reading and writing files in the dump format, and you can desing the wrapper specifically for your third-party tool, language or problem domain. You can also extend Gwyddion in ways beyond what is possible using plug-ins.

Can I use other graphical library (Qt, MFC) with the program?

Yes you can do it in a form of simple plug-ins. But note, that with using some libraries (MFC) you may produce code that is not portable. This is not problem if you use code for you own, but you might be in a problem when you want to share your plug-in with someone.

Will my plug-ins work with future versions of Gwyddion?

Yes, virtually forever.

Even if a decision was made the current plug-in system is so bad that a new one must be designed, Gwyddion architecture would allow the old and new plug-in system to coexist, and the current would be kept for compatibility with existing plug-ins.

Note: The current plug-in system is actually considered ill-designed. While this does not mean the plug-in support will disappear soon (certainly it will not disappear before Gwyddion 4.0), it is not the preferred method to add routines in other programming languages any more and it cannot be expected to be further developed. See the entry about extending Gwyddion for better alternatives.

Will my modules work with future versions of Gwyddion?

Yes, under normal circumstances.

Modules are bound to Gwyddion more tightly than plug-ins, so a substantial change in it may break compatibility. Normally, all new versions are both source and binary level compatible with previous ones and modules linked against old versions work even with the newest one.

Gwyddion 2.0 is neither binary compatible (so modules have to be recompiled) not source compatible (so beside recompilation, some changes in module code are necessary) with 1.x versions. But all 2.x version will be backward compatible with other 2.x versions again.

Actually, there already was a one unplanned incompatible change, in version 1.3, where a serious bug present in previous versions could not be fixed while retaining compatibility. This should not happen again.

I linked Gwyddion with --as-needed and it broke. How to fix it?

Contrary to the popular belief, linking with --as-needed would make Gwyddion slow and bloated, not more efficient. So the short answer is: you fix it by not linking with --as-needed.

On platforms that support it, and that means at least all modern Unix systems, the main application is linked with some “redundant” libraries and modules are not linked with anything (unless they need a specific extra library). Symbols in modules are resolved from the libraries the main application was linked with. Obviously, --as-needed makes this optimization impossible and every module then has to be linked with all libraries it requires – this is less than the full set of libraries but still much more than none. It takes more time to build (even 2×) and install (almost 10×) and it makes the program start more slowly (module loading time increases 2×).

But if you insist then pass --enable-library-bloat option to configure and all the bloat will be linked in.

How do I write a module in C++?

Easily. You only need to ensure two elementary things:

In fact, Gwyddion contains a C++ module modules/file/hdrimage.cc although it is written in quite C-like C++ because it also interacts with lots of C libraries.

Can I speed up make install when working on a single module?

First, run make install from the corresponding subdirectory. It will install only modules from this directory.

However, some module subdirectories in Gwyddion source code are large and running make install in them can still take considerable time. You can compile and install only a single module by overriding the Makefile variable specifying the list of modules. Since we use libtool you need to enter the .la files, for example:

make install file_LTLIBRARIES=gwyfile.la

or

make install process_LTLIBRARIES=level.la

How can I expedite integration of my module/patch?

Patches should have a well-defined purpose: take the code from state A to state B. Do not lump unrelated changes together or mix fully working features with experimental stuff.

Ensure the change cannot cause crashes, hangs or memory leaks. Incomplete implementations can be all right sometimes, especially in the case of reverse-engineered weird file formats. But program defensively and do not assume that a file import module will receive only files it can actually load. Always verify that you read meaningful data sizes, file offsets, etc. and give an error if you do not. Similarly for data processing modules. For instance, if they work with multiple data fields do not assume the file contains data with some specific properties. Check the field properties, for instance using gwy_field_check_compatibility().

Try to implement things in the same manner they are done in other modules, i.e. The Gwyddion Way. First, it simplifies review greatly. Second, it is quite likely that you code will be read and modified by people familiar with Gwyddion code in future. If you are not sure about the recommended or common method of handling something then ask.

On the same note, follow the Gwyddion coding style. You can find a description of the style as devel-docs/CODING-STANDARDS in the source code. Furthermore, there is also a Python script utils/check-coding-style.py which checks the most common or obvious style issues. You can run it as

check-coding-style.py sourcefile.c [othersource.c...]

The script is not perfect and does not catch every deviation while it warns about things which may be acceptable in certain circumstances (namely lines longer than 80 characters). However, if your patch makes the warning count go from 2 to 200 for some file something is clearly amiss.

1.129 (yeti, 2016-11-25 09:48:25)
© David Nečas and Petr Klapetek

Home Download News Features Screenshots Documentation English guide French guide Russian guide FAQ Communicate Participate Resources Applications Site Map

Valid XHTML 1.0 Valid CSS