Statistics: Gwyddion Library Reference Manual

## Statistics Statistics — Two-dimensional statistical functions |

## Functions

gdouble | gwy_field_max ()
gdouble | gwy_field_min ()
void | gwy_field_min_max ()
gdouble | gwy_field_mean ()
gdouble | gwy_field_rms ()
gdouble | gwy_field_mean_square ()
gdouble | gwy_field_sum ()
gdouble | gwy_field_median ()
gdouble | gwy_field_surface_area ()
gdouble | gwy_field_rms_slope ()
gdouble | gwy_field_variation ()
gdouble | gwy_field_entropy ()
gdouble | gwy_field_entropy_2d ()
gdouble | gwy_field_otsu_threshold ()
gdouble | gwy_field_area_max ()
gdouble | gwy_field_area_min ()
void | gwy_field_area_min_max ()
gdouble | gwy_field_area_mean ()
gdouble | gwy_field_area_rms ()
gdouble | gwy_field_area_grainwise_rms ()
gdouble | gwy_field_area_sum ()
gdouble | gwy_field_area_median ()
gdouble | gwy_field_area_surface_area ()
gdouble | gwy_field_area_rms_slope ()
gdouble | gwy_field_area_mean_square ()
gdouble | gwy_field_area_entropy_at_scales ()
gdouble | gwy_field_entropy_2d_at_scales ()
gdouble | gwy_field_area_variation ()
gdouble | gwy_field_area_entropy ()
gdouble | gwy_field_area_volume ()
gdouble | gwy_field_area_material_volume ()
void | gwy_field_autorange ()
void | gwy_field_area_autorange ()
void | gwy_field_stats ()
void | gwy_field_area_stats ()
void | gwy_field_area_count_in_range ()
void | gwy_field_area_height_dist ()
void | gwy_field_height_dist ()
void | gwy_field_area_angle_dist ()
void | gwy_field_angle_dist ()
void | gwy_field_area_acf ()
void | gwy_field_acf ()
void | gwy_field_area_hhcf ()
void | gwy_field_hhcf ()
void | gwy_field_area_psdf ()
void | gwy_field_psdf ()
void | gwy_field_area_rpsdf ()
void | gwy_field_rpsdf ()
void | gwy_field_area_ipsdf ()
void | gwy_field_ipsdf ()
GwyLine * | gwy_field_area_row_acf ()
GwyLine * | gwy_field_area_row_hhcf ()
GwyLine * | gwy_field_area_row_psdf ()
GwyLine * | gwy_field_area_row_asg ()
void | gwy_field_area_acf_2d ()
void | gwy_field_acf_2d ()
void | gwy_field_area_psdf_2d ()
void | gwy_field_psdf_2d ()
void | gwy_field_area_racf ()
void | gwy_field_racf ()
GwyLine * | gwy_field_minkowski ()
GwyLine * | gwy_field_area_minkowski ()
gdouble | gwy_field_area_dispersion ()
gdouble | gwy_field_dispersion ()
void | gwy_field_slope_distribution ()
void | gwy_field_facet_distribution ()
void | gwy_field_normal_coeffs ()
gint | gwy_field_area_normal_coeffs ()
void | gwy_field_inclination ()
void | gwy_field_area_inclination ()
void | gwy_field_line_stats ()
GwyLine * | gwy_field_area_line_stats ()
guint | gwy_field_count_maxima ()
guint | gwy_field_count_minima ()
GwyLine * | gwy_field_psdf_to_angular_spectrum ()
GwyLine * | gwy_field_angular_average ()

## Types and Values

enum | GwyMinkowskiFunctional
enum | GwyFieldVolumeMethod

## Includes

    #include <libgwyddion/gwyddion.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_field_max()

    gdouble
    gwy_field_max (GwyField *field);

Finds the maximum value of a data field.

This quantity is cached.

#### Parameters

field | A data field. |

#### Returns

The maximum value.

### gwy_field_min()

    gdouble
    gwy_field_min (GwyField *field);

Finds the minimum value of a data field.

This quantity is cached.

#### Parameters

field | A data field. |

#### Returns

The minimum value.

