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

level

level — Leveling and background removal

Functions

void gwy_data_field_area_fit_plane ()
void gwy_data_field_fit_plane ()
gboolean gwy_data_field_fit_facet_plane ()
void gwy_data_field_plane_level ()
void gwy_data_field_plane_rotate ()
void gwy_data_field_fit_lines ()
gdouble * gwy_data_field_fit_polynom ()
gdouble * gwy_data_field_area_fit_polynom ()
void gwy_data_field_subtract_polynom ()
void gwy_data_field_area_subtract_polynom ()
gdouble * gwy_data_field_fit_legendre ()
gdouble * gwy_data_field_area_fit_legendre ()
void gwy_data_field_subtract_legendre ()
void gwy_data_field_area_subtract_legendre ()
gdouble * gwy_data_field_fit_poly_max ()
gdouble * gwy_data_field_area_fit_poly_max ()
void gwy_data_field_subtract_poly_max ()
void gwy_data_field_area_subtract_poly_max ()
gdouble * gwy_data_field_fit_poly ()
gdouble * gwy_data_field_area_fit_poly ()
void gwy_data_field_subtract_poly ()
void gwy_data_field_area_subtract_poly ()
GwyDataField ** gwy_data_field_area_fit_local_planes ()
GwyDataField * gwy_data_field_area_local_plane_quantity ()
GwyDataField ** gwy_data_field_fit_local_planes ()
GwyDataField * gwy_data_field_local_plane_quantity ()

Includes

#include <libprocess/gwyprocess.h>

Description

Functions

gwy_data_field_area_fit_plane ()

void
gwy_data_field_area_fit_plane (GwyDataField *data_field,
                               GwyDataField *mask,
                               gint col,
                               gint row,
                               gint width,
                               gint height,
                               gdouble *pa,
                               gdouble *pbx,
                               gdouble *pby);

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

The coefficients can be used for plane leveling using the same relation as in gwy_data_field_fit_plane(), counting indices from area top left corner.

Parameters

data_field

A data field

 

mask

Mask of values to take values into account, or NULL for full data_field . 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 (0.0, 1.0) is undefined (it may be specified in the future).

 

col

Upper-left column coordinate.

 

row

Upper-left row coordinate.

 

width

Area width (number of columns).

 

height

Area height (number of rows).

 

pa

Where constant coefficient should be stored (or NULL).

 

pbx

Where x plane coefficient should be stored (or NULL).

 

pby

Where y plane coefficient should be stored (or NULL).

 

gwy_data_field_fit_plane ()

void
gwy_data_field_fit_plane (GwyDataField *data_field,
                          gdouble *pa,
                          gdouble *pbx,
                          gdouble *pby);

Fits a plane through a data field.

The coefficients can be used for plane leveling using relation data[i] := data[i] - (pa + pby*i + pbx*j);

Parameters

data_field

A data field.

 

pa

Where constant coefficient should be stored (or NULL).

 

pbx

Where x plane coefficient should be stored (or NULL).

 

pby

Where y plane coefficient should be stored (or NULL).

 

gwy_data_field_fit_facet_plane ()

gboolean
gwy_data_field_fit_facet_plane (GwyDataField *data_field,
                                GwyDataField *mfield,
                                GwyMaskingType masking,
                                gdouble *pa,
                                gdouble *pbx,
                                gdouble *pby);

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_data_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_data_field_plane_level() uses pixel-based lateral coordinates, the coefficients must be divided by gwy_data_field_get_dx(data_field) and gwy_data_field_get_dy(data_field) to obtain physical plane coefficients.

Parameters

data_field

A data field.

 

mfield

Mask specifying which values to take into account/exclude, or NULL.

 

masking

Masking mode to use.

 

pa

Where constant coefficient should be stored (or NULL).

 

pbx

Where x plane coefficient should be stored.

 

pby

Where y plane coefficient should be stored.

 

Returns

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

Since: 2.37

gwy_data_field_plane_level ()

void
gwy_data_field_plane_level (GwyDataField *data_field,
                            gdouble a,
                            gdouble bx,
                            gdouble by);

Subtracts plane from a data field.

See gwy_data_field_fit_plane() for details.

Parameters

data_field

A data field.

 

a

Constant coefficient.

 

bx

X plane coefficient.

 

by

Y plane coefficient.

 

gwy_data_field_plane_rotate ()

void
gwy_data_field_plane_rotate (GwyDataField *data_field,
                             gdouble xangle,
                             gdouble yangle,
                             GwyInterpolationType interpolation);

Performs rotation of plane along x and y axis.

Parameters

data_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_data_field_fit_lines ()

void
gwy_data_field_fit_lines (GwyDataField *data_field,
                          gint col,
                          gint row,
                          gint width,
                          gint height,
                          gint degree,
                          gboolean exclude,
                          GwyOrientation orientation);

