inttrans — FFT and other integral transforms
gint  gwy_fft_find_nice_size () 
void  gwy_data_line_fft () 
void  gwy_data_line_part_fft () 
void  gwy_data_line_fft_raw () 
void  gwy_data_line_zoom_fft () 
void  gwy_data_field_zoom_fft () 
void  gwy_data_field_1dfft () 
void  gwy_data_field_area_1dfft () 
void  gwy_data_field_1dfft_raw () 
void  gwy_data_field_2dfft () 
void  gwy_data_field_area_2dfft () 
void  gwy_data_field_2dfft_raw () 
void  gwy_data_field_2dfft_humanize () 
void  gwy_data_field_2dfft_dehumanize () 
void  gwy_data_field_fft_postprocess () 
void  gwy_data_field_fft_filter_1d () 
void  gwy_data_line_fft_window () 
void  gwy_data_field_fft_window () 
void  gwy_data_field_fft_window_1d () 
void  gwy_data_field_cwt () 
#include <libprocess/gwyprocess.h>
There are two main groups of FFT functions.
Highlevel 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.
Lowlevel 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 FFTW3 routines.
gint
gwy_fft_find_nice_size (gint size
);
Finds a niceforFFT array size.
Here ‘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. 
A nice FFT array size.
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 type to use. 

direction 
FFT direction. 

interpolation 
Interpolation type. Ignored since 2.8 as no resampling is performed. 

preserverms 


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

rdest 
Real output data line, it will be resized to 

idest 
Imaginary output data line, it will be resized to 

from 
The index in input lines to start from (inclusive). 

len 
Lenght of data line part, it must be at least 2. 

windowing 
Windowing type to use. 

direction 
FFT direction. 

interpolation 
Interpolation type. Ignored since 2.8 as no resampling is performed. 

preserverms 


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). 
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.
The normalisation of FFT is symmetrical, so transformations in both directions are unitary.
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 

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
void gwy_data_line_zoom_fft (GwyDataLine *rsrc
,GwyDataLine *isrc
,GwyDataLine *rdest
,GwyDataLine *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.
rsrc 
Real input data line. 

isrc 
Imaginary input data line. It can be 

rdest 
Real output data line. It will be resized to 

idest 
Imaginary output data line. It will be resized to 

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. 
Since: 2.61
void gwy_data_field_zoom_fft (GwyDataField *rsrc
,GwyDataField *isrc
,GwyDataField *rdest
,GwyDataField *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 topleft 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.
rsrc 
Real input data field. 

isrc 
Imaginary input data field. It can be 

rdest 
Real output data field. It will be resized to 

idest 
Imaginary output data field. It will be resized to 

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. 
Since: 2.62
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 

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 

windowing 
Windowing type. 

direction 
FFT direction. 

interpolation 
Interpolation type. Ignored since 2.8 as no resampling is performed. 

preserverms 


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

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 
Upperleft column coordinate. 

row 
Upperleft 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 

windowing 
Windowing type. 

direction 
FFT direction. 

interpolation 
Interpolation type. Ignored since 2.8 as no resampling is performed. 

preserverms 


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). 
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.
The normalisation of FFT is symmetrical, so transformations in both directions are unitary.
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 

rout 
Real output data field, it will be resized to 

iout 
Imaginary output data field, it will be resized to 

orientation 
Orientation: pass 

direction 
FFT direction. 
Since: 2.1
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.
Lateral dimensions, offsets and units are unchanged. See gwy_data_field_fft_postprocess()
for that.
rin 
Real input data field. 

iin 
Imaginary input data field. It can be 

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 


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

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 
Upperleft column coordinate. 

row 
Upperleft 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 resampling is performed. 

preserverms 


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). 
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.
The normalisation of FFT is symmetrical, so transformations in both directions are unitary.
Since 2.8 the dimensions need not to be from the set of sizes returned by gwy_fft_find_nice_size()
.
Lateral dimensions, offsets and units are unchanged. See gwy_data_field_fft_postprocess()
for that.
Since 2.53 iout
can be NULL
for complextoreal 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 nonNULL
iout
.
rin 
Real input data field. 

iin 
Imaginary input data field. It can be 

rout 
Real output data field, it will be resized to 

iout 
Imaginary output data field, it will be resized to 

direction 
FFT direction. It should be 
Since: 2.1
void
gwy_data_field_2dfft_humanize (GwyDataField *data_field
);
Rearranges 2D FFT output to a humanfriendly form.
Topleft, topright, bottomleft and bottomright subrectangles are swapped to obtain a humanized 2D FFT output with (0,0) in the centre.
More precisely, for even field dimensions the equallysized 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. 
void
gwy_data_field_2dfft_dehumanize (GwyDataField *data_field
);
Rearranges 2D FFT output back from the humanfriendly form.
Topleft, topright, bottomleft and bottomright subrectangles 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
void gwy_data_field_fft_postprocess (GwyDataField *data_field
,gboolean humanize
);
Updates units, dimensions and offsets for a 2D FFTprocessed field.
The field is expected to have dimensions and units of the original directspace 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_data_field_2dfft_humanize()
is applied to the field data and the lateral offsets are set
accordingly. Otherwise the offsets are cleared.
Value units are kept intact.
data_field 
A data field. 

humanize 

Since: 2.38
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 

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. 
void gwy_data_line_fft_window (GwyDataLine *line
,GwyWindowingType windowing
);
Performs windowing of a data line in preparation for FFT.
line 
A onedimensional data line. 

windowing 
Windowing type to use. 
Since: 2.62
void gwy_data_field_fft_window (GwyDataField *field
,GwyWindowingType windowing
);
Performs twodimensional windowing of a data field in preparation for 2D FFT.
The same windowing function is used rowwise and columnwise.
field 
A twodimensional data field. 

windowing 
Windowing type to use. 
Since: 2.62
void gwy_data_field_fft_window_1d (GwyDataField *field
,GwyOrientation orientation
,GwyWindowingType windowing
);
Performs rowwise or columnwise windowing of a data field in preparation for 1D FFT.
field 
A twodimensional data field. 

orientation 
Windowing orientation (the same as corresponding FFT orientation). 

windowing 
Windowing type to use. 
Since: 2.62
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 resampling is performed. 

scale 
Wavelet scale. 

wtype 
Wavelet type. 