Levelling: Gwyddion Library Reference Manual

## Levelling Levelling — Leveling and background removal |

## Functions

void | gwy_line_fit_line ()
void | gwy_line_line_level ()
void | gwy_line_rotate ()
gdouble * | gwy_line_part_fit_poly ()
gdouble * | gwy_line_fit_poly ()
void | gwy_line_part_subtract_poly ()
void | gwy_line_subtract_poly ()
gint | gwy_field_area_fit_plane ()
gint | gwy_field_fit_plane ()
gboolean | gwy_field_fit_facet_plane ()
gboolean | gwy_field_facet_level ()
void | gwy_field_plane_level ()
void | gwy_field_plane_rotate ()
gdouble * | gwy_field_fit_legendre ()
gdouble * | gwy_field_area_fit_legendre ()
void | gwy_field_subtract_legendre ()
void | gwy_field_area_subtract_legendre ()
gdouble * | gwy_field_fit_poly_max ()
gdouble * | gwy_field_area_fit_poly_max ()
void | gwy_field_subtract_poly_max ()
void | gwy_field_area_subtract_poly_max ()
gdouble * | gwy_field_fit_poly ()
gdouble * | gwy_field_area_fit_poly ()
void | gwy_field_subtract_poly ()
void | gwy_field_area_subtract_poly ()
GwyField ** | gwy_field_area_fit_local_planes ()
GwyField * | gwy_field_area_local_plane_quantity ()
GwyField ** | gwy_field_fit_local_planes ()
GwyField * | gwy_field_local_plane_quantity ()

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

## Functions

### gwy_line_fit_line()

    void
    gwy_line_fit_line (GwyLine *line,
                       gdouble *a,
                       gdouble *b);

Finds line leveling coefficients.

The coefficients can be used for line leveling using relation

data[i] := data[i] - (av + bv*i)

#### Parameters

line | A data line. |
a | Height coefficient. | [out]
b | Slope coeficient. | [out]

### gwy_line_line_level()

    void
    gwy_line_line_level (GwyLine *line,
                         gdouble a,
                         gdouble b);

Levels a data line by subtraction.

See `gwy_line_fit_line()` for deails.

#### Parameters

line | A data line. |
a | Height coefficient. |
b | Slope coefficient. |

### gwy_line_rotate()

    void
    gwy_line_rotate (GwyLine *line,
                     gdouble angle,
                     GwyInterpolationType interpolation);

Levels a data line by rotation.

This is operation similar to `gwy_line_line_level()`, but it does not change the angles between line segments (on the other hand it introduces other deformations due to discretisation).

#### Parameters

line | A data line. |
angle | Angle of rotation (in radians), counterclockwise. |
interpolation | Interpolation method to use (can be only of two-point type). |

### gwy_line_part_fit_poly()

    gdouble *
    gwy_line_part_fit_poly (GwyLine *line,
                            gint pos,
                            gint len,
                            gint n,
                            gdouble *coeffs);

Fits a polynomial through a part of a data line.

Please see `gwy_line_fit_poly()` for more details.

#### Parameters

line | A data line. |
n | Polynom degree. |
coeffs | An array of size `n` +1 to store the coefficients to, or `NULL` (a fresh array is allocated then). | [nullable]
pos | Index where to start. |
len | Length of extracted segment. |

#### Returns

The coefficients of the polynomial (`coeffs` when it was not `NULL`, otherwise a newly allocated array).

### gwy_line_fit_poly()

    gdouble *
    gwy_line_fit_poly (GwyLine *line,
                       gint n,
                       gdouble *coeffs);

Fits a polynomial through a data line.

Note `n` is polynomial degree, so the size of `coeffs` is `n` +1. X-values are indices in the data line.

For polynomials of degree 0 and 1 it's better to use `gwy_line_get_avg()` and `gwy_line_fit_line()` because they are faster.

#### Parameters

line | A data line. |
n | Polynom degree. |
coeffs | An array of size `n` +1 to store the coefficients to, or `NULL` (a fresh array is allocated then). | [nullable]

#### Returns

The coefficients of the polynomial (`coeffs` when it was not `NULL`, otherwise a newly allocated array).

### gwy_line_part_subtract_poly()

    void
    gwy_line_part_subtract_poly (GwyLine *line,
                                 gint pos,
                                 gint len,
                                 gint n,
                                 const gdouble *coeffs);

Subtracts a polynomial from a part of a data line.

#### Parameters

line | A data line. |
n | Polynom degree. |
coeffs | An array of size `n` +1 with polynomial coefficients to. |
pos | Index where to start. |
len | Length of extracted segment. |

