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

filters (HEAD)

filters — Convolution and other 2D data filters

Functions

void	gwy_data_field_normalize ()
void	gwy_data_field_renormalize ()
void	gwy_data_field_area_renormalize ()
gint	gwy_data_field_threshold ()
gint	gwy_data_field_area_threshold ()
gint	gwy_data_field_clamp ()
gint	gwy_data_field_area_clamp ()
void	gwy_data_field_area_gather ()
void	gwy_data_field_convolve ()
void	gwy_data_field_area_convolve ()
void	gwy_data_field_fft_convolve ()
void	gwy_data_field_area_ext_convolve ()
void	gwy_data_field_convolve_1d ()
void	gwy_data_field_area_convolve_1d ()
void	gwy_data_field_area_ext_row_convolve ()
void	gwy_data_field_filter_median ()
void	gwy_data_field_area_filter_median ()
void	gwy_data_field_filter_mean ()
void	gwy_data_field_area_filter_mean ()
void	gwy_data_field_filter_conservative ()
void	gwy_data_field_area_filter_conservative ()
void	gwy_data_field_filter_laplacian ()
void	gwy_data_field_area_filter_laplacian ()
void	gwy_data_field_filter_laplacian_of_gaussians ()
void	gwy_data_field_area_filter_laplacian_of_gaussians ()
void	gwy_data_field_filter_sobel ()
void	gwy_data_field_area_filter_sobel ()
void	gwy_data_field_filter_sobel_total ()
void	gwy_data_field_filter_prewitt ()
void	gwy_data_field_area_filter_prewitt ()
void	gwy_data_field_filter_prewitt_total ()
void	gwy_data_field_filter_slope ()
void	gwy_data_field_filter_gauss_step ()
void	gwy_data_field_filter_dechecker ()
void	gwy_data_field_area_filter_dechecker ()
void	gwy_data_field_filter_gaussian ()
void	gwy_data_field_area_filter_gaussian ()
void	gwy_data_field_row_gaussian ()
void	gwy_data_field_column_gaussian ()
void	gwy_data_field_filter_minimum ()
void	gwy_data_field_area_filter_minimum ()
void	gwy_data_field_filter_maximum ()
void	gwy_data_field_area_filter_maximum ()
void	gwy_data_field_area_filter_min_max ()
void	gwy_data_field_area_filter_disc_asf ()
gboolean	gwy_data_field_area_filter_kth_rank ()
void	gwy_data_line_part_filter_kth_rank ()
gboolean	gwy_data_field_area_filter_trimmed_mean ()
void	gwy_data_field_filter_rms ()
void	gwy_data_field_area_filter_rms ()
void	gwy_data_field_filter_kuwahara ()
void	gwy_data_field_area_filter_kuwahara ()
void	gwy_data_field_filter_canny ()
void	gwy_data_field_shade ()
void	gwy_data_field_filter_harris ()
void	gwy_data_field_deconvolve_regularized ()
void	gwy_data_field_deconvolve_psf_leastsq ()
gdouble	gwy_data_field_find_regularization_sigma_for_psf ()
gdouble	gwy_data_field_find_regularization_sigma_leastsq ()

Includes

#include <libprocess/gwyprocess.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 GwyDataField methods.

Functions

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.

Parameters

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

Parameters

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

gwy_data_field_area_renormalize ()

