Gwyddion – Free SPM (AFM, SNOM/NSOM, STM, MFM, …) data analysis software

stats

stats — Two-dimensional statistical functions

Functions

gdouble	gwy_data_field_get_max ()
gdouble	gwy_data_field_get_min ()
void	gwy_data_field_get_min_max ()
gdouble	gwy_data_field_get_avg ()
gdouble	gwy_data_field_get_rms ()
gdouble	gwy_data_field_get_mean_square ()
gdouble	gwy_data_field_get_sum ()
gdouble	gwy_data_field_get_median ()
gdouble	gwy_data_field_get_surface_area ()
gdouble	gwy_data_field_get_surface_slope ()
gdouble	gwy_data_field_get_variation ()
gdouble	gwy_data_field_get_entropy ()
gdouble	gwy_data_field_get_entropy_2d ()
gdouble	gwy_data_field_area_get_max ()
gdouble	gwy_data_field_area_get_min ()
void	gwy_data_field_area_get_min_max ()
void	gwy_data_field_area_get_min_max_mask ()
gdouble	gwy_data_field_area_get_avg ()
gdouble	gwy_data_field_area_get_avg_mask ()
gdouble	gwy_data_field_area_get_rms ()
gdouble	gwy_data_field_area_get_rms_mask ()
gdouble	gwy_data_field_area_get_grainwise_rms ()
gdouble	gwy_data_field_area_get_sum ()
gdouble	gwy_data_field_area_get_sum_mask ()
gdouble	gwy_data_field_area_get_median ()
gdouble	gwy_data_field_area_get_median_mask ()
gdouble	gwy_data_field_area_get_surface_area ()
gdouble	gwy_data_field_area_get_surface_area_mask ()
gdouble	gwy_data_field_area_get_surface_slope_mask ()
gdouble	gwy_data_field_area_get_mean_square ()
gdouble	gwy_data_field_area_get_entropy_at_scales ()
gdouble	gwy_data_field_get_entropy_2d_at_scales ()
gdouble	gwy_data_field_area_get_variation ()
gdouble	gwy_data_field_area_get_entropy ()
gdouble	gwy_data_field_area_get_volume ()
void	gwy_data_field_get_autorange ()
void	gwy_data_field_area_get_autorange ()
void	gwy_data_field_get_stats ()
void	gwy_data_field_area_get_stats ()
void	gwy_data_field_area_get_stats_mask ()
void	gwy_data_field_area_count_in_range ()
void	gwy_data_field_area_dh ()
void	gwy_data_field_dh ()
void	gwy_data_field_area_cdh ()
void	gwy_data_field_cdh ()
void	gwy_data_field_area_da ()
void	gwy_data_field_area_da_mask ()
void	gwy_data_field_da ()
void	gwy_data_field_area_cda ()
void	gwy_data_field_area_cda_mask ()
void	gwy_data_field_cda ()
void	gwy_data_field_area_acf ()
void	gwy_data_field_acf ()
GwyDataLine *	gwy_data_field_area_row_acf ()
void	gwy_data_field_area_hhcf ()
void	gwy_data_field_hhcf ()
GwyDataLine *	gwy_data_field_area_row_hhcf ()
void	gwy_data_field_area_psdf ()
void	gwy_data_field_psdf ()
GwyDataLine *	gwy_data_field_area_row_psdf ()
void	gwy_data_field_area_rpsdf ()
void	gwy_data_field_rpsdf ()
GwyDataLine *	gwy_data_field_area_row_asg ()
void	gwy_data_field_area_2dacf ()
void	gwy_data_field_area_2dacf_mask ()
void	gwy_data_field_2dacf ()
void	gwy_data_field_area_2dpsdf_mask ()
void	gwy_data_field_2dpsdf ()
void	gwy_data_field_area_racf ()
void	gwy_data_field_racf ()
void	gwy_data_field_area_minkowski_volume ()
void	gwy_data_field_minkowski_volume ()
void	gwy_data_field_area_minkowski_boundary ()
void	gwy_data_field_minkowski_boundary ()
void	gwy_data_field_area_minkowski_euler ()
void	gwy_data_field_minkowski_euler ()
gdouble	gwy_data_field_area_get_dispersion ()
gdouble	gwy_data_field_get_dispersion ()
void	gwy_data_field_slope_distribution ()
void	gwy_data_field_facet_distribution ()
void	gwy_data_field_get_normal_coeffs ()
void	gwy_data_field_area_get_normal_coeffs ()
gint	gwy_data_field_area_get_normal_coeffs_mask ()
void	gwy_data_field_area_get_inclination ()
void	gwy_data_field_get_inclination ()
void	gwy_data_field_area_get_line_stats ()
void	gwy_data_field_get_line_stats_mask ()
void	gwy_data_field_get_line_stats ()
guint	gwy_data_field_count_maxima ()
guint	gwy_data_field_count_minima ()
GwyDataLine *	gwy_data_field_psdf_to_angular_spectrum ()
void	gwy_data_field_angular_average ()

Includes

#include <libprocess/gwyprocess.h>

Description

Many statistical functions permit to pass masks that determine which values in the data field to take into account or ignore when calculating the statistical characteristics. Masking mode GWY_MASK_INCLUDE means that maks values equal to 0.0 and below cause corresponding data field samples to be ignored, values equal to 1.0 and above cause inclusion of corresponding data field samples. The behaviour for values inside interval (0.0, 1.0) is undefined. In mode GWY_MASK_EXCLUDE , the meaning of mask is inverted, as if all mask values x were replaced with 1-x. The mask field is ignored in mode GWY_MASK_IGNORE , i.e. the same behaviour occurs as with NULL mask argument.

Functions

gwy_data_field_get_max ()

gdouble
gwy_data_field_get_max (GwyDataField *data_field);

Finds the maximum value of a data field.

This quantity is cached.

Parameters

data_field

A data field.

Returns

The maximum value.

gwy_data_field_get_min ()

gdouble
gwy_data_field_get_min (GwyDataField *data_field);

Finds the minimum value of a data field.

This quantity is cached.

Parameters

data_field

A data field.

Returns

The minimum value.

gwy_data_field_get_min_max ()

void
gwy_data_field_get_min_max (GwyDataField *data_field,
                            gdouble *min,
                            gdouble *max);

Finds minimum and maximum values of a data field.

Parameters

data_field	A data field.
min	Location to store minimum to.
max	Location to store maximum to.

gwy_data_field_get_avg ()

gdouble
gwy_data_field_get_avg (GwyDataField *data_field);

Computes average value of a data field.

This quantity is cached.

Parameters

data_field

A data field

Returns

The average value.

gwy_data_field_get_rms ()

gdouble
gwy_data_field_get_rms (GwyDataField *data_field);

Computes root mean square value of a data field.

The root mean square value is calculated with respect to the mean value. See gwy_data_field_get_mean_square() for a similar function which does not subtract the mean value.

This quantity is cached.

Parameters

data_field

A data field.

Returns

The root mean square value.

gwy_data_field_get_mean_square ()

gdouble
gwy_data_field_get_mean_square (GwyDataField *data_field);

Computes mean square value of a data field.

See gwy_data_field_area_get_mean_square() for remarks.

Parameters

data_field

A two-dimensional data field.

Returns

The mean square value.

Since: 2.52

gwy_data_field_get_sum ()

gdouble
gwy_data_field_get_sum (GwyDataField *data_field);

Sums all values in a data field.

This quantity is cached.

Parameters

data_field

A data field.

Returns

The sum of all values.

gwy_data_field_get_median ()

gdouble
gwy_data_field_get_median (GwyDataField *data_field);

Computes median value of a data field.

This quantity is cached.

Parameters

data_field

A data field.

Returns

The median value.

gwy_data_field_get_surface_area ()

gdouble
gwy_data_field_get_surface_area (GwyDataField *data_field);

Computes surface area of a data field.

This quantity is cached.

Parameters

data_field

A data field.

Returns

