Integral transforms: Gwyddion Library Reference Manual

## Integral transforms Integral transforms — FFT and other integral transforms |

## Functions

void | gwy_line_fft ()
void | gwy_line_part_fft ()
void | gwy_line_fft_raw ()
void | gwy_line_zoom_fft ()
void | gwy_field_zoom_fft ()
void | gwy_field_fft_1d ()
void | gwy_field_area_fft_1d ()
void | gwy_field_fft_1d_raw ()
void | gwy_field_fft_2d ()
void | gwy_field_area_fft_2d ()
void | gwy_field_fft_2d_raw ()
void | gwy_field_fft_2d_center ()
void | gwy_field_fft_2d_decenter ()
void | gwy_field_fft_postprocess ()
void | gwy_field_fft_filter_1d ()
void | gwy_line_fft_window ()
void | gwy_field_fft_window ()
void | gwy_field_fft_window_1d ()

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

There are two main groups of FFT functions.

High-level functions such as `gwy_field_fft_2d()`, `gwy_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_field_fft_2d_raw()`, `gwy_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 FFTW3 routines.

## Functions

### gwy_line_fft()

    void
    gwy_line_fft (GwyLine *rsrc,
                  GwyLine *isrc,
                  GwyLine *rdest,
                  GwyLine *idest,
                  GwyWindowingType windowing,
                  GwyTransformDirection direction,
                  gboolean preserverms,
                  gint level);

Calculates Fast Fourier Transform of a data line.

A windowing or data leveling can be applied if requested.

#### Parameters

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 type to use. |
direction | FFT direction. |
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_line_part_fft()

    void
    gwy_line_part_fft (GwyLine *rsrc,
                       GwyLine *isrc,
                       GwyLine *rdest,
                       GwyLine *idest,
                       gint from,
                       gint len,
                       GwyWindowingType windowing,
                       GwyTransformDirection direction,
                       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.

#### Parameters

rsrc | Real input data line. |
isrc | Imaginary input data line. It can be `NULL` for real-to-complex transforms. | [nullable]
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 | Length of data line part, it must be at least 2. |
windowing | Windowing type to use. |
direction | FFT direction. |
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_line_fft_raw()

    void
    gwy_line_fft_raw (GwyLine *rsrc,
                      GwyLine *isrc,
                      GwyLine *rdest,
                      GwyLine *idest,
                      GwyTransformDirection direction);

Calculates Fast Fourier Transform of a data line.

No leveling, windowing nor scaling is performed.

The normalisation of FFT is symmetrical, so transformations in both directions are unitary.

#### Parameters

rsrc | Real input data line. |
isrc | Imaginary input data line. It can be `NULL` for real-to-complex transform. | [nullable]
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. |

### gwy_line_zoom_fft()

    void
    gwy_line_zoom_fft (GwyLine *rsrc,
                       GwyLine *isrc,
                       GwyLine *rdest,
                       GwyLine *idest,
                       gint m,
                       gdouble f0,
                       gdouble f1);

Computes Zoom FFT of a data line.

The output is DFTs, but computed for an arbitrary linear sequence of frequencies. The frequencies do not have to be in any relation to the data sampling step.

The first item of output corresponds exactly to `f0` and the last exactly to `f1` . So the frequency sampling step will be (`f1` − `f0` )/(`m` − 1), instead of the more usual division by `m` . To follow the usual Gwyddion conventions, the output data line real size will be (`f1` − `f0` )/(`m` − 1)*`m` . If it seems confusing, just take the output as indexed by integers and work with that.

Frequency step of one corresponds to the normal DFT frequency step. Therefore, passing `f0` =0, `f1` =`n` -1 (where `rsrc` has `n` points) and `m` =`n` reproduces the usual DFT, except more slowly. The result is normalised as raw FFT and the units of the output data lines are unchanged.

The transform direction is always forward. Windowing or other preprocessing need to be done separately beforehand. They would be usually once, but followed by any number of (Zoom) FFTs.

#### Parameters

rsrc | Real input data line. |
isrc | Imaginary input data line. It can be `NULL` for real-to-complex transform. | [nullable]
rdest | Real output data line. It will be resized to `m` samples. |
idest | Imaginary output data line. It will be resized to `m` samples. |
f0 | The first spatial frequency, measured in DFT frequency steps. |
f1 | The last spatial frequency, measured in DFT frequency steps. |
m | The number of frequencies to compute. It must be at least 2. |

### gwy_field_zoom_fft()

    void
    gwy_field_zoom_fft (GwyField *rsrc,
                        GwyField *isrc,
                        GwyField *rdest,
                        GwyField *idest,
                        gint mx,
                        gint my,
                        gdouble fx0,
                        gdouble fy0,
                        gdouble fx1,
                        gdouble fy1);

Computes Zoom FFT of a data field.

The output is DFTs, but computed for an arbitrary 2D Cartesian grid of frequencies along `x` and `y` . The frequencies do not have to be in any relation to the data sampling step.

The top-left pixel of output corresponds exactly to (`fx0` ,`fy0` ) and the bottom right exactly to (`fx1` ,`fy1` ). So the frequency sampling steps will be (`fx1` − `fx0` )/(`mx` − 1) and (`fy1` − `fy0` )/(`my` − 1), instead of the more usual division by `mx` and `my` . To follow the usual Gwyddion conventions, the output data field real size will be (`fx1` − `fx0` )/(`mx` − 1)*`mx` along `x` , and similarly along `y` . If it seems confusing, just take the output as indexed by integers and work with that.

Frequency step of one corresponds to the normal DFT frequency step. Therefore, passing `fx0` =0, `fx1` =`xres` –1, `fy0` =0, `fy1` =`yres` –1 (where `rsrc` has `xres` × `yres` points), `mx` =`xres` and `my` =`yres` reproduces the usual DFT, except more slowly. The result is normalised as raw FFT and the units of the output data fields are unchanged.

The transform direction is always forward. Windowing or other preprocessing need to be done separately beforehand. They would be usually once, but followed by any number of (Zoom) FFTs.

#### Parameters

rsrc | Real input data field. |
isrc | Imaginary input data field. It can be `NULL` for real-to-complex transform. | [nullable]
rdest | Real output data field. It will be resized to `mx` × `my` samples. |
idest | Imaginary output data field. It will be resized to `mx` × `my` samples. |
fx0 | The first horizontal spatial frequency, measured in DFT frequency steps. |
fy0 | The first vertical spatial frequency, measured in DFT frequency steps. |
fx1 | The last horizontal spatial frequency, measured in DFT frequency steps. |
fy1 | The last vetical spatial frequency, measured in DFT frequency steps. |
mx | The number of horizontal frequencies to compute. It must be at least 2. |
my | The number of vertical frequencies to compute. It must be at least 2. |

### gwy_field_fft_1d()

    void
    gwy_field_fft_1d (GwyField *rin,
                      GwyField *iin,
                      GwyField *rout,
                      GwyField *iout,
                      GwyOrientation orientation,
                      GwyWindowingType windowing,
                      GwyTransformDirection direction,
                      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.

#### Parameters

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. | [nullable]
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. |
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_field_area_fft_1d()

    void
    gwy_field_area_fft_1d (GwyField *rin,
                           GwyField *iin,
                           GwyField *rout,
                           GwyField *iout,
                           gint col,
                           gint row,
                           gint width,
                           gint height,
                           GwyOrientation orientation,
                           GwyWindowingType windowing,
                           GwyTransformDirection direction,
                           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.

#### Parameters

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. | [nullable]
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. |
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_field_fft_1d_raw()

    void
    gwy_field_fft_1d_raw (GwyField *rin,
                          GwyField *iin,
                          GwyField *rout,
                          GwyField *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.

The normalisation of FFT is symmetrical, so transformations in both directions are unitary.

#### Parameters

rin | Real input data field. |
iin | Imaginary input data field. It can be `NULL` for real-to-complex transform. | [nullable]
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. |

### gwy_field_fft_2d()

    void
    gwy_field_fft_2d (GwyField *rin,
                      GwyField *iin,
                      GwyField *rout,
                      GwyField *iout,
                      GwyWindowingType windowing,
                      GwyTransformDirection direction,
                      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.

Lateral dimensions, offsets and units are unchanged. See `gwy_field_fft_postprocess()` for that.

#### Parameters

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. | [nullable]
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. |
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_field_area_fft_2d()

    void
    gwy_field_area_fft_2d (GwyField *rin,
                           GwyField *iin,
                           GwyField *rout,
                           GwyField *iout,
                           gint col,
                           gint row,
                           gint width,
                           gint height,
                           GwyWindowingType windowing,
                           GwyTransformDirection direction,
                           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.

#### Parameters

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. | [nullable]
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. |
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_field_fft_2d_raw()

    void
    gwy_field_fft_2d_raw (GwyField *rin,
                          GwyField *iin,
                          GwyField *rout,
                          GwyField *iout,
                          GwyTransformDirection direction);

Calculates 2D Fast Fourier Transform of a data field.

No leveling, windowing nor scaling is performed.

The normalisation of FFT is symmetrical, so transformations in both directions are unitary.

Lateral dimensions, offsets and units are unchanged. See `gwy_field_fft_postprocess()` for that.

It is possible to pass `NULL` as `iout` for complex-to-real transforms. Note that this means Hermitean symmetry of the input data is assumed, i.e. about half of the input is ignored. If you want to extract the real part of a complex transform, you must pass a non-`NULL` `iout` .

#### Parameters

rin | Real input data field. |
iin | Imaginary input data field. It can be `NULL` for real-to-complex transform. | [nullable]
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. It should be `GWY_TRANSFORM_DIRECTION_FORWARD` for real-to-complex transforms and `GWY_TRANSFORM_DIRECTION_BACKWARD` for complex-to-real transforms. |

### gwy_field_fft_2d_center()

    void
    gwy_field_fft_2d_center (GwyField *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_field_fft_2d_decenter()`. However, if any dimension is odd, `gwy_field_fft_2d_center()` and `gwy_field_fft_2d_decenter()` are different, therefore they must be paired properly.

