## filters

filters — Convolution and other 2D data filters

## Synopsis

    #include <libprocess/gwyprocess.h>

    void                gwy_data_field_normalize            (GwyDataField *data_field);
    void                gwy_data_field_renormalize          (GwyDataField *data_field,
                                                             gdouble range,
                                                             gdouble offset);
    gint                gwy_data_field_threshold            (GwyDataField *data_field,
                                                             gdouble threshval,
                                                             gdouble bottom,
                                                             gdouble top);
    gint                gwy_data_field_area_threshold       (GwyDataField *data_field,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height,
                                                             gdouble threshval,
                                                             gdouble bottom,
                                                             gdouble top);
    gint                gwy_data_field_clamp                (GwyDataField *data_field,
                                                             gdouble bottom,
                                                             gdouble top);
    gint                gwy_data_field_area_clamp           (GwyDataField *data_field,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height,
                                                             gdouble bottom,
                                                             gdouble top);
    void                gwy_data_field_area_gather          (GwyDataField *data_field,
                                                             GwyDataField *result,
                                                             GwyDataField *buffer,
                                                             gint hsize,
                                                             gint vsize,
                                                             gboolean average,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);
    void                gwy_data_field_convolve             (GwyDataField *data_field,
                                                             GwyDataField *kernel_field);
    void                gwy_data_field_area_convolve        (GwyDataField *data_field,
                                                             GwyDataField *kernel_field,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);
    void                gwy_data_field_convolve_1d          (GwyDataField *data_field,
                                                             GwyDataLine *kernel_line,
                                                             GwyOrientation orientation);
    void                gwy_data_field_area_convolve_1d     (GwyDataField *data_field,
                                                             GwyDataLine *kernel_line,
                                                             GwyOrientation orientation,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);
    void                gwy_data_field_filter_median        (GwyDataField *data_field,
                                                             gint size);
    void                gwy_data_field_area_filter_median   (GwyDataField *data_field,
                                                             gint size,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);
    void                gwy_data_field_filter_mean          (GwyDataField *data_field,
                                                             gint size);
    void                gwy_data_field_area_filter_mean     (GwyDataField *data_field,
                                                             gint size,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);
    void                gwy_data_field_filter_conservative  (GwyDataField *data_field,
                                                             gint size);
    void                gwy_data_field_area_filter_conservative
                                                            (GwyDataField *data_field,
                                                             gint size,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);
    void                gwy_data_field_filter_laplacian     (GwyDataField *data_field);
    void                gwy_data_field_area_filter_laplacian
                                                            (GwyDataField *data_field,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);
    void                gwy_data_field_filter_sobel         (GwyDataField *data_field,
                                                             GwyOrientation orientation);
    void                gwy_data_field_area_filter_sobel    (GwyDataField *data_field,
                                                             GwyOrientation orientation,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);
    void                gwy_data_field_filter_prewitt       (GwyDataField *data_field,
                                                             GwyOrientation orientation);
    void                gwy_data_field_area_filter_prewitt  (GwyDataField *data_field,
                                                             GwyOrientation orientation,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);
    void                gwy_data_field_filter_dechecker     (GwyDataField *data_field);
    void                gwy_data_field_area_filter_dechecker
                                                            (GwyDataField *data_field,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);
    void                gwy_data_field_filter_gaussian      (GwyDataField *data_field,
                                                             gdouble sigma);
    void                gwy_data_field_area_filter_gaussian (GwyDataField *data_field,
                                                             gdouble sigma,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);
    void                gwy_data_field_filter_minimum       (GwyDataField *data_field,
                                                             gint size);
    void                gwy_data_field_area_filter_minimum  (GwyDataField *data_field,
                                                             gint size,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);
    void                gwy_data_field_filter_maximum       (GwyDataField *data_field,
                                                             gint size);
    void                gwy_data_field_area_filter_maximum  (GwyDataField *data_field,
                                                             gint size,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);
    void                gwy_data_field_filter_rms           (GwyDataField *data_field,
                                                             gint size);
    void                gwy_data_field_area_filter_rms      (GwyDataField *data_field,
                                                             gint size,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);
    void                gwy_data_field_filter_kuwahara      (GwyDataField *data_field);
    void                gwy_data_field_area_filter_kuwahara (GwyDataField *data_field,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);
    void                gwy_data_field_filter_canny         (GwyDataField *data_field,
                                                             gdouble threshold);
    void                gwy_data_field_shade                (GwyDataField *data_field,
                                                             GwyDataField *target_field,
                                                             gdouble theta,
                                                             gdouble phi);
    void                gwy_data_field_filter_harris        (GwyDataField *x_gradient,
                                                             GwyDataField *y_gradient,
                                                             GwyDataField *result,
                                                             gint neighbourhood,
                                                             gdouble alpha);