The surface area.

gwy_data_field_get_surface_slope ()

gdouble
gwy_data_field_get_surface_slope (GwyDataField *data_field);

Computes root mean square surface slope (Sdq) of a data field.

Parameters

data_field

A data field.

Returns

The root mean square surface slope.

Since: 2.58

gwy_data_field_get_variation ()

gdouble
gwy_data_field_get_variation (GwyDataField *data_field);

Computes the total variation of a data field.

See gwy_data_field_area_get_variation() for the definition.

This quantity is cached.

Parameters

data_field

A data field.

Returns

The variation.

Since: 2.38

gwy_data_field_get_entropy ()

gdouble
gwy_data_field_get_entropy (GwyDataField *data_field);

Computes the entropy of a data field.

See gwy_data_field_area_get_entropy() for the definition.

This quantity is cached.

Parameters

data_field

A data field.

Returns

The value distribution entropy.

Since: 2.42

gwy_data_field_get_entropy_2d ()

gdouble
gwy_data_field_get_entropy_2d (GwyDataField *xfield,
                               GwyDataField *yfield);

Computes the entropy of a two-dimensional point cloud.

Each pair of corresponding xfield and yfield pixels is assumed to represent the coordinates (x ,y ) of a point in plane. Hence they must have the same dimensions.

Parameters

xfield	A data field containing the `x` -coordinates.
yfield	A data field containing the `y` -coordinates.

Returns

The two-dimensional distribution entropy.

Since: 2.44

gwy_data_field_area_get_max ()

gdouble
gwy_data_field_area_get_max (GwyDataField *data_field,
                             GwyDataField *mask,
                             gint col,
                             gint row,
                             gint width,
                             gint height);

Finds the maximum value in a rectangular part of a data field.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).

Returns

The maximum value. When the number of samples to calculate maximum of is zero, -G_MAXDOUBLE is returned.

gwy_data_field_area_get_min ()

gdouble
gwy_data_field_area_get_min (GwyDataField *data_field,
                             GwyDataField *mask,
                             gint col,
                             gint row,
                             gint width,
                             gint height);

Finds the minimum value in a rectangular part of a data field.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).

Returns

The minimum value. When the number of samples to calculate minimum of is zero, -G_MAXDOUBLE is returned.

gwy_data_field_area_get_min_max ()

void
gwy_data_field_area_get_min_max (GwyDataField *data_field,
                                 GwyDataField *mask,
                                 gint col,
                                 gint row,
                                 gint width,
                                 gint height,
                                 gdouble *min,
                                 gdouble *max);

Warning

gwy_data_field_area_get_min_max is deprecated and should not be used in newly-written code.

Finds minimum and maximum values in a rectangular part of a data field.

This function is equivalent to calling gwy_data_field_area_get_min_max_mask() with masking mode GWY_MASK_INCLUDE.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
min	Location to store minimum to.
max	Location to store maximum to.

gwy_data_field_area_get_min_max_mask ()

void
gwy_data_field_area_get_min_max_mask (GwyDataField *data_field,
                                      GwyDataField *mask,
                                      GwyMaskingType mode,
                                      gint col,
                                      gint row,
                                      gint width,
                                      gint height,
                                      gdouble *min,
                                      gdouble *max);

Finds minimum and maximum values in a rectangular part of a data field.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
mode	Masking mode to use. See the introduction for description of masking modes.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
min	Location to store minimum to.
max	Location to store maximum to.

Since: 2.18

gwy_data_field_area_get_avg ()

gdouble
gwy_data_field_area_get_avg (GwyDataField *data_field,
                             GwyDataField *mask,
                             gint col,
                             gint row,
                             gint width,
                             gint height);

Warning

gwy_data_field_area_get_avg is deprecated and should not be used in newly-written code.

Computes average value of a rectangular part of a data field.

This function is equivalent to calling gwy_data_field_area_get_avg_mask() with masking mode GWY_MASK_INCLUDE.

Parameters

data_field	A data field
mask	Mask specifying which values to take into account/exclude, or `NULL`.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).

Returns

The average value.

gwy_data_field_area_get_avg_mask ()

gdouble
gwy_data_field_area_get_avg_mask (GwyDataField *data_field,
                                  GwyDataField *mask,
                                  GwyMaskingType mode,
                                  gint col,
                                  gint row,
                                  gint width,
                                  gint height);

Computes average value of a rectangular part of a data field.

Parameters

data_field	A data field
mask	Mask specifying which values to take into account/exclude, or `NULL`.
mode	Masking mode to use. See the introduction for description of masking modes.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).

Returns

The average value.

Since: 2.18

gwy_data_field_area_get_rms ()

gdouble
gwy_data_field_area_get_rms (GwyDataField *data_field,
                             GwyDataField *mask,
                             gint col,
                             gint row,
                             gint width,
                             gint height);

Warning

gwy_data_field_area_get_rms is deprecated and should not be used in newly-written code.

Computes root mean square value of a rectangular part of a data field.

The root mean square value is calculated with respect to the mean value.

This function is equivalent to calling gwy_data_field_area_get_rms_mask() with masking mode GWY_MASK_INCLUDE.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).

Returns

The root mean square value.

gwy_data_field_area_get_rms_mask ()

gdouble
gwy_data_field_area_get_rms_mask (GwyDataField *data_field,
                                  GwyDataField *mask,
                                  GwyMaskingType mode,
                                  gint col,
                                  gint row,
                                  gint width,
                                  gint height);

Computes root mean square value of deviations of a rectangular part of a data field.

The root mean square value is calculated with respect to the mean value.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
mode	Masking mode to use. See the introduction for description of masking modes.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).

Returns

The root mean square value of deviations from the mean value.

Since: 2.18

gwy_data_field_area_get_grainwise_rms ()

gdouble
gwy_data_field_area_get_grainwise_rms (GwyDataField *data_field,
                                       GwyDataField *mask,
                                       GwyMaskingType mode,
                                       gint col,
                                       gint row,
                                       gint width,
                                       gint height);

Computes grain-wise root mean square value of deviations of a rectangular part of a data field.

Grain-wise means that the mean value is determined for each grain (i.e. cotinguous part of the mask or inverted mask) separately and the deviations are calculated from these mean values.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
mode	Masking mode to use. See the introduction for description of masking modes.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).

Returns

The root mean square value of deviations from the mean value.

Since: 2.29

gwy_data_field_area_get_sum ()

gdouble
gwy_data_field_area_get_sum (GwyDataField *data_field,
                             GwyDataField *mask,
                             gint col,
                             gint row,
                             gint width,
                             gint height);

Warning

gwy_data_field_area_get_sum is deprecated and should not be used in newly-written code.

Sums values of a rectangular part of a data field.

This function is equivalent to calling gwy_data_field_area_get_sum_mask() with masking mode GWY_MASK_INCLUDE.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).

Returns

The sum of all values inside area.

gwy_data_field_area_get_sum_mask ()

gdouble
gwy_data_field_area_get_sum_mask (GwyDataField *data_field,
                                  GwyDataField *mask,
                                  GwyMaskingType mode,
                                  gint col,
                                  gint row,
                                  gint width,
                                  gint height);

Sums values of a rectangular part of a data field.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
mode	Masking mode to use. See the introduction for description of masking modes.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).

Returns

The sum of all values inside area.

Since: 2.18

gwy_data_field_area_get_median ()

gdouble
gwy_data_field_area_get_median (GwyDataField *data_field,
                                GwyDataField *mask,
                                gint col,
                                gint row,
                                gint width,
                                gint height);

Warning

gwy_data_field_area_get_median is deprecated and should not be used in newly-written code.

Computes median value of a data field area.

This function is equivalent to calling gwy_data_field_area_get_median_mask() with masking mode GWY_MASK_INCLUDE.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).

Returns

The median value.

gwy_data_field_area_get_median_mask ()

