Simple Field Files

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.

Overall structure

A GSF file consists of four parts, in the following order:

magic line

Files begin with a magic line identifying the file type.

text header

The header consists of lines of the form

name = value

defining individual parameters.

NUL padding

The header is terminated by one to four NUL bytes, aligning the data start to a multiple of 4.

binary data

Binary data is in 32bit floating-point format.

Magic line

GSF files start with the line

Gwyddion Simple Field 1.0

terminated by a linefeed character (\n, ASCII 0x0a).

Text header

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:

NameTypeValue
XResMandatory The horizontal size in pixels, a positive integer.
YResMandatory The vertical size in pixels, a positive integer.
XRealOptional Horizontal size in physical units (given by XYUnits), a positive floating point number. It defaults to 1.0 if not given.
YRealOptional Vertical size in physical units (given by XYUnits), a positive floating point number. It defaults to 1.0 if not given.
XOffsetOptional Horizontal offset in physical units (given by XYUnits), a floating point number. It defaults to 0.0 if not given.
YOffsetOptional Vertical offset in physical units (given by XYUnits), a floating point number. It defaults to 0.0 if not given.
TitleOptional Data/channel title. It has no default, applications might display ‘Unknown’ or something similar if not given.
XYUnitsOptional 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.
ZUnitsOptional 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

NUL padding

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):

RemainderNumber of padding NULs
04
13
22
31

Binary data

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.

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.