## Description

Filters are point-wise operations, such as thresholding, or generally local operations producing a value based on the data in the vicinity of each point: gradients, step detectors and convolutions. Some simple common point-wise operations, e.g. value inversion, are also found in base GwyDataField methods.

## Details

### gwy_data_field_normalize ()

    void                gwy_data_field_normalize            (GwyDataField *data_field);

Normalizes data in a data field to range 0.0 to 1.0.

It is equivalent to gwy_data_field_renormalize(`data_field`, 1.0, 0.0);

If `data_field` is filled with only one value, it is changed to 0.0.

`data_field` : | A data field.

### gwy_data_field_renormalize ()

    void                gwy_data_field_renormalize          (GwyDataField *data_field,
                                                             gdouble range,
                                                             gdouble offset);

Transforms data in a data field with first linear function to given range.

When `range` is positive, the new data range is (`offset`, `offset`+`range`); when `range` is negative, the new data range is (`offset`-`range`, `offset`). In neither case the data are flipped, negative range only means different selection of boundaries.

When `range` is zero, this method is equivalent to gwy_data_field_fill(`data_field`, `offset`).

`data_field` : | A data field.
`range` : | New data interval size.
`offset` : | New data interval offset.

### gwy_data_field_threshold ()

    gint                gwy_data_field_threshold            (GwyDataField *data_field,
                                                             gdouble threshval,
                                                             gdouble bottom,
                                                             gdouble top);

Tresholds values of a data field.

Values smaller than `threshold` are set to value `bottom`, values higher than `threshold` or equal to it are set to value `top`

`data_field` : | A data field.
`threshval` : | Threshold value.
`bottom` : | Lower replacement value.
`top` : | Upper replacement value.
Returns : | The total number of values above threshold.

### gwy_data_field_area_threshold ()

    gint                gwy_data_field_area_threshold       (GwyDataField *data_field,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height,
                                                             gdouble threshval,
                                                             gdouble bottom,
                                                             gdouble top);

Tresholds values of a rectangular part of a data field.

Values smaller than `threshold` are set to value `bottom`, values higher than `threshold` or equal to it are set to value `top`

`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).
`threshval` : | Threshold value.
`bottom` : | Lower replacement value.
`top` : | Upper replacement value.
Returns : | The total number of values above threshold.

### gwy_data_field_clamp ()

    gint                gwy_data_field_clamp                (GwyDataField *data_field,
                                                             gdouble bottom,
                                                             gdouble top);

Limits data field values to a range.

`data_field` : | A data field.
`bottom` : | Lower limit value.
`top` : | Upper limit value.
Returns : | The number of changed values, i.e., values that were outside [`bottom`, `top`].

### gwy_data_field_area_clamp ()

    gint                gwy_data_field_area_clamp           (GwyDataField *data_field,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height,
                                                             gdouble bottom,
                                                             gdouble top);

Limits values in a rectangular part of a data field to a range.

`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).
`bottom` : | Lower limit value.
`top` : | Upper limit value.
Returns : | The number of changed values, i.e., values that were outside [`bottom`, `top`].

### gwy_data_field_area_gather ()

    void                gwy_data_field_area_gather          (GwyDataField *data_field,
                                                             GwyDataField *result,
                                                             GwyDataField *buffer,
                                                             gint hsize,
                                                             gint vsize,
                                                             gboolean average,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);

Sums or averages values in reactangular areas around each sample in a data field.

When the gathered area extends out of calculation area, only samples from their intersection are taken into the local sum (or average).

There are no restrictions on values of `hsize` and `vsize` with regard to `width` and `height`, but they have to be positive.

The result is calculated by the means of two-dimensional rolling sums. One one hand it means the calculation time depends linearly on (`width` + `hsize`)*(`height` + `vsize`) instead of `width`*`hsize`*`height`*`vsize`. On the other hand it means absolute rounding errors of all output values are given by the largest input values, that is relative precision of results small in absolute value may be poor.