### gwy_field_min_max()

    void
    gwy_field_min_max (GwyField *field,
                       gdouble *min,
                       gdouble *max);

Finds minimum and maximum values of a data field.

#### Parameters

field | A data field. |
min | Location to store minimum to. | [out]
max | Location to store maximum to. | [out]

### gwy_field_mean()

    gdouble
    gwy_field_mean (GwyField *field);

Computes average value of a data field.

This quantity is cached.

#### Parameters

field | A data field |

#### Returns

The average value.

### gwy_field_rms()

    gdouble
    gwy_field_rms (GwyField *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_field_mean_square()` for a similar function which does not subtract the mean value.

This quantity is cached.

#### Parameters

field | A data field. |

#### Returns

The root mean square value.

### gwy_field_mean_square()

    gdouble
    gwy_field_mean_square (GwyField *field);

Computes mean square value of a data field.

See `gwy_field_area_get_mean_square()` for remarks.

#### Parameters

field | A two-dimensional data field. |

#### Returns

The mean square value.

### gwy_field_sum()

    gdouble
    gwy_field_sum (GwyField *field);

Sums all values in a data field.

This quantity is cached.

#### Parameters

field | A data field. |

#### Returns

The sum of all values.

### gwy_field_median()

    gdouble
    gwy_field_median (GwyField *field);

Computes median value of a data field.

This quantity is cached.

#### Parameters

field | A data field. |

#### Returns

The median value.

### gwy_field_surface_area()

    gdouble
    gwy_field_surface_area (GwyField *field);

Computes surface area of a data field.

This quantity is cached.

#### Parameters

field | A data field. |

#### Returns

The surface area.

### gwy_field_rms_slope()

    gdouble
    gwy_field_rms_slope (GwyField *field);

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

#### Parameters

field | A data field. |

#### Returns

The root mean square surface slope.

### gwy_field_variation()

    gdouble
    gwy_field_variation (GwyField *field);

Computes the total variation of a data field.

See `gwy_field_area_get_variation()` for the definition.

This quantity is cached.

#### Parameters

field | A data field. |

#### Returns

The variation.

### gwy_field_entropy()

    gdouble
    gwy_field_entropy (GwyField *field);

Computes the entropy of a data field.

See `gwy_field_area_get_entropy()` for the definition.

This quantity is cached.

#### Parameters

field | A data field. |

#### Returns

The value distribution entropy.

### gwy_field_entropy_2d()

    gdouble
    gwy_field_entropy_2d (GwyField *xfield,
                          GwyField *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.

### gwy_field_otsu_threshold()

    gdouble
    gwy_field_otsu_threshold (GwyField *field);

Finds Otsu's height threshold for a data field.

The Otsu's threshold is optimal in the sense that it minimises the inter-class variances of two classes of pixels: above and below theshold.

#### Parameters

field | A data field. |

#### Returns

The threshold.

### gwy_field_area_max()

    gdouble
    gwy_field_area_max (GwyField *field,
                        GwyNield *mask,
                        GwyMaskingType masking,
                        gint col,
                        gint row,
                        gint width,
                        gint height);

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

#### Parameters

field | A data field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
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). |

#### Returns

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

### gwy_field_area_min()

    gdouble
    gwy_field_area_min (GwyField *field,
                        GwyNield *mask,
                        GwyMaskingType masking,
                        gint col,
                        gint row,
                        gint width,
                        gint height);

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

#### Parameters

field | A data field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
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). |

#### Returns

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

### gwy_field_area_min_max()

    void
    gwy_field_area_min_max (GwyField *field,
                            GwyNield *mask,
                            GwyMaskingType masking,
                            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.

Both `min` and `max` must be non-`NULL`. Use `gwy_field_area_get_min()` or `gwy_field_area_get_max()` if you only need one of the values.

#### Parameters

field | A data field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
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). |
min | Location to store minimum to. | [out]
max | Location to store maximum to. | [out]

### gwy_field_area_mean()

    gdouble
    gwy_field_area_mean (GwyField *field,
                         GwyNield *mask,
                         GwyMaskingType masking,
                         gint col,
                         gint row,
                         gint width,
                         gint height);

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

#### Parameters

field | A data field |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
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). |

#### Returns

The average value.

### gwy_field_area_rms()

    gdouble
    gwy_field_area_rms (GwyField *field,
                        GwyNield *mask,
                        GwyMaskingType masking,
                        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

field | A data field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
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). |

#### Returns

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

### gwy_field_area_grainwise_rms()

    gdouble
    gwy_field_area_grainwise_rms (GwyField *field,
                                  GwyNield *nield,
                                  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 separately. Grains are regions in `mask` , not necessarily cotinguous, which have the same number. Avoid huge numbers in `mask` ; the function allocates memory proportional to `gwy_nield_max()`.

If all `mask` is just a single grain, the function is equivalent to normal masked rms in `GWY_MASK_INCLUDE` mode. If you want grains to be defined as contiguous regions, use `gwy_nield_number_contiguous()` beforehand.

It is possible, albeit probably ill-advised, to pass a `NULL` `nield` . The function then returns zero as it does for empty `nield` .

#### Parameters

field | A data field. |
nield | Number field specifying grain numbers. | [nullable]
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.

### gwy_field_area_sum()

    gdouble
    gwy_field_area_sum (GwyField *field,
                        GwyNield *mask,
                        GwyMaskingType masking,
                        gint col,
                        gint row,
                        gint width,
                        gint height);

Sums values of a rectangular part of a data field.

#### Parameters

field | A data field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
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). |

#### Returns

The sum of all values inside area.

### gwy_field_area_median()

    gdouble
    gwy_field_area_median (GwyField *field,
                           GwyNield *mask,
                           GwyMaskingType masking,
                           gint col,
                           gint row,
                           gint width,
                           gint height);

Computes median value of a data field area.

#### Parameters

field | A data field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
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). |

#### Returns

The median value.

### gwy_field_area_surface_area()

    gdouble
    gwy_field_area_surface_area (GwyField *field,
                                 GwyNield *mask,
                                 GwyMaskingType masking,
                                 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 `field` are the same physical quantities.

#### 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). |

#### Returns

The surface area.

### gwy_field_area_rms_slope()

    gdouble
    gwy_field_area_rms_slope (GwyField *field,
                              GwyNield *mask,
                              GwyMaskingType masking,
                              gint col,
                              gint row,
                              gint width,
                              gint height);

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

#### 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). |

#### Returns

The root mean square surface slope.

### gwy_field_area_mean_square()

    gdouble
    gwy_field_area_mean_square (GwyField *field,
                                GwyNield *mask,
                                GwyMaskingType masking,
                                gint col,
                                gint row,
                                gint width,
                                gint height);

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

Unlike `gwy_field_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

field | A two-dimensional data field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
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). |