### gwy_line_subtract_poly()

    void
    gwy_line_subtract_poly (GwyLine *line,
                            gint n,
                            const gdouble *coeffs);

Subtracts a polynomial from a data line.

#### Parameters

line | A data line. |
n | Polynom degree. |
coeffs | An array of size `n` +1 with polynomial coefficients to. | [array]

### gwy_field_area_fit_plane()

    gint
    gwy_field_area_fit_plane (GwyField *field,
                              GwyNield *mask,
                              GwyMaskingType masking,
                              gint col,
                              gint row,
                              gint width,
                              gint height,
                              gdouble *a,
                              gdouble *bx,
                              gdouble *by);

Fits a plane through a rectangular part of a data field with masking.

The coefficients can be used for plane leveling using relation data[i,j] → data[i,j] - (a + by*i + bx*j), where the integer indices start from (0, 0) at the top left corner of the are (not the image).

If the returned value is smaller than 3 then the pixel configuration is degenerate in some sense, for instance there are only two pixels contributing to the plane fitting. The function calculates the minimum norm solution. This is reasonable for instance for 1×N areas where it gives a zero coefficient for the undetermined direction and line coefficients for the good direction. However, one may also simply not use the result in degenerate cases.

#### Parameters

field | A data field |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
masking | Masking mode to use. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |
a | Where constant coefficient should be stored (or `NULL`). | [out][optional]
bx | Where x plane coefficient should be stored (or `NULL`). | [out][optional]
by | Where y plane coefficient should be stored (or `NULL`). | [out][optional]

#### Returns

The rank of the normal matrix.

### gwy_field_fit_plane()

    gint
    gwy_field_fit_plane (GwyField *field,
                         gdouble *a,
                         gdouble *bx,
                         gdouble *by);

Fits a plane through a data field.

The coefficients can be used for plane leveling using relation data[i,j] → data[i,j] - (a + by*i + bx*j), where the integer indices start from (0, 0) at the image top left corner.

#### Parameters

field | A data field. |
a | Where constant coefficient should be stored (or `NULL`). | [out][optional]
bx | Where x plane coefficient should be stored (or `NULL`). | [out][optional]
by | Where y plane coefficient should be stored (or `NULL`). | [out][optional]

#### Returns

The rank of the normal matrix.

### gwy_field_fit_facet_plane()

    gboolean
    gwy_field_fit_facet_plane (GwyField *field,
                               GwyNield *mask,
                               GwyMaskingType masking,
                               gdouble *a,
                               gdouble *bx,
                               gdouble *by);

Calculates the inclination of a plane close to the dominant plane in a data field.

The dominant plane is determined by taking into account larger local slopes with exponentially smaller weight.

This is the basis of so-called facet levelling algorithm. Usually, the plane found by this method is subtracted using `gwy_field_plane_level()` and the entire process is repeated until it converges. A convergence criterion may be sufficiently small values of the x and y plane coefficients. Note that since `gwy_field_plane_level()` uses pixel-based lateral coordinates, the coefficients must be divided by gwy_field_get_dx(field) and gwy_field_get_dy(field) to obtain physical plane coefficients.

#### Parameters

field | A data field. |
mask | Mask specifying which values to take into account/exclude, or `NULL`. | [nullable]
masking | Masking mode to use. |
a | Where constant coefficient should be stored (or `NULL`). | [out][optional]
bx | Where x plane coefficient should be stored. | [out]
by | Where y plane coefficient should be stored. | [out]

#### Returns

`TRUE` if any plane was actually fitted; `FALSE` if there was an insufficient number of unmasked pixels.

### gwy_field_facet_level()

    gboolean
    gwy_field_facet_level (GwyField *field,
                           GwyNield *mask,
                           GwyMaskingType masking,
                           gint maxiter,
                           GwySetFractionFunc set_fraction);

Performs facet-levelling of a data field.

The levelling consists of repeated computation of the dominant plane using `gwy_field_fit_facet_plane()` and subtraction of the dominant plane. Usually only several iterations are required for convergence.

#### Parameters

field | A data field. It the procedure is cancelled it will be unchanged. |
mask | Mask field specifying which values to take into account/exclude, or `NULL`. | [nullable]
masking | Masking mode to use. |
maxiter | Maximum number of levelling iterations. Pass a non-positive number for (a high) default. |
set_fraction | Function that sets progress fraction to output (or `NULL`). | [scope call][nullable]

#### Returns

