Simple XYZ Files

Although Gwyddion does work with general XYZ data and raw XYZ data are interpolated to a grid upon import, need has arisen for a file format similar in spirit to Gwyddion simple field (.gsf) but representing the data in XYZ format. Such file format, called Gwyddion XYZ Field (.gxyzf), is described in this section.

It should be noted that Z simply stands for the ordinate here. Z values in the file may be actual Z coordinates (heights) but they may also be currents, voltages, etc.

GXYZF can be written by Gwyddion version 2.31 or later. They can also be read since this version, although the regularisation to a grid may be somewhat crude.

Overall structure

A GXYZF 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 eight NUL bytes, aligning the data start to a multiple of 8.

binary data

Binary data is in 64bit floating-point format.

Magic line

gxyzf files start with the line

Gwyddion XYZ 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 channel titles, are represented in UTF-8 encoding. The NUL character may not occur in the header.

Header fields:

NChannelsMandatory Number of value (Z) channels, a positive integer. The values stored for each point include also coordinates X and Y but they are not counted into NChannels.
NPointsMandatory Number data points in the file.
XYUnitsOptional Lateral units, i.e. units of X and Y values. 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.
ZUnits1, ZUnits2, … Optional Value units, i.e. units of data values for individual channels. Channels are numbered from 1 to NChannels. See XYUnits above for details.
Title1, Title2, … Optional Titles of individual channels. Channels are numbered from 1 to NChannels. Titles have no default, applications might display ‘Unknown’ or something similar if not given.
XResOptional Hint specifying the preferred horizontal size in pixels if the data are regularised to a grid, a positive integer. Readers are not required to honour it and may interpolate data to grids of different dimensions.
YResOptional Hint specifying the preferred vertical size in pixels if the data are regularised to a grid, a positive integer. Readers are not required to honour it and may interpolate data to grids of different dimensions.

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 of a two-channel file (also including the magic line):

Gwyddion XYZ Field 1.0
NChannels = 2
NPoints = 457884
XYUnits = m
ZUnits1 = m
ZUnits2 = V
Title1 = Height
Title2 = ADC2

NUL padding

The text header is followed by one to eight 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 8. More precisely, denoting N the total length of the magic line and the text header, the data starts at the nearest multiple of 8 larger than N.

This padding to a multiple of 8 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 eight (N mod 8):

RemainderNumber of padding NULs

Binary data

Data values are stored as IEEE 64bit double-precision floating point numbers, in little-endian (LSB, or Intel) byte order. Points are stored in arbitrary order. Each point is stored as a block of NChannels+2 values: X, Y and then all ordinate values, in the channel order.

The physical units of the values are given by XYUnits for X and Y and then ZUnits1, ZUnits2, … for the ordinate values.

The size of the data is exactly 8*NPoints*(NChannels+2) bytes and there is no data after it in the file.