The Gwyddion native file format
captures all the information and state Gwyddion needs to save and
consequently it is quite complex. Often it is not practical to save files
in .gwy format in custom programs and scripts creating
input for Gwyddion.
The Gwyddion Simple Field file format (.gsf) can be
used in these situations instead. It is a single-channel format for 2D
data that was designed to be easy and efficient to read and write, with
human-readable header, reasonably expressive, and avoiding instrument or
application specific fields (though it can optionally bear them).
GSF can be read and written by Gwyddion version 2.20 or later. Third party implementations also exist, for instance Python gsffile.
A GSF file consists of four parts, in the following order:
Files begin with a “magic line” identifying the file type.
The header consists of lines of the form
name=value
defining individual parameters.
The header is terminated by one to four NUL bytes, aligning the data start to a multiple of 4.
Binary data is in 32bit floating-point format.
GSF files start with the line
Gwyddion Simple Field 1.0
terminated by a linefeed character (\n, ASCII 0x0a).
Each header line has the form
name=value
where any whitespace before the name, around the equal sign and at the end of value is ignored. Field names are case-sensitive and follow the usual rules for identifiers in programming languages.
Similarly to the magic line, the lines in the text header are terminated by a linefeed character as is usual on Unix. This means the header must be read and written in binary mode to ensure preservation of end-of-line characters on other systems (and not changing the header size e.g. by LF → CRLF transformation).
Any non-ASCII characters, that can occur for example in the channel title, are represented in UTF-8 encoding. The NUL character may not occur in the header.
Header fields:
| Name | Type | Value |
|---|---|---|
XRes | Mandatory | The horizontal size in pixels, a positive integer. |
YRes | Mandatory | The vertical size in pixels, a positive integer. |
XReal | Optional |
Horizontal size in physical units (given by
XYUnits), a positive floating point number.
It defaults to 1.0 if not given.
|
YReal | Optional |
Vertical size in physical units (given by
XYUnits), a positive floating point number. It
defaults to 1.0 if not given.
|
XOffset | Optional |
Horizontal offset in physical units (given by
XYUnits), a floating point number. It defaults
to 0.0 if not given.
|
YOffset | Optional |
Vertical offset in physical units (given by
XYUnits), a floating point number.
It defaults to 0.0 if not given.
|
Title | Optional | Data/channel title. It has no default, applications might display ‘Unknown’ or something similar if not given. |
XYUnits | Optional |
Lateral units, i.e. units of physical sizes and offsets. They
must be given as base units, that is m or
A with no power-of-10 prefix (Gwyddion could
deal with it but it might present a problem for other software).
The default is no units. This means in SPM data, you normally
wish to specify XYUnits as
m because the lateral dimensions are in
metres.
|
ZUnits | Optional |
Value units, i.e. units of data values. See
XYUnits above for details.
|
Floating point numbers can be in the scientific format, e.g.
1.23e-4. They are represented in the standard C/POSIX
locale, i.e. decimal dot is used (not comma or other separators).
The header may contain other fields beside those listed above. Gwyddion
will load them into metadata.
Common informational fields can include Comment,
Date or Direction.
Fields may occur in any order, nevertheless, it is recommended to start with mandatory fields, continue with optional fields and put custom fields last.
A simple header example (also including the magic line):
Gwyddion Simple Field 1.0 XRes = 400 YRes = 400 XReal = 5e-05 YReal = 5e-05 XYUnits = m ZUnits = V Title = ADC2
The text header is followed by one to four NUL (\0,
ASCII 0x00) bytes that (a) terminate it and (b) align the data start to
an offset from the begining of file that is a multiple of 4. More
precisely, denoting N the total length of
the magic line and the text header, the data starts at the nearest
multiple of 4 larger than N.
This padding to a multiple of 4 ensures aligned memory access when mapping the file directly to memory. The number of NUL bytes is uniquely determined by the remainder of the length modulo four (N mod 4):
Data values are stored as IEEE 32bit single-precision floating point numbers, in little-endian (LSB, or Intel) byte order. Values are stored by row, from top to bottom, and in each row from left to right.
Similarly to GWY files, the data should not contain infinities and NaNs (not-a-numbers). Gwyddion replaces and masks such values upon import since version 2.57, but behaviour in older versions is undefined.
The physical units of these values are ZUnits.
The size of the image data is exactly 4*XRes*YRes
bytes and there is no data after it in the file.