`data_field` : | A data field.
`result` : | A data field to put the result to, it may be `data_field` itself.
`buffer` : | A data field to use as a scratch area, its size must be at least `width`*`height`. May be `NULL` to allocate a private temporary buffer.
`hsize` : | Horizontal size of gathered area. The area is centered around each sample if `hsize` is odd, it extends one pixel more to the right if `hsize` is even.
`vsize` : | Vertical size of gathered area. The area is centered around each sample if `vsize` is odd, it extends one pixel more down if `vsize` is even.
`average` : | `TRUE` to divide resulting sums by the number of involved samples to get averages instead of sums.
`col` : | Upper-left column coordinate.
`row` : | Upper-left row coordinate.
`width` : | Area width (number of columns).
`height` : | Area height (number of rows).

### gwy_data_field_convolve ()

    void                gwy_data_field_convolve             (GwyDataField *data_field,
                                                             GwyDataField *kernel_field);

Convolves a data field with given kernel.

`data_field` : | A data field to convolve. It must be at least as large as 1/3 of `kernel_field` in each dimension.
`kernel_field` : | Kenrel field to convolve `data_field` with.

### gwy_data_field_area_convolve ()

    void                gwy_data_field_area_convolve        (GwyDataField *data_field,
                                                             GwyDataField *kernel_field,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);

Convolves a rectangular part of a data field with given kernel.

`data_field` : | A data field to convolve. It must be at least as large as 1/3 of `kernel_field` in each dimension.
`kernel_field` : | Kenrel field to convolve `data_field` with.
`col` : | Upper-left column coordinate.
`row` : | Upper-left row coordinate.
`width` : | Area width (number of columns).
`height` : | Area height (number of rows).

### gwy_data_field_convolve_1d ()

    void                gwy_data_field_convolve_1d          (GwyDataField *data_field,
                                                             GwyDataLine *kernel_line,
                                                             GwyOrientation orientation);

Convolves a data field with given linear kernel.

`data_field` : | A data field to convolve. It must be at least as large as 1/3 of `kernel_field` in the corresponding dimension.
`kernel_line` : | Kenrel line to convolve `data_field` with.
`orientation` : | Filter orientation (see `gwy_data_field_area_convolve_1d()`).

Since 2.4

### gwy_data_field_area_convolve_1d ()

    void                gwy_data_field_area_convolve_1d     (GwyDataField *data_field,
                                                             GwyDataLine *kernel_line,
                                                             GwyOrientation orientation,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);

Convolves a rectangular part of a data field with given linear kernel.

For large separable kernels it can be more efficient to use a sequence of horizontal and vertical convolutions instead one 2D convolution.

`data_field` : | A data field to convolve. It must be at least as large as 1/3 of `kernel_field` in the corresponding dimension.
`kernel_line` : | Kernel line to convolve `data_field` with.
`orientation` : | Filter orientation (`GWY_ORIENTATION_HORIZONTAL` for row-wise convolution, `GWY_ORIENTATION_VERTICAL` for column-wise convolution).
`col` : | Upper-left column coordinate.
`row` : | Upper-left row coordinate.
`width` : | Area width (number of columns).
`height` : | Area height (number of rows).

Since 2.4

### gwy_data_field_filter_median ()

    void                gwy_data_field_filter_median        (GwyDataField *data_field,
                                                             gint size);

Filters a data field with median filter.

`data_field` : | A data field to apply the filter to.
`size` : | Size of area to take median of.

### gwy_data_field_area_filter_median ()

    void                gwy_data_field_area_filter_median   (GwyDataField *data_field,
                                                             gint size,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);

Filters a rectangular part of a data field with median filter.

`data_field` : | A data field to apply the filter to.
`size` : | Size of area to take median of.
`col` : | Upper-left column coordinate.
`row` : | Upper-left row coordinate.
`width` : | Area width (number of columns).
`height` : | Area height (number of rows).

### gwy_data_field_filter_mean ()

    void                gwy_data_field_filter_mean          (GwyDataField *data_field,
                                                             gint size);

Filters a data field with mean filter of size `size`.

`data_field` : | A data field to apply the filter to.
`size` : | Averaged area size.

### gwy_data_field_area_filter_mean ()

    void                gwy_data_field_area_filter_mean     (GwyDataField *data_field,
                                                             gint size,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);

Filters a rectangular part of a data field with mean filter of size `size`.

This method is a simple `gwy_data_field_area_gather()` wrapper.

`data_field` : | A data field to apply the filter to.
`size` : | Averaged area size.
`col` : | Upper-left column coordinate.
`row` : | Upper-left row coordinate.
`width` : | Area width (number of columns).
`height` : | Area height (number of rows).