`TRUE` if levelling has finished (either by converging or reaching the maximum number of iterations); `FALSE` if it was cancelled or there was an insufficient number of unmasked pixels.

### gwy_field_plane_level()

    void
    gwy_field_plane_level (GwyField *field,
                           gdouble a,
                           gdouble bx,
                           gdouble by);

Subtracts plane from a data field.

See `gwy_field_fit_plane()` for details.

#### Parameters

field | A data field. |
a | Constant coefficient. |
bx | X plane coefficient. |
by | Y plane coefficient. |

### gwy_field_plane_rotate()

    void
    gwy_field_plane_rotate (GwyField *field,
                            gdouble xangle,
                            gdouble yangle,
                            GwyInterpolationType interpolation);

Performs rotation of plane along x and y axis.

#### Parameters

field | A data field. |
xangle | Rotation angle in x direction (rotation along y axis, in radians). |
yangle | Rotation angle in y direction (rotation along x axis, in radians). |
interpolation | Interpolation type (can be only of two-point type). |

### gwy_field_fit_legendre()

    gdouble *
    gwy_field_fit_legendre (GwyField *field,
                            gint col_degree,
                            gint row_degree,
                            gdouble *coeffs);

Fits two-dimensional Legendre polynomial to a data field.

See `gwy_field_area_fit_legendre()` for details.

#### Parameters

field | A data field. |
col_degree | Degree of polynomial to fit column-wise (x-coordinate). |
row_degree | Degree of polynomial to fit row-wise (y-coordinate). |
coeffs | An array of size (`row_degree` +1)*(`col_degree` +1) to store the coefficients to, or `NULL` (a fresh array is allocated then). | [nullable]

#### Returns

Either `coeffs` if it was not `NULL`, or a newly allocated array with coefficients.

### gwy_field_area_fit_legendre()

    gdouble *
    gwy_field_area_fit_legendre (GwyField *field,
                                 gint col,
                                 gint row,
                                 gint width,
                                 gint height,
                                 gint col_degree,
                                 gint row_degree,
                                 gdouble *coeffs);

Fits two-dimensional Legendre polynomial to a rectangular part of a data field.

The `col_degree` and `row_degree` parameters limit the maximum powers of x and y exactly as if simple powers were fitted, therefore if you do not intend to interpret contents of `coeffs` youself, the only difference is that this method is much more numerically stable.

The coefficients are organized exactly like in `gwy_field_area_fit_poly()`, but they are not coefficients of x^n y^m, instead they are coefficients of P_n(x) P_m(x), where P are Legendre polynomials. The polynomials are evaluated in coordinates where first row (column) corresponds to -1.0, and the last row (column) to 1.0.

Note the polynomials are normal Legendre polynomials that are not exactly orthogonal on a discrete point set (if their degrees are equal mod 2).

#### Parameters

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). |
col_degree | Degree of polynomial to fit column-wise (x-coordinate). |
row_degree | Degree of polynomial to fit row-wise (y-coordinate). |
coeffs | An array of size (`row_degree` +1)*(`col_degree` +1) to store the coefficients to, or `NULL` (a fresh array is allocated then). | [nullable]

#### Returns

Either `coeffs` if it was not `NULL`, or a newly allocated array with coefficients.

### gwy_field_subtract_legendre()

    void
    gwy_field_subtract_legendre (GwyField *field,
                                 gint col_degree,
                                 gint row_degree,
                                 const gdouble *coeffs);

Subtracts a two-dimensional Legendre polynomial fit from a data field.

#### Parameters

field | A data field. |
col_degree | Degree of polynomial to subtract column-wise (x-coordinate). |
row_degree | Degree of polynomial to subtract row-wise (y-coordinate). |
coeffs | An array of size (`row_degree` +1)*(`col_degree` +1) with coefficients, see `gwy_field_area_fit_legendre()` for details. |

### gwy_field_area_subtract_legendre()

    void
    gwy_field_area_subtract_legendre (GwyField *field,
                                      gint col,
                                      gint row,
                                      gint width,
                                      gint height,
                                      gint col_degree,
                                      gint row_degree,
                                      const gdouble *coeffs);

Subtracts a two-dimensional Legendre polynomial fit from a rectangular part of a data field.

Due to the transform of coordinates to [-1,1] x [-1,1], this method can be used on an area of dimensions different than the area the coefficients were calculated for.

#### Parameters

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). |
col_degree | Degree of polynomial to subtract column-wise (x-coordinate). |
row_degree | Degree of polynomial to subtract row-wise (y-coordinate). |
coeffs | An array of size (`row_degree` +1)*(`col_degree` +1) with coefficients, see `gwy_field_area_fit_legendre()` for details. |

