interpolation: Gwyddion Library Reference Manual

## interpolation interpolation — General interpolation functions |

## Functions

gdouble | gwy_interpolation_interpolate ()
gdouble | gwy_interpolation_interpolate_equidists ()
gdouble | gwy_interpolation_interpolate_1d ()
gdouble | gwy_interpolation_interpolate_2d ()
gboolean | gwy_interpolation_has_interpolating_basis ()
gint | gwy_interpolation_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_interpolate()

    gdouble
    gwy_interpolation_interpolate (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_interpolate_equidists()

    gdouble
    gwy_interpolation_interpolate_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_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_support_size()

    gint
    gwy_interpolation_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 | Values of exterior pixels are extended by connecting the opposite end in a somewhat smooth manner, implying periodicity. It is mainly a 1D method. The 2D variant simply applies it to rows and column separately, which is less useful. |