gdouble
gwy_data_field_area_get_median_mask (GwyDataField *data_field,
                                     GwyDataField *mask,
                                     GwyMaskingType mode,
                                     gint col,
                                     gint row,
                                     gint width,
                                     gint height);

Computes median value of a data field area.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
mode	Masking mode to use. See the introduction for description of masking modes.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).

Returns

The median value.

Since: 2.18

gwy_data_field_area_get_surface_area ()

gdouble
gwy_data_field_area_get_surface_area (GwyDataField *data_field,
                                      GwyDataField *mask,
                                      gint col,
                                      gint row,
                                      gint width,
                                      gint height);

Warning

gwy_data_field_area_get_surface_area is deprecated and should not be used in newly-written code.

Computes surface area of a rectangular part of a data field.

This function is equivalent to calling gwy_data_field_area_get_surface_area_mask() with masking mode GWY_MASK_INCLUDE.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).

Returns

The surface area.

gwy_data_field_area_get_surface_area_mask ()

gdouble
gwy_data_field_area_get_surface_area_mask
                               (GwyDataField *data_field,
                                GwyDataField *mask,
                                GwyMaskingType mode,
                                gint col,
                                gint row,
                                gint width,
                                gint height);

Computes surface area of a rectangular part of a data field.

This quantity makes sense only if the lateral dimensions and values of data_field are the same physical quantities.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
mode	Masking mode to use. See the introduction for description of masking modes.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).

Returns

The surface area.

Since: 2.18

gwy_data_field_area_get_surface_slope_mask ()

gdouble
gwy_data_field_area_get_surface_slope_mask
                               (GwyDataField *data_field,
                                GwyDataField *mask,
                                GwyMaskingType mode,
                                gint col,
                                gint row,
                                gint width,
                                gint height);

Computes root mean square surface slope (Sdq) of a rectangular part of a data field.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
mode	Masking mode to use. See the introduction for description of masking modes.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).

Returns

The root mean square surface slope.

Since: 2.58

gwy_data_field_area_get_mean_square ()

gdouble
gwy_data_field_area_get_mean_square (GwyDataField *data_field,
                                     GwyDataField *mask,
                                     GwyMaskingType mode,
                                     gint col,
                                     gint row,
                                     gint width,
                                     gint height);

Computes mean square value of a rectangular part of a data field.

Unlike gwy_data_field_get_rms(), this function does not subtract the mean value beforehand. Therefore, it is useful to sum the squared values of data fields which can have the zero level set differently, for instance when the field contains a distribution.

Parameters

data_field	A two-dimensional data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
mode	Masking mode to use. See the introduction for description of masking modes.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).

Returns

The mean square value.

Since: 2.52

gwy_data_field_area_get_entropy_at_scales ()

gdouble
gwy_data_field_area_get_entropy_at_scales
                               (GwyDataField *data_field,
                                GwyDataLine *target_line,
                                GwyDataField *mask,
                                GwyMaskingType mode,
                                gint col,
                                gint row,
                                gint width,
                                gint height,
                                gint maxdiv);

Calculates estimates of value distribution entropy at various scales.

Parameters

data_field	A data field.
target_line	A data line to store the result to. It will be resampled to `maxdiv` +1 items.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
mode	Masking mode to use. See the introduction for description of masking modes.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
maxdiv	Maximum number of divisions of the value range. Pass zero to choose it automatically.

Returns

The best estimate, as gwy_data_field_area_get_entropy().

Since: 2.44

gwy_data_field_get_entropy_2d_at_scales ()

gdouble
gwy_data_field_get_entropy_2d_at_scales
                               (GwyDataField *xfield,
                                GwyDataField *yfield,
                                GwyDataLine *target_line,
                                gint maxdiv);

Calculates estimates of entropy of two-dimensional point cloud at various scales.

Parameters

xfield	A data field containing the `x` -coordinates.
yfield	A data field containing the `y` -coordinates.
target_line	A data line to store the result to. It will be resampled to `maxdiv` +1 items.
maxdiv	Maximum number of divisions of the value range. Pass zero to choose it automatically.

Returns

The best estimate, as gwy_data_field_get_entropy_2d().

Since: 2.44

gwy_data_field_area_get_variation ()

gdouble
gwy_data_field_area_get_variation (GwyDataField *data_field,
                                   GwyDataField *mask,
                                   GwyMaskingType mode,
                                   gint col,
                                   gint row,
                                   gint width,
                                   gint height);

Computes the total variation of a rectangular part of a data field.

The total variation is estimated as the integral of the absolute value of local gradient.

This quantity has the somewhat odd units of value unit times lateral unit. It can be envisioned as follows. If the surface has just two height levels (upper and lower planes) then the quantity is the length of the boundary between the upper and lower part, multiplied by the step height. If the surface is piece-wise constant, then the variation is the step height integrated along the boundaries between the constant parts. Therefore, for non-fractal surfaces it scales with the linear dimension of the image, not with its area, despite being an area integral.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
mode	Masking mode to use. See the introduction for description of masking modes.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).

Returns

The variation.

Since: 2.38

gwy_data_field_area_get_entropy ()

gdouble
gwy_data_field_area_get_entropy (GwyDataField *data_field,
                                 GwyDataField *mask,
                                 GwyMaskingType mode,
                                 gint col,
                                 gint row,
                                 gint width,
                                 gint height);

Estimates the entropy of field data distribution.

The estimate is calculated as S = ln(n Δ) − 1/n ∑ n_i ln(n_i ), where n is the number of pixels considered, Δ the bin size and n_i the count in the i -th bin. If S is plotted as a function of the bin size Δ, it is, generally, a growing function with a plateau for ‘reasonable’ bin sizes. The estimate is taken at the plateau. If no plateau is found, which means the distribution is effectively a sum of δ-functions, -G_MAXDOUBLE is returned.

It should be noted that this estimate may be biased.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
mode	Masking mode to use. See the introduction for description of masking modes.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).

Returns

The estimated entropy of the data values. The entropy of no data or a single single is returned as -G_MAXDOUBLE.

Since: 2.42

gwy_data_field_area_get_volume ()

gdouble
gwy_data_field_area_get_volume (GwyDataField *data_field,
                                GwyDataField *basis,
                                GwyDataField *mask,
                                gint col,
                                gint row,
                                gint width,
                                gint height);

Computes volume of a rectangular part of a data field.

Parameters

data_field	A data field.
basis	The basis or background for volume calculation if not `NULL`. The height of each vertex is then the difference between `data_field` value and `basis` value. Value `NULL` is the same as passing all zeroes for the basis.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).

Returns

The volume.

Since: 2.3

gwy_data_field_get_autorange ()

void
gwy_data_field_get_autorange (GwyDataField *data_field,
                              gdouble *from,
                              gdouble *to);

Computes data field value range with outliers cut-off.

The purpose of this function is to find a range is suitable for false color mapping. The precise method how it is calculated is unspecified and may be subject to changes.

However, it is guaranteed minimum <= from <= to <= maximum.

This quantity is cached.

Parameters

data_field	A data field.
from	Location to store range start.
to	Location to store range end.

gwy_data_field_area_get_autorange ()

void
gwy_data_field_area_get_autorange (GwyDataField *data_field,
                                   GwyDataField *mask,
                                   GwyMaskingType masking,
                                   gint col,
                                   gint row,
                                   gint width,
                                   gint height,
                                   gdouble *from,
                                   gdouble *to);

Computes data field area value range with outliers cut-off.

See gwy_data_field_get_autorange() for discussion.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
masking	Masking mode to use. See the introduction for description of masking modes.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
from	Location to store range start.
to	Location to store range end.

Since: 2.54

gwy_data_field_get_stats ()

void
gwy_data_field_get_stats (GwyDataField *data_field,
                          gdouble *avg,
                          gdouble *ra,
                          gdouble *rms,
                          gdouble *skew,
                          gdouble *kurtosis);

Computes basic statistical quantities of a data field.

Note the kurtosis returned by this function returns is the excess kurtosis which is zero for the Gaussian distribution (not 3).

