Resources

Various bits of data, e.g. false color maps or raw file import presets, are stored in standalone files that are collectively called resource files. Gwyddion looks for resources in two different locations: system and user-specific.

System resources are installed along with the program and they are not modifiable. Typically, they are located under a directory such as /usr/share/gwyddion (Unix), Program Files\Gwyddion (MS Windows) or other directory determined by GWYDDION_DATADIR.

User resources are located in a user's directory, this usually means under ~/.gwyddion (Unix) or Documents and Settings\gwyddion (MS Windows).

All resource files are simple text files that can be easily examined and modified by text editors or sent to other users (if they are copied or created manually Gwyddion needs to be restarted to notice them). In most cases only characters of the ASCII can appear in the files. If international text can appear there it must be in the UTF-8 encoding. Numerical values are represented in the standard POSIX format, i.e. with decimal point, independently on what decimal separator is usual in the user's language.

Resources are organized in subdirectories according to their kind, e.g. color gradients reside in the subdirectory gradients. The name of the file determines the resource name – gradient Gray is found in file gradients/Gray. Modules can define their own resource types; the types described here are the most important types but the list may not be comprehensive.

Every resource file has the same structure. It starts with a line identifying the resource type:

Gwyddion resource GwyGradient

where GwyGradient is the type name in the type system (which is quite a low-level detail but so it is), followed by named parameters in the form

name value

and resource data. Some resource types may contain only named parameters, other may contain only data.

Gradients

Gradients, i.e. false color maps, reside in directory gradients, they are identified by GwyGradient and contain only data. They can be edited in the application using the gradient editor.

The gradient data consists of rows corresponding to individual points in the gradient:

position red green blue alpha

The position determines where the color defined by red, green, blue and alpha components is placed in the interval [0, 1] where 0 corresponds to the gradient start, 1 corresponds to the end. The color is interpolated linearly between the specified points.

The positions must form an increasing sequence from 0 to 1 (i.e. the minimum number of color points is two). The range of the color components is also [0, 1]. Note the alpha value, corresponding to opacity, is unused and must be given as 1 (fully opaque).

For instance, the standard gradient Red going from black (0 0 0) to red (1 0 0) to white (1 1 1) is defined as follows:

Gwyddion resource GwyGradient
0.0 0 0 0 1
0.5 1 0 0 1
1.0 1 1 1 1

OpenGL Materials

OpenGL materials reside in directory glmaterials, they are identified by GwyGLMaterial and contain only data. They can be edited in the application using the OpenGL material editor.

The material data consists of four RGBA lines, similar to gradients that correspond in to the four OpenGL material components in the following order:

  1. ambient,
  2. diffuse,
  3. specular,
  4. emission.

See section OpenGL Material Editor for explanation of the components. They are followed by a line containing the shininess, again as a number from the interval [0, 1].

Note the emission component, while read and written by Gwyddion, is presently unused by the 3D view. It is recommended to set it to 0 0 0 1, i.e. black.

For instance, the standard material Red-Rubber with very dark red ambient color, grayish diffuse reflection, red specular reflection and low shininess is defined as follows:

Gwyddion resource GwyGLMaterial
0.05 0.0  0.0  1.0
0.5  0.4  0.4  1.0
0.7  0.04 0.04 1.0
0.0  0.0  0.0  1.0
.078125

Grain Values

Grain values reside in directory grainvalues, they are identified by GwyGrainValue and contain only named parameters. They can be used to define additional grain quantities, derived from the built-in quantities, that appear under User group in grain analysis functions. At the time of writing this, there is no editor in the application, new quantities must be created manually.

The named parameters are summarized in the following table:

ParameterRequiredTypeDescription
symbolrequiredidentifier Identifier to use in other expressions (but see below). It must be a valid identifier of ASCII letters, numbers and underscores, starting with a letter.
expressionrequiredfree-form Formula for calculation of this quantity from other grain quantities. The general expression syntax is described in section Expressions.
symbol_markupoptionalfree-form Fancy symbol that can include Greek letters or subscripts and superscripts expressed with the Pango markup language. It is used for presentation in the application so, while it is optional, it is recommended to at least define it identically to symbol.
power_xyoptionalinteger The power in which the lateral dimensions appear in the quantity. For instance, this is 1 for grain dimensions, 2 for areas and volumes. The default value is 0.
power_zoptionalinteger The power in which the height dimension appears in the quantity. For instance, this is 1 for values and volumes, 0 for dimensions and areas. The default value is 0.
same_unitsoptional0 or 1 Given as 1 if the quantity makes sense only for lateral and height dimensions being the same physical quantities. For instance, this is required for the surface area. The default is 0.
is_angleoptional0 or 1 Given as 1 if the quantity is an angle. The expression should calculate angles in radians. However, if is_angle is set Gwyddion knowns the value can be converted to degrees for presentation. The default is 0.