#### Returns

The mean square value.

### gwy_field_area_entropy_at_scales()

    gdouble
    gwy_field_area_entropy_at_scales (GwyField *field,
                                      GwyNield *mask,
                                      GwyMaskingType masking,
                                      GwyLine *target_line,
                                      gint col,
                                      gint row,
                                      gint width,
                                      gint height,
                                      gint maxdiv);

Calculates estimates of value distribution entropy at various scales.

#### Parameters

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`. | [nullable]
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). |
maxdiv | Maximum number of divisions of the value range. Pass zero to choose it automatically. |

#### Returns

The best estimate, as `gwy_field_area_get_entropy()`.

### gwy_field_entropy_2d_at_scales()

    gdouble
    gwy_field_entropy_2d_at_scales (GwyField *xfield,
                                    GwyField *yfield,
                                    GwyLine *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_field_entropy_2d()`.

### gwy_field_area_variation()

    gdouble
    gwy_field_area_variation (GwyField *field,
                              GwyNield *mask,
                              GwyMaskingType masking,
                              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

field | A data field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
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). |

#### Returns

The variation.

### gwy_field_area_entropy()

    gdouble
    gwy_field_area_entropy (GwyField *field,
                            GwyNield *mask,
                            GwyMaskingType masking,
                            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

field | A data field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
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). |

#### Returns

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