Parameters

data_field	A data field.
avg	Where average height value of the surface should be stored, or `NULL`.
ra	Where average value of irregularities should be stored, or `NULL`.
rms	Where root mean square value of irregularities (Rq) should be stored, or `NULL`.
skew	Where skew (symmetry of height distribution) should be stored, or `NULL`.
kurtosis	Where kurtosis (peakedness of height ditribution) should be stored, or `NULL`.

gwy_data_field_area_get_stats ()

void
gwy_data_field_area_get_stats (GwyDataField *data_field,
                               GwyDataField *mask,
                               gint col,
                               gint row,
                               gint width,
                               gint height,
                               gdouble *avg,
                               gdouble *ra,
                               gdouble *rms,
                               gdouble *skew,
                               gdouble *kurtosis);

Warning

gwy_data_field_area_get_stats is deprecated and should not be used in newly-written code.

Computes basic statistical quantities of a rectangular part of a data field.

This function is equivalent to calling gwy_data_field_area_get_stats_mask() with masking mode GWY_MASK_INCLUDE.

Note the kurtosis returned by this function returns is the excess kurtosis which is zero for the Gaussian distribution (not 3).

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
avg	Where average height value of the surface should be stored, or `NULL`.
ra	Where average value of irregularities should be stored, or `NULL`.
rms	Where root mean square value of irregularities (Rq) should be stored, or `NULL`.
skew	Where skew (symmetry of height distribution) should be stored, or `NULL`.
kurtosis	Where kurtosis (peakedness of height ditribution) should be stored, or `NULL`.

gwy_data_field_area_get_stats_mask ()

void
gwy_data_field_area_get_stats_mask (GwyDataField *data_field,
                                    GwyDataField *mask,
                                    GwyMaskingType mode,
                                    gint col,
                                    gint row,
                                    gint width,
                                    gint height,
                                    gdouble *avg,
                                    gdouble *ra,
                                    gdouble *rms,
                                    gdouble *skew,
                                    gdouble *kurtosis);

Computes basic statistical quantities of a rectangular part of a data field.

Note the kurtosis returned by this function returns is the excess kurtosis which is zero for the Gaussian distribution (not 3).

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
mode	Masking mode to use. See the introduction for description of masking modes.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
avg	Where average height value of the surface should be stored, or `NULL`.
ra	Where average value of irregularities should be stored, or `NULL`.
rms	Where root mean square value of irregularities (Rq) should be stored, or `NULL`.
skew	Where skew (symmetry of height distribution) should be stored, or `NULL`.
kurtosis	Where kurtosis (peakedness of height ditribution) should be stored, or `NULL`.

Since: 2.18

gwy_data_field_area_count_in_range ()

void
gwy_data_field_area_count_in_range (GwyDataField *data_field,
                                    GwyDataField *mask,
                                    gint col,
                                    gint row,
                                    gint width,
                                    gint height,
                                    gdouble below,
                                    gdouble above,
                                    gint *nbelow,
                                    gint *nabove);

Counts data samples in given range.

No assertion is made about the values of above and below , in other words above may be larger than below . To count samples in an open interval instead of a closed interval, exchange below and above and then subtract the nabove and nbelow from width *height to get the complementary counts.

With this trick the common task of counting positive values can be realized:

gwy_data_field_area_count_in_range(data_field, NULL,
                                   col, row, width, height,
                                   0.0, 0.0, &count, NULL);
count = width*height - count;

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account, or `NULL`.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
below	Upper bound to compare data to. The number of samples less than or equal to `below` is stored in `nbelow` .
above	Lower bound to compare data to. The number of samples greater than or equal to `above` is stored in `nabove` .
nbelow	Location to store the number of samples less than or equal to `below` , or `NULL`.
nabove	Location to store the number of samples greater than or equal to `above` , or `NULL`.

gwy_data_field_area_dh ()

void
gwy_data_field_area_dh (GwyDataField *data_field,
                        GwyDataField *mask,
                        GwyDataLine *target_line,
                        gint col,
                        gint row,
                        gint width,
                        gint height,
                        gint nstats);

Calculates distribution of heights in a rectangular part of data field.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account, or `NULL`.
target_line	A data line to store the distribution to. It will be resampled to requested width.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
nstats	The number of samples to take on the distribution function. If nonpositive, a suitable resolution is determined automatically.

gwy_data_field_dh ()

void
gwy_data_field_dh (GwyDataField *data_field,
                   GwyDataLine *target_line,
                   gint nstats);

Calculates distribution of heights in a data field.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
nstats	The number of samples to take on the distribution function. If nonpositive, a suitable resolution is determined automatically.

gwy_data_field_area_cdh ()

void
gwy_data_field_area_cdh (GwyDataField *data_field,
                         GwyDataField *mask,
                         GwyDataLine *target_line,
                         gint col,
                         gint row,
                         gint width,
                         gint height,
                         gint nstats);

Calculates cumulative distribution of heights in a rectangular part of data field.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account, or `NULL`.
target_line	A data line to store the distribution to. It will be resampled to requested width.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
nstats	The number of samples to take on the distribution function. If nonpositive, a suitable resolution is determined automatically.

gwy_data_field_cdh ()

void
gwy_data_field_cdh (GwyDataField *data_field,
                    GwyDataLine *target_line,
                    gint nstats);

Calculates cumulative distribution of heights in a data field.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
nstats	The number of samples to take on the distribution function. If nonpositive, a suitable resolution is determined automatically.

gwy_data_field_area_da ()

void
gwy_data_field_area_da (GwyDataField *data_field,
                        GwyDataLine *target_line,
                        gint col,
                        gint row,
                        gint width,
                        gint height,
                        GwyOrientation orientation,
                        gint nstats);

Calculates distribution of slopes in a rectangular part of data field.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
orientation	Orientation to compute the slope distribution in.
nstats	The number of samples to take on the distribution function. If nonpositive, a suitable resolution is determined automatically.

gwy_data_field_area_da_mask ()

void
gwy_data_field_area_da_mask (GwyDataField *data_field,
                             GwyDataField *mask,
                             GwyDataLine *target_line,
                             gint col,
                             gint row,
                             gint width,
                             gint height,
                             GwyOrientation orientation,
                             gint nstats);

Calculates distribution of slopes in a rectangular part of data field, with masking.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account, or `NULL`.
target_line	A data line to store the distribution to. It will be resampled to requested width.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
orientation	Orientation to compute the slope distribution in.
nstats	The number of samples to take on the distribution function. If nonpositive, a suitable resolution is determined automatically.

Since: 2.49

gwy_data_field_da ()

void
gwy_data_field_da (GwyDataField *data_field,
                   GwyDataLine *target_line,
                   GwyOrientation orientation,
                   gint nstats);

Calculates distribution of slopes in a data field.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
orientation	Orientation to compute the slope distribution in.
nstats	The number of samples to take on the distribution function. If nonpositive, a suitable resolution is determined automatically.

gwy_data_field_area_cda ()

void
gwy_data_field_area_cda (GwyDataField *data_field,
                         GwyDataLine *target_line,
                         gint col,
                         gint row,
                         gint width,
                         gint height,
                         GwyOrientation orientation,
                         gint nstats);

Calculates cumulative distribution of slopes in a rectangular part of data field.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
orientation	Orientation to compute the slope distribution in.
nstats	The number of samples to take on the distribution function. If nonpositive, a suitable resolution is determined automatically.

gwy_data_field_area_cda_mask ()

void
gwy_data_field_area_cda_mask (GwyDataField *data_field,
                              GwyDataField *mask,
                              GwyDataLine *target_line,
                              gint col,
                              gint row,
                              gint width,
                              gint height,
                              GwyOrientation orientation,
                              gint nstats);

Calculates cumulative distribution of slopes in a rectangular part of data field, with masking.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account, or `NULL`.
target_line	A data line to store the distribution to. It will be resampled to requested width.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
orientation	Orientation to compute the slope distribution in.
nstats	The number of samples to take on the distribution function. If nonpositive, a suitable resolution is determined automatically.

