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, 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 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:
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 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:
Parameter | Required | Type | Description |
---|---|---|---|
symbol | required | identifier | 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. |
expression | required | free-form | Formula for calculation of this quantity from other grain quantities. The general expression syntax is described in section Expressions. |
symbol_markup | optional | free-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_xy | optional | integer | 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_z | optional | integer | 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_units | optional | 0 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_angle | optional | 0 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:
Symbol | Group | Name |
---|---|---|
x_c | Position | Center x position |
y_c | Position | Center y position |
z_min | Value | Minimum value |
z_max | Value | Maximum value |
z_m | Value | Mean value |
z_med | Value | Median value |
z_rms | Value | RMS value |
b_min | Value | Minimum value on boundary |
b_max | Value | Maximum value on boundary |
A_px | Area | Pixel area |
A_0 | Area | Projected area |
A_s | Area | Surface area |
a_eq | Area | Equivalent square side |
r_eq | Area | Equivalent disc radius |
A_h | Area | Area above half-height |
A_c | Area | Area of convex hull |
V_0 | Volume | Zero basis volume |
V_min | Volume | Grain minimum basis volume |
V_L | Volume | Laplacian background basis volume |
L_b0 | Boundary | Projected boundary length |
D_min | Boundary | Minimum bounding size |
phi_min | Boundary | Minimum bounding direction |
D_max | Boundary | Maximum bounding size |
phi_max | Boundary | Maximum bounding direction |
R_i | Boundary | Maximum inscribed disc radius |
x_i | Boundary | Maximum inscribed disc center x position |
y_i | Boundary | Maximum inscribed disc center y position |
R_e | Boundary | Minimum circumcircle radius |
x_e | Boundary | Minimum circumcircle center x position |
y_e | Boundary | Minimum circumcircle center y position |
R_m | Boundary | Mean radius |
M_min | Boundary | Minimum Martin diameter |
omega_min | Boundary | Direction of minimum Martin diameter |
M_max | Boundary | Maximum Martin diameter |
omega_max | Boundary | Direction of maximum Martin diameter |
theta | Slope | Inclination θ |
phi | Slope | Inclination φ |
x_0 | Curvature | Curvature center x position |
y_0 | Curvature | Curvature center y position |
z_0 | Curvature | Curvature center z value |
kappa_1 | Curvature | Curvature 1 |
kappa_2 | Curvature | Curvature 2 |
phi_1 | Curvature | Curvature angle 1 |
phi_2 | Curvature | Curvature angle 2 |
a_e1 | Moment | Major semiaxis of equivalent ellipse |
a_e2 | Moment | Minor semiaxis of equivalent ellipse |
phi_e1 | Moment | Orientation 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 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.
Parameter | Type | Description |
---|---|---|
xres , yres | integer | horizontal and vertical size |
xreal , yreal | number |
physical dimensions, in units given by
xyexponent and xyunit
|
xyexponent | multiple of 3 |
power of 10 to multiply xreal and
yreal with
|
xyunit | string |
base units of xreal and
yreal , e.g. "m"
|
zscale | number | unit step in values |
zexponent | multiple of 3 |
power of 10 to multiply zscale with
|
zunit | string |
base units of zscale
|
havemissing | 0 or 1 | 0 means missing value handling is disabled, 1 means it is enabled |
missingvalue | number | the special subsitute value that denotes missing data |
format | 0 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:
Type | Description |
---|---|
0 | user-specified |
1 | signed 8bit integer |
2 | unsigned 8bit integer |
3 | signed 16bit integer |
4 | unsigned 16bit integer |
5 | signed 32bit integer |
6 | unsigned 32bit integer |
7 | IEEE float |
8 | IEEE double |
9 | signed 64bit integer |
10 | unsigned 64bit integer |