### gwy_field_fit_poly_max()

    gdouble *
    gwy_field_fit_poly_max (GwyField *field,
                            gint max_degree,
                            gdouble *coeffs);

Fits two-dimensional polynomial with limited total degree to a data field.

See `gwy_field_area_fit_poly_max()` for details.

#### Parameters

field | A data field. |
max_degree | Maximum total polynomial degree, that is the maximum of m+n in x^n y^m terms. |
coeffs | An array of size (`max_degree` +1)*(`max_degree` +2)/2 to store the coefficients to, or `NULL` (a fresh array is allocated then). | [nullable]

#### Returns

Either `coeffs` if it was not `NULL`, or a newly allocated array with coefficients.

### gwy_field_area_fit_poly_max()

    gdouble *
    gwy_field_area_fit_poly_max (GwyField *field,
                                 gint col,
                                 gint row,
                                 gint width,
                                 gint height,
                                 gint max_degree,
                                 gdouble *coeffs);

Fits two-dimensional polynomial with limited total degree to a rectangular part of a data field.

See `gwy_field_area_fit_legendre()` for description. This function differs by limiting the total maximum degree, while `gwy_field_area_fit_legendre()` limits the maximum degrees in horizontal and vertical directions independently.

#### Parameters

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). |
max_degree | Maximum total polynomial degree, that is the maximum of m+n in x^n y^m terms. |
coeffs | An array of size (`max_degree` +1)*(`max_degree` +2)/2 to store the coefficients to, or `NULL` (a fresh array is allocated then). | [nullable]

#### Returns

Either `coeffs` if it was not `NULL`, or a newly allocated array with coefficients.

### gwy_field_subtract_poly_max()

    void
    gwy_field_subtract_poly_max (GwyField *field,
                                 gint max_degree,
                                 const gdouble *coeffs);

Subtracts a two-dimensional polynomial with limited total degree from a data field.

#### Parameters

field | A data field. |
max_degree | Maximum total polynomial degree, that is the maximum of m+n in x^n y^m terms. |
coeffs | An array of size (`row_degree` +1)*(`col_degree` +2)/2 with coefficients, see `gwy_field_area_fit_poly_max()` for details. |

### gwy_field_area_subtract_poly_max()

    void
    gwy_field_area_subtract_poly_max (GwyField *field,
                                      gint col,
                                      gint row,
                                      gint width,
                                      gint height,
                                      gint max_degree,
                                      const gdouble *coeffs);

Subtracts a two-dimensional polynomial with limited total degree from a rectangular part of a data field.

Due to the transform of coordinates to [-1,1] x [-1,1], this method can be used on an area of dimensions different than the area the coefficients were calculated for.

#### Parameters

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). |
max_degree | Maximum total polynomial degree, that is the maximum of m+n in x^n y^m terms. |
coeffs | An array of size (`row_degree` +1)*(`col_degree` +2)/2 with coefficients, see `gwy_field_area_fit_poly_max()` for details. |

### gwy_field_fit_poly()

    gdouble *
    gwy_field_fit_poly (GwyField *field,
                        GwyNield *mask,
                        GwyMaskingType masking,
                        gint nterms,
                        const gint *term_powers,
                        gdouble *coeffs);

Fit a given set of polynomial terms to a data field.

#### 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. |
nterms | The number of polynomial terms to take into account (half the number of items in `term_powers` ). |
term_powers | Array of size 2*`nterms` describing the terms to fit. Each terms is described by a couple of powers (powerx, powery). |
coeffs | Array of size `nterms` to store the coefficients to, or `NULL` to allocate a new array. | [nullable]

#### Returns

Either `coeffs` if it was not `NULL`, or a newly allocated array with coefficients.

### gwy_field_area_fit_poly()

    gdouble *
    gwy_field_area_fit_poly (GwyField *field,
                             GwyNield *mask,
                             GwyMaskingType masking,
                             gint col,
                             gint row,
                             gint width,
                             gint height,
                             gint nterms,
                             const gint *term_powers,
                             gdouble *coeffs);

Fit a given set of polynomial terms to a rectangular part of a data field.

The polynomial coefficients correspond to normalized coordinates that are always from the interval [-1,1] where -1 corresponds to the left/topmost pixel and 1 corresponds to the bottom/rightmost pixel of the area (not the entire field).