Since: 2.49

gwy_data_field_cda ()

void
gwy_data_field_cda (GwyDataField *data_field,
                    GwyDataLine *target_line,
                    GwyOrientation orientation,
                    gint nstats);

Calculates cumulative distribution of slopes in a data field.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
orientation	Orientation to compute the slope distribution in.
nstats	The number of samples to take on the distribution function. If nonpositive, a suitable resolution is determined automatically.

gwy_data_field_area_acf ()

void
gwy_data_field_area_acf (GwyDataField *data_field,
                         GwyDataLine *target_line,
                         gint col,
                         gint row,
                         gint width,
                         gint height,
                         GwyOrientation orientation,
                         GwyInterpolationType interpolation,
                         gint nstats);

Calculates one-dimensional autocorrelation function of a rectangular part of a data field.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
orientation	Orientation of lines (ACF is simply averaged over the other orientation).
interpolation	Interpolation to use when `nstats` is given and requires resampling.
nstats	The number of samples to take on the distribution function. If nonpositive, `width` (`height` ) is used.

gwy_data_field_acf ()

void
gwy_data_field_acf (GwyDataField *data_field,
                    GwyDataLine *target_line,
                    GwyOrientation orientation,
                    GwyInterpolationType interpolation,
                    gint nstats);

Calculates one-dimensional autocorrelation function of a data field.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
orientation	Orientation of lines (ACF is simply averaged over the other orientation).
interpolation	Interpolation to use when `nstats` is given and requires resampling.
nstats	The number of samples to take on the distribution function. If nonpositive, data field width (height) is used.

gwy_data_field_area_row_acf ()

GwyDataLine *
gwy_data_field_area_row_acf (GwyDataField *field,
                             GwyDataField *mask,
                             GwyMaskingType masking,
                             guint col,
                             guint row,
                             guint width,
                             guint height,
                             guint level,
                             GwyDataLine *weights);

Calculates the row-wise autocorrelation function (ACF) of a field.

The calculated ACF has the natural number of points, i.e. width .

Masking is performed by omitting all terms that contain excluded pixels. Since different rows contain different numbers of pixels, the resulting ACF values are calculated as a weighted sums where weight of each row's contribution is proportional to the number of contributing terms. In other words, the weighting is fair: each contributing pixel has the same influence on the result.

Only level values 0 (no levelling) and 1 (subtract the mean value) used to be available. For SPM data, you usually wish to pass 1. Since 2.56 you can also pass 2 for mean line subtraction.

Parameters

field	A two-dimensional data field.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
mask	Mask specifying which values to take into account/exclude, or `NULL`.
masking	Masking mode to use (has any effect only with non-`NULL` `mask` ).
level	The first polynomial degree to keep in the rows, lower degrees than `level` are subtracted.
weights	Line to store the denominators to (or `NULL`). It will be resized to match the returned line. The denominators are integers equal to the number of terms that contributed to each value. They are suitable as fitting weights if the ACF is fitted.

Returns

A new one-dimensional data line with the ACF.

gwy_data_field_area_hhcf ()

void
gwy_data_field_area_hhcf (GwyDataField *data_field,
                          GwyDataLine *target_line,
                          gint col,
                          gint row,
                          gint width,
                          gint height,
                          GwyOrientation orientation,
                          GwyInterpolationType interpolation,
                          gint nstats);

Calculates one-dimensional autocorrelation function of a rectangular part of a data field.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
orientation	Orientation of lines (HHCF is simply averaged over the other orientation).
interpolation	Interpolation to use when `nstats` is given and requires resampling.
nstats	The number of samples to take on the distribution function. If nonpositive, `width` (`height` ) is used.

gwy_data_field_hhcf ()

void
gwy_data_field_hhcf (GwyDataField *data_field,
                     GwyDataLine *target_line,
                     GwyOrientation orientation,
                     GwyInterpolationType interpolation,
                     gint nstats);

Calculates one-dimensional autocorrelation function of a data field.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
orientation	Orientation of lines (HHCF is simply averaged over the other orientation).
interpolation	Interpolation to use when `nstats` is given and requires resampling.
nstats	The number of samples to take on the distribution function. If nonpositive, data field width (height) is used.

gwy_data_field_area_row_hhcf ()

GwyDataLine *
gwy_data_field_area_row_hhcf (GwyDataField *field,
                              GwyDataField *mask,
                              GwyMaskingType masking,
                              guint col,
                              guint row,
                              guint width,
                              guint height,
                              guint level,
                              GwyDataLine *weights);

Calculates the row-wise height-height correlation function (HHCF) of a rectangular part of a field.

The calculated HHCF has the natural number of points, i.e. width .

Masking is performed by omitting all terms that contain excluded pixels. Since different rows contain different numbers of pixels, the resulting HHCF values are calculated as a weighted sums where weight of each row's contribution is proportional to the number of contributing terms. In other words, the weighting is fair: each contributing pixel has the same influence on the result.

Only level values 0 (no levelling) and 1 (subtract the mean value) used to be available. There is no difference between them for HHCF. Since 2.56 you can also pass 2 for mean line subtraction.

Parameters

field	A two-dimensional data field.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
mask	Mask specifying which values to take into account/exclude, or `NULL`.
masking	Masking mode to use (has any effect only with non-`NULL` `mask` ).
level	The first polynomial degree to keep in the rows, lower degrees than `level` are subtracted.
weights	Line to store the denominators to (or `NULL`). It will be resized to match the returned line. The denominators are integers equal to the number of terms that contributed to each value. They are suitable as fitting weights if the HHCF is fitted.

Returns

A new one-dimensional data line with the HHCF.

gwy_data_field_area_psdf ()

void
gwy_data_field_area_psdf (GwyDataField *data_field,
                          GwyDataLine *target_line,
                          gint col,
                          gint row,
                          gint width,
                          gint height,
                          GwyOrientation orientation,
                          GwyInterpolationType interpolation,
                          GwyWindowingType windowing,
                          gint nstats);

Calculates one-dimensional power spectrum density function of a rectangular part of a data field.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
orientation	Orientation of lines (PSDF is simply averaged over the other orientation).
interpolation	Interpolation to use when `nstats` is given and requires resampling.
windowing	Windowing type to use.
nstats	The number of samples to take on the distribution function. If nonpositive, data field width (height) is used.

gwy_data_field_psdf ()

void
gwy_data_field_psdf (GwyDataField *data_field,
                     GwyDataLine *target_line,
                     GwyOrientation orientation,
                     GwyInterpolationType interpolation,
                     GwyWindowingType windowing,
                     gint nstats);

Calculates one-dimensional power spectrum density function of a data field.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
orientation	Orientation of lines (PSDF is simply averaged over the other orientation).
interpolation	Interpolation to use when `nstats` is given and requires resampling.
windowing	Windowing type to use.
nstats	The number of samples to take on the distribution function. If nonpositive, data field width (height) is used.

gwy_data_field_area_row_psdf ()

GwyDataLine *
gwy_data_field_area_row_psdf (GwyDataField *field,
                              GwyDataField *mask,
                              GwyMaskingType masking,
                              guint col,
                              guint row,
                              guint width,
                              guint height,
                              GwyWindowingType windowing,
                              guint level);

Calculates the row-wise power spectrum density function (PSDF) of a rectangular part of a field.

The calculated PSDF has the natural number of points that follows from DFT, i.e. width /2+1.

The reduction of the total energy by windowing is compensated by multiplying the PSDF to make its sum of squares equal to the input data sum of squares.

Masking is performed by omitting all terms that contain excluded pixels. Since different rows contain different numbers of pixels, the resulting PSDF is calculated as a weighted sum where each row's weight is proportional to the number of contributing pixels. In other words, the weighting is fair: each contributing pixel has the same influence on the result.

