5.5. FFTW-Filter#

Summary:

Wrapper for the FFTW

Type:

Algorithm

License:

Licensed under GPL (uses FFTW licensed under GPL, too).

Platforms:

Windows, Linux

Author:

W. Lyda, twip optical solutions GmbH, T. Boettcher, M. Gronle, Universität Stuttgart

5.5.1. Overview#

This plugin provides wrappers for Fourier Transforms using the FFTW-library. These are for instance: - 1D FFT (over an arbitrary axis) - 1D inverse FFT (over an arbitrary axis) - 2D FFT (over the last two axes) - 2D inverse FFT (over the last two axes)

The FFTW package was developed at MIT by Matteo Frigo and Steven G. Johnson.It was published under GNU General Public License and can be downloaded under http://www.fftw.org/ .

To build this plugin you will need the libs from the fftw.

These filters are defined in the plugin:

  1. fftshift()

  2. fftw()

  3. fftw2D()

  4. ifftshift()

  5. ifftw()

  6. ifftw2D()

5.5.2. Usage#

5.5.2.1. For Windows:#

  1. Download from fftw-3.3.5-dll64.zip from http://www.fftw.org/install/windows.html

  2. Unzip the file.

  3. Create the import library (.lib file):

3.1 Open the Visual Studio Developer Command prompt:

On my machine the location is C:Program Files (x86)Microsoft Visual Studio2019CommunityCommon7ToolsVsDevCmd.bat

  1. Navigate to the unzip location and type:

    lib /machine:x64 /def:libfftw3-3.def lib /machine:x64 /def:libfftw3f-3.def lib /machine:x64 /def:libfftw3l-3.def

  2. Set the CMake variable FFTW_DIR to this new folder or define a windows environment variable FFTW_ROOT.

5.5.2.2. For Ubuntu:#

> sudo apt-get update -y > sudo apt-get install -y fftw-dev

5.5.3. Filters#

Detailed overview about all defined filters:

itom.algorithms.fftshift(source[, axis, axisIndex])#

Perform fftshift as known from Python, Matlab and so on, i.e. make the zero order of diffraction appear in the center.

The shift is implemented along the x and y or one of both axes within each plane (inplace) by using the axis parameter. The axisIndex parameter is used the shift a >2D dataObject in the 0 axis.

Parameters:

  • source (itom.dataObject) – Input object (n-dimensional, (u)int8, (u)int16, int32, float32, float64, complex64, complex128) which is shifted in-place.

  • axis (int, optional) –

    shift axis: x and y axis (-1, default), only y axis (0), only x axis (1)

    Value range: [-1, 1], Default: -1

  • axisIndex (int, optional) – shift axis in the case of a > 2D dataObject. (-1, default) the axis parameter is considered, (0) the 0 axis of a 3D dataObject is shifted

itom.algorithms.fftw(source, destination[, plan_flag, axis, norm])#

Compute the one-dimensional discrete Fourier Transform.

This method computes the one-dimensional n-point discrete Fourier Transform (DFT) with the efficient Fast Fourier Transform (FFT) algorithm using the fast, GPL licensed library FFTW (fftw.org). The transform is executed over a desired axis.

This method applies the forward transform, use ‘ifft’ for the inverse transform. The method works both inplace as well as out-of-place. The output is a complex64 object of the same size than the input object if the input is of one of the following types: (u)int8, (u)int16, int32, float32 or complex64. If the input object has one of the types float64 or complex128, the output is complex128. If a type conversion is necessary, a new dataObject is always put into the destination object.

Meta and axes information are copied to the output object. Only properties of the chosen axis are changed:

  • offset: 0.0

  • scaling: 1.0 / (previous-scaling * n), the factor 2pi is not considered here

  • unit: inverse of previous-unit, e.g. ‘1/previous-unit’

Per default, no value scaling is applied to the result. However, the optional parameter ‘norm’ influences this. If ‘norm’ is set to ‘ortho’, the values are scaled by 1/sqrt(n).

The FFTW library comes with two execution strategies: Measure and Estimate. One of both can be chosen by the optional parameter ‘plan_flag’. While Estimate selects a default algorithm, Measure will process some test runs with several implementations on your machine in order to find out the fastest algorithm for the given type of object. This will take some time but might speed-up calculations of huge objects.

Parameters:

  • source (itom.dataObject) – Input object (n-dimensional, (u)int8, (u)int16, int32, float32, float64, complex64, complex128)

  • destination (itom.dataObject) – Output object (inplace allowed, but only feasible if source is complex64 or complex128). Destination has the same size than the input object, the type is either complex128 (for float64 or complex128 inputs) or complex64 (else).

  • plan_flag (int, optional) –

    Method flag, 0: Estimate (default), 1: Measure. Measure instructs FFTW to run and measure the execution time of several FFTs in order to find the best way to compute the transform of size n. This process takes some time (usually a few seconds), depending on your machine and on the size of the transform. Estimate, on the contrary, does not run any computation and just builds a reasonable plan that is probably sub-optimal. In short, if your program performs many transforms of the same size and initialization time is not important, use Measure; otherwise use Estimate.

    Value range: [0, 1], Default: 0

  • axis (int, optional) –

    Axis over which to compute the FFT. If not given, the last axis is used.

    Value range: [-1, inf], Default: -1

  • norm (str, optional) –

    Normalization method. no: neither fft nor ifft are scaled, default: direct transform (fft) is not scaled, inverse transform is scaled by 1/n, ortho: both direct and inverse transforms are scaled by 1/sqrt(n)

    Match: [“no”, “default”, “ortho”], Default: “default”