### gwy_data_field_filter_conservative ()

    void                gwy_data_field_filter_conservative  (GwyDataField *data_field,
                                                             gint size);

Filters a data field with conservative denoise filter.

`data_field` : | A data field to apply the filter to.
`size` : | Filtered area size.

### gwy_data_field_area_filter_conservative ()

    void                gwy_data_field_area_filter_conservative
                                                            (GwyDataField *data_field,
                                                             gint size,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);

Filters a rectangular part of a data field with conservative denoise filter.

`data_field` : | A data field to apply the filter to.
`size` : | Filtered area size.
`col` : | Upper-left column coordinate.
`row` : | Upper-left row coordinate.
`width` : | Area width (number of columns).
`height` : | Area height (number of rows).

### gwy_data_field_filter_laplacian ()

    void                gwy_data_field_filter_laplacian     (GwyDataField *data_field);

Filters a data field with Laplacian filter.

`data_field` : | A data field to apply the filter to.

### gwy_data_field_area_filter_laplacian ()

    void                gwy_data_field_area_filter_laplacian
                                                            (GwyDataField *data_field,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);

Filters a rectangular part of a data field with Laplacian filter.

`data_field` : | A data field to apply the filter to.
`col` : | Upper-left column coordinate.
`row` : | Upper-left row coordinate.
`width` : | Area width (number of columns).
`height` : | Area height (number of rows).

### gwy_data_field_filter_sobel ()

    void                gwy_data_field_filter_sobel         (GwyDataField *data_field,
                                                             GwyOrientation orientation);

Filters a data field with Sobel filter.

`data_field` : | A data field to apply the filter to.
`orientation` : | Filter orientation.

### gwy_data_field_area_filter_sobel ()

    void                gwy_data_field_area_filter_sobel    (GwyDataField *data_field,
                                                             GwyOrientation orientation,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);

Filters a rectangular part of a data field with Sobel filter.

`data_field` : | A data field to apply the filter to.
`orientation` : | Filter orientation.
`col` : | Upper-left column coordinate.
`row` : | Upper-left row coordinate.
`width` : | Area width (number of columns).
`height` : | Area height (number of rows).

### gwy_data_field_filter_prewitt ()

    void                gwy_data_field_filter_prewitt       (GwyDataField *data_field,
                                                             GwyOrientation orientation);

Filters a data field with Prewitt filter.

`data_field` : | A data field to apply the filter to.
`orientation` : | Filter orientation.

### gwy_data_field_area_filter_prewitt ()

    void                gwy_data_field_area_filter_prewitt  (GwyDataField *data_field,
                                                             GwyOrientation orientation,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);

Filters a rectangular part of a data field with Prewitt filter.

`data_field` : | A data field to apply the filter to.
`orientation` : | Filter orientation.
`col` : | Upper-left column coordinate.
`row` : | Upper-left row coordinate.
`width` : | Area width (number of columns).
`height` : | Area height (number of rows).

### gwy_data_field_filter_dechecker ()

    void                gwy_data_field_filter_dechecker     (GwyDataField *data_field);

Filters a data field with 5x5 checker pattern removal filter.

`data_field` : | A data field to apply the filter to.

Since 2.1

### gwy_data_field_area_filter_dechecker ()

    void                gwy_data_field_area_filter_dechecker
                                                            (GwyDataField *data_field,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);

Filters a rectangular part of a data field with 5x5 checker pattern removal filter.

`data_field` : | A data field to apply the filter to.
`col` : | Upper-left column coordinate.
`row` : | Upper-left row coordinate.
`width` : | Area width (number of columns).
`height` : | Area height (number of rows).

Since 2.1

### gwy_data_field_filter_gaussian ()

    void                gwy_data_field_filter_gaussian      (GwyDataField *data_field,
                                                             gdouble sigma);

Filters a data field with a Gaussian filter.

`data_field` : | A data field to apply the filter to.
`sigma` : | The sigma parameter of the Gaussian.

Since 2.4

### gwy_data_field_area_filter_gaussian ()

    void                gwy_data_field_area_filter_gaussian (GwyDataField *data_field,
                                                             gdouble sigma,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);

Filters a rectangular part of a data field with a Gaussian filter.

The Gausian is normalized, i.e. it is sum-preserving.