### gwy_field_area_volume()

    gdouble
    gwy_field_area_volume (GwyField *field,
                           GwyNield *mask,
                           GwyMaskingType masking,
                           GwyFieldVolumeMethod method,
                           gint col,
                           gint row,
                           gint width,
                           gint height);

Computes volume of a rectangular part of a data field.

#### Parameters

field | A data field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
masking | Masking mode to use. See the introduction for description of masking modes. |
method | Quadrature method. Pass `GWY_FIELD_VOLUME_DEFAULT` (zero). |
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.

### gwy_field_area_material_volume()

    gdouble
    gwy_field_area_material_volume (GwyField *field,
                                    GwyNield *mask,
                                    GwyMaskingType masking,
                                    gint col,
                                    gint row,
                                    gint width,
                                    gint height,
                                    gboolean material,
                                    gdouble base);

Calculates the volume of material or voids between a field surface and given base level.

This functions differs from `gwy_field_volume()` substantially. If material volume above a certain base is calculated, then only the parts of the surface that are above the base contribute to the result. The parts below the base do not contribute at all, whereas in `gwy_field_volume()` they contribute a negative volume.

The volume quadrature method is fixed and corresponds to `GWY_FIELD_VOLUME_TRIANGULAR`. Unlike methods integrating exactly certain polynomials, it explicitly specifies the surface shape. Therefore, surface intersections with the base level are well-defined.

#### Parameters

field | A two-dimensional data field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
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). |
material | `TRUE` to calculate the material volume above `base` , `FALSE` to calculate the volume of voids below `base` . |
base | Base level above or below which the volume is to be calculated. |

#### Returns

The volume of material above `base` and below the field surface (or the opposite when `material` is `FALSE`).

### gwy_field_autorange()

    void
    gwy_field_autorange (GwyField *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.

The range is cached.

#### Parameters

field | A data field. |
from | Location to store range start. | [out]
to | Location to store range end. | [out]

### gwy_field_area_autorange()

    void
    gwy_field_area_autorange (GwyField *field,
                              GwyNield *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_field_autorange()` for discussion.

#### Parameters

field | A data field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
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. | [out]
to | Location to store range end. | [out]

### gwy_field_stats()

    void
    gwy_field_stats (GwyField *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

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

### gwy_field_area_stats()

    void
    gwy_field_area_stats (GwyField *field,
                          GwyNield *mask,
                          GwyMaskingType masking,
                          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

field | A data field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
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). |
avg | Where average height value of the surface should be stored, or `NULL`. | [out][optional]
ra | Where average value of irregularities should be stored, or `NULL`. | [out][optional]
rms | Where root mean square value of irregularities (Rq) should be stored, or `NULL`. | [out][optional]
skew | Where skew (symmetry of height distribution) should be stored, or `NULL`. | [out][optional]
kurtosis | Where excess kurtosis (peakedness of height ditribution) should be stored, or `NULL`. | [out][optional]

### gwy_field_area_count_in_range()

    void
    gwy_field_area_count_in_range (GwyField *field,
                                   GwyNield *mask,
                                   GwyMaskingType masking,
                                   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:

    1
    2
    3
    4
    gwy_field_area_count_in_range(field, NULL,
                                  col, row, width, height,
                                  0.0, 0.0, &count, NULL);
    count = width*height - count;

#### Parameters

field | A data field. |
mask | Mask specifying which values to take into account, or `NULL`. | [nullable]
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). |
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`. | [out][optional]
nabove | Location to store the number of samples greater than or equal to `above` , or `NULL`. | [out][optional]

### gwy_field_area_height_dist()

    void
    gwy_field_area_height_dist (GwyField *field,
                                GwyNield *mask,
                                GwyMaskingType masking,
                                GwyLine *target_line,
                                gint col,
                                gint row,
                                gint width,
                                gint height,
                                gint nstats);

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

#### Parameters

field | A data field. |
mask | Mask specifying which values to take into account, or `NULL`. | [nullable]
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 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_field_height_dist()

    void
    gwy_field_height_dist (GwyField *field,
                           GwyLine *target_line,
                           gint nstats);

Calculates distribution of heights in a data field.

#### Parameters

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_field_area_angle_dist()

    void
    gwy_field_area_angle_dist (GwyField *field,
                               GwyNield *mask,
                               GwyMaskingType masking,
                               GwyLine *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

field | A data field. |
mask | Mask specifying which values to take into account, or `NULL`. | [nullable]
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 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_field_angle_dist()

    void
    gwy_field_angle_dist (GwyField *field,
                          GwyLine *target_line,
                          GwyOrientation orientation,
                          gint nstats);

Calculates distribution of slopes in a data field.

#### Parameters

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_field_area_acf()

    void
    gwy_field_area_acf (GwyField *field,
                        GwyLine *target_line,
                        gint col,
                        gint row,
                        gint width,
                        gint height,
                        GwyOrientation orientation);

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

#### Parameters

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). |

### gwy_field_acf()

    void
    gwy_field_acf (GwyField *field,
                   GwyLine *target_line,
                   GwyOrientation orientation);

Calculates one-dimensional autocorrelation function of a data field.

#### Parameters

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). |

### gwy_field_area_hhcf()

    void
    gwy_field_area_hhcf (GwyField *field,
                         GwyLine *target_line,
                         gint col,
                         gint row,
                         gint width,
                         gint height,
                         GwyOrientation orientation);

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

#### Parameters

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). |

