This file format description specifies in fact two different things that are sometimes useful to distinguish:

In should be usually quite clear where we talk about the generic format and where about specific Gwyddion data objects (occassionally it will be explicitly noted). We will start with the physical file structure.

All data are stored in little-endian (also known as LSB or Intel) byte order.

The file header consists of four bytes (magic number) with the values of ASCII characters GWYP.

This is the new file format; an older version of file format with magic header GWYO also exists. It will not be discussed here as it is mostly extinct nowadays.

The rest of a Gwyddion file consists of a serialized GwyContainer object that contains all the data. This top-level object is stored exactly the same way as any other object, that is as described in the next section.

A generic GWY file can have some other object as the top-level object.

An object consists of three parts (in the following order):

The number of components is not explicitly stored. It is implied by the total serialized data size. The components take together exactly this many bytes; there is no padding.

Object layout illustrated for a GwyContainer.

Each component consists of three parts (in the following order):

Components are often called items in libgwyfile and Gwyddion libraries.

Component size is not explicitly represented – it is implied by its type and contents. Skipping an unknown (or uninteresting) component while reading a GWY file can be done by first reading the component name and type. Then there are several possibilities:

Illustration of representation of three components, integer xres, floating point xreal and nested object si_unit_xy. They would simply follow one another in the file.

Available atomic data types are listed in following table:

Each atomic type except boolean has its array counterpart. The type character of array types is the same as of the corresponding atomic type, except it is uppercase. An array is stored as unsigned 32bit integer representing the number of items, followed by the item values. The number of items must be positive; empty arrays are not stored. Array data types are listed in following table:

Array component layout illustrated for an array of doubles called data.

GwyContainer is a general dictionary-like data object that can hold arbitrary components of arbitrary types. This permits incorporating unforeseen data structures into GWY files in a relatively sane manner.

The names (keys) of data objects in a GwyContainer representing a Gwyddion GWY file strongly resemble UNIX file names, i.e. they have the form of /-separated paths and form a sort of tree-like structure. For instance the title of the first image, numbered 0, is stored under the key /0/data/title. Note that some data or information is found under keys that may not seem logical; the reason is usually historical.

The following sections describe the organisation of interesting data and information in the top-level GwyContainer. The list is not necessarily complete. However, since all data items in the file specify consistently their name, type and size in bytes it is always possible to skip unknown data types or data you are not interested in and extract only the desired data items.

The following table summarises the common keys of image-related data in the top-level container for image number 0. For other images, the number 0 has to be replaced with the corresponding image number. Note that images are often numbered sequentially, starting from 0. However, they can have any numbers and the set of images numbers does not have to be contiguous.

Channels are represented as GwyDataField objects. The components of a GwyDataField are summarised in the following table:

The following table summarises the common keys of graph-related data in the top-level container for graph number 1. For other graphs, the number 1 has to be replaced with the corresponding graph number. Note that graphs are often numbered sequentially, starting from 1, however, they can have any numbers positive and the set of graph numbers does not have to be contiguous. The number 0 in the prefix of graph keys is a historical relic that does not mean anything and it is always 0.

Graphs are represented as GwyGraphModel objects. The components of a GwyGraphModel are summarised in the following table:

Graph curves are represented as GwyGraphCurveModel objects. The components of a GwyGraphCurveModel are summarised in the following table:

The following table summarises the common keys of spectra-related data in the top-level container for spectra set number 0. For other spectra, the number 0 has to be replaced with the corresponding spectra set number. Note that spectra sets are often numbered sequentially, starting from 0, however, they can have any numbers and the set of spectra set numbers does not have to be contiguous.

Sets of spectra of one kind are represented as GwySpectra objects. The components of a GwySpectra are summarised in the following table:

Individual curves in spectra are represented as GwyDataLine objects. The GwyDataLine object is a one-dimensional counterpart of GwyDataField and is used also for other regular one-dimensional data. The components of a GwyDataLine are summarised in the following table:

The following table summarises the common keys of volume-related data in the top-level container for volume data number 0. For other volume data, the number 0 has to be replaced with the corresponding volume data number. Note that volume data are often numbered sequentially, starting from 0, however, they can have any numbers and the set of volume data numbers does not have to be contiguous.

Volume data are represented as GwyBrick objects. The components of a GwyBrick are summarised in the following table:

The following table summarises the common keys of XYZ-related data in the top-level container for XYZ data number 0. For other XYZ data, the number 0 has to be replaced with the corresponding XYZ data number. Note that XYZ data are often numbered sequentially, starting from 0, however, they can have any numbers and the set of XYZ data numbers does not have to be contiguous.

XYZ data are represented as GwySurface objects. The components of a GwySurface are summarised in the following table:

The following table summarises the common keys of curve map related data in the top-level container for XYZ data number 0. For other curve map data, the number 0 has to be replaced with the corresponding curve map data number. Note that curve map data are often numbered sequentially, starting from 0, however, they can have any numbers and the set of curve map data numbers does not have to be contiguous.

Curve map data are represented as GwyLawn objects. The components of a GwyLawn are summarised in the following table:

The main GwyContainer contains also items that do not pertain to any specific channel, graph or other data type.

The components of a GwySIUnit are summarised in the following table:

The components of a GwySelection are summarised in the following table. Some selection types can have other data members; refer to the documentation of specific selection classes for how to interpret the data.

The components of a GwyStringList are summarised in the following table. Note that if GwyStringLists are used to represent logs, the strings have a specific structure described above.