![]() |
![]() |
![]() |
Gwyddion Module Library Reference Manual | ![]() |
---|
Dump FormatDump Format — Dumb dump file format used for data exchange between plug-in proxy and plug-ins |
The dump format consists of text lines, except for the actual data samples which are for efficiency reasons stored as arrays of (binary) IEEE double precision numbers.
Since dump files contain binary data (along with text lines) they have to be always opened in binary mode to avoid end-of-line conversions (on systems distinguishing between text and binary files). Unix end-of-lines are always used, i.e., lines are always terminated by a single LF (line feed) character, ASCII 0x0a. Plugin-proxy always writes data with Unix end-of-lines and although it may read dumps with CRLF end-of-lines without problems too, don't count on it.
The text lines have the form
.
The keys are keys in data container
created for the data, and the values are corresponding values.
Except for a few special keys specified below, all values are stored
as strings.
key
=value
There are only a few types of data you may expect to find in or want to write to a dump file:
/meta/
followed by an arbitrary key string. Not used directly by
Gwyddion, but will appear in Metadata Browser.
The data samples themselves are stored as a sequence of binary IEEE
double precision floating point numbers in little-endian byte order.
The array is
preceded by line /0/data=[
and
a single left bracket [
(with no newline after).
The data samples are closed by a sequence of two right brackets
]]
and a single LF character.
The end of data field marker serves as a check the data was read
correctly, as its size must be know beforehand.
To be more precise, /0/data
is the name of the
main data field. As data fields can generally have arbitrary names
and left bracket is a valid value, a [
as a value
marks start of a data field if and only if the next line starts with a
[
too. Otherwise it is a regular metadata value.
The data samples are stored in `screen' order. That means they are ordered by lines (rows), starting from the uppermost one, and inside lines they are ordered by column, from left to right.
The resolutions and physical dimensions are specified using special
keys /0/data/xres
, /0/data/yres
,
/0/data/xreal
, and /0/data/yreal
.
Since the resolutions must be obviously known before data samples can
be read, the lines
/0/data/xres=
and
x-resolution
/0/data/yres=
must appear somewhere before them in the file. It is also strongly
recommended to specify physical dimensions too, though it is not
strictly necessary if you don't mind some bogus default value (like
1 meter) is substituted then.
y-resolution
All the values are in base SI units, i.e., dimensions are in meters
(not micrometers, nanometres, or kilometres), currents in ampers
(not picoampers), etc. The base units can be specified using the
/0/data/unit-xy
(lateral) and
/0/data/unit-z
(value, height) keys.
If not specified, meters are assumed.
A dump file with a single data field "/0/data"
thus could look (replacing binary data with dots):