### gwy_field_hhcf()

    void
    gwy_field_hhcf (GwyField *field,
                    GwyLine *target_line,
                    GwyOrientation orientation);

Calculates one-dimensional autocorrelation function of a data field.

#### Parameters

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). |

### gwy_field_area_psdf()

    void
    gwy_field_area_psdf (GwyField *field,
                         GwyLine *target_line,
                         gint col,
                         gint row,
                         gint width,
                         gint height,
                         GwyOrientation orientation,
                         GwyWindowingType windowing);

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

#### Parameters

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). |
windowing | Windowing type to use. |

### gwy_field_psdf()

    void
    gwy_field_psdf (GwyField *field,
                    GwyLine *target_line,
                    GwyOrientation orientation,
                    GwyWindowingType windowing);

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

#### Parameters

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). |
windowing | Windowing type to use. |

### gwy_field_area_rpsdf()

    void
    gwy_field_area_rpsdf (GwyField *field,
                          GwyLine *target_line,
                          gint col,
                          gint row,
                          gint width,
                          gint height,
                          GwyWindowingType windowing,
                          gint nstats);

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

The function calculates density in the radial wavevector. See `gwy_field_area_ipsdf()` for angular averaging of the spectral density.

#### Parameters

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). |
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_field_rpsdf()

    void
    gwy_field_rpsdf (GwyField *field,
                     GwyLine *target_line,
                     GwyWindowingType windowing,
                     gint nstats);

Calculates radial power spectral density function of a data field.

The function calculates density in the radial wavevector. See `gwy_field_ipsdf()` for angular averaging of the spectral density.

#### Parameters

field | A data field. |
target_line | A data line to store the distribution to. It will be resampled to requested width. |
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_field_area_ipsdf()

    void
    gwy_field_area_ipsdf (GwyField *field,
                          GwyLine *target_line,
                          gint col,
                          gint row,
                          gint width,
                          gint height,
                          GwyWindowingType windowing,
                          gint nstats);

Calculates angularly averaged power spectral density function of a rectangular part of a data field.

The function may seem like more intutitive analog of 1D power spectral density if the data are isotropic. However, it is merely an angular average. It is not, in fact, actually any kind of spectral density. It also has the same units as the 2D PSDF. See `gwy_field_area_rpsdf()` for density in the radial wavevector.

#### Parameters

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). |
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_field_ipsdf()

    void
    gwy_field_ipsdf (GwyField *field,
                     GwyLine *target_line,
                     GwyWindowingType windowing,
                     gint nstats);

Calculates angularly averaged power spectral density function of a data field.

The function may seem like more intutitive analog of 1D power spectral density if the data are isotropic. However, it is merely an angular average. It is not, in fact, actually any kind of spectral density. It also has the same units as the 2D PSDF. See `gwy_field_rpsdf()` for density in the radial wavevector.

#### Parameters

