filters: Gwyddion Library Reference Manual

## filters filters — Convolution and other 2D data filters |

## Functions

void | gwy_field_normalize ()
void | gwy_field_renormalize ()
void | gwy_field_area_renormalize ()
gsize | gwy_field_threshold ()
gsize | gwy_field_area_threshold ()
gsize | gwy_field_clamp ()
gsize | gwy_field_area_clamp ()
void | gwy_field_area_gather ()
void | gwy_field_area_filter_3x3 ()
void | gwy_field_filter_3x3 ()
void | gwy_field_area_enhance_filter ()
void | gwy_field_enhance_filter ()
void | gwy_field_derivative_filter ()
void | gwy_field_convolve ()
void | gwy_field_area_convolve ()
void | gwy_field_fft_convolve ()
void | gwy_field_area_ext_convolve ()
void | gwy_field_convolve_1d ()
void | gwy_field_area_convolve_1d ()
void | gwy_field_area_ext_row_convolve ()
void | gwy_field_filter_median ()
void | gwy_field_area_filter_median ()
void | gwy_field_filter_mean ()
void | gwy_field_area_filter_mean ()
void | gwy_field_filter_conservative ()
void | gwy_field_area_filter_conservative ()
void | gwy_field_laplacian_of_gaussians ()
void | gwy_field_filter_gauss_step ()
void | gwy_field_filter_gaussian ()
void | gwy_field_area_filter_gaussian ()
void | gwy_field_row_gaussian ()
void | gwy_field_column_gaussian ()
void | gwy_field_filter_minimum ()
void | gwy_field_area_filter_minimum ()
void | gwy_field_filter_maximum ()
void | gwy_field_area_filter_maximum ()
void | gwy_field_filter_min_max ()
void | gwy_field_area_filter_min_max ()
void | gwy_field_area_filter_disc_asf ()
void | gwy_nield_filter_min_max ()
void | gwy_nield_area_filter_min_max ()
void | gwy_nield_area_filter_disc_asf ()
gboolean | gwy_field_area_filter_kth_rank ()
void | gwy_line_part_filter_kth_rank ()
gboolean | gwy_field_area_filter_trimmed_mean ()
void | gwy_field_filter_rms ()
void | gwy_field_filter_canny ()
void | gwy_field_shade ()
void | gwy_field_filter_harris ()
void | gwy_field_deconvolve_regularized ()
void | gwy_field_deconvolve_psf_leastsq ()
gdouble | gwy_field_find_regularization_sigma_for_psf ()
gdouble | gwy_field_find_regularization_sigma_leastsq ()

## Types and Values

enum | GwyDerivativeFilterType
enum | GwyEnhanceFilterType
enum | GwyMinMaxFilterType

## Includes

    #include <libgwyddion/gwyddion.h>

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

## Functions

### gwy_field_normalize()

    void
    gwy_field_normalize (GwyField *field);

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

It is equivalent to gwy_field_renormalize(`field` , 1.0, 0.0);

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

#### Parameters

field | A data field. |

### gwy_field_renormalize()

    void
    gwy_field_renormalize (GwyField *field,
                           gdouble range,
                           gdouble offset);

Transforms data in a data field with 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 a different selection of boundaries.

When `range` is zero, this method is equivalent to gwy_field_fill(`field` , `offset` ).

#### Parameters

field | A data field. |
range | New data interval size. |
offset | New data interval offset. |

### gwy_field_area_renormalize()

    void
    gwy_field_area_renormalize (GwyField *field,
                                gint col,
                                gint row,
                                gint width,
                                gint height,
                                gdouble range,
                                gdouble offset);

Transforms data in a part of a data field with 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_field_fill(`field` , `offset` ).

#### Parameters

field | A data field. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |
range | New data interval size. |
offset | New data interval offset. |

### gwy_field_threshold()

    gsize
    gwy_field_threshold (GwyField *field,
                         gdouble threshold,
                         gdouble below,
                         gdouble above);

Tresholds values of a data field.

Values smaller than `threshold` are set to value `below` , values higher than `threshold` or equal to it are set to value `above` .

#### Parameters

field | A data field. |
threshold | Threshold value. |
below | Lower replacement value. |
above | Upper replacement value. |

#### Returns

The total number of values above threshold.

### gwy_field_area_threshold()

    gsize
    gwy_field_area_threshold (GwyField *field,
                              gint col,
                              gint row,
                              gint width,
                              gint height,
                              gdouble threshold,
                              gdouble below,
                              gdouble above);

Tresholds values of a rectangular part of a data field.

Values smaller than `threshold` are set to value `below` , values higher than `threshold` or equal to it are set to value `above`

#### Parameters

field | A data field. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |
threshold | Threshold value. |
below | Lower replacement value. |
above | Upper replacement value. |

#### Returns

The total number of values above threshold.

### gwy_field_clamp()

    gsize
    gwy_field_clamp (GwyField *field,
                     gdouble bottom,
                     gdouble top);

Limits data field values to a range.

#### Parameters

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

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

#### Parameters

field | A data field. |
mask | Mask of values to modify, or `NULL` for full `field` . | [nullable]
masking | Masking mode to use. See the introduction for description of masking modes. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |
bottom | Lower limit value. |
top | Upper limit value. |

