Gwyddion native data files consists of a tree-like structure of serialized objects. Generally, these objects can be of various kind and contain other embedded objects (hence the tree-like structure). It can be instructive to play with gwydump, a simple file structure visualizer available in on the project's web, for a while and examine the contents of various files.
First of all, we will describe physical file structure without regard to possible interpretation of contained data.
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.
The rest of the file consists of a serialized GwyContainer object that contains all the data. It is stored exactly the same way as any other object, that is as described in the next section.
An object consists of three parts (in the following order):
NUL-terminated string of
ASCII characters. This is the type name in GObject type system.
Each component consists of three parts (in the following order):
NUL-terminated string.
Available atomic data types are listed in following table:
| Type | Character | Note |
|---|---|---|
| boolean | b | Stored as a byte, zero is false, nonzero (normally 1) is true |
| character | c | |
| 32bit integer | i | |
| 64bit integer | q | |
| double | d | finite IEEE 754 double precision floating point number, i.e. files must not contain infinities and not-a-numbers |
| string | s |
NUL-terminated
|
| object | o | Serialized object as described above |
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. Arrays are stored as unsigned 32bit array length (the number of items), followed by the item values. Array data types are listed in following table:
| Type | Character | Note |
|---|---|---|
| array of characters | C |
Not NUL-terminated
|
| array of 32bit integers | I | |
| array of 64bit integers | Q | |
| array of doubles | D | |
| array of strings | S | |
| array of objects | O | Uppercase Oh, not zero |
The names (keys) of data objects in a GwyContainer representing a Gwyddion
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 channel, numbered 0, is stored under the key
/0/data/title. Note some data or information is found under keys
that do not seem logical; the reason is usually historical.
The following sections describe the organisation of interesting data and information in the 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 channel-related data in the top-level container for channel number 0. For other channels, the number 0 has to be replaced with the corresponding channel number. Note that channels are often numbered sequentially, starting from 0, however, they can have any numbers and the set of channels numbers does not have to be contiguous.
| Key | Type | Meaning |
|---|---|---|
/0/data | GwyDataField | Channel data. |
/0/data/title | string | Channel title, as shown in the data browser. |
/0/data/visible | boolean | Whether the channel should be displayed in a window when the file is loaded. |
/0/base/palette | string | Name of the false color gradient used to display the channel. |
/0/base/range-type | 32bit integer | False color mapping type (as set by the Color range tool), the value is from GwyLayerBasicRangeType enum. |
/0/base/min | double | Minimum value for user-set display range. |
/0/base/max | double | Maximum value for user-set display range. |
/0/mask | GwyDataField | Mask data. The pixel dimensions of this data field must match those of the channel data. |
/0/mask/red | double | Red component of the mask color. |
/0/mask/green | double | Green component of the mask color. |
/0/mask/blue | double | Blue component of the mask color. |
/0/mask/alpha | double | Alpha (opacity) component of the mask color. |
/0/show | GwyDataField | Presentation data. The pixel dimensions of this data field must match those of the channel data. |
/0/meta | GwyContainer | Channel metadata. The keys are directly the names as displayed in the metadata browser and the string values are the values. |
/0/select/ | a GwySelection subclass |
Selection data. Each kind of selection has (usually) a different object
type and is stored under a different name; the specific name
foo is the same as shown in the
selection manager.
|
Channels are represented as GwyDataField objects. The components of a GwyDataField are summarised in the following table:
| Component | Type | Meaning |
|---|---|---|
xres | 32bit integer | Horizontal size in pixels. |
yres | 32bit integer | Vertical size in pixels. |
xreal | double | Horizontal dimension in physical units. |
yreal | double | Vertical dimension in physical units. |
xoff | double | Horizontal offset of the top-left corner in physical units. It usually occurs only if non-zero. |
yoff | double | Vertical offset of the top-left corner in physical units. It usually occurs only if non-zero. |
si_unit_xy | GwySIUnit | Unit of lateral dimensions. |
si_unit_z | GwySIUnit | Unit of data values. |
data | array of doubles |
Field data, stored as a flat array of size
xres×yres,
from top to bottom and from left to right.
|
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.
| Key | Type | Meaning |
|---|---|---|
/0/graph/graph/1 | GwyGraphModel | Graph model object data. |
/0/graph/graph/1/visible | boolean | Whether the graph should be displayed in a window when the file is loaded. |
Graphs are represented as GwyGraphModel objects. The components of a GwyGraphModel are summarised in the following table:
| Component | Type | Meaning |
|---|---|---|
curves | array of GwyGraphCurveModels | Individual graph curves. |
title | string | Graph title as displayed in the data browser. |
x_unit | GwySIUnit | Unit of the abscissa. |
y_unit | GwySIUnit | Unit of the ordinate. |
top_label | string | Label on the top axis. |
bottom_label | string | Label on the bottom axis. |
left_label | string | Label on the left axis. |
right_label | string | Label on the right axis. |
x_is_logarithmic | boolean | Whether the abscissa has a logarithmic scale. |
y_is_logarithmic | boolean | Whether the ordinate has a logarithmic scale. |
x_min | double | User-set minimum value of the abscissa. |
x_min_set | boolean | Whether user-set minimum value of the abscissa should be used (otherwise the range is determined automatically). |
x_max | double | User-set maximum value of the abscissa. |
x_max_set | boolean | Whether user-set maximum value of the abscissa should be used (otherwise the range is determined automatically). |
y_min | double | User-set minimum value of the ordinate. |
y_min_set | boolean | Whether user-set minimum value of the ordinate should be used (otherwise the range is determined automatically). |
y_max | double | User-set maximum value of the ordinate. |
y_max_set | boolean | Whether user-set maximum value of the ordinate should be used (otherwise the range is determined automatically). |
grid-type | 32bit integer | Type of grid shown. The value is from GwyGraphGridType enum. |
label.has_frame | boolean | Whether the graph key has a frame. |
label.frame_thickness | 32bit integer | Width of graph key frame. |
label.reverse | boolean | Whether to reverse the graph key. |
label.visible | boolean | Whether the graph key is visible. |
label.position | 32bit integer | The position (corner) where the graph key is places. The value is from GwyGraphLabelPosition enum. |
Graph curves are represented as GwyGraphCurveModel objects. The components of a GwyGraphCurveModel are summarised in the following table:
| Component | Type | Meaning |
|---|---|---|
xdata | array of doubles |
Abscissa points. The number of point must match ydata.
|
ydata | array of doubles |
Ordinate points. The number of point must match xdata.
|
description | string | Curve description (name). |
type | 32bit integer | Curve mode (points, lines, etc.) The value is from GwyGraphCurveType enum. |
color.red | double | Red component of the curve color. |
color.green | double | Green component of the curve color. |
color.blue | double | Blue component of the curve color. |
point_type | 32bit integer | Type of symbols representing data points. The value is from GwyGraphPointType enum. |
point_size | 32bit integer | Size of symbols representing data points. |
line_type | 32bit integer | Type of lines connecting data points. The value is from GwyGraphLineType enum. |
line_size | 32bit integer | Width of lines connecting data points. |
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.
| Key | Type | Meaning |
|---|---|---|
/sps/0 | GwySpectra | Spectra data. |
Sets of spectra of one kind are represented as GwySpectra objects. The components of a GwySpectra are summarised in the following table:
| Component | Type | Meaning |
|---|---|---|
title | string | Spectra title as displayed in the data browser. |
si_unit_xy | GwySIUnit | Unit of spectrum position coordinates. |
coords | array of doubles |
Coordinates of points where the spectra were taken, in physical units.
Each spectrum takes two items: for the horizontal and vertical coordinate.
The number of coordinates must match the number of curves in
data.
|
data | array of GwyDataLines | Individual spectra curves. |
selected | array of 32bit integers | Indices of selected spectra curves. |
Individual curves in spectra are represented as GwyDataLine objects. The components of a GwyDataLine are summarised in the following table:
| Component | Type | Meaning |
|---|---|---|
res | 32bit integer | Number of data points. |
real | double | Length in physical units. |
off | double | Offset of the begining in physical units. It usually occurs only if non-zero. |
si_unit_x | GwySIUnit | Unit of abscissa. |
si_unit_y | GwySIUnit | Unit of data values. |
data | array of doubles |
Line data, stored as an array of res,
from left to right.
|
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.
| Key | Type | Meaning |
|---|---|---|
/brick/0 | GwyBrick | Volume data. |
/brick/0/preview | GwyDataField | Two-dimensional data shown when the volume data is displayed in a window. |
/brick/0/title | string | Volume data title, as shown in the data browser. |
/brick/0/visible | boolean | Whether the volume data should be displayed in a window when the file is loaded. |
/brick/0/preview/palette | string | Name of the false color gradient used to display the preview data. |
/brick/0/meta | GwyContainer | Volume data metadata. The keys are directly the names as displayed in the metadata browser and the string values are the values. |
Volume data are represented as GwyBrick objects. The components of a GwyBrick are summarised in the following table:
| Component | Type | Meaning |
|---|---|---|
xres | 32bit integer | Horizontal size in pixels. |
yres | 32bit integer | Vertical size in pixels. |
zres | 32bit integer | Depth (number of levels) in pixels. |
xreal | double | Horizontal dimension in physical units. |
yreal | double | Vertical dimension in physical units. |
zreal | double | Depthwise dimension in physical units. |
xoff | double | Horizontal offset of the top-left corner in physical units. It usually occurs only if non-zero. |
yoff | double | Vertical offset of the top-left corner in physical units. It usually occurs only if non-zero. |
zoff | double | Depthwise offset of the top-left corner in physical units. It usually occurs only if non-zero. |
si_unit_x | GwySIUnit | Unit of horizontal lateral dimensions. |
si_unit_y | GwySIUnit | Unit of vertical lateral dimensions. |
si_unit_z | GwySIUnit | Unit of depthwise dimensions. |
si_unit_w | GwySIUnit | Unit of data values. |
data | array of doubles |
Field data, stored as a flat array of size
xres×yres×zres,
from the zeroth to the last plane, top to bottom and from left to right.
|
The components of a GwySIUnit are summarised in the following table:
| Component | Type | Meaning |
|---|---|---|
unitstr | string |
Textual representation of the unit, e.g. "A"
or "m^-1" (as base SI unit, prefixes are ignored).
|
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.
| Component | Type | Meaning |
|---|---|---|
max | 32bit integer |
Maximum number of objects the selection can hold (this is the number
set by gwy_selection_set_max_objects()).
|
data | array of doubles | Selection data. The number of items that form one selection object is determined by the selection type. |