itom.algorithms.fftw2D(source, destination[, plan_flag, norm])#

Compute the two-dimensional discrete Fourier Transform.

This method computes the two-dimensional n-point discrete Fourier Transform (DFT) with the efficient Fast Fourier Transform (FFT) algorithm using the fast, GPL licensed library FFTW (fftw.org). The transform is executed over the last two axes, denoted as planes.

This method applies the forward transform, use ‘ifft2D’ for the inverse transform. The method works both inplace as well as out-of-place. The output is a complex64 object of the same size than the input object if the input is of one of the following types: (u)int8, (u)int16, int32, float32 or complex64. If the input object has one of the types float64 or complex128, the output is complex128. If a type conversion is necessary, a new dataObject is always put into the destination object.

Meta and axes information are copied to the output object. Only properties of the last two axes are changed:

  • offset: 0.0

  • scaling: 1.0 / (previous-scaling * n), the factor 2pi is not considered here

  • unit: inverse of previous-unit, e.g. ‘1/previous-unit’

Per default, no value scaling is applied to the result. However, the optional parameter ‘norm’ influences this. If ‘norm’ is set to ‘ortho’, the values are scaled by 1/sqrt(n).

The FFTW library comes with two execution strategies: Measure and Estimate. One of both can be chosen by the optional parameter ‘plan_flag’. While Estimate selects a default algorithm, Measure will process some test runs with several implementations on your machine in order to find out the fastest algorithm for the given type of object. This will take some time but might speed-up calculations of huge objects.

Parameters:

  • source (itom.dataObject) – Input object (n-dimensional, (u)int8, (u)int16, int32, float32, float64, complex64, complex128)

  • destination (itom.dataObject) – Output object (inplace allowed, but only feasible if source is complex64 or complex128). Destination has the same size than the input object, the type is either complex128 (for float64 or complex128 inputs) or complex64 (else).

  • plan_flag (int, optional) –

    Method flag, 0: Estimate (default), 1: Measure. Measure instructs FFTW to run and measure the execution time of several FFTs in order to find the best way to compute the transform of size n. This process takes some time (usually a few seconds), depending on your machine and on the size of the transform. Estimate, on the contrary, does not run any computation and just builds a reasonable plan that is probably sub-optimal. In short, if your program performs many transforms of the same size and initialization time is not important, use Measure; otherwise use Estimate.

    Value range: [0, 1], Default: 0

  • norm (str, optional) –

    Normalization method. no: neither fft nor ifft are scaled, default: direct transform (fft) is not scaled, inverse transform is scaled by 1/n, ortho: both direct and inverse transforms are scaled by 1/sqrt(n)

    Match: [“no”, “default”, “ortho”], Default: “default”

itom.algorithms.ifftshift(source[, axis, axisIndex])#

Perform ifftshift as known from Python, Matlab and so on, i.e. move the zero order of diffraction back to the corner to run the inverse fft correctly.

The shift is implemented along the x and y or one of both axes within each plane (inplace) by using the axis parameter. The axisIndex parameter is used the shift a >2D dataObject in the 0 axis.

Parameters:

  • source (itom.dataObject) – Input object (n-dimensional, (u)int8, (u)int16, int32, float32, float64, complex64, complex128) which is shifted in-place.

  • axis (int, optional) –

    shift axis: x and y axis (-1, default), only y axis (0), only x axis (1)

    Value range: [-1, 1], Default: -1

  • axisIndex (int, optional) – shift axis in the case of a > 2D dataObject. (-1, default) the axis parameter is considered, (0) the 0 axis of a 3D dataObject is shifted

itom.algorithms.ifftw(source, destination[, plan_flag, axis, norm])#

Compute the inverse one-dimensional discrete Fourier Transform.

This method computes the inverse one-dimensional n-point discrete Fourier Transform (DFT) with the efficient Fast Fourier Transform (FFT) algorithm using the fast, GPL licensed library FFTW (fftw.org). The transform is executed over a desired axis.

This method applies the inverse transform, use ‘fft’ for the forward transform. The method works both inplace as well as out-of-place. The output is a complex64 object of the same size than the input object if the input is of one of the following types: (u)int8, (u)int16, int32, float32 or complex64. If the input object has one of the types float64 or complex128, the output is complex128. If a type conversion is necessary, a new dataObject is always put into the destination object.

Meta and axes information are copied to the output object. Only properties of the chosen axis are changed:

  • offset: 0.0

  • scaling: 1.0 / (previous-scaling * n), the factor 2pi is not considered here

  • unit: inverse of previous-unit, e.g. ‘1/previous-unit’