#### Returns

The number of changed values, i.e., values that were outside [`bottom` , `top` ].

### gwy_field_area_gather()

    void
    gwy_field_area_gather (GwyField *field,
                           GwyField *result,
                           GwyField *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.

#### Parameters

field | A data field. |
result | A data field to put the result to, it may be `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. | [nullable]
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |
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. |

### gwy_field_area_filter_3x3()

    void
    gwy_field_area_filter_3x3 (GwyField *field,
                               GwyField *target,
                               GwyNield *mask,
                               GwyMaskingType masking,
                               gint col,
                               gint row,
                               gint width,
                               gint height,
                               const gdouble *kernel);

Applies a 3×3 convolution filter to a data field area.

The filter is appled as a convolution filter. For asymmetrical filters, for example derivatives, the signs needs to be [1, 0, -1] instead of [-1, 0, 1] to get the usual derivative sign.

The mask, if given, determines which pixels are modified by the filter, not which are used as the inpot data (which would hardly make any sense for irregular masked regions). If `target` differs from `source` , pixels excluded according to the current masking mode are unchanged.

#### Parameters

field | A data field to apply the filter to. |
target | Target data field where to put the result. It can be `field` itself and in any case it must have the same size. |
mask | Mask specifying which pixels to apply the filter to. |
masking | Masking mode to use. See the introduction for description of masking modes. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |
kernel | Filter kernel. | [array size=9]

### gwy_field_filter_3x3()

    void
    gwy_field_filter_3x3 (GwyField *field,
                          GwyField *target,
                          const gdouble *kernel);

Applies a 3×3 convolution filter to a data field.

The filter is appled as a convolution filter. For asymmetrical filters, for example derivatives, the signs needs to be [1, 0, -1] instead of [-1, 0, 1] to get the usual derivative sign.

#### Parameters

field | A data field to apply the filter to. |
target | Target data field where to put the result. It can be `field` itself and in any case it must have the same size. |
kernel | Filter kernel. | [array size=9]

### gwy_field_area_enhance_filter()

    void
    gwy_field_area_enhance_filter (GwyField *field,
                                   GwyField *target,
                                   GwyNield *mask,
                                   GwyMaskingType masking,
                                   gint col,
                                   gint row,
                                   gint width,
                                   gint height,
                                   GwyEnhanceFilterType filter_type);

Applies a simple enhance filter to a data field area.

The mask, if given, determines which pixels are modified by the filter, not which are used as the inpot data (which would hardly make any sense for irregular masked regions). If `target` differs from `source` , pixels excluded according to the current masking mode are unchanged.

#### Parameters

field | A data field to apply the filter to. |
target | Target data field where to put the result. It can be `field` itself and in any case it must have the same size. |
mask | Mask specifying which pixels to apply the filter to. |
masking | Masking mode to use. See the introduction for description of masking modes. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |
filter_type | Predefined denoising filter type. |

### gwy_field_enhance_filter()

    void
    gwy_field_enhance_filter (GwyField *field,
                              GwyField *target,
                              GwyEnhanceFilterType filter_type);

Applies a simple enhance filter to a data field.

#### Parameters

field | A data field to apply the filter to. |
target | Target data field where to put the result. It can be `field` itself and in any case it must have the same size. |
filter_type | Simple predefined filter type. |

### gwy_field_derivative_filter()

    void
    gwy_field_derivative_filter (GwyField *field,
                                 GwyField *target,
                                 GwyDerivativeFilterType filter_type,
                                 gboolean as_derivative);

Applies a simple predefined derivative filter to a data field.

If `as_derivative` is `TRUE`, `field` sampling steps are used to scale the differences to approximate derivatives. Regardless of `as_derivative` , `target` real dimensions and units are updated. For derivatives, the units will be the units of derivatives. For discrete differences, `target` will have the same units as `field` .

#### Parameters

field | A data field to apply the filter to. |
target | Target data field where to put the result. It can also be `field` itself. It will be resized if necessary. |
filter_type | Simple predefined filter type. |
as_derivative | `TRUE` to calculate derivatives in physical units, `FALSE` to calculate discrete differences. |

### gwy_field_convolve()

    void
    gwy_field_convolve (GwyField *field,
                        GwyField *kernel_field);

Convolves a data field with given kernel.

Note that the convolution is done by summation and can be slow for large kernels.

#### Parameters

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

### gwy_field_area_convolve()

    void
    gwy_field_area_convolve (GwyField *field,
                             GwyField *kernel_field,
                             gint col,
                             gint row,
                             gint width,
                             gint height);

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

Note that the convolution is done by summation and can be slow for large kernels.

#### Parameters

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

    void
    gwy_field_fft_convolve (GwyField *field,
                            GwyField *kernel_field);

Convolves a data field with given kernel of the same size using FFT.

This is a simple FFT-based convolution done by multiplication in the frequency domain.

This is a somewhat low-level function. There is no padding or boundary treatment; images are considered periodic. The result is normalised as if the convolution was done by summation and the physical units of `field` are unchanged.

Also note that in order to obtain unshifted result, the kernel needs to be centered around the top left corner. You can use `gwy_field_fft_2d_decenter()` to transform a centered kernel.

#### Parameters

field | A data field to convolve. |
kernel_field | Kenrel field to convolve `field` with. It must have the same size as `field` . |

### gwy_field_area_ext_convolve()

    void
    gwy_field_area_ext_convolve (GwyField *field,
                                 guint col,
                                 guint row,
                                 guint width,
                                 guint height,
                                 GwyField *target,
                                 GwyField *kernel,
                                 GwyExteriorType exterior,
                                 gdouble fill_value,
                                 gboolean as_integral);

Convolve a field with a two-dimensional kernel.

Pixel dimensions of `target` may match either `field` or just the rectangular area. In the former case the result is written in the same rectangular area; in the latter case the result fills the entire `target` .

The convolution is performed with the kernel centred on the respective field pixels. For directions in which the kernel has an odd size this holds precisely. For an even-sized kernel this means the kernel centre is placed 0.5 pixel left or up (towards lower indices) from the respective field pixel.

See `gwy_field_extend()` for what constitutes the exterior and how it is handled.

If `as_integral` is `FALSE` the function performs a simple discrete convolution sum and the value units of `target` are set to product of `field` and `kernel` units.

If `as_integral` is `TRUE` the function approximates a convolution integral. In this case `kernel` should be a sampled continuous transfer function. The units of value `target` are set to product of `field` and `kernel` value units and `field` lateral units squared. Furthermore, the discrete sum is multiplied by the pixel size (i.e. d`x` d`y` in the integral).

In either case, the lateral units and pixel size of `kernel` are assumed to be the same as for `field` (albeit not checked), because the convolution does not make sense otherwise.

#### Parameters

field | A two-dimensional data field. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |
target | A two-dimensional data field where the result will be placed. It may be `field` for an in-place modification. |
kernel | Kernel to convolve `field` with. |
exterior | Exterior pixels handling. |
fill_value | The value to use with `GWY_EXTERIOR_FIXED_VALUE` exterior. |
as_integral | `TRUE` for normalisation and units as a convolution integral, `FALSE` as a sum. |

### gwy_field_convolve_1d()

    void
    gwy_field_convolve_1d (GwyField *field,
                           GwyLine *kernel_line,
                           GwyOrientation orientation);

Convolves a data field with given linear kernel.

#### Parameters

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 `field` with. |
orientation | Filter orientation (see `gwy_field_area_convolve_1d()`). |

### gwy_field_area_convolve_1d()

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

#### Parameters

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

### gwy_field_area_ext_row_convolve()

    void
    gwy_field_area_ext_row_convolve (GwyField *field,
                                     guint col,
                                     guint row,
                                     guint width,
                                     guint height,
                                     GwyField *target,
                                     GwyLine *kernel,
                                     GwyExteriorType exterior,
                                     gdouble fill_value,
                                     gboolean as_integral);

Convolve a field row-wise with a one-dimensional kernel.

Pixel dimensions of `target` may match either `field` or just the rectangular area. In the former case the result is written in the same rectangular area; in the latter case the result fills the entire `target` .

The convolution is performed with the kernel centred on the respective field pixels. For an odd-sized kernel this holds precisely. For an even-sized kernel this means the kernel centre is placed 0.5 pixel to the left (towards lower column indices) from the respective field pixel.

See `gwy_field_extend()` for what constitutes the exterior and how it is handled.

If `as_integral` is `FALSE` the function performs a simple discrete convolution sum and the value units of `target` are set to product of `field` and `kernel` units.

If `as_integral` is `TRUE` the function approximates a convolution integral. In this case `kernel` should be a sampled continuous transfer function. The units of value `target` are set to product of `field` and `kernel` value units and `field` lateral units. Furthermore, the discrete sum is multiplied by the pixel size (i.e. d`x` in the integral).

In either case, the lateral units and pixel size of `kernel` are assumed to be the same as for a `field` 's row (albeit not checked), because the convolution does not make sense otherwise.

#### Parameters

field | A two-dimensional data field. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |
target | A two-dimensional data field where the result will be placed. It may be `field` for an in-place modification. |
kernel | Kernel to convolve `field` with. |
exterior | Exterior pixels handling. |
fill_value | The value to use with `GWY_EXTERIOR_FIXED_VALUE` exterior. |
as_integral | `TRUE` for normalisation and units as a convolution integral, `FALSE` as a sum. |

### gwy_field_filter_median()

    void
    gwy_field_filter_median (GwyField *field,
                             gint size);

Filters a data field with median filter.

This method uses a simple square kernel. Use the general function `gwy_field_area_filter_kth_rank()` to perform filtering with a different kernel, for instance circular.

#### Parameters

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

### gwy_field_area_filter_median()

    void
    gwy_field_area_filter_median (GwyField *field,
                                  gint size,
                                  gint col,
                                  gint row,
                                  gint width,
                                  gint height);

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

This method uses a simple square kernel. Use the general function `gwy_field_area_filter_kth_rank()` to perform filtering with a different kernel, for instance circular.

#### Parameters

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

    void
    gwy_field_filter_mean (GwyField *field,
                           gint size);

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

This method is a simple `gwy_field_area_gather()` wrapper, so the kernel is square. Use convolution `gwy_field_area_ext_convolve()` to perform a mean filter with different, for instance circular, kernel.

#### Parameters

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

### gwy_field_area_filter_mean()

    void
    gwy_field_area_filter_mean (GwyField *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_field_area_gather()` wrapper, so the kernel is square. Use convolution `gwy_field_area_ext_convolve()` to perform a mean filter with different, for instance circular, kernel.

#### Parameters

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

    void
    gwy_field_filter_conservative (GwyField *field,
                                   gint size);

Filters a data field with conservative denoise filter.

#### Parameters

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

### gwy_field_area_filter_conservative()

    void
    gwy_field_area_filter_conservative (GwyField *field,
                                        gint size,
                                        gint col,
                                        gint row,
                                        gint width,
                                        gint height);

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

#### Parameters

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

    void
    gwy_field_laplacian_of_gaussians (GwyField *field,
                                      GwyField *target);

Applies a simple predefined Laplacian of Gaussians filter to a data field.

Dimensions and units of `target` are updated. Since this is a discrete derivative filter, the units of `target` are kept the same as `field` .

#### Parameters

field | A data field to apply the filter to. |
target | Target data field where to put the result. It can also be `field` itself. It will be resized if necessary. |

### gwy_field_filter_gauss_step()

    void
    gwy_field_filter_gauss_step (GwyField *field,
                                 GwyField *target,
                                 gdouble sigma);

Processes a data field with Gaussian step detection filter.

The filter is a multi-directional combination of convolutions with Gaussian multiplied by a signed step function.

The resulting values correspond roughly to the step height around the pixel.

#### Parameters

field | A data field to apply the filter to. |
target | A data field to put the result to. It will be resized to match `field` . |
sigma | Gaussian filter width (in pixels). |

### gwy_field_filter_gaussian()

    void
    gwy_field_filter_gaussian (GwyField *field,
                               gdouble sigma);

Filters a data field with a Gaussian filter.

#### Parameters

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

### gwy_field_area_filter_gaussian()

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

#### Parameters

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

### gwy_field_row_gaussian()

    void
    gwy_field_row_gaussian (GwyField *field,
                            gdouble sigma);

Filters a data field with a Gaussian filter in horizontal direction.

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

#### Parameters

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

### gwy_field_column_gaussian()

    void
    gwy_field_column_gaussian (GwyField *field,
                               gdouble sigma);

Filters a data field with a Gaussian filter in vertical direction.

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

#### Parameters

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

### gwy_field_filter_minimum()

    void
    gwy_field_filter_minimum (GwyField *field,
                              gint size);

Filters a data field with minimum filter.

This method uses a simple square kernel. Use the general function `gwy_field_area_filter_min_max()` to perform filtering with a different kernel, for instance circular.

#### Parameters

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

### gwy_field_area_filter_minimum()

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

This method uses a simple square kernel. Use the general function `gwy_field_area_filter_min_max()` to perform filtering with a different kernel, for instance circular.

Another difference is that this function filters the rectangular area as an independent data field. Meaning, only values inside the rectangle influence the result.

#### Parameters

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

    void
    gwy_field_filter_maximum (GwyField *field,
                              gint size);

Filters a data field with maximum filter.

This method uses a simple square kernel. Use the general function `gwy_field_area_filter_min_max()` to perform filtering with a different kernel, for instance circular.

#### Parameters

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

### gwy_field_area_filter_maximum()

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

This method uses a simple square kernel. Use the general function `gwy_field_area_filter_min_max()` to perform filtering with a different kernel, for instance circular.

Another difference is that this function filters the rectangular area as an independent data field. Meaning, only values inside the rectangle influence the result.

#### Parameters

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

    void
    gwy_field_filter_min_max (GwyField *field,
                              GwyNield *kernel,
                              GwyMinMaxFilterType filtertype);

Applies a morphological operation with a flat structuring element to a data field.

See `gwy_field_area_filter_min_max()` for description. This function simply applies the operation the entire field.

#### Parameters

field | A data field to apply the filter to. |
kernel | Number field defining the flat structuring element. |
filtertype | The type of filter to apply. |

### gwy_field_area_filter_min_max()

    void
    gwy_field_area_filter_min_max (GwyField *field,
                                   GwyNield *kernel,
                                   GwyMinMaxFilterType filtertype,
                                   gint col,
                                   gint row,
                                   gint width,
                                   gint height);

Applies a morphological operation with a flat structuring element to a part of a data field.

Morphological operations with flat structuring elements can be expressed using minimum (erosion) and maximum (dilation) filters that are the basic operations this function can perform.

The kernel field is a mask that defines the shape of the flat structuring element. It is reflected for all maximum operations (dilation). For symmetrical kernels this does not matter. You can use `gwy_field_elliptic_area_fill()` to create a true circular (or elliptical) kernel.

The kernel is implicitly centered, i.e. it will be applied symmetrically to avoid unexpected data movement. Even-sized kernels (generally not recommended) will extend farther towards the top left image corner for minimum (erosion) and towards the bottom right corner for maximum (dilation) operations due to the reflection. If you need off-center structuring elements you can add empty rows or columns to one side of the kernel to counteract the symmetrisation.

The operation is linear-time in kernel size for any convex kernel. Note `gwy_field_area_filter_minimum()` and `gwy_field_area_filter_maximum()`, which are limited to square structuring elements, are much faster for large sizes of the squares.

The exterior is always handled as `GWY_EXTERIOR_BORDER`. For most reasonable kernels, it makes no difference, and the result is the same as if there was no exterior. However, for odd-shaped, non-convex kernels, there is a difference. For example, near image boundaries, such kernel can intersect with the image in such a way that all its pixels lie outside the image. The exterior then still gives a well-defined value.

#### Parameters

field | A data field to apply the filter to. |
kernel | Number field defining the flat structuring element. It must be non-empty. |
filtertype | The type of filter to apply. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |

### gwy_field_area_filter_disc_asf()

    void
    gwy_field_area_filter_disc_asf (GwyField *field,
                                    gint radius,
                                    gboolean closing,
                                    gint col,
                                    gint row,
                                    gint width,
                                    gint height);

Applies an alternating sequential morphological filter with a flat disc structuring element to a part of a data field.

Alternating sequential filter is a filter consisting of repeated opening and closing (or closing and opening) with progressively larger structuring elements. This function performs such filtering for sequence of structuring elements consisting of true Euclidean discs with increasing radii. The largest disc in the sequence fits into a (2`size` + 1) × (2`size` + 1) square.

#### Parameters

field | A data field to apply the filter to. |
radius | Maximum radius of the circular structuring element, in pixels. For radius 0 and smaller the filter is no-op. |
closing | `TRUE` requests an opening-closing filter (i.e. ending with closing), `FALSE` requests a closing-opening filter (i.e. ending with opening). |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |

### gwy_nield_filter_min_max()

    void
    gwy_nield_filter_min_max (GwyNield *nield,
                              GwyNield *kernel,
                              GwyMinMaxFilterType filtertype);

Applies a morphological operation with a flat structuring element to a number field.

See `gwy_field_area_filter_min_max()` for more details on kernels and exterior handling.

The minimum and maximum filters are executed on the `nield` content as-is. Although it can be occasionaly useful to do so with number fields containing aribrary integers, the typical use of this function is as a binary image morphological operation. In such case first flatten the input to 0 and 1 with `gwy_nield_flatten()`.

#### Parameters

nield | A number field to apply the filter to. |
kernel | Number field defining the flat structuring element. It must be non-empty. |
filtertype | The type of filter to apply. The `GWY_MIN_MAX_FILTER_NORMALIZATION` filter is not valid for number fields. |

### gwy_nield_area_filter_min_max()

    void
    gwy_nield_area_filter_min_max (GwyNield *nield,
                                   GwyNield *kernel,
                                   GwyMinMaxFilterType filtertype,
                                   gint col,
                                   gint row,
                                   gint width,
                                   gint height);

Applies a morphological operation with a flat structuring element to a part of a number field.

See `gwy_field_area_filter_min_max()` for more details on kernels and exterior handling.

The minimum and maximum filters are executed on the `nield` content as-is. Although it can be occasionaly useful to do so with number fields containing aribrary integers, the typical use of this function is as a binary image morphological operation. In such case first flatten the input to 0 and 1 with `gwy_nield_flatten()`.

#### Parameters

nield | A number field to apply the filter to. |
kernel | Number field defining the flat structuring element. It must be non-empty. |
filtertype | The type of filter to apply. The `GWY_MIN_MAX_FILTER_NORMALIZATION` filter is not valid for number fields. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |

### gwy_nield_area_filter_disc_asf()

    void
    gwy_nield_area_filter_disc_asf (GwyNield *nield,
                                    gint radius,
                                    gboolean closing,
                                    gint col,
                                    gint row,
                                    gint width,
                                    gint height);

Applies an alternating sequential morphological filter with a flat disc structuring element to a part of a number field.

Alternating sequential filter is a filter consisting of repeated opening and closing (or closing and opening) with progressively larger structuring elements. This function performs such filtering for sequence of structuring elements consisting of true Euclidean discs with increasing radii. The largest disc in the sequence fits into a (2`size` + 1) × (2`size` + 1) square.

The opening and closing filters are executed on the `nield` content as-is. Although it can be occasionaly useful to do so with number fields containing aribrary integers, the typical use of this function is as a binary image morphological operation. In such case first flatten the input to 0 and 1 with `gwy_nield_flatten()`.

#### Parameters

nield | A number field to apply the filter to. |
radius | Maximum radius of the circular structuring element, in pixels. For radius 0 and smaller the filter is no-op. |
closing | `TRUE` requests an opening-closing filter (i.e. ending with closing), `FALSE` requests a closing-opening filter (i.e. ending with opening). |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |

### gwy_field_area_filter_kth_rank()

    gboolean
    gwy_field_area_filter_kth_rank (GwyField *field,
                                    GwyNield *kernel,
                                    gint col,
                                    gint row,
                                    gint width,
                                    gint height,
                                    gint k,
                                    GwySetFractionFunc set_fraction);

Applies a `k` -th rank filter to a part of a data field.

Pass half the number of non-zero values in `kernel` as `k` for a median filter.

The kernel field is a mask that defines the shape of the kernel. You can use `gwy_nield_elliptic_area_fill()` to create a true circular (or elliptical) kernel. The kernel field must contain at least `k` +1 pixels with positive values.

The kernel is implicitly centered, i.e. it will be applied symmetrically to avoid unexpected data movement.

The exterior is always handled as `GWY_EXTERIOR_BORDER`. Considering exterior pixels ensures that even close to image edges, there are always the same number of values for the `k` -th rank calculation. It also makes the result well-defined for odd-shaped, non-convex kernels, which can intersect with the image in such a way that all its pixels lie outside the image. However, it increases the weight of boundary values close to image edges.

If the operation is aborted the contents of `field` is untouched.

#### Parameters

field | A data field to apply the filter to. |
kernel | Number field defining the kernel shape. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |
k | Rank of the value to store as the output (from lowest to highest). |
set_fraction | Function that sets fraction to output (or `NULL`). | [scope call][nullable]

#### Returns

`TRUE` if the operation was not aborted via `set_fraction` returning `FALSE`; `FALSE` if it was aborted.

### gwy_line_part_filter_kth_rank()

    void
    gwy_line_part_filter_kth_rank (GwyLine *line,
                                   gint klen,
                                   gint pos,
                                   gint len,
                                   gint k);

Applies a `k` -th rank filter to a part of a data line.

The exterior is always handled as `GWY_EXTERIOR_BORDER`.

#### Parameters

line | A data line. |
klen | Kernel size. The kernel is symmetrical segment of `klen` pixels. |
pos | Index where to start. |
len | Length of the segment. |
k | Rank of the value to store as the output (from lowest to highest). It must be between 0 and `klen` -1 (inclusive). |

### gwy_field_area_filter_trimmed_mean()

    gboolean
    gwy_field_area_filter_trimmed_mean (GwyField *field,
                                        GwyNield *kernel,
                                        gint col,
                                        gint row,
                                        gint width,
                                        gint height,
                                        gint nlowest,
                                        gint nhighest,
                                        GwySetFractionFunc set_fraction);

Applies a trimmed mean filter to a part of a data field.

At least one value must remain after the trimming, i.e. `nlowest` + `nhighest` must be smaller than the number of non-zero values in `kernel` . Usually one passes the same number as both `nlowest` and `nhighest` , but it is not a requirement.

The kernel field is a mask that defines the shape of the kernel. You can use `gwy_field_elliptic_area_fill()` to create a true circular (or elliptical) kernel. The kernel field must contain at least `nlowest` +`nhighest` +1 pixels with positive values.

The kernel is implicitly centered, i.e. it will be applied symmetrically to avoid unexpected data movement. Even-sized kernels (generally not recommended) will extend farther towards the top left image corner for minimum (erosion) and towards the bottom right corner for maximum (dilation) operations due to the reflection. If you need off-center structuring elements you can add empty rows or columns to one side of the kernel to counteract the symmetrisation.

The exterior is always handled as `GWY_EXTERIOR_BORDER`. Considering exterior pixels ensures that even close to image edges, there are always the same number of values for the omission of `nlowest` and `nhighest` . It also makes the result well-defined for odd-shaped, non-convex kernels, which can intersect with the image in such a way that all its pixels lie outside the image. However, it increases the weight of boundary values close to image edges.

If the operation is aborted the contents of `field` is untouched.

#### Parameters

field | A data field to apply the filter to. |
kernel | Number field defining the kernel shape. |
col | Upper-left column coordinate. |
row | Upper-left row coordinate. |
width | Area width (number of columns). |
height | Area height (number of rows). |
nlowest | The number of lowest values to discard. |
nhighest | The number of highest values to discard. |
set_fraction | Function that sets fraction to output (or `NULL`). | [scope call][nullable]

#### Returns

`TRUE` if the operation was not aborted via `set_fraction` returning `FALSE`; `FALSE` if it was aborted.

### gwy_field_filter_rms()

    void
    gwy_field_filter_rms (GwyField *field,
                          GwyField *target,
                          gint size);

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

RMS filter computes root mean square in given area.

#### Parameters

field | A data field to apply RMS filter to. |
target | A data field to put the shade to. It will be resized to match `field` . It can be `field` itself. |
size | Area size. |

### gwy_field_filter_canny()

    void
    gwy_field_filter_canny (GwyField *field,
                            GwyField *target,
                            gdouble threshold);

Filters a data field with the Canny edge detector filter.

#### Parameters

field | A data field to apply the filter to. |
target | A data field to put the result to. It can be `field` itself. It will be resized to match `field` . |
threshold | Slope detection threshold (range 0..1). |

### gwy_field_shade()

    void
    gwy_field_shade (GwyField *field,
                     GwyField *target,
                     gdouble theta,
                     gdouble phi);

Shades a data field.

#### Parameters

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

### gwy_field_filter_harris()

    void
    gwy_field_filter_harris (GwyField *x_gradient,
                             GwyField *y_gradient,
                             GwyField *result,
                             gint neighbourhood,
                             gdouble alpha);

Applies Harris corner detection filter to a pair of gradient data fields.

All passed data field must have the same size.

#### Parameters

x_gradient | Data field with pre-calculated horizontal derivative. |
y_gradient | Data field with pre-calculated vertical derivative. |
result | Data field for the result. |
neighbourhood | Neighbourhood size. |
alpha | Sensitivity parameter (the squared trace is multiplied by it). |

### gwy_field_deconvolve_regularized()

    void
    gwy_field_deconvolve_regularized (GwyField *field,
                                      GwyField *operand,
                                      GwyField *out,
                                      gdouble sigma);

Performs deconvolution of a data field using a simple regularization.

The operation can be used to deblur an image or conversely recover the point spread function from ideal response image.

Convolving the result with the operand using `gwy_field_area_ext_convolve()` with `as_integral` =`TRUE` will recover (approximately) the image. This means the deconvolution assumes continous convolution, not discrete sums. Note that for the latter case this means the point spread function will be centered in `out` .

For recovery of transfer function, `field` and `operand` should be windowed beforehand if they are not periodic.

#### Parameters

field | A data field. |
operand | One of the factors entering the convolution resulting in `field` . It must have the same dimensions as `field` and it is assumed it has also the same physical size. |
out | Data field where to put the result into. It will be resized to match `field` . It can also be `field` itself. |
sigma | Regularization parameter. |

### gwy_field_deconvolve_psf_leastsq()

    void
    gwy_field_deconvolve_psf_leastsq (GwyField *field,
                                      GwyField *operand,
                                      GwyField *out,
                                      gdouble sigma,
                                      gint border);

Performs reconstruction of transfer function from convolved and ideal sharp images.

The transfer function is reconstructed by solving the corresponding least squares problem. This method is suitable when the dimensions of `out` are much smaller than the images.

Since the method accumulates errors close to edges, they can be removed within the procedure by reconstructing a slightly larger transfer function and then cutting the result. The extension is given by `border` , typical suitable values are 2 or 3.

Convolving the result with the operand using `gwy_field_area_ext_convolve()` with `as_integral` =`TRUE` will recover (approximately) the image. This means the deconvolution assumes continous convolution, not discrete sums. Note that for the latter case this means the point spread function will be centered in `out` .

Fields `field` and `operand` should be windowed beforehand if they are not periodic.

#### Parameters

field | A data field. |
operand | Ideal sharp measurement (before convolution). It must have the same dimensions as `field` and it is assumed it has also the same physical size. |
out | Output field for the transfer function. Its dimensions are preserved and determine the transfer function support. It must be smaller than half of `field` . |
sigma | Regularization parameter. |
border | Number of pixel to extend and cut off the transfer function. |

### gwy_field_find_regularization_sigma_for_psf()

    gdouble
    gwy_field_find_regularization_sigma_for_psf
                                   (GwyField *field,
                                    GwyField *ideal);

Finds regularization parameter for point spread function calculation using regularized deconvolution.

The estimated value should be suitable for reconstruction of the point spread function using `gwy_field_deconvolve_regularized()`. The estimate is only suitable for PSF, it does not work for image sharpening using a known PSF.

#### Parameters

field | A data field with convolved noisy data. |
ideal | A data field with ideal sharp data. |

#### Returns

Estimated regularization parameter.

### gwy_field_find_regularization_sigma_leastsq()

    gdouble
    gwy_field_find_regularization_sigma_leastsq
                                   (GwyField *field,
                                    GwyField *ideal,
                                    gint width,
                                    gint height,
                                    gint border);

Finds regularization parameter for point spread function calculation using least squares method.

The estimated value should be suitable for reconstruction of the point spread function using `gwy_field_deconvolve_psf_leastsq()`.

#### Parameters

field | A data field with convolved noisy data. |
ideal | A data field with ideal sharp data. |
width | Horizontal size of transfer function support. |
height | Vertical size of transfer function support. |
border | Number of pixel to extend and cut off the transfer function. |

#### Returns

Estimated regularization parameter.

## Types and Values

### enum GwyDerivativeFilterType

Type of simple predefined derivative-type filter type.

These filters are used with `gwy_field_derivative_filter()`. All can be used to calculate either discrete derivatives or approximate real derivatives, which take into account sampling steps.

The Laplacian filters have the following 3×3 kernel (corresponding to 1/3 weight):

    1
    2
    3
    1/20   1/5   1/20
    1/5   -1     1/5
    1/20   1/5   1/20

The Sobel derivative filters have the following 3×3 kernels:

    1
    2
    3
    4
    Horizontal                Vertical
    1/8   0   -1/8            1/8    1/4    1/8
    1/4   0   -1/4            0      0      0
    1/8   0   -1/8           -1/8   -1/4   -1/4

The Prewitt derivative filters have the following 3×3 kernels:

    1
    2
    3
    4
    Horizontal                Vertical
    1/6   0   -1/6            1/6    1/6    1/6
    1/6   0   -1/6            0      0      0
    1/6   0   -1/6           -1/6   -1/6   -1/6

The Scharr derivative filters have the following 3×3 kernels:

    1
    2
    3
    4
    Horizontal                Vertical
    3/32   0   -3/32          3/32   5/16   3/32
    5/16   0   -5/16          0      0      0
    3/32   0   -3/32         -3/32  -5/16  -3/32

The XY derivative filter has the following 3×3 kernels:

    1
    2
    3
    -1/4   0    1/4
     0     0    0
     1/4   0   -1/4

The smooth (or slightly smoother) second derivative filters have the following 3×3 kernels:

    1
    2
    3
    4
    Horizontal                Vertical
    1/4   -1/2   1/4          1/4    1/2    1/4
    1/2   -1     1/2         -1/2   -1     -1/2
    1/4   -1/2   1/4          1/4    1/2    1/4

The absolute value of the derivative is calculated as hypotenuse of the derivatives calculated by the corresponding directional filters.

#### Members

GWY_DERIVATIVE_FILTER_XDER | Simple symmetrical horizontal derivative (except edges, where it is one-sided). |
GWY_DERIVATIVE_FILTER_YDER | Simple symmetrical vertical derivative (except edges, where it is one-sided). |
GWY_DERIVATIVE_FILTER_DER | Simple total gradient (except edges, where it is one-sided). |
GWY_DERIVATIVE_FILTER_HPREWITT | Horizontal Prewitt derivative filter. |
GWY_DERIVATIVE_FILTER_VPREWITT | Vertical Prewitt derivative filter. |
GWY_DERIVATIVE_FILTER_PREWITT | Total Prewitt filter (hypotenuse of horizontal and vertical). |
GWY_DERIVATIVE_FILTER_HSOBEL | Horizontal Sobel derivative filter. |
GWY_DERIVATIVE_FILTER_VSOBEL | Vertical Sobel derivative filter. |
GWY_DERIVATIVE_FILTER_SOBEL | Total Sobel filter (hypotenuse of horizontal and vertical). |
GWY_DERIVATIVE_FILTER_HSCHARR | Horizontal Scharr derivative filter. |
GWY_DERIVATIVE_FILTER_VSCHARR | Vertical Scharr derivative filter. |
GWY_DERIVATIVE_FILTER_SCHARR | Total Scharr filter (hypotenuse of horizontal and vertical). |
GWY_DERIVATIVE_FILTER_XDER2 | Simple symmetrical second horizontal derivative. |
GWY_DERIVATIVE_FILTER_YDER2 | Simple symmetrical second vertical derivative. |
GWY_DERIVATIVE_FILTER_XYDER | Simple symmetrical second horizontal derivative. |
GWY_DERIVATIVE_FILTER_SXDER2 | Smooth symmetrical second horizontal derivative. |
GWY_DERIVATIVE_FILTER_SYDER2 | Smooth symmetrical second vertical derivative. |
GWY_DERIVATIVE_FILTER_DET2DER | Determinant-of-Hessian second derviative filter. |
GWY_DERIVATIVE_FILTER_LAPLACE | Simple isotropic Laplacian filter. |

### enum GwyEnhanceFilterType

Type of simple predefined denoising filter type.

These filters are used with `gwy_field_enhance_filter()` and `gwy_field_area_enhance_filter()`.

The dechecker filter is a convolution filter with the following 5×5 kernel:

    1
    2
    3
    4
    5
    0        1/144   -1/72    1/144     0
    1/144   -1/18     1/9    -1/18      1/144
    -1/72     1/9      7/9     1/9      -1/72
    1/144   -1/18     1/9    -1/18      1/144
    0        1/144   -1/72    1/144     0

The Kuwahara filter works on blocks 5×5. In each such block the corner 3×3 sub-block with the lowest variance is chosen and its mean value is the filter result. Notably, the central 3×3 sub-block is not among the options. So, while the filter enhances edges, it does not preserve linear gradients and is susceptible to rounding errors when all the variances are equal.

Schulze Mean of Least Variance (MLV) edge-enhancing filter is an improved version of the Kuwahara filter. It considers all nine 3×3 sub-blocks.

#### Members

GWY_ENHANCE_FILTER_KUWAHARA | Kuwahara edge-preserving smoothing filter. |
GWY_ENHANCE_FILTER_MLV | Schulze Mean of Least Variance edge-enhancing filter. |
GWY_ENHANCE_FILTER_DECHECKER | Checker pattern suppression filter. |

### enum GwyMinMaxFilterType

Type of operation based on morphological filters with flat structuring elements.

#### Members

GWY_MIN_MAX_FILTER_MINIMUM | Minimum filter, i.e. the minimum of the surrounding values. Single-pixel minima will take reflected kernel shape. |
GWY_MIN_MAX_FILTER_EROSION | Morphological erosion filter. This is another name for `GWY_MIN_MAX_FILTER_MINIMUM` . |
GWY_MIN_MAX_FILTER_FROSION | Flipped morphological erosion filter. This is not a standard operation and exists for completness. Single-pixel minima will take direct kernel shape. |
GWY_MIN_MAX_FILTER_MAXIMUM | Maximum filter, i.e. the maximum of the surrounding values. Single-pixel maxima will take reflected kernel shape. |
GWY_MIN_MAX_FILTER_DILATION | Morphological dilation filter. Single-pixel maxima will take direct kernel shape. |
GWY_MIN_MAX_FILTER_OPENING | Morphological opening filter. |
GWY_MIN_MAX_FILTER_CLOSING | Morphological closing filter. |
GWY_MIN_MAX_FILTER_RANGE | Difference between maximum and minimum. |
GWY_MIN_MAX_FILTER_NORMALIZATION | Data value rescaled to the range between minimum and maximum. |