field | A data field. |
target_line | A data line to store the distribution to. It will be resampled to requested width. |
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_field_area_row_acf()

    GwyLine *
    gwy_field_area_row_acf (GwyField *field,
                            GwyNield *mask,
                            GwyMaskingType masking,
                            guint col,
                            guint row,
                            guint width,
                            guint height,
                            guint level,
                            GwyLine *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) and 2 (subtract the mean plane) are currently available. For SPM data, you usually wish to pass 1.

#### 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`. | [nullable]
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. | [nullable]

#### Returns

A new one-dimensional data line with the ACF.

[transfer full]

### gwy_field_area_row_hhcf()

    GwyLine *
    gwy_field_area_row_hhcf (GwyField *field,
                             GwyNield *mask,
                             GwyMaskingType masking,
                             guint col,
                             guint row,
                             guint width,
                             guint height,
                             guint level,
                             GwyLine *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) and 2 (subtract the mean plane) are currently available. For SPM data, you usually wish to pass 1.

#### 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`. | [nullable]
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. | [nullable]

#### Returns

A new one-dimensional data line with the HHCF.

[transfer full]

### gwy_field_area_row_psdf()

    GwyLine *
    gwy_field_area_row_psdf (GwyField *field,
                             GwyNield *mask,
                             GwyMaskingType masking,
                             guint col,
                             guint row,
                             guint width,
                             guint height,
                             GwyWindowingType windowing,
                             guint level);

Calculates the row-wise power spectral 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) and 2 (subtract the mean plane) are currently available. For SPM data, you usually wish to pass 1.

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`. | [nullable]
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.

[transfer full]

### gwy_field_area_row_asg()

    GwyLine *
    gwy_field_area_row_asg (GwyField *field,
                            GwyNield *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_field_area_row_hhcf()` for details of its calculation.

Only `level` values 0 (no levelling) and 1 (subtract the mean value) and 2 (subtract the mean plane) are currently available. For SPM data, you usually wish to pass 1.

#### 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`. | [nullable]
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.

[transfer full]