#### Parameters

field | A data field. |

### gwy_field_fft_2d_decenter()

    void
    gwy_field_fft_2d_decenter (GwyField *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_field_fft_2d_center()` for discussion.

#### Parameters

field | A data field. |

### gwy_field_fft_postprocess()

    void
    gwy_field_fft_postprocess (GwyField *field,
                               gboolean humanize);

Updates units, dimensions and offsets for a 2D FFT-processed field.

The field is expected to have dimensions and units of the original direct-space data. The lateral units and resolutions are updated to correspond to its Fourier transform.

The real dimensions are set for spatial frequencies, not wavevectors. For wavevector lateral coordinates, mutiply all real dimensions and offsets by 2*`G_PI`.

If `humanize` is `TRUE` `gwy_field_fft_2d_center()` is applied to the field data and the lateral offsets are set accordingly. Otherwise the offsets are cleared.

Value units are kept intact.

#### Parameters

field | A data field. |
humanize | `TRUE` to rearrange data to have the frequency origin in the centre. |

### gwy_field_fft_filter_1d()

    void
    gwy_field_fft_filter_1d (GwyField *field,
                             GwyField *result_field,
                             GwyLine *weights,
                             GwyOrientation orientation,
                             GwyInterpolationType interpolation);

Performs 1D FFT filtering of a data field.

#### Parameters

field | A data field to filter. |
result_field | A data field to store the result to. It will be resized to `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 of `weights` , if necessary. |

### gwy_line_fft_window()

    void
    gwy_line_fft_window (GwyLine *line,
                         GwyWindowingType windowing);

Performs windowing of a data line in preparation for FFT.

#### Parameters

line | A one-dimensional data line. |
windowing | Windowing type to use. |

### gwy_field_fft_window()

    void
    gwy_field_fft_window (GwyField *field,
                          GwyWindowingType windowing);

Performs two-dimensional windowing of a data field in preparation for 2D FFT.

The same windowing function is used row-wise and column-wise.

#### Parameters

field | A two-dimensional data field. |
windowing | Windowing type to use. |

### gwy_field_fft_window_1d()

    void
    gwy_field_fft_window_1d (GwyField *field,
                             GwyOrientation orientation,
                             GwyWindowingType windowing);

Performs row-wise or column-wise windowing of a data field in preparation for 1D FFT.

#### Parameters

field | A two-dimensional data field. |
orientation | Windowing orientation (the same as corresponding FFT orientation). |
windowing | Windowing type to use. |