## interpolation

interpolation — General interpolation functions

## Synopsis

    #include <libprocess/gwyprocess.h>

    gdouble             gwy_interpolation_get_dval          (gdouble x,
                                                             gdouble x1_,
                                                             gdouble y1_,
                                                             gdouble x2_,
                                                             gdouble y2_,
                                                             GwyInterpolationType interpolation);
    gdouble             gwy_interpolation_get_dval_of_equidists
                                                            (gdouble x,
                                                             gdouble *data,
                                                             GwyInterpolationType interpolation);
    gdouble             gwy_interpolation_interpolate_1d    (gdouble x,
                                                             const gdouble *coeff,
                                                             GwyInterpolationType interpolation);
    gdouble             gwy_interpolation_interpolate_2d    (gdouble x,
                                                             gdouble y,
                                                             gint rowstride,
                                                             const gdouble *coeff,
                                                             GwyInterpolationType interpolation);
    gboolean            gwy_interpolation_has_interpolating_basis
                                                            (GwyInterpolationType interpolation);
    gint                gwy_interpolation_get_support_size  (GwyInterpolationType interpolation);
    void                gwy_interpolation_resolve_coeffs_1d (gint n,
                                                             gdouble *data,
                                                             GwyInterpolationType interpolation);
    void                gwy_interpolation_resolve_coeffs_2d (gint width,
                                                             gint height,
                                                             gint rowstride,
                                                             gdouble *data,
                                                             GwyInterpolationType interpolation);
    void                gwy_interpolation_resample_block_1d (gint length,
                                                             gdouble *data,
                                                             gint newlength,
                                                             gdouble *newdata,
                                                             GwyInterpolationType interpolation,
                                                             gboolean preserve);
    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);
    void                gwy_interpolation_shift_block_1d    (gint length,
                                                             gdouble *data,
                                                             gdouble offset,
                                                             gdouble *newdata,
                                                             GwyInterpolationType interpolation,
                                                             GwyExteriorType exterior,
                                                             gdouble fill_value,
                                                             gboolean preserve);

## 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 GwyDataField or GwyDataLine methods instead of these functions.

## Details

### gwy_interpolation_get_dval ()

    gdouble             gwy_interpolation_get_dval          (gdouble x,
                                                             gdouble x1_,
                                                             gdouble y1_,
                                                             gdouble x2_,
                                                             gdouble y2_,
                                                             GwyInterpolationType interpolation);

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

`x` : | requested value coordinate
`x1_` : | x coordinate of first value
`y1_` : | y coordinate of first value
`x2_` : | x coordinate of second value
`y2_` : | 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,
                                                             gdouble *data,
                                                             GwyInterpolationType interpolation);

Computes interpolated value from 2 or 4 equidistant values.

For `GWY_INTERPOLATION_NONE` no `data` value is actually used, and zero is returned.

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.

`x` : | Possibily noninteger position in `data` to get value at.
`data` : | Array of 4 values to interpolate between (see below).
`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 signle data point in one dimension.

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

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

Since 2.2

### gwy_interpolation_interpolate_2d ()

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

Interpolates a signle data point in two dimensions.

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

Since 2.2

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

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

Since 2.2

### gwy_interpolation_get_support_size ()

    gint                gwy_interpolation_get_support_size  (GwyInterpolationType interpolation);

Obtains the basis support size for an interpolation type.

`interpolation` : | Interpolation type.
Returns : | The length of the support interval of the interpolation basis.

Since 2.2

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

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

Since 2.2

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

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

Since 2.2

### 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_data_line_new_resampled()` provide more convenient interface.

`length` : | Data block length.
`data` : | Data block to resample.
`newlength` : | Requested length after resampling.
`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.

Since 2.2

### 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_data_field_new_resampled()` provide more convenient interface.

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

Since 2.2

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

`length` : | Data block length.
`data` : | Data block to shift.
`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.
`interpolation` : | Interpolation type to use.
`exterior` : | Exterior pixels handling.
`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.

Since 2.2