At present, user-defined grain quantities cannot depend on other user-defined grain quantities to avoid circular dependencies. The built-in grain quantities are listed below:

SymbolGroupName
x_cPositionCenter x position
y_cPositionCenter y position
z_minValueMinimum value
z_maxValueMaximum value
z_mValueMean value
z_medValueMedian value
b_minValueMinimum value on boundary
b_maxValueMaximum value on boundary
A_0AreaProjected area
A_sAreaSurface area
a_eqAreaEquivalent square side
r_eqAreaEquivalent disc radius
A_hAreaArea above half-height
A_cAreaArea of convex hull
V_0VolumeZero basis volume
V_minVolumeGrain minimum basis volume
V_LVolumeLaplacian background basis volume
L_b0BoundaryProjected boundary length
D_minBoundaryMinimum bounding size
phi_minBoundaryMinimum bounding direction
D_maxBoundaryMaximum bounding size
phi_maxBoundaryMaximum bounding direction
R_iBoundaryMaximum inscribed disc radius
x_iBoundaryMaximum inscribed disc center x position
y_iBoundaryMaximum inscribed disc center y position
R_eBoundaryMinimum circumcircle radius
x_eBoundaryMinimum circumcircle center x position
y_eBoundaryMinimum circumcircle center y position
R_mBoundaryMean radius
thetaSlopeInclination θ
phiSlopeInclination φ
x_0CurvatureCurvature center x position
y_0CurvatureCurvature center y position
z_0CurvatureCurvature center z value
kappa_1CurvatureCurvature 1
kappa_2CurvatureCurvature 2
phi_1CurvatureCurvature angle 1
phi_2CurvatureCurvature angle 2
a_e1MomentMajor semiaxis of equivalent ellipse
a_e2MomentMinor semiaxis of equivalent ellipse
phi_e1MomentOrientation of equivalent ellipse

For instance, a new grain value Height, measuring the grain height as the difference between the maximum and minimum value, can be defined as follows:

Gwyddion resource GwyGrainValue
symbol dz
symbol_markup Δz
power_xy 0
power_z 1
expression z_max - z_min

Raw File Presets

Raw file presents reside in directory rawfile, they are identified by GwyRawFilePreset and contain only named parameters. They are normally created and edited by the preset editor in the raw file import module.

The named parameters in the resource files correspond closely to the parameters in the user interface explained in detail in section Raw Data File Import. Hence, they will be described only briefly here.

ParameterTypeDescription
xres, yresinteger horizontal and vertical size
xreal, yrealnumber physical dimensions, in units given by xyexponent and xyunit
xyexponentmultiple of 3 power of 10 to multiply xreal and yreal with
xyunitstring base units of xreal and yreal, e.g. "m"
zscalenumber unit step in values
zexponentmultiple of 3 power of 10 to multiply zscale with
zunitstring base units of zscale
havemissing0 or 1 0 means missing value handling is disabled, 1 means it is enabled
missingvaluenumber the special subsitute value that denotes missing data
format0 or 1 0 means binary, 1 means text
builtin (binary)integer built-in data format id, see below
offset (binary)integer data offset in file, in bytes
size (binary)integer data value size, in bits
skip (binary)integer number of bits to skip after each value
rowskip (binary)integer number of additional bits to skip after each row
sign (binary)0 or 1 0 means unsigned, 1 means signed
revsample (binary)0 or 1 1 means reverse bits in values
revbyte (binary)0 or 1 1 means reverse bits in bytes
byteswap (binary)integer byte swap pattern
lineoffset (text)integer lines to skip before starting to read the data
skipfields (text)integer fields to skip at the start of each line
delimiter (text)string field delimiter, empty string means arbitrary whitespace
decomma (text)0 or 1 1 if decimal separator is comma, 0 for dot

Note the choice of a built-in binary format, i.e. nonzero builtin, implies the binary format to some extent. This means the options size, revbyte and sign are ignored as they are used only for detailed specification of user formats. The available formats are listed in the following table:

TypeDescription
0user-specified
1signed 8bit integer
2unsigned 8bit integer
3signed 16bit integer
4unsigned 16bit integer
5signed 32bit integer
6unsigned 32bit integer
7IEEE float
8IEEE double
9signed 64bit integer
10unsigned 64bit integer