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.
A GXYZF 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 eight NUL bytes, aligning the data start to a multiple of 8.
Binary data is in 64bit floating-point format.
gxyzf files start with the line
Gwyddion XYZ 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 channel titles, are represented in UTF-8 encoding. The NUL character may not occur in the header.
Header fields:
| Name | Type | Value |
|---|---|---|
NChannels | Mandatory |
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.
|
NPoints | Mandatory | Number data points in the file. |
XYUnits | Optional |
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.
|
XRes | Optional | 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. |
YRes | Optional | 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
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):
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.