interpolation: Gwyddion Library Reference Manual

interpolation

interpolation — General interpolation functions

Functions

gdouble	gwy_interpolation_get_dval ()
gdouble	gwy_interpolation_get_dval_of_equidists ()
gdouble	gwy_interpolation_interpolate_1d ()
gdouble	gwy_interpolation_interpolate_2d ()
gboolean	gwy_interpolation_has_interpolating_basis ()
gint	gwy_interpolation_get_support_size ()
void	gwy_interpolation_resolve_coeffs_1d ()
void	gwy_interpolation_resolve_coeffs_2d ()
void	gwy_interpolation_resample_block_1d ()
void	gwy_interpolation_resample_block_2d ()
void	gwy_interpolation_shift_block_1d ()

Types and Values

enum	GwyInterpolationType
enum	GwyExteriorType

Includes

#include <libgwyddion/gwyddion.h>

Description

Data interpolation is usually pixel-like in Gwyddion, not function-like. That means the contribution of individual data saples is preserved on scaling (the area that “belongs” to all values is the same, it is not reduced to half for edge pixels).

Most of the functions listed here are quite low-level and typically one would use GwyField or GwyLine methods instead of these functions.

Functions

gwy_interpolation_get_dval()

gdouble
gwy_interpolation_get_dval (gdouble x,
                            gdouble xa,
                            gdouble ya,
                            gdouble xb,
                            gdouble yb,
                            GwyInterpolationType interpolation);

Calculates linear interpolation between two points.

This function uses two-point interpolation methods to get interpolated value between two arbitrary data points.

Parameters

x	requested value coordinate
xa	x coordinate of first value
ya	y coordinate of first value
xb	x coordinate of second value
yb	y coordinate of second value
interpolation	interpolation type

Returns

Interpolated value.

gwy_interpolation_get_dval_of_equidists()

gdouble
gwy_interpolation_get_dval_of_equidists
                               (gdouble x,
                                const gdouble *data,
                                GwyInterpolationType interpolation);

Computes interpolated value from 2 or 4 equidistant values.

For GWY_INTERPOLATION_ROUND or GWY_INTERPOLATION_LINEAR it is enough to set middle two data values, that to use data in format {0, data[i], data[i+1], 0} and function computes value at data[i+x] (the outer values are not used).

For four value interpolations you have to prepare data as {data[i-1], data[i], data[i+1], data[i+2]} and function again returns value at data[i+x].

Interpolation with non-interpolating bases are silently replaced with an interpolating function with the same support size. See gwy_interpolation_interpolate_1d() for a function interpolating from interpolation coefficients.

Parameters

x	Possibily noninteger position in `data` to get value at.
data	Array of 4 values to interpolate between (see below).	[array fixed-size=4]
interpolation	Interpolation type to use.

Returns

Interpolated value.

gwy_interpolation_interpolate_1d()

gdouble
gwy_interpolation_interpolate_1d (gdouble x,
                                  const gdouble *coeff,
                                  GwyInterpolationType interpolation);

Interpolates a single data point in one dimension.

The interpolation basis support size can be obtained generically with gwy_interpolation_get_support_size().

Parameters

x	Position in interval [0,1) to get value at.
coeff	Array of support-length size with interpolation coefficients (that are equal to data values for an interpolating basis).
interpolation	Interpolation type to use.

Returns

Interpolated value.

gwy_interpolation_interpolate_2d()

gdouble
gwy_interpolation_interpolate_2d (gdouble x,
                                  gdouble y,
                                  gint rowstride,
                                  const gdouble *coeff,
                                  GwyInterpolationType interpolation);

Interpolates a single data point in two dimensions.

Parameters

x	X-position in interval [0,1) to get value at.
y	Y-position in interval [0,1) to get value at.
rowstride	Row stride of `coeff` .
coeff	Array of support-length-squared size with interpolation coefficients (that are equal to data values for an interpolating basis).
interpolation	Interpolation type to use.

Returns

Interpolated value.

gwy_interpolation_has_interpolating_basis()

gboolean
gwy_interpolation_has_interpolating_basis
                               (GwyInterpolationType interpolation);

Obtains the interpolating basis property of an inteprolation type.

Interpolation types with inteprolating basis directly use data values for interpolation. For these types gwy_interpolation_resolve_coeffs_1d() and gwy_interpolation_resolve_coeffs_2d() are no-op.

Generalized interpolation types (with non-interpolation basis) require to preprocess the data values to obtain interpolation coefficients first. On the ohter hand they typically offer much higher interpolation quality.

Parameters

interpolation

Interpolation type.

Returns

TRUE if the inteprolation type has interpolating basis, FALSE if data values cannot be directly used for interpolation of this type.

gwy_interpolation_get_support_size()

gint
gwy_interpolation_get_support_size (GwyInterpolationType interpolation);

Obtains the basis support size for an interpolation type.

Parameters

interpolation

Interpolation type.

Returns

The length of the support interval of the interpolation basis.

gwy_interpolation_resolve_coeffs_1d()

void
gwy_interpolation_resolve_coeffs_1d (gint n,
                                     gdouble *data,
                                     GwyInterpolationType interpolation);

Transforms data values in a one-dimensional array to interpolation coefficients.

This function is no-op for interpolation types with finite-support interpolating function. Therefore you can also omit it and use the data array directly for these interpolation types.

Parameters

