## inttrans

inttrans — FFT and other integral transforms

## Synopsis

    #include <libprocess/gwyprocess.h>

    gint                gwy_fft_find_nice_size              (gint size);
    void                gwy_data_line_fft                   (GwyDataLine *rsrc,
                                                             GwyDataLine *isrc,
                                                             GwyDataLine *rdest,
                                                             GwyDataLine *idest,
                                                             GwyWindowingType windowing,
                                                             GwyTransformDirection direction,
                                                             GwyInterpolationType interpolation,
                                                             gboolean preserverms,
                                                             gint level);
    void                gwy_data_line_part_fft              (GwyDataLine *rsrc,
                                                             GwyDataLine *isrc,
                                                             GwyDataLine *rdest,
                                                             GwyDataLine *idest,
                                                             gint from,
                                                             gint len,
                                                             GwyWindowingType windowing,
                                                             GwyTransformDirection direction,
                                                             GwyInterpolationType interpolation,
                                                             gboolean preserverms,
                                                             gint level);
    void                gwy_data_line_fft_raw               (GwyDataLine *rsrc,
                                                             GwyDataLine *isrc,
                                                             GwyDataLine *rdest,
                                                             GwyDataLine *idest,
                                                             GwyTransformDirection direction);
    void                gwy_data_field_1dfft                (GwyDataField *rin,
                                                             GwyDataField *iin,
                                                             GwyDataField *rout,
                                                             GwyDataField *iout,
                                                             GwyOrientation orientation,
                                                             GwyWindowingType windowing,
                                                             GwyTransformDirection direction,
                                                             GwyInterpolationType interpolation,
                                                             gboolean preserverms,
                                                             gint level);
    void                gwy_data_field_area_1dfft           (GwyDataField *rin,
                                                             GwyDataField *iin,
                                                             GwyDataField *rout,
                                                             GwyDataField *iout,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height,
                                                             GwyOrientation orientation,
                                                             GwyWindowingType windowing,
                                                             GwyTransformDirection direction,
                                                             GwyInterpolationType interpolation,
                                                             gboolean preserverms,
                                                             gint level);
    void                gwy_data_field_1dfft_raw            (GwyDataField *rin,
                                                             GwyDataField *iin,
                                                             GwyDataField *rout,
                                                             GwyDataField *iout,
                                                             GwyOrientation orientation,
                                                             GwyTransformDirection direction);
    void                gwy_data_field_2dfft                (GwyDataField *rin,
                                                             GwyDataField *iin,
                                                             GwyDataField *rout,
                                                             GwyDataField *iout,
                                                             GwyWindowingType windowing,
                                                             GwyTransformDirection direction,
                                                             GwyInterpolationType interpolation,
                                                             gboolean preserverms,
                                                             gint level);
    void                gwy_data_field_area_2dfft           (GwyDataField *rin,
                                                             GwyDataField *iin,
                                                             GwyDataField *rout,
                                                             GwyDataField *iout,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height,
                                                             GwyWindowingType windowing,
                                                             GwyTransformDirection direction,
                                                             GwyInterpolationType interpolation,
                                                             gboolean preserverms,
                                                             gint level);
    void                gwy_data_field_2dfft_raw            (GwyDataField *rin,
                                                             GwyDataField *iin,
                                                             GwyDataField *rout,
                                                             GwyDataField *iout,
                                                             GwyTransformDirection direction);
    void                gwy_data_field_2dfft_humanize       (GwyDataField *data_field);
    void                gwy_data_field_2dfft_dehumanize     (GwyDataField *data_field);
    void                gwy_data_field_fft_filter_1d        (GwyDataField *data_field,
                                                             GwyDataField *result_field,
                                                             GwyDataLine *weights,
                                                             GwyOrientation orientation,
                                                             GwyInterpolationType interpolation);
    void                gwy_data_field_cwt                  (GwyDataField *data_field,
                                                             GwyInterpolationType interpolation,
                                                             gdouble scale,
                                                             Gwy2DCWTWaveletType wtype);

## Description

There are two main groups of FFT functions.

High-level functions such as `gwy_data_field_2dfft()`, `gwy_data_line_fft()` can perform windowing, leveling and other pre- and postprocessing. This makes them suitable for calculation of spectral densities and other statistical characteristics.

Low-level functions have `raw` appended to their name: `gwy_data_field_2dfft_raw()`, `gwy_data_line_fft_raw()`. They perform no other operations on the data beside the transform itself. This makes them suitable for applications where both forward and inverse transform is performed.

Both types of functions wrap a Fourier transform backend which can be currently either `gwy_fft_simple()`, available always, or FFTW3, available when Gwyddion was compiled with it.

## Details

### gwy_fft_find_nice_size ()

    gint                gwy_fft_find_nice_size              (gint size);