Only level values 0 (no levelling) and 1 (subtract the mean value) used to be available. For SPM data, you usually wish to pass 1. Since 2.56 you can also pass 2 for mean line subtraction.

Do not assume the PSDF values are all positive, when masking is in effect. The PSDF should still have the correct integral, but it will be contaminated with noise, both positive and negative.

Parameters

field	A two-dimensional data field.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
mask	Mask specifying which values to take into account/exclude, or `NULL`.
masking	Masking mode to use (has any effect only with non-`NULL` `mask` ).
windowing	Windowing type to use.
level	The first polynomial degree to keep in the rows; lower degrees than `level` are subtracted.

Returns

A new one-dimensional data line with the PSDF.

gwy_data_field_area_rpsdf ()

void
gwy_data_field_area_rpsdf (GwyDataField *data_field,
                           GwyDataLine *target_line,
                           gint col,
                           gint row,
                           gint width,
                           gint height,
                           GwyInterpolationType interpolation,
                           GwyWindowingType windowing,
                           gint nstats);

Calculates radial power spectrum density function of a rectangular part of a data field.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
interpolation	Interpolation to use when `nstats` is given and requires resampling.
windowing	Windowing type to use.
nstats	The number of samples to take on the distribution function. If nonpositive, data field width (height) is used.

Since: 2.7

gwy_data_field_rpsdf ()

void
gwy_data_field_rpsdf (GwyDataField *data_field,
                      GwyDataLine *target_line,
                      GwyInterpolationType interpolation,
                      GwyWindowingType windowing,
                      gint nstats);

Calculates radial power spectrum density function of a data field.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
interpolation	Interpolation to use when `nstats` is given and requires resampling.
windowing	Windowing type to use.
nstats	The number of samples to take on the distribution function. If nonpositive, data field width (height) is used.

Since: 2.7

gwy_data_field_area_row_asg ()

GwyDataLine *
gwy_data_field_area_row_asg (GwyDataField *field,
                             GwyDataField *mask,
                             GwyMaskingType masking,
                             guint col,
                             guint row,
                             guint width,
                             guint height,
                             guint level);

Calculates the row-wise area scale graph (ASG) of a rectangular part of a field.

The calculated ASG has the natural number of points, i.e. width -1.

The ASG represents the apparent area excess (ratio of surface and projected area minus one) observed at given length scale. The quantity calculated by this function serves a similar purpose as ASME B46.1 area scale graph but is defined differently, based on the HHCF. See gwy_data_field_area_row_hhcf() for details of its calculation.

Only level values 0 (no levelling) and 1 (subtract the mean value) used to be available. There is no difference between them for HHCF. Since 2.56 you can also pass 2 for mean line subtraction.

Parameters

field	A two-dimensional data field.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
mask	Mask specifying which values to take into account/exclude, or `NULL`.
masking	Masking mode to use (has any effect only with non-`NULL` `mask` ).
level	The first polynomial degree to keep in the rows, lower degrees than `level` are subtracted.

Returns

A new one-dimensional data line with the ASG.

gwy_data_field_area_2dacf ()

void
gwy_data_field_area_2dacf (GwyDataField *data_field,
                           GwyDataField *target_field,
                           gint col,
                           gint row,
                           gint width,
                           gint height,
                           gint xrange,
                           gint yrange);

Calculates two-dimensional autocorrelation function of a data field area.

The resulting data field has the correlation corresponding to (0,0) in the centre.

The maximum possible values of xrange and yrange are data_field width and height, respectively. However, as the values for longer distances are calculated from smaller number of data points they become increasingly bogus, therefore the default range is half of the size.

Parameters

data_field	A data field.
target_field	A data field to store the result to. It will be resampled to (2`xrange` -1)×(2`yrange` -1).
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
xrange	Horizontal correlation range. Non-positive value means the default range of half of `data_field` width will be used.
yrange	Vertical correlation range. Non-positive value means the default range of half of `data_field` height will be used.

Since: 2.7

gwy_data_field_area_2dacf_mask ()

void
gwy_data_field_area_2dacf_mask (GwyDataField *data_field,
                                GwyDataField *target_field,
                                GwyDataField *mask,
                                GwyMaskingType masking,
                                gint col,
                                gint row,
                                gint width,
                                gint height,
                                gint xrange,
                                gint yrange,
                                GwyDataField *weights);

Calculates two-dimensional autocorrelation function of a data field area.

The resulting data field has the correlation corresponding to (0,0) in the centre.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
masking	Masking mode to use (has any effect only with non-`NULL` `mask` ).
target_field	A data field to store the result to. It will be resampled to (2`xrange` -1)×(2`yrange` -1).
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
xrange	Horizontal correlation range. Non-positive value means the default range of half of `data_field` width will be used.
yrange	Vertical correlation range. Non-positive value means the default range of half of `data_field` height will be used.
weights	Field to store the denominators to (or `NULL`). It will be resized like `target_field` . The denominators are integers equal to the number of terms that contributed to each value. They are suitable as fitting weights if the ACF is fitted.

Since: 2.50

gwy_data_field_2dacf ()

void
gwy_data_field_2dacf (GwyDataField *data_field,
                      GwyDataField *target_field);

Calculates two-dimensional autocorrelation function of a data field.

See gwy_data_field_area_2dacf() for details. Parameters missing (not adjustable) in this function are set to their default values.

Parameters

data_field	A data field.
target_field	A data field to store the result to.

Since: 2.7

gwy_data_field_area_2dpsdf_mask ()

void
gwy_data_field_area_2dpsdf_mask (GwyDataField *field,
                                 GwyDataField *target_field,
                                 GwyDataField *mask,
                                 GwyMaskingType masking,
                                 gint col,
                                 gint row,
                                 gint width,
                                 gint height,
                                 GwyWindowingType windowing,
                                 gint level);

Calculates two-dimensional power spectrum density function of a data field area.

The resulting data field has the spectrum density corresponding zero frequency (0,0) in the centre.

Only level values 0 (no levelling) and 1 (subtract the mean value) used to be available. For SPM data, you usually wish to pass 1. Since 2.56 you can also pass 2 for mean plane subtraction.

The reduction of the total energy by windowing is compensated by multiplying the PSDF to make its sum of squares equal to the input data sum of squares.

Do not assume the PSDF values are all positive, when masking is in effect. The PSDF should still have the correct integral, but it will be contaminated with noise, both positive and negative.

Parameters

field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
masking	Masking mode to use (has any effect only with non-`NULL` `mask` ).
windowing	Windowing type to use.
level	The first polynomial degree to keep in the area; lower degrees than `level` are subtracted.
target_field	A data field to store the result to. It will be resampled to `width` ×`height` .
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).

Since: 2.51

gwy_data_field_2dpsdf ()

void
gwy_data_field_2dpsdf (GwyDataField *field,
                       GwyDataField *target_field,
                       GwyWindowingType windowing,
                       gint level);

Calculates two-dimensional power spectrum density function of a data field.

See gwy_data_field_area_2dpsdf_mask() for details and discussion.

Parameters

field	A data field.
windowing	Windowing type to use.
level	The first polynomial degree to keep in the area; lower degrees than `level` are subtracted. Note only values 0, 1, and 2 are available at present. For SPM data, you usually wish to pass 1.
target_field	A data field to store the result to. It will be resampled to the same size as `data_field` .

Since: 2.51

gwy_data_field_area_racf ()

void
gwy_data_field_area_racf (GwyDataField *data_field,
                          GwyDataLine *target_line,
                          gint col,
                          gint row,
                          gint width,
                          gint height,
                          gint nstats);

Calculates radially averaged autocorrelation function of a rectangular part of a data field.

Parameters

data_field	A data field.
target_line	A data line to store the autocorrelation function to. It will be resampled to requested width.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
nstats	The number of samples to take on the autocorrelation function. If nonpositive, a suitable resolution is chosen automatically.

Since: 2.22

gwy_data_field_racf ()