void
gwy_data_field_area_renormalize (GwyDataField *data_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 zero, this method is equivalent to gwy_data_field_fill(data_field , offset ).

Parameters

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

Since: 2.45

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

Parameters

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

Parameters

data_field	A data field.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
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.

Parameters

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.

Parameters

data_field	A data field.
col	Upper-left column coordinate.
row	Upper-left row coordinate.
width	Area width (number of columns).
height	Area height (number of rows).
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.

Parameters

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

void
gwy_data_field_convolve (GwyDataField *data_field,
                         GwyDataField *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

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.

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

Parameters

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

void
gwy_data_field_fft_convolve (GwyDataField *data_field,
                             GwyDataField *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 data_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_data_field_2dfft_dehumanize() to transform a centered kernel.

Parameters

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

Since: 2.54

gwy_data_field_area_ext_convolve ()

void
gwy_data_field_area_ext_convolve (GwyDataField *field,
                                  guint col,
                                  guint row,
                                  guint width,
                                  guint height,
                                  GwyDataField *target,
                                  GwyDataField *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_data_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. dx dy 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.

Since: 2.49

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.

Parameters

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.

Parameters

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

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

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

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_data_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. dx 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.

Since: 2.49

gwy_data_field_filter_median ()

void
gwy_data_field_filter_median (GwyDataField *data_field,
                              gint size);

Filters a data field with median filter.

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

Parameters

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.

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

Parameters

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 .

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

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

void
gwy_data_field_filter_laplacian_of_gaussians
                               (GwyDataField *data_field);

Filters a data field with Laplacian of Gaussians filter.

Parameters

data_field

A data field to apply the filter to.

Since: 2.23

gwy_data_field_area_filter_laplacian_of_gaussians ()

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

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

Parameters

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

gwy_data_field_filter_sobel ()

void
gwy_data_field_filter_sobel (GwyDataField *data_field,
                             GwyOrientation orientation);

Filters a data field with a directional Sobel filter.

Parameters

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 a directional Sobel filter.

Parameters

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

void
gwy_data_field_filter_sobel_total (GwyDataField *data_field);

Filters a data field with total Sobel filter.

Parameters

data_field

A data field to apply the filter to.

Since: 2.31

gwy_data_field_filter_prewitt ()

void
gwy_data_field_filter_prewitt (GwyDataField *data_field,
                               GwyOrientation orientation);

Filters a data field with Prewitt filter.

Parameters

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 a directional Prewitt filter.

Parameters

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

void
gwy_data_field_filter_prewitt_total (GwyDataField *data_field);

Filters a data field with total Prewitt filter.

Parameters

data_field

A data field to apply the filter to.

Since: 2.31

gwy_data_field_filter_slope ()

void
gwy_data_field_filter_slope (GwyDataField *data_field,
                             GwyDataField *xder,
                             GwyDataField *yder);

Calculates x and y derivaties for an entire field.

The derivatives are in physical units (not pixel-wise) and calculated from simple symmetrical differences, except at the edges where the differences are one-sided.

Parameters

data_field	A data field to apply the filter to.
xder	Data field where the x-derivative is to be stored, or `NULL` if you are only interested in the y-derivative. It will be resized to match `data_field` .
yder	Data field where the y-derivative is to be stored, or `NULL` if you are only interested in the x-derivative. It will be resized to match `data_field` .

Since: 2.37

gwy_data_field_filter_gauss_step ()

void
gwy_data_field_filter_gauss_step (GwyDataField *data_field,
                                  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

data_field	A data field to apply the filter to.
sigma	Gaussian filter width (in pixels).

Since: 2.54

gwy_data_field_filter_dechecker ()

void
gwy_data_field_filter_dechecker (GwyDataField *data_field);

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

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

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

Since: 2.54

gwy_data_field_column_gaussian ()

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

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

Since: 2.54

gwy_data_field_filter_minimum ()

void
gwy_data_field_filter_minimum (GwyDataField *data_field,
                               gint size);

Filters a data field with minimum filter.

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

Parameters

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.

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

Parameters

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.

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

Parameters

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.

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

Parameters

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

void
gwy_data_field_area_filter_min_max (GwyDataField *data_field,
                                    GwyDataField *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_data_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_data_field_area_filter_minimum() and gwy_data_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_EXTEND.

Parameters

data_field	A data field to apply the filter to.
kernel	Data field defining the flat structuring element.
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).

Since: 2.43

gwy_data_field_area_filter_disc_asf ()

void
gwy_data_field_area_filter_disc_asf (GwyDataField *data_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 (2size + 1) × (2size + 1) square.

Parameters

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

Since: 2.43

gwy_data_field_area_filter_kth_rank ()

gboolean
gwy_data_field_area_filter_kth_rank (GwyDataField *data_field,
                                     GwyDataField *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_data_field_elliptic_area_fill() to create a true circular (or elliptical) kernel. The kernel must be non-empty.

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

If the operation is aborted the contents of data_field is untouched.

Parameters

data_field	A data field to apply the filter to.
kernel	Data 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`).

Returns

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

Since: 2.51

gwy_data_line_part_filter_kth_rank ()

void
gwy_data_line_part_filter_kth_rank (GwyDataLine *data_line,
                                    gint klen,
                                    gint from,
                                    gint to,
                                    gint k);

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

The exterior is always handled as GWY_EXTERIOR_BORDER_EXTEND.

Parameters

data_line	A data line.
klen	Kernel size. The kernel is symmetrical segment of `klen` pixels.
from	The index in `data_line` to start from (inclusive).
to	The index in `data_line` to stop (noninclusive).
k	Rank of the value to store as the output (from lowest to highest). It must be between 0 and `klen` -1 (inclusive).

Since: 2.63

gwy_data_field_area_filter_trimmed_mean ()

gboolean
gwy_data_field_area_filter_trimmed_mean
                               (GwyDataField *data_field,
                                GwyDataField *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_data_field_elliptic_area_fill() to create a true circular (or elliptical) kernel. The kernel must be non-empty.

The exterior is always handled as GWY_EXTERIOR_BORDER_EXTEND.

If the operation is aborted the contents of data_field is untouched.

Parameters

data_field	A data field to apply the filter to.
kernel	Data 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`).

Returns

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

Since: 2.53

gwy_data_field_filter_rms ()

void
gwy_data_field_filter_rms (GwyDataField *data_field,
                           gint size);

Filters a data field with RMS filter.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

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 paramter (the squared trace is multiplied by it).

gwy_data_field_deconvolve_regularized ()

void
gwy_data_field_deconvolve_regularized (GwyDataField *dfield,
                                       GwyDataField *operand,
                                       GwyDataField *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_data_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, dfield and operand should be windowed beforehand if they are not periodic.

Parameters

dfield	A data field.
operand	One of the factors entering the convolution resulting in `dfield` . It must have the same dimensions as `dfield` 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 `dfield` . It can also be `dfield` itself.
sigma	Regularization parameter.

Since: 2.51

gwy_data_field_deconvolve_psf_leastsq ()

void
gwy_data_field_deconvolve_psf_leastsq (GwyDataField *dfield,
                                       GwyDataField *operand,
                                       GwyDataField *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.

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

Parameters

dfield	A data field.
operand	Ideal sharp measurement (before convolution). It must have the same dimensions as `dfield` 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 `dfield` .
sigma	Regularization parameter.
border	Number of pixel to extend and cut off the transfer function.

Since: 2.52

gwy_data_field_find_regularization_sigma_for_psf ()

gdouble
gwy_data_field_find_regularization_sigma_for_psf
                               (GwyDataField *dfield,
                                GwyDataField *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_data_field_deconvolve_regularized(). The estimate is only suitable for PSF, it does not work for image sharpening using a known PSF.

Parameters

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

Returns

Estimated regularization parameter.

Since: 2.51

gwy_data_field_find_regularization_sigma_leastsq ()

gdouble
gwy_data_field_find_regularization_sigma_leastsq
                               (GwyDataField *dfield,
                                GwyDataField *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_data_field_deconvolve_psf_leastsq().

Parameters

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

Since: 2.52