Independently levels profiles on each row/column in a data field.

Lines that have no intersection with area selected by ulcol , ulrow , brcol , brrow are always leveled as a whole. Lines that have intersection with selected area, are leveled using polynomial coefficients computed only from data inside (or outside for exclude = TRUE) the area.

Parameters

data_field

A data field.

 

col

Upper-left column coordinate.

 

row

Upper-left row coordinate.

 

width

Area width (number of columns).

 

height

Area height (number of rows).

 

degree

Fitted polynomial degree.

 

exclude

If TRUE, outside of area selected by ulcol , ulrow , brcol , brrow will be used for polynomial coefficients computation, instead of inside.

 

orientation

Line orientation.

 

gwy_data_field_fit_polynom ()

gdouble *
gwy_data_field_fit_polynom (GwyDataField *data_field,
                            gint col_degree,
                            gint row_degree,
                            gdouble *coeffs);

Fits a two-dimensional polynomial to a data field.

Parameters

data_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), see gwy_data_field_area_fit_polynom() for details.

 

Returns

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

gwy_data_field_area_fit_polynom ()

gdouble *
gwy_data_field_area_fit_polynom (GwyDataField *data_field,
                                 gint col,
                                 gint row,
                                 gint width,
                                 gint height,
                                 gint col_degree,
                                 gint row_degree,
                                 gdouble *coeffs);

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

The coefficients are stored by row into coeffs , like data in a datafield. Row index is y-degree, column index is x-degree.

Note naive x^n y^m polynomial fitting is numerically unstable, therefore this method works only up to col_degree = row_degree = 6.

Parameters

data_field

A data field.

 

col

Upper-left column coordinate.

 

row

Upper-left row coordinate.

 

width

Area width (number of columns).

 

height

Area height (number of rows).

 

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

 

Returns

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

gwy_data_field_subtract_polynom ()

void
gwy_data_field_subtract_polynom (GwyDataField *data_field,
                                 gint col_degree,
                                 gint row_degree,
                                 const gdouble *coeffs);

Subtracts a two-dimensional polynomial from a data field.

Parameters

data_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_data_field_area_fit_polynom() for details.

 

gwy_data_field_area_subtract_polynom ()

void
gwy_data_field_area_subtract_polynom (GwyDataField *data_field,
                                      gint col,
                                      gint row,
                                      gint width,
                                      gint height,
                                      gint col_degree,
                                      gint row_degree,
                                      const gdouble *coeffs);

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

Parameters

data_field

A data field.

 

col

Upper-left column coordinate.

 

row

Upper-left row coordinate.

 

width

Area width (number of columns).

 

height

Area height (number of rows).

 

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_data_field_area_fit_polynom() for details.

 

gwy_data_field_fit_legendre ()

gdouble *
gwy_data_field_fit_legendre (GwyDataField *data_field,
                             gint col_degree,
                             gint row_degree,
                             gdouble *coeffs);

Fits two-dimensional Legendre polynomial to a data field.

See gwy_data_field_area_fit_legendre() for details.

Parameters

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

 

Returns

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

gwy_data_field_area_fit_legendre ()