n	Number of points in `data` .
data	An array of data values. It will be rewritten with the coefficients.	[array length=n]
interpolation	Interpolation type to prepare `data` for.

gwy_interpolation_resolve_coeffs_2d()

void
gwy_interpolation_resolve_coeffs_2d (gint width,
                                     gint height,
                                     gint rowstride,
                                     gdouble *data,
                                     GwyInterpolationType interpolation);

Transforms data values in a two-dimensional array to interpolation coefficients.

This function is no-op for interpolation types with finite-support interpolating function. Therefore you can also omit it and use the data array directly for these interpolation types.

Parameters

width	Number of columns in `data` .
height	Number of rows in `data` .
rowstride	Total row length (including `width` ).
data	An array of data values. It will be rewritten with the coefficients.
interpolation	Interpolation type to prepare `data` for.

gwy_interpolation_resample_block_1d()

void
gwy_interpolation_resample_block_1d (gint length,
                                     gdouble *data,
                                     gint newlength,
                                     gdouble *newdata,
                                     GwyInterpolationType interpolation,
                                     gboolean preserve);

Resamples a one-dimensional data array.

This is a primitive operation, in most cases methods such as gwy_line_new_resampled() provide more convenient interface.

Parameters

length	Data block length.
data	Data block to resample.	[array length=length]
newlength	Requested length after resampling.
newdata	Array to put the resampled data to.	[out][array]
interpolation	Interpolation type to use.
preserve	`TRUE` to preserve the content of `data` , `FALSE` to permit its overwriting with temporary data.

gwy_interpolation_resample_block_2d()

void
gwy_interpolation_resample_block_2d (gint width,
                                     gint height,
                                     gint rowstride,
                                     gdouble *data,
                                     gint newwidth,
                                     gint newheight,
                                     gint newrowstride,
                                     gdouble *newdata,
                                     GwyInterpolationType interpolation,
                                     gboolean preserve);

Resamples a two-dimensional data array.

This is a primitive operation, in most cases methods such as gwy_field_new_resampled() provide more convenient interface.

Parameters

width	Number of columns in `data` .
height	Number of rows in `data` .
rowstride	Total row length (including `width` ).
data	Data block to resample.
newwidth	Requested number of columns after resampling.
newheight	Requested number of rows after resampling.
newrowstride	Requested total row length after resampling (including `newwidth` ).
newdata	Array to put the resampled data to.
interpolation	Interpolation type to use.
preserve	`TRUE` to preserve the content of `data` , `FALSE` to permit its overwriting with temporary data.

gwy_interpolation_shift_block_1d()

void
gwy_interpolation_shift_block_1d (gint length,
                                  gdouble *data,
                                  gdouble offset,
                                  gdouble *newdata,
                                  GwyInterpolationType interpolation,
                                  GwyExteriorType exterior,
                                  gdouble fill_value,
                                  gboolean preserve);

Shifts a one-dimensional data block by a possibly non-integer offset.

The GWY_EXTERIOR_LAPLACE exterior type cannot be used with this function.

Parameters

length	Data block length.
data	Data block to shift.	[array length=length]
offset	The shift, in corrective sense. Shift value of 1.0 means the zeroth value of `newdata` will be set to the first value of `data` .
newdata	Array to put the shifted data to.	[out][array length=length]
interpolation	Interpolation type to use.
exterior	Exterior pixels handling. Only elementary exteriors like border, mirror or periodic are currently available.
fill_value	The value to use with `GWY_EXTERIOR_FIXED_VALUE` .
preserve	`TRUE` to preserve the content of `data` , `FALSE` to permit its overwriting with temporary data.

Types and Values

enum GwyInterpolationType

Interpolation types.

Members

GWY_INTERPOLATION_ROUND	Round interpolation (more precisely symmetric nearest neighbour interpolation).
GWY_INTERPOLATION_LINEAR	Linear interpolation.
GWY_INTERPOLATION_KEY	Cubic Key's interpolation (with a=-1/2).
GWY_INTERPOLATION_BSPLINE	B-spline interpolation.
GWY_INTERPOLATION_OMOMS	Omoms interpolation.
GWY_INTERPOLATION_NNA	Nearest neighbour approximation.
GWY_INTERPOLATION_SCHAUM	Cubic Schaum interpolation.

enum GwyExteriorType

Methods to handle pixels outside data.

Many methods currently use a fixed metod of handling of exterior pixels, for example area calculation uses extension (border and mirror coincide), convolution uses mirror extension, rotation fills exterior with a fixed value.

Members

GWY_EXTERIOR_UNDEFINED	The values corresponding to or calculated from exterior data values are undefined, they may be left unset or set to bogus values. The caller must handle them itself afterwards, for instance by resizing the result to consist of valid data only.
GWY_EXTERIOR_BORDER	Values of exterior pixels are considered to be equal to the values of the nearest interior pixels.
GWY_EXTERIOR_MIRROR	The data is considered to be periodically repeated, with odd instances reflected (the total period is thus twice the size of the data).
GWY_EXTERIOR_PERIODIC	The data is considered to be periodically repeated.
GWY_EXTERIOR_FIXED_VALUE	Values of exterior pixels are considered to be all equal to a user-specified value.
GWY_EXTERIOR_LAPLACE	Values of exterior pixels are extended using Laplace interpolation (actually extrapolation) like `gwy_field_laplace_solve()`. Only some functions implement this method.
GWY_EXTERIOR_CONNECT