filters

filters — Convolution and other 2D data filters

Functions

void gwy_data_field_normalize ()
void gwy_data_field_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_convolve_1d ()
void gwy_data_field_area_convolve_1d ()
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_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_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_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 ()

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 first linear function to given range.

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

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

Parameters

data_field

A data field.

 

range

New data interval size.

 

offset

New data interval offset.

 

gwy_data_field_threshold ()

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

Tresholds values of a data field.

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

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.

 

hsize

Horizontal size of gathered area. The area is centered around each sample if hsize is odd, it extends one pixel more to the right if hsize is even.

 

vsize

Vertical size of gathered area. The area is centered around each sample if vsize is odd, it extends one pixel more down if vsize is even.

 

average

TRUE to divide resulting sums by the number of involved samples to get averages instead of sums.

 

col

Upper-left column coordinate.

 

row

Upper-left row coordinate.

 

width

Area width (number of columns).

 

height

Area height (number of rows).

 

gwy_data_field_convolve ()

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

Convolves a data field with given kernel.

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.

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_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_filter_median ()

void
gwy_data_field_filter_median (GwyDataField *data_field,
                              gint size);

Filters a data field with median filter.

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.

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 .

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 .

This method is a simple gwy_data_field_area_gather() wrapper.

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 calculated as the simple symmetrical differences (in physical units, not pixel-wise), 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-derivarive is to be stored, or NULL if you are only interested in the y-derivarive.

 

yder

Data field where the y-derivarive is to be stored, or NULL if you are only interested in the x-derivarive.

 

Since: 2.37


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

void
gwy_data_field_filter_minimum (GwyDataField *data_field,
                               gint size);

Filters a data field with minimum filter.

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.

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.

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.

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

Types and Values