#### 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. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |
nterms | The number of polynomial terms to take into account (half the number of items in `term_powers` ). |
term_powers | Array of size 2*`nterms` describing the terms to fit. Each terms is described by a couple of powers (powerx, powery). |
coeffs | Array of size `nterms` to store the coefficients to, or `NULL` to allocate a new array. | [nullable]

#### Returns

Either `coeffs` if it was not `NULL`, or a newly allocated array with coefficients.

### gwy_field_subtract_poly()

    void
    gwy_field_subtract_poly (GwyField *field,
                             gint nterms,
                             const gint *term_powers,
                             const gdouble *coeffs);

Subtract a given set of polynomial terms from a data field.

#### Parameters

field | A data field. |
nterms | The number of polynomial terms to take into account (half the number of items in `term_powers` ). |
term_powers | Array of size 2*`nterms` describing the fitter terms. Each terms is described by a couple of powers (powerx, powery). |
coeffs | Array of size `nterms` to store with the coefficients. |

### gwy_field_area_subtract_poly()

    void
    gwy_field_area_subtract_poly (GwyField *field,
                                  gint col,
                                  gint row,
                                  gint width,
                                  gint height,
                                  gint nterms,
                                  const gint *term_powers,
                                  const gdouble *coeffs);

Subtract a given set of polynomial terms from a rectangular part of a data field.

#### Parameters

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). |
nterms | The number of polynomial terms to take into account (half the number of items in `term_powers` ). |
term_powers | Array of size 2*`nterms` describing the fitted terms. Each terms is described by a couple of powers (powerx, powery). |
coeffs | Array of size `nterms` to store with the coefficients. |

### gwy_field_area_fit_local_planes()

    GwyField **
    gwy_field_area_fit_local_planes (GwyField *field,
                                     gint size,
                                     gint col,
                                     gint row,
                                     gint width,
                                     gint height,
                                     gint nresults,
                                     const GwyPlaneFitQuantity *types,
                                     GwyField **results);

Fits a plane through neighbourhood of each sample in a rectangular part of a data field.

The sample is always in the origin of its local (x,y) coordinate system, even if the neighbourhood is not centered about it (e.g. because sample is on the edge of data field). Z-coordinate is however not centered, that is `GWY_PLANE_FIT_A` is normal mean value.

#### Parameters

field | A data field. |
size | Neighbourhood size (must be at least 2). It is centered around each pixel, unless `size` is even when it sticks to the right. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |
nresults | The number of requested quantities. |
types | The types of requested quantities. |
results | An array to store quantities to, may be `NULL` to allocate a new one which must be freed by caller then. If any item is `NULL`, a new data field is allocated for it, existing data fields are resized to `width` × `height` . | [nullable]

#### Returns

An array of data fields with requested quantities, that is `results` unless it was `NULL` and a new array was allocated.

[transfer full]

### gwy_field_area_local_plane_quantity()

    GwyField *
    gwy_field_area_local_plane_quantity (GwyField *field,
                                         gint size,
                                         gint col,
                                         gint row,
                                         gint width,
                                         gint height,
                                         GwyPlaneFitQuantity type,
                                         GwyField *result);

Convenience function to get just one quantity from `gwy_field_area_fit_local_planes()`.

#### Parameters

field | A data field. |
size | Neighbourhood size. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |
type | The type of requested quantity. |
result | A data field to store result to, or `NULL` to allocate a new one. | [nullable]

#### Returns

`result` if it is not `NULL`, otherwise a newly allocated data field.

[transfer full]

### gwy_field_fit_local_planes()

    GwyField **
    gwy_field_fit_local_planes (GwyField *field,
                                gint size,
                                gint nresults,
                                const GwyPlaneFitQuantity *types,
                                GwyField **results);

Fits a plane through neighbourhood of each sample in a data field.

See `gwy_field_area_fit_local_planes()` for details.

#### Parameters

field | A data field. |
size | Neighbourhood size. |
nresults | The number of requested quantities. |
types | The types of requested quantities. |
results | An array to store quantities to. |

#### Returns

An array of data fields with requested quantities.

[transfer full]

### gwy_field_local_plane_quantity()

    GwyField *
    gwy_field_local_plane_quantity (GwyField *field,
                                    gint size,
                                    GwyPlaneFitQuantity type,
                                    GwyField *result);

Convenience function to get just one quantity from `gwy_field_fit_local_planes()`.

#### Parameters

field | A data field. |
size | Neighbourhood size. |
type | The type of requested quantity. |
result | A data field to store result to, or `NULL` to allocate a new one. | [nullable]

#### Returns

`result` if it is not `NULL`, otherwise a newly allocated data field.

[transfer full]