Per default, the values are scaled by (1/n). However, the optional parameter ‘norm’ influences this. If ‘norm’ is set to ‘no’, no scaling is applied, if ‘norm’ is set to ‘ortho’, the values are scaled by 1/sqrt(n).

The FFTW library comes with two execution strategies: Measure and Estimate. One of both can be chosen by the optional parameter ‘plan_flag’. While Estimate selects a default algorithm, Measure will process some test runs with several implementations on your machine in order to find out the fastest algorithm for the given type of object. This will take some time but might speed-up calculations of huge objects.

Parameters:

  • source (itom.dataObject) – Input object (n-dimensional, (u)int8, (u)int16, int32, float32, float64, complex64, complex128)

  • destination (itom.dataObject) – Output object (inplace allowed, but only feasible if source is complex64 or complex128). Destination has the same size than the input object, the type is either complex128 (for float64 or complex128 inputs) or complex64 (else).

  • plan_flag (int, optional) –

    Method flag, 0: Estimate (default), 1: Measure. Measure instructs FFTW to run and measure the execution time of several FFTs in order to find the best way to compute the transform of size n. This process takes some time (usually a few seconds), depending on your machine and on the size of the transform. Estimate, on the contrary, does not run any computation and just builds a reasonable plan that is probably sub-optimal. In short, if your program performs many transforms of the same size and initialization time is not important, use Measure; otherwise use Estimate.

    Value range: [0, 1], Default: 0

  • axis (int, optional) –

    Axis over which to compute the FFT. If not given, the last axis is used.

    Value range: [-1, inf], Default: -1

  • norm (str, optional) –

    Normalization method. no: neither fft nor ifft are scaled, default: direct transform (fft) is not scaled, inverse transform is scaled by 1/n, ortho: both direct and inverse transforms are scaled by 1/sqrt(n)

    Match: [“no”, “default”, “ortho”], Default: “default”

itom.algorithms.ifftw2D(source, destination[, plan_flag, norm])#

Compute the inverse two-dimensional discrete Fourier Transform.

This method computes the inverse two-dimensional n-point discrete Fourier Transform (DFT) with the efficient Fast Fourier Transform (FFT) algorithm using the fast, GPL licensed library FFTW (fftw.org). The transform is executed over the last two axes, denoted as planes.

This method applies the inverse transform, use ‘fft2D’ for the forward transform. The method works both inplace as well as out-of-place. The output is a complex64 object of the same size than the input object if the input is of one of the following types: (u)int8, (u)int16, int32, float32 or complex64. If the input object has one of the types float64 or complex128, the output is complex128. If a type conversion is necessary, a new dataObject is always put into the destination object.

Meta and axes information are copied to the output object. Only properties of the last two axes are changed:

  • offset: 0.0

  • scaling: 1.0 / (previous-scaling * n), the factor 2pi is not considered here

  • unit: inverse of previous-unit, e.g. ‘1/previous-unit’

Per default, the values are scaled by (1/n). However, the optional parameter ‘norm’ influences this. If ‘norm’ is set to ‘no’, no scaling is applied, if ‘norm’ is set to ‘ortho’, the values are scaled by 1/sqrt(n).

The FFTW library comes with two execution strategies: Measure and Estimate. One of both can be chosen by the optional parameter ‘plan_flag’. While Estimate selects a default algorithm, Measure will process some test runs with several implementations on your machine in order to find out the fastest algorithm for the given type of object. This will take some time but might speed-up calculations of huge objects.

Parameters:

  • source (itom.dataObject) – Input object (n-dimensional, (u)int8, (u)int16, int32, float32, float64, complex64, complex128)

  • destination (itom.dataObject) – Output object (inplace allowed, but only feasible if source is complex64 or complex128). Destination has the same size than the input object, the type is either complex128 (for float64 or complex128 inputs) or complex64 (else).

  • plan_flag (int, optional) –

    Method flag, 0: Estimate (default), 1: Measure. Measure instructs FFTW to run and measure the execution time of several FFTs in order to find the best way to compute the transform of size n. This process takes some time (usually a few seconds), depending on your machine and on the size of the transform. Estimate, on the contrary, does not run any computation and just builds a reasonable plan that is probably sub-optimal. In short, if your program performs many transforms of the same size and initialization time is not important, use Measure; otherwise use Estimate.

    Value range: [0, 1], Default: 0

  • norm (str, optional) –

    Normalization method. no: neither fft nor ifft are scaled, default: direct transform (fft) is not scaled, inverse transform is scaled by 1/n, ortho: both direct and inverse transforms are scaled by 1/sqrt(n)

    Match: [“no”, “default”, “ortho”], Default: “default”

5.5.4. Changelog#

  • itom setup 2.2.1: This plugin has been compiled using the FFTW 3.3.5

  • itom setup 3.0.0: This plugin has been compiled using the FFTW 3.3.5

  • itom setup 3.1.0: This plugin has been compiled using the FFTW 3.3.5

  • itom setup 3.2.1: This plugin has been compiled using the FFTW 3.3.5

  • itom setup 4.0.0: This plugin has been compiled using the FFTW 3.3.5