Finds a nice-for-FFT array size.

The `nice' means three properties are guaranteed: it is greater than or equal to `size`; it can be directly used with current FFT backend without scaling (since 2.8 this is true for any size); and the transform is fast, i.e. the number is highly factorable.

To be compatible with Gwyddion <= 2.7 one has to pass only data fields and lines with sizes returned by this function to raw integral transforms. Otherwise this function is mainly useful if you extend and pad the input data for other reasons and thus have the freedom to choose a convenient transform size.

`size` : | Transform size.
Returns : | A nice FFT array size.

### gwy_data_line_fft ()

    void                gwy_data_line_fft                   (GwyDataLine *rsrc,
                                                             GwyDataLine *isrc,
                                                             GwyDataLine *rdest,
                                                             GwyDataLine *idest,
                                                             GwyWindowingType windowing,
                                                             GwyTransformDirection direction,
                                                             GwyInterpolationType interpolation,
                                                             gboolean preserverms,
                                                             gint level);

Calculates Fast Fourier Transform of a data line.

A windowing or data leveling can be applied if requested.

`rsrc` : | Real input data line.
`isrc` : | Imaginary input data line.
`rdest` : | Real output data line. It will be resized to the size of the input data line.
`idest` : | Imaginary output data line. It will be resized to the size of the input data line.
`windowing` : | Windowing mode.
`direction` : | FFT direction.
`interpolation` : | Interpolation type. Ignored since 2.8 as no reampling is performed.
`preserverms` : | `TRUE` to preserve RMS value while windowing.
`level` : | 0 to perform no leveling, 1 to subtract mean value, 2 to subtract line (the number can be interpreted as the first polynomial degree to keep, but only the enumerated three values are available).

### gwy_data_line_part_fft ()

    void                gwy_data_line_part_fft              (GwyDataLine *rsrc,
                                                             GwyDataLine *isrc,
                                                             GwyDataLine *rdest,
                                                             GwyDataLine *idest,
                                                             gint from,
                                                             gint len,
                                                             GwyWindowingType windowing,
                                                             GwyTransformDirection direction,
                                                             GwyInterpolationType interpolation,
                                                             gboolean preserverms,
                                                             gint level);

Calculates Fast Fourier Transform of a part of a data line.

A windowing or data leveling can be applied if requested.

`rsrc` : | Real input data line.
`isrc` : | Imaginary input data line. Since 2.7 it can be `NULL` for real-to-complex transforms.
`rdest` : | Real output data line, it will be resized to `len`.
`idest` : | Imaginary output data line, it will be resized to `len`.
`from` : | The index in input lines to start from (inclusive).
`len` : | Lenght of data line part, it must be at least 2.
`windowing` : | Windowing mode.
`direction` : | FFT direction.
`interpolation` : | Interpolation type. Ignored since 2.8 as no reampling is performed.
`preserverms` : | `TRUE` to preserve RMS value while windowing.
`level` : | 0 to perform no leveling, 1 to subtract mean value, 2 to subtract line (the number can be interpreted as the first polynomial degree to keep, but only the enumerated three values are available).

### gwy_data_line_fft_raw ()

    void                gwy_data_line_fft_raw               (GwyDataLine *rsrc,
                                                             GwyDataLine *isrc,
                                                             GwyDataLine *rdest,
                                                             GwyDataLine *idest,
                                                             GwyTransformDirection direction);

Calculates Fast Fourier Transform of a data line.

No leveling, windowing nor scaling is performed.

Since 2.8 the dimensions need not to be from the set of sizes returned by `gwy_fft_find_nice_size()`.

`rsrc` : | Real input data line.
`isrc` : | Imaginary input data line. Since 2.7 it can be `NULL` for real-to-complex transform.
`rdest` : | Real output data line. It will be resized to the size of the input data line.
`idest` : | Imaginary output data line. It will be resized to the size of the input data line.
`direction` : | FFT direction.

Since 2.1

### gwy_data_field_1dfft ()

    void                gwy_data_field_1dfft                (GwyDataField *rin,
                                                             GwyDataField *iin,
                                                             GwyDataField *rout,
                                                             GwyDataField *iout,
                                                             GwyOrientation orientation,
                                                             GwyWindowingType windowing,
                                                             GwyTransformDirection direction,
                                                             GwyInterpolationType interpolation,
                                                             gboolean preserverms,
                                                             gint level);

Transforms all rows or columns in a data field with Fast Fourier Transform.

If requested a windowing and/or leveling is applied to preprocess data to obtain reasonable results.

`rin` : | Real input data field.
`iin` : | Imaginary input data field. It can be `NULL` for real-to-complex transform which can be somewhat faster than complex-to-complex transform.
`rout` : | Real output data field, it will be resized to area size.
`iout` : | Imaginary output data field, it will be resized to area size.
`orientation` : | Orientation: pass `GWY_ORIENTATION_HORIZONTAL` to transform rows, `GWY_ORIENTATION_VERTICAL` to transform columns.
`windowing` : | Windowing type.
`direction` : | FFT direction.
`interpolation` : | Interpolation type. Ignored since 2.8 as no reampling is performed.
`preserverms` : | `TRUE` to preserve RMS while windowing.
`level` : | 0 to perform no leveling, 1 to subtract mean value, 2 to subtract line (the number can be interpreted as the first polynomial degree to keep, but only the enumerated three values are available).

### gwy_data_field_area_1dfft ()

    void                gwy_data_field_area_1dfft           (GwyDataField *rin,
                                                             GwyDataField *iin,
                                                             GwyDataField *rout,
                                                             GwyDataField *iout,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height,
                                                             GwyOrientation orientation,
                                                             GwyWindowingType windowing,
                                                             GwyTransformDirection direction,
                                                             GwyInterpolationType interpolation,
                                                             gboolean preserverms,
                                                             gint level);

Transforms all rows or columns in a rectangular part of a data field with Fast Fourier Transform.

If requested a windowing and/or leveling is applied to preprocess data to obtain reasonable results.

`rin` : | Real input data field.
`iin` : | Imaginary input data field. It can be `NULL` for real-to-complex transform which can be somewhat faster than complex-to-complex transform.
`rout` : | Real output data field, it will be resized to area size.
`iout` : | Imaginary output data field, it will be resized to area size.
`col` : | Upper-left column coordinate.
`row` : | Upper-left row coordinate.
`width` : | Area width (number of columns), must be at least 2 for horizontal transforms.
`height` : | Area height (number of rows), must be at least 2 for vertical transforms.
`orientation` : | Orientation: pass `GWY_ORIENTATION_HORIZONTAL` to transform rows, `GWY_ORIENTATION_VERTICAL` to transform columns.
`windowing` : | Windowing type.
`direction` : | FFT direction.
`interpolation` : | Interpolation type. Ignored since 2.8 as no reampling is performed.
`preserverms` : | `TRUE` to preserve RMS while windowing.
`level` : | 0 to perform no leveling, 1 to subtract mean value, 2 to subtract lines (the number can be interpreted as the first polynomial degree to keep, but only the enumerated three values are available).

### gwy_data_field_1dfft_raw ()

    void                gwy_data_field_1dfft_raw            (GwyDataField *rin,
                                                             GwyDataField *iin,
                                                             GwyDataField *rout,
                                                             GwyDataField *iout,
                                                             GwyOrientation orientation,
                                                             GwyTransformDirection direction);

Transforms all rows or columns in a data field with Fast Fourier Transform.

No leveling, windowing nor scaling is performed.

Since 2.8 the dimensions need not to be from the set of sizes returned by `gwy_fft_find_nice_size()`.

`rin` : | Real input data field.
`iin` : | Imaginary input data field. It can be `NULL` for real-to-complex transform.
`rout` : | Real output data field, it will be resized to `rin` size.
`iout` : | Imaginary output data field, it will be resized to `rin` size.
`orientation` : | Orientation: pass `GWY_ORIENTATION_HORIZONTAL` to transform rows, `GWY_ORIENTATION_VERTICAL` to transform columns.
`direction` : | FFT direction.

Since 2.1

### gwy_data_field_2dfft ()

    void                gwy_data_field_2dfft                (GwyDataField *rin,
                                                             GwyDataField *iin,
                                                             GwyDataField *rout,
                                                             GwyDataField *iout,
                                                             GwyWindowingType windowing,
                                                             GwyTransformDirection direction,
                                                             GwyInterpolationType interpolation,
                                                             gboolean preserverms,
                                                             gint level);

Calculates 2D Fast Fourier Transform of a rectangular a data field.

If requested a windowing and/or leveling is applied to preprocess data to obtain reasonable results.

`rin` : | Real input data field.
`iin` : | Imaginary input data field. It can be `NULL` for real-to-complex transform which can be somewhat faster than complex-to-complex transform.
`rout` : | Real output data field, it will be resized to area size.
`iout` : | Imaginary output data field, it will be resized to area size.
`windowing` : | Windowing type.
`direction` : | FFT direction.
`interpolation` : | Interpolation type.
`preserverms` : | `TRUE` to preserve RMS while windowing.
`level` : | 0 to perform no leveling, 1 to subtract mean value, 2 to subtract plane (the number can be interpreted as the first polynomial degree to keep, but only the enumerated three values are available).

### gwy_data_field_area_2dfft ()

    void                gwy_data_field_area_2dfft           (GwyDataField *rin,
                                                             GwyDataField *iin,
                                                             GwyDataField *rout,
                                                             GwyDataField *iout,
                                                             gint col,
                                                             gint row,
                                                             gint width,
                                                             gint height,
                                                             GwyWindowingType windowing,
                                                             GwyTransformDirection direction,
                                                             GwyInterpolationType interpolation,
                                                             gboolean preserverms,
                                                             gint level);

Calculates 2D Fast Fourier Transform of a rectangular area of a data field.

If requested a windowing and/or leveling is applied to preprocess data to obtain reasonable results.

`rin` : | Real input data field.
`iin` : | Imaginary input data field. It can be `NULL` for real-to-complex transform which can be somewhat faster than complex-to-complex transform.
`rout` : | Real output data field, it will be resized to area size.
`iout` : | Imaginary output data field, it will be resized to area size.
`col` : | Upper-left column coordinate.
`row` : | Upper-left row coordinate.
`width` : | Area width (number of columns), must be at least 2.
`height` : | Area height (number of rows), must be at least 2.
`windowing` : | Windowing type.
`direction` : | FFT direction.
`interpolation` : | Interpolation type. Ignored since 2.8 as no reampling is performed.
`preserverms` : | `TRUE` to preserve RMS while windowing.
`level` : | 0 to perform no leveling, 1 to subtract mean value, 2 to subtract plane (the number can be interpreted as the first polynomial degree to keep, but only the enumerated three values are available).

### gwy_data_field_2dfft_raw ()

    void                gwy_data_field_2dfft_raw            (GwyDataField *rin,
                                                             GwyDataField *iin,
                                                             GwyDataField *rout,
                                                             GwyDataField *iout,
                                                             GwyTransformDirection direction);

Calculates 2D Fast Fourier Transform of a data field.

No leveling, windowing nor scaling is performed.

Since 2.8 the dimensions need not to be from the set of sizes returned by `gwy_fft_find_nice_size()`.

`rin` : | Real input data field.
`iin` : | Imaginary input data field. It can be `NULL` for real-to-complex transform.
`rout` : | Real output data field, it will be resized to `rin` size.
`iout` : | Imaginary output data field, it will be resized to `rin` size.
`direction` : | FFT direction.

Since 2.1

### gwy_data_field_2dfft_humanize ()

    void                gwy_data_field_2dfft_humanize       (GwyDataField *data_field);

Rearranges 2D FFT output to a human-friendly form.

Top-left, top-right, bottom-left and bottom-right sub-rectangles are swapped to obtain a humanized 2D FFT output with (0,0) in the centre.

More precisely, for even field dimensions the equally-sized blocks starting with the Nyquist frequency and with the zero frequency (constant component) will exchange places. For odd field dimensions, the block containing the zero frequency is one item larger and the constant component will actually end up in the exact centre.

Also note if both dimensions are even, this function is involutory and identical to `gwy_data_field_2dfft_dehumanize()`. However, if any dimension is odd, `gwy_data_field_2dfft_humanize()` and `gwy_data_field_2dfft_dehumanize()` are different, therefore they must be paired properly.

`data_field` : | A data field.

### gwy_data_field_2dfft_dehumanize ()

    void                gwy_data_field_2dfft_dehumanize     (GwyDataField *data_field);

Rearranges 2D FFT output back from the human-friendly form.

Top-left, top-right, bottom-left and bottom-right sub-rectangles are swapped to reshuffle a humanized 2D FFT output back into the natural positions.

See `gwy_data_field_2dfft_humanize()` for discussion.

`data_field` : | A data field.

Since 2.8

### gwy_data_field_fft_filter_1d ()

    void                gwy_data_field_fft_filter_1d        (GwyDataField *data_field,
                                                             GwyDataField *result_field,
                                                             GwyDataLine *weights,
                                                             GwyOrientation orientation,
                                                             GwyInterpolationType interpolation);

Performs 1D FFT filtering of a data field.

`data_field` : | A data field to filter.
`result_field` : | A data field to store the result to. It will be resampled to `data_field`'s size.
`weights` : | Filter weights for the lower half of the spectrum (the other half is symmetric). Its size can be arbitrary, it will be interpolated.
`orientation` : | Filter direction.
`interpolation` : | The interpolation to use for resampling.

### gwy_data_field_cwt ()

    void                gwy_data_field_cwt                  (GwyDataField *data_field,
                                                             GwyInterpolationType interpolation,
                                                             gdouble scale,
                                                             Gwy2DCWTWaveletType wtype);

Computes a continuous wavelet transform (CWT) at given scale and using given wavelet.

`data_field` : | A data field.
`interpolation` : | Interpolation type. Ignored since 2.8 as no reampling is performed.
`scale` : | Wavelet scale.
`wtype` : | Wavelet type.