`data_field` : | A data field to apply the filter to.
`sigma` : | The sigma parameter of the Gaussian.
`col` : | Upper-left column coordinate.
`row` : | Upper-left row coordinate.
`width` : | Area width (number of columns).
`height` : | Area height (number of rows).

Since 2.4

### gwy_data_field_filter_minimum ()

    void                gwy_data_field_filter_minimum       (GwyDataField *data_field,
                                                             gint size);

Filters a data field with minimum filter.

`data_field` : | A data field to apply minimum filter to.
`size` : | Neighbourhood size for minimum search.

### gwy_data_field_area_filter_minimum ()

    void                gwy_data_field_area_filter_minimum  (GwyDataField *data_field,
                                                             gint size,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);

Filters a rectangular part of a data field with minimum filter.

This operation is often called erosion filter.

`data_field` : | A data field to apply minimum filter to.
`size` : | Neighbourhood size for minimum search.
`col` : | Upper-left column coordinate.
`row` : | Upper-left row coordinate.
`width` : | Area width (number of columns).
`height` : | Area height (number of rows).

### gwy_data_field_filter_maximum ()

    void                gwy_data_field_filter_maximum       (GwyDataField *data_field,
                                                             gint size);

Filters a data field with maximum filter.

`data_field` : | A data field to apply maximum filter to.
`size` : | Neighbourhood size for maximum search.

### gwy_data_field_area_filter_maximum ()

    void                gwy_data_field_area_filter_maximum  (GwyDataField *data_field,
                                                             gint size,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);

Filters a rectangular part of a data field with maximum filter.

This operation is often called dilation filter.

`data_field` : | A data field to apply maximum filter to.
`size` : | Neighbourhood size for maximum search.
`col` : | Upper-left column coordinate.
`row` : | Upper-left row coordinate.
`width` : | Area width (number of columns).
`height` : | Area height (number of rows).

### gwy_data_field_filter_rms ()

    void                gwy_data_field_filter_rms           (GwyDataField *data_field,
                                                             gint size);

Filters a data field with RMS filter.

`data_field` : | A data field to apply RMS filter to.
`size` : | Area size.

### gwy_data_field_area_filter_rms ()

    void                gwy_data_field_area_filter_rms      (GwyDataField *data_field,
                                                             gint size,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);

Filters a rectangular part of a data field with RMS filter of size `size`.

RMS filter computes root mean square in given area.

`data_field` : | A data field to apply RMS filter to.
`size` : | Area size.
`col` : | Upper-left column coordinate.
`row` : | Upper-left row coordinate.
`width` : | Area width (number of columns).
`height` : | Area height (number of rows).

### gwy_data_field_filter_kuwahara ()

    void                gwy_data_field_filter_kuwahara      (GwyDataField *data_field);

Filters a data field with Kuwahara filter.

`data_field` : | A data field to apply Kuwahara filter to.

### gwy_data_field_area_filter_kuwahara ()

    void                gwy_data_field_area_filter_kuwahara (GwyDataField *data_field,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height);

Filters a rectangular part of a data field with a Kuwahara (edge-preserving smoothing) filter.

`data_field` : | A data filed to apply Kuwahara filter to.
`col` : | Upper-left column coordinate.
`row` : | Upper-left row coordinate.
`width` : | Area width (number of columns).
`height` : | Area height (number of rows).

### gwy_data_field_filter_canny ()

    void                gwy_data_field_filter_canny         (GwyDataField *data_field,
                                                             gdouble threshold);

Filters a rectangular part of a data field with canny edge detector filter.

`data_field` : | A data field to apply the filter to.
`threshold` : | Slope detection threshold (range 0..1).

### gwy_data_field_shade ()

    void                gwy_data_field_shade                (GwyDataField *data_field,
                                                             GwyDataField *target_field,
                                                             gdouble theta,
                                                             gdouble phi);

Shades a data field.

`data_field` : | A data field.
`target_field` : | A data field to put the shade to. It will be resized to match `data_field`.
`theta` : | Shading angle (in radians, from north pole).
`phi` : | Shade orientation in xy plane (in radians, counterclockwise).

### gwy_data_field_filter_harris ()

    void                gwy_data_field_filter_harris        (GwyDataField *x_gradient,
                                                             GwyDataField *y_gradient,
                                                             GwyDataField *result,
                                                             gint neighbourhood,
                                                             gdouble alpha);

`x_gradient` : |
`y_gradient` : |
`result` : |
`neighbourhood` : |
`alpha` : |