## level

level — Leveling and background removal

## Synopsis

    #include <libprocess/gwyprocess.h>

    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);
    void                gwy_data_field_fit_plane            (GwyDataField *data_field,
                                                             gdouble *pa,
                                                             gdouble *pbx,
                                                             gdouble *pby);
    void                gwy_data_field_plane_level          (GwyDataField *data_field,
                                                             gdouble a,
                                                             gdouble bx,
                                                             gdouble by);
    void                gwy_data_field_plane_rotate         (GwyDataField *data_field,
                                                             gdouble xangle,
                                                             gdouble yangle,
                                                             GwyInterpolationType interpolation);
    void                gwy_data_field_fit_lines            (GwyDataField *data_field,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height,
                                                             gint degree,
                                                             gboolean exclude,
                                                             GwyOrientation orientation);
    gdouble*            gwy_data_field_fit_polynom          (GwyDataField *data_field,
                                                             gint col_degree,
                                                             gint row_degree,
                                                             gdouble *coeffs);
    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);
    void                gwy_data_field_subtract_polynom     (GwyDataField *data_field,
                                                             gint col_degree,
                                                             gint row_degree,
                                                             const gdouble *coeffs);
    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);
    gdouble*            gwy_data_field_fit_legendre         (GwyDataField *data_field,
                                                             gint col_degree,
                                                             gint row_degree,
                                                             gdouble *coeffs);
    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);
    void                gwy_data_field_subtract_legendre    (GwyDataField *data_field,
                                                             gint col_degree,
                                                             gint row_degree,
                                                             const gdouble *coeffs);
    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);
    gdouble*            gwy_data_field_fit_poly_max         (GwyDataField *data_field,
                                                             gint max_degree,
                                                             gdouble *coeffs);
    gdouble*            gwy_data_field_area_fit_poly_max    (GwyDataField *data_field,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height,
                                                             gint max_degree,
                                                             gdouble *coeffs);
    void                gwy_data_field_subtract_poly_max    (GwyDataField *data_field,
                                                             gint max_degree,
                                                             const gdouble *coeffs);
    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);
    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);
    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);
    GwyDataField**      gwy_data_field_fit_local_planes     (GwyDataField *data_field,
                                                             gint size,
                                                             gint nresults,
                                                             const GwyPlaneFitQuantity *types,
                                                             GwyDataField **results);
    GwyDataField*       gwy_data_field_local_plane_quantity (GwyDataField *data_field,
                                                             gint size,
                                                             GwyPlaneFitQuantity type,
                                                             GwyDataField *result);

## Description

## Details

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

`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);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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