### gwy_field_area_acf_2d()

    void
    gwy_field_area_acf_2d (GwyField *field,
                           GwyNield *mask,
                           GwyMaskingType masking,
                           GwyField *target,
                           gint col,
                           gint row,
                           gint width,
                           gint height,
                           gint xrange,
                           gint yrange,
                           GwyField *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.

The maximum possible values of `xrange` and `yrange` are `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

field | A data field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
masking | Masking mode to use (has any effect only with non-`NULL` `mask` ). |
target | 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 `field` width will be used. |
yrange | Vertical correlation range. Non-positive value means the default range of half of `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. | [nullable]

### gwy_field_acf_2d()

    void
    gwy_field_acf_2d (GwyField *field,
                      GwyField *target_field);

Calculates two-dimensional autocorrelation function of a data field.

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

#### Parameters

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

### gwy_field_area_psdf_2d()

    void
    gwy_field_area_psdf_2d (GwyField *field,
                            GwyNield *mask,
                            GwyMaskingType masking,
                            GwyField *target,
                            gint col,
                            gint row,
                            gint width,
                            gint height,
                            GwyWindowingType windowing,
                            gint level);

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

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

Only `level` values 0 (no levelling) and 1 (subtract the mean value) and 2 (subtract the mean plane) are currently available. For SPM data, you usually wish to pass 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.

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`. | [nullable]
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 | 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). |

### gwy_field_psdf_2d()

    void
    gwy_field_psdf_2d (GwyField *field,
                       GwyField *target_field,
                       GwyWindowingType windowing,
                       gint level);

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

See `gwy_field_area_psdf_2d_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 `field` . |

### gwy_field_area_racf()

    void
    gwy_field_area_racf (GwyField *field,
                         GwyLine *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

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. |

### gwy_field_racf()

    void
    gwy_field_racf (GwyField *field,
                    GwyLine *target_line,
                    gint nstats);

Calculates radially averaged autocorrelation function of a data field.

#### Parameters

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. |

### gwy_field_minkowski()

    GwyLine *
    gwy_field_minkowski (GwyField *field,
                         GwyMinkowskiFunctional type,
                         gint nstats);

Calculates a Minkowski functional of a data field.

#### Parameters

field | A two-dimensional data field. |
type | Type of functional to calculate. |
nstats | Resolution, i.e. the number of returned line points. Pass zero to choose a suitable resolution automatically. |

#### Returns

A new one-dimensional data line with the requested functional.

[transfer full]

### gwy_field_area_minkowski()

    GwyLine *
    gwy_field_area_minkowski (GwyField *field,
                              GwyNield *mask,
                              GwyMaskingType masking,
                              gint col,
                              gint row,
                              gint width,
                              gint height,
                              GwyMinkowskiFunctional type,
                              gint nstats,
                              gdouble min,
                              gdouble max);

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

Pass `max` <= `min` to calculate the functional in the full data range (with masking still considered).

If the area contains no pixels to consider due to masking, a valid but useless GwyLine is returned. It is best to check the number of pixels with `gwy_nield_area_count()`.

#### Parameters

field | A two-dimensional data field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
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). |
type | Type of functional to calculate. |
nstats | Resolution, i.e. the number of returned line points. Pass zero to choose a suitable resolution automatically. |
min | Minimum value of the range to calculate the distribution in. |
max | Maximum value of the range to calculate the distribution in. |

#### Returns

A new one-dimensional data line with the requested functional.

[transfer full]

### gwy_field_area_dispersion()

    gdouble
    gwy_field_area_dispersion (GwyField *field,
                               GwyNield *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 `field` as a distribution, finds the centre of mass in the area and then calculates the mean squared distance from this centre, weighted by `field` values. Normally `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 `field` . Note, however, that `xcenter` and `ycenter` is returned in pixel coordinates since it is usually more convenient.

#### Parameters

field | A data field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
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`. | [out][optional]
ycenter | Location where to store the vertical position of centre of mass (in pixel coordinates), or `NULL`. | [out][optional]

#### Returns

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

### gwy_field_dispersion()

    gdouble
    gwy_field_dispersion (GwyField *field,
                          gdouble *xcenter,
                          gdouble *ycenter);

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

See `gwy_field_area_get_dispersion()` for discussion.

#### Parameters

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

#### Returns

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

### gwy_field_slope_distribution()

    void
    gwy_field_slope_distribution (GwyField *field,
                                  GwyLine *derdist,
                                  gint kernel_size);

Computes angular slope distribution.

#### Parameters

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_field_facet_distribution()

    void
    gwy_field_facet_distribution (GwyField *field,
                                  GwyField *dist,
                                  gint half_res,
                                  gint size,
                                  GwyField *theta_field,
                                  GwyField *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_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`. |

### gwy_field_normal_coeffs()

    void
    gwy_field_normal_coeffs (GwyField *field,
                             gdouble *nx,
                             gdouble *ny,
                             gdouble *nz);

Computes average normal vector of a data field.

#### Parameters

field | A data field. |
nx | Where x-component of average normal vector should be stored, or `NULL`. | [out][optional]
ny | Where y-component of average normal vector should be stored, or `NULL`. | [out][optional]
nz | Where z-component of average normal vector should be stored, or `NULL`. | [out][optional]

### gwy_field_area_normal_coeffs()

    gint
    gwy_field_area_normal_coeffs (GwyField *field,
                                  GwyNield *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_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`. | [nullable]
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`. | [out][optional]
ny | Where y-component of average normal vector should be stored, or `NULL`. | [out][optional]
nz | Where z-component of average normal vector should be stored, or `NULL`. | [out][optional]

#### 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).

### gwy_field_inclination()

    void
    gwy_field_inclination (GwyField *field,
                           gdouble *theta,
                           gdouble *phi);

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

#### Parameters

field | A data field. |
theta | Where theta angle (in radians) should be stored, or `NULL`. | [out][optional]
phi | Where phi angle (in radians) should be stored, or `NULL`. | [out][optional]

### gwy_field_area_inclination()

    void
    gwy_field_area_inclination (GwyField *field,
                                GwyNield *mask,
                                GwyMaskingType masking,
                                gint col,
                                gint row,
                                gint width,
                                gint height,
                                gdouble *theta,
                                gdouble *phi);

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

#### Parameters

field | A data field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
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). |
theta | Where theta angle (in radians) should be stored, or `NULL`. | [out][optional]
phi | Where phi angle (in radians) should be stored, or `NULL`. | [out][optional]

### gwy_field_line_stats()

    void
    gwy_field_line_stats (GwyField *field,
                          GwyLine *target_line,
                          GwyLineStatQuantity quantity,
                          GwyOrientation orientation);

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

#### Parameters

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

### gwy_field_area_line_stats()

    GwyLine *
    gwy_field_area_line_stats (GwyField *field,
                               GwyNield *mask,
                               GwyMaskingType masking,
                               gint col,
                               gint row,
                               gint width,
                               gint height,
                               GwyLineStatQuantity quantity,
                               GwyOrientation orientation,
                               GwyLine *weights);

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

#### Parameters

field | A data field. |
mask | Mask of values to take values into account, or `NULL` for full `field` . | [nullable]
masking | Masking mode to use. See the introduction for description of masking modes. |
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. | [nullable]
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. |

#### Returns

A newly created data line with the row on column values.

[transfer full]

### gwy_field_count_maxima()

    guint
    gwy_field_count_maxima (GwyField *field);

Counts the number of regional maxima in a data field.

See `gwy_field_mark_extrema()` for the definition of a regional maximum.

#### Parameters

field | A data field. |

#### Returns

The number of regional maxima.

### gwy_field_count_minima()

    guint
    gwy_field_count_minima (GwyField *field);

Counts the number of regional minima in a data field.

See `gwy_field_mark_extrema()` for the definition of a regional minimum.

#### Parameters

field | A data field |

#### Returns

The number of regional minima.

### gwy_field_psdf_to_angular_spectrum()

    GwyLine *
    gwy_field_psdf_to_angular_spectrum (GwyField *psdf,
                                        gint nstats);

Transforms 2D power spectral density to an angular spectral.

#### 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 spectral.

[transfer full]

### gwy_field_angular_average()

    GwyLine *
    gwy_field_angular_average (GwyField *field,
                               GwyNield *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

field | A data field. |
mask | Mask of pixels to include from/exclude in the averaging, or `NULL` for full `field` . | [nullable]
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. |

#### Returns

A new data line to with the distribution.

## Types and Values

### enum GwyMinkowskiFunctional

Types of Minkowski functionals and related quantities.

Each quantity is a function of threshold; pixels above this threshold are considered ‘white’, pixels below ‘black’. The normalisation is always to the total number of things that could contribute, making the maximum possible value one. This can differ from some traditional definitions that normalise edges to pixels, for example, which is not applicable to irregular regions.

#### Members

GWY_MINKOWSKI_VOLUME | Fraction of ‘white’ pixels from the total number of pixels. |
GWY_MINKOWSKI_BOUNDARY | Fraction of ‘black–white’ pixel edges from the total number of edges. |
GWY_MINKOWSKI_BLACK | The number of ‘black’ connected areas (grains) divided by the total number of pixels. |
GWY_MINKOWSKI_WHITE | The number of ‘white’ connected areas (grains) divided by the total number of pixels. |
GWY_MINKOWSKI_CONNECTIVITY | Difference between the numbers of ‘white’ and ‘black’ connected areas (grains) divided by the total number of pixels. |

### enum GwyFieldVolumeMethod

Field volume calculation methods.

#### Members

GWY_FIELD_VOLUME_DEFAULT | The default method, whatever it is (currently `GWY_FIELD_VOLUME_BIQUADRATIC`). The only method you need. |
GWY_FIELD_VOLUME_GWYDDION2 | Reproduce how Gwyddion 2.x calculated the volume by using the same quadrature weights, although they are of unclear origin. |
GWY_FIELD_VOLUME_TRIANGULAR | Calculate the volume using the pixel centre point surface triangulation. |
GWY_FIELD_VOLUME_BILINEAR | Exactly integrate bilinear interpolation in each quarter. |
GWY_FIELD_VOLUME_BIQUADRATIC | Exactly integrate biquadratic interpolation. |