void
gwy_data_field_racf (GwyDataField *data_field,
                     GwyDataLine *target_line,
                     gint nstats);

Calculates radially averaged autocorrelation function of a data field.

Parameters

data_field	A data field.
target_line	A data line to store the autocorrelation function to. It will be resampled to requested width.
nstats	The number of samples to take on the autocorrelation function. If nonpositive, a suitable resolution is chosen automatically.

Since: 2.22

gwy_data_field_area_minkowski_volume ()

void
gwy_data_field_area_minkowski_volume (GwyDataField *data_field,
                                      GwyDataLine *target_line,
                                      gint col,
                                      gint row,
                                      gint width,
                                      gint height,
                                      gint nstats);

Calculates Minkowski volume functional of a rectangular part of a data field.

Volume functional is calculated as the number of values above each threshold value (,white pixels`) divided by the total number of samples in the area. Is it's equivalent to 1-CDH.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
nstats	The number of samples to take on the distribution function. If nonpositive, a suitable resolution is determined automatically.

gwy_data_field_minkowski_volume ()

void
gwy_data_field_minkowski_volume (GwyDataField *data_field,
                                 GwyDataLine *target_line,
                                 gint nstats);

Calculates Minkowski volume functional of a data field.

See gwy_data_field_area_minkowski_volume() for details.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
nstats	The number of samples to take on the distribution function. If nonpositive, a suitable resolution is determined automatically.

gwy_data_field_area_minkowski_boundary ()

void
gwy_data_field_area_minkowski_boundary
                               (GwyDataField *data_field,
                                GwyDataLine *target_line,
                                gint col,
                                gint row,
                                gint width,
                                gint height,
                                gint nstats);

Calculates Minkowski boundary functional of a rectangular part of a data field.

Boundary functional is calculated as the number of boundaries for each threshold value (the number of pixel sides where of neighouring pixels is ,white and the other ,black) divided by the total number of samples in the area.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
nstats	The number of samples to take on the distribution function. If nonpositive, a suitable resolution is determined automatically.

gwy_data_field_minkowski_boundary ()

void
gwy_data_field_minkowski_boundary (GwyDataField *data_field,
                                   GwyDataLine *target_line,
                                   gint nstats);

Calculates Minkowski boundary functional of a data field.

See gwy_data_field_area_minkowski_boundary() for details.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
nstats	The number of samples to take on the distribution function. If nonpositive, a suitable resolution is determined automatically.

gwy_data_field_area_minkowski_euler ()

void
gwy_data_field_area_minkowski_euler (GwyDataField *data_field,
                                     GwyDataLine *target_line,
                                     gint col,
                                     gint row,
                                     gint width,
                                     gint height,
                                     gint nstats);

Calculates Minkowski connectivity functional (Euler characteristics) of a rectangular part of a data field.

Connectivity functional is calculated as the number connected areas of pixels above threhsold (,white) minus the number of connected areas of pixels below threhsold (,black) for each threshold value, divided by the total number of samples in the area.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
nstats	The number of samples to take on the distribution function. If nonpositive, a suitable resolution is determined automatically.

gwy_data_field_minkowski_euler ()

void
gwy_data_field_minkowski_euler (GwyDataField *data_field,
                                GwyDataLine *target_line,
                                gint nstats);

Calculates Minkowski connectivity functional (Euler characteristics) of a data field.

See gwy_data_field_area_minkowski_euler() for details.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to requested width.
nstats	The number of samples to take on the distribution function. If nonpositive, a suitable resolution is determined automatically.

gwy_data_field_area_get_dispersion ()

gdouble
gwy_data_field_area_get_dispersion (GwyDataField *data_field,
                                    GwyDataField *mask,
                                    GwyMaskingType masking,
                                    gint col,
                                    gint row,
                                    gint width,
                                    gint height,
                                    gdouble *xcenter,
                                    gdouble *ycenter);

Calculates the dispersion of a data field area, taking it as a distribution.

The function takes data_field as a distribution, finds the centre of mass in the area and then calculates the mean squared distance from this centre, weighted by data_field values. Normally data_field should contain only non-negative data.

The dispersion is measured in real coordinates, so horizontal and vertical pixel sizes play a role and the units are squared lateral units of data_field . Note, however, that xcenter and ycenter is returned in pixel coordinates since it is usually more convenient.

Parameters

data_field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
masking	Masking mode to use (has any effect only with non-`NULL` `mask` ).
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
xcenter	Location where to store the horizontal position of centre of mass (in pixel coordinates), or `NULL`.
ycenter	Location where to store the vertical position of centre of mass (in pixel coordinates), or `NULL`.

Returns

Dispersion, i.e. estimated average squared distance from centre of mass.

Since: 2.52

gwy_data_field_get_dispersion ()

gdouble
gwy_data_field_get_dispersion (GwyDataField *data_field,
                               gdouble *xcenter,
                               gdouble *ycenter);

Calculates the dispersion of a data field, taking it as a distribution.

See gwy_data_field_area_get_dispersion() for discussion.

Parameters

data_field	A data field.
xcenter	Location where to store the horizontal position of centre of mass (in pixel coordinates), or `NULL`.
ycenter	Location where to store the vertical position of centre of mass (in pixel coordinates), or `NULL`.

Returns

Dispersion, i.e. estimated average squared distance from centre of mass.

Since: 2.52

gwy_data_field_slope_distribution ()

void
gwy_data_field_slope_distribution (GwyDataField *data_field,
                                   GwyDataLine *derdist,
                                   gint kernel_size);

Computes angular slope distribution.

Parameters

data_field	A data field.
derdist	A data line to fill with angular slope distribution. Its resolution determines resolution of the distribution.
kernel_size	If positive, local plane fitting will be used for slope computation; if nonpositive, plain central derivations will be used.

gwy_data_field_facet_distribution ()

void
gwy_data_field_facet_distribution (GwyDataField *field,
                                   GwyDataField *dist,
                                   gint half_res,
                                   gint size,
                                   GwyDataField *theta_field,
                                   GwyDataField *phi_field);

Calculates two-dimensional facet angle distribution for a data field.

The distribution field dist is constructed as an area-preserving projection of local facet orientation distribution on the upper half-sphere. The radial coordinate in the projection is √2*sin(ϑ/2) where ϑ is the polar coordinate on the sphere. The returned field only covers as large part of the sphere as necessary. i.e. ϑ usually does not go to up to π/2. Use the real dimensions of computed dist to obtain the range.

The two optional outputs theta_field and phi_field will be resized to the same dimensions as field and filled with the theta and phi angles in the corresponding pixels as computed by this function. Pass NULL if you do not have further use for the facet angles.

Note that facet distribution is generally meaningful only if the values are the same physical quantity as the lateral dimensions because it relies on slope angles.

Parameters

field	A data field.
dist	Target data field for the distribution.
half_res	Requested distribution resolution, as half-size. Data field `dist` will be resized to size 2*`half_res` +1.
size	Neighbourhood size, as in `gwy_data_field_fit_local_planes()`; or one for simple derivatives. Odd values are preferred.
theta_field	Output field for theta angles in corresponding pixels, or `NULL`.
phi_field	Output field for phi angles in corresponding pixels, or `NULL`.

Since: 2.67

gwy_data_field_get_normal_coeffs ()

void
gwy_data_field_get_normal_coeffs (GwyDataField *data_field,
                                  gdouble *nx,
                                  gdouble *ny,
                                  gdouble *nz,
                                  gboolean normalize1);

Computes average normal vector of a data field.

Parameters

data_field	A data field.
nx	Where x-component of average normal vector should be stored, or `NULL`.
ny	Where y-component of average normal vector should be stored, or `NULL`.
nz	Where z-component of average normal vector should be stored, or `NULL`.
normalize1	`TRUE` to normalize the normal vector to 1, `FALSE` to normalize the vector so that `z` -component is 1.

gwy_data_field_area_get_normal_coeffs ()

void
gwy_data_field_area_get_normal_coeffs (GwyDataField *data_field,
                                       gint col,
                                       gint row,
                                       gint width,
                                       gint height,
                                       gdouble *nx,
                                       gdouble *ny,
                                       gdouble *nz,
                                       gboolean normalize1);

Computes average normal vector of an area of a data field.

The function can use outside pixels for two-side derivatives. See gwy_data_field_area_get_normal_coeffs_mask() for a function which always honours the boundaries.

Parameters

data_field	A data field.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
nx	Where x-component of average normal vector should be stored, or `NULL`.
ny	Where y-component of average normal vector should be stored, or `NULL`.
nz	Where z-component of average normal vector should be stored, or `NULL`.
normalize1	`TRUE` to normalize the normal vector to 1, `FALSE` to normalize the vector so that `z` -component is 1.

gwy_data_field_area_get_normal_coeffs_mask ()

gint
gwy_data_field_area_get_normal_coeffs_mask
                               (GwyDataField *field,
                                GwyDataField *mask,
                                GwyMaskingType masking,
                                gint col,
                                gint row,
                                gint width,
                                gint height,
                                gdouble *nx,
                                gdouble *ny,
                                gdouble *nz);

Computes average normal vector of an area of a data field, with masking.

Values outside the area or excluded by masking never enter the computation. This is different from functions like gwy_data_field_area_get_normal_coeffs() which can use outside pixels for two-side derivatives. Two-side derivatives are used for interior pixels, one-sided when two-side are not possible. Normals are not calculated for pixels excluded by masking, even when all their neighbours are included and two-sided derivatives do not actually use the central value.

The sign convention is also natural for the Gwyddion coordinate system.

Parameters

field	A data field.
mask	Mask specifying which values to take into account/exclude, or `NULL`.
masking	Masking mode to use. See the introduction for description of masking modes.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
nx	Where x-component of average normal vector should be stored, or `NULL`.
ny	Where y-component of average normal vector should be stored, or `NULL`.
nz	Where z-component of average normal vector should be stored, or `NULL`.

Returns

The number of vectors averaged. Zero means failure (typically occuring when masking did not leave any contiguous patch of pixels for computation of derivatives).

Since: 2.64

gwy_data_field_area_get_inclination ()

void
gwy_data_field_area_get_inclination (GwyDataField *data_field,
                                     gint col,
                                     gint row,
                                     gint width,
                                     gint height,
                                     gdouble *theta,
                                     gdouble *phi);

Calculates the inclination of the image (polar and azimuth angle).

Parameters

data_field	A data field.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
theta	Where theta angle (in radians) should be stored, or `NULL`.
phi	Where phi angle (in radians) should be stored, or `NULL`.

gwy_data_field_get_inclination ()

void
gwy_data_field_get_inclination (GwyDataField *data_field,
                                gdouble *theta,
                                gdouble *phi);

Calculates the inclination of the image (polar and azimuth angle).

Parameters

data_field	A data field.
theta	Where theta angle (in radians) should be stored, or `NULL`.
phi	Where phi angle (in radians) should be stored, or `NULL`.

gwy_data_field_area_get_line_stats ()

void
gwy_data_field_area_get_line_stats (GwyDataField *data_field,
                                    GwyDataField *mask,
                                    GwyDataLine *target_line,
                                    gint col,
                                    gint row,
                                    gint width,
                                    gint height,
                                    GwyLineStatQuantity quantity,
                                    GwyOrientation orientation);

Calculates a line quantity for each row or column in a data field area.

Use gwy_data_field_get_line_stats_mask() for full masking type options.

Parameters

data_field	A data field.
mask	Mask of values to take values into account, or `NULL` for full `data_field` .
target_line	A data line to store the distribution to. It will be resampled to the number of rows (columns).
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
quantity	The line quantity to calulate for each row (column).
orientation	Line orientation. For `GWY_ORIENTATION_HORIZONTAL` each `target_line` point corresponds to a row of the area, for `GWY_ORIENTATION_VERTICAL` each `target_line` point corresponds to a column of the area.

Since: 2.2

gwy_data_field_get_line_stats_mask ()

void
gwy_data_field_get_line_stats_mask (GwyDataField *data_field,
                                    GwyDataField *mask,
                                    GwyMaskingType masking,
                                    GwyDataLine *target_line,
                                    GwyDataLine *weights,
                                    gint col,
                                    gint row,
                                    gint width,
                                    gint height,
                                    GwyLineStatQuantity quantity,
                                    GwyOrientation orientation);

Calculates a line quantity for each row or column in a data field area.

Parameters

data_field	A data field.
mask	Mask of values to take values into account, or `NULL` for full `data_field` .
masking	Masking mode to use. See the introduction for description of masking modes.
target_line	A data line to store the distribution to. It will be resampled to the number of rows (columns).
weights	A data line to store number of data points contributing to each value in `target_line` , or `NULL`. It is useful when masking is used to possibly exclude values calculated from too few data points.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
quantity	The line quantity to calulate for each row (column).
orientation	Line orientation. For `GWY_ORIENTATION_HORIZONTAL` each `target_line` point corresponds to a row of the area, for `GWY_ORIENTATION_VERTICAL` each `target_line` point corresponds to a column of the area.

Since: 2.46

gwy_data_field_get_line_stats ()

void
gwy_data_field_get_line_stats (GwyDataField *data_field,
                               GwyDataLine *target_line,
                               GwyLineStatQuantity quantity,
                               GwyOrientation orientation);

Calculates a line quantity for each row or column of a data field.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to `data_field` height (width).
quantity	The line quantity to calulate for each row (column).
orientation	Line orientation. See `gwy_data_field_area_get_line_stats()`.

Since: 2.2

gwy_data_field_count_maxima ()

guint
gwy_data_field_count_maxima (GwyDataField *data_field);

Counts the number of regional maxima in a data field.

See gwy_data_field_mark_extrema() for the definition of a regional maximum.

Parameters

data_field

A data field.

Returns

The number of regional maxima.

Since: 2.38

gwy_data_field_count_minima ()

guint
gwy_data_field_count_minima (GwyDataField *data_field);

Counts the number of regional minima in a data field.

See gwy_data_field_mark_extrema() for the definition of a regional minimum.

Parameters

data_field

A data field

Returns

The number of regional minima.

Since: 2.38

gwy_data_field_psdf_to_angular_spectrum ()

GwyDataLine *
gwy_data_field_psdf_to_angular_spectrum
                               (GwyDataField *psdf,
                                gint nstats);

Transforms 2D power spectral density to an angular spectrum.

Parameters

psdf	A data field containing 2D spectral density, humanized (i.e. with zero frequency in the centre).
nstats	The number of samples to take on the distribution function. If nonpositive, a suitable number is chosen automatically.

Returns

A new one-dimensional data line with the angular spectrum.

Since: 2.56

gwy_data_field_angular_average ()

void
gwy_data_field_angular_average (GwyDataField *data_field,
                                GwyDataLine *target_line,
                                GwyDataField *mask,
                                GwyMaskingType masking,
                                gdouble x,
                                gdouble y,
                                gdouble r,
                                gint nstats);

Performs angular averaging of a part of a data field.

The result of such averaging is an radial profile, starting from the disc centre.

The function does not guarantee that target_line will have exactly nstats samples upon return. A smaller number of samples than requested may be calculated for instance if either central or outer part of the disc is excluded by masking.

Parameters

data_field	A data field.
target_line	A data line to store the distribution to. It will be resampled to `nstats` size.
mask	Mask of pixels to include from/exclude in the averaging, or `NULL` for full `data_field` .
masking	Masking mode to use. See the introduction for description of masking modes.
x	X-coordinate of the averaging disc origin, in real coordinates including offsets.
y	Y-coordinate of the averaging disc origin, in real coordinates including offsets.
r	Radius, in real coordinates. It determines the real length of the resulting line.
nstats	The number of samples the resulting line should have. A non-positive value means the sampling will be determined automatically.

Since: 2.42