gdouble *
gwy_data_field_area_fit_legendre (GwyDataField *data_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_data_field_area_fit_polynom(), 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

data_field

A data field.

 

col

Upper-left column coordinate.

 

row

Upper-left row coordinate.

 

width

Area width (number of columns).

 

height

Area height (number of rows).

 

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

 

Returns

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

gwy_data_field_subtract_legendre ()

void
gwy_data_field_subtract_legendre (GwyDataField *data_field,
                                  gint col_degree,
                                  gint row_degree,
                                  const gdouble *coeffs);

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

Parameters

data_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_data_field_area_fit_legendre() for details.

 

gwy_data_field_area_subtract_legendre ()

void
gwy_data_field_area_subtract_legendre (GwyDataField *data_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

data_field

A data field.

 

col

Upper-left column coordinate.

 

row

Upper-left row coordinate.

 

width

Area width (number of columns).

 

height

Area height (number of rows).

 

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_data_field_area_fit_legendre() for details.

 

gwy_data_field_fit_poly_max ()

gdouble *
gwy_data_field_fit_poly_max (GwyDataField *data_field,
                             gint max_degree,
                             gdouble *coeffs);

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

See gwy_data_field_area_fit_poly_max() for details.

Parameters

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

 

Returns

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

gwy_data_field_area_fit_poly_max ()

gdouble *
gwy_data_field_area_fit_poly_max (GwyDataField *data_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_data_field_area_fit_legendre() for description. This function differs by limiting the total maximum degree, while gwy_data_field_area_fit_legendre() limits the maximum degrees in horizontal and vertical directions independently.

Parameters

data_field

A data field.

 

col

Upper-left column coordinate.

 

row

Upper-left row coordinate.

 

width

Area width (number of columns).

 

height

Area height (number of rows).

 

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

 

Returns

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

gwy_data_field_subtract_poly_max ()

void
gwy_data_field_subtract_poly_max (GwyDataField *data_field,
                                  gint max_degree,
                                  const gdouble *coeffs);

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

Parameters

data_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_data_field_area_fit_poly_max() for details.

 

gwy_data_field_area_subtract_poly_max ()

void
gwy_data_field_area_subtract_poly_max (GwyDataField *data_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

data_field

A data field.

 

col

Upper-left column coordinate.

 

row

Upper-left row coordinate.

 

width

Area width (number of columns).

 

height

Area height (number of rows).

 

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_data_field_area_fit_poly_max() for details.

 

gwy_data_field_fit_poly ()

gdouble *
gwy_data_field_fit_poly (GwyDataField *data_field,
                         GwyDataField *mask_field,
                         gint nterms,
                         const gint *term_powers,
                         gboolean exclude,
                         gdouble *coeffs);

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

Parameters

data_field

A data field.

 

mask_field

Mask of values to take values into account, or NULL for full data_field . 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 (0.0, 1.0) is undefined (it may be specified in the future).

 

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

 

exclude

Interpret values w in the mask as 1.0-w .

 

coeffs

Array of size nterms to store the coefficients to, or NULL to allocate a new array.

 

Returns

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

Since: 2.11

gwy_data_field_area_fit_poly ()

gdouble *
gwy_data_field_area_fit_poly (GwyDataField *data_field,
                              GwyDataField *mask_field,
                              gint col,
                              gint row,
                              gint width,
                              gint height,
                              gint nterms,
                              const gint *term_powers,
                              gboolean exclude,
                              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.

Parameters

data_field

A data field.

 

mask_field

Mask of values to take values into account, or NULL for full data_field . 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 (0.0, 1.0) is undefined (it may be specified in the future).

 

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

 

exclude

Interpret values w in the mask as 1.0-w .

 

coeffs

Array of size nterms to store the coefficients to, or NULL to allocate a new array.

 

Returns

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

Since: 2.11

gwy_data_field_subtract_poly ()

void
gwy_data_field_subtract_poly (GwyDataField *data_field,
                              gint nterms,
                              const gint *term_powers,
                              const gdouble *coeffs);

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

Parameters

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

 

Since: 2.11

gwy_data_field_area_subtract_poly ()

void
gwy_data_field_area_subtract_poly (GwyDataField *data_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

data_field

A data field.

 

col

Upper-left column coordinate.

 

row

Upper-left row coordinate.

 

width

Area width (number of columns).

 

height

Area height (number of rows).

 

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.

 

Since: 2.11

gwy_data_field_area_fit_local_planes ()

GwyDataField **
gwy_data_field_area_fit_local_planes (GwyDataField *data_field,
                                      gint size,
                                      gint col,
                                      gint row,
                                      gint width,
                                      gint height,
                                      gint nresults,
                                      const GwyPlaneFitQuantity *types,
                                      GwyDataField **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

data_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 x height .

 

Returns

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

gwy_data_field_area_local_plane_quantity ()

GwyDataField *
gwy_data_field_area_local_plane_quantity
                               (GwyDataField *data_field,
                                gint size,
                                gint col,
                                gint row,
                                gint width,
                                gint height,
                                GwyPlaneFitQuantity type,
                                GwyDataField *result);

Convenience function to get just one quantity from gwy_data_field_area_fit_local_planes().

Parameters

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

 

Returns

result if it isn't NULL, otherwise a newly allocated data field.

gwy_data_field_fit_local_planes ()

GwyDataField **
gwy_data_field_fit_local_planes (GwyDataField *data_field,
                                 gint size,
                                 gint nresults,
                                 const GwyPlaneFitQuantity *types,
                                 GwyDataField **results);

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

See gwy_data_field_area_fit_local_planes() for details.

Parameters

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

gwy_data_field_local_plane_quantity ()

GwyDataField *
gwy_data_field_local_plane_quantity (GwyDataField *data_field,
                                     gint size,
                                     GwyPlaneFitQuantity type,
                                     GwyDataField *result);

Convenience function to get just one quantity from gwy_data_field_fit_local_planes().

Parameters

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

 

Returns

result if it isn't NULL, otherwise a newly allocated data field.

Types and Values

© David Nečas and Petr Klapetek

Home Download News Features Screenshots Documentation Communicate Participate Resources Publications Applications Site Map

Valid XHTML 1.0 Valid CSS