Transforms module
#include "diplib/dft.h"
template<typename T>
dip::RDFT class

An object that encapsulates the real-valued Discrete Fourier Transform (DFT).

Contents

Usage:

RDFT rdft( size, inverse );        // creates the object with all the data ready to start running DFTs.
dft.Apply( in, out );              // computes a DFT, repeat as necessary
dft.Initialize( size2, inverse );  // changes the options for the new size / direction
dft.Apply( in, out );              // computes a different DFT, repeat as necessary

Here, in is a real-valued array with size elements , and out is a complex-valued array with size/2+1 elements, containing only the non-redundant values of the transform; the remaining values can be trivially computed if needed using std::conj. For the inverse transform, the output is the real-valued array. Both arrays are passed into dip::RDFT::Apply using a real-valued pointer.

The template can be instantiated for T = float or T = double. Linker errors will result for other types.

The DFT is computed using either PocketFFT or FFTW, depending on compile-time configuration (see the DIP_ENABLE_FFTW CMake configuration option).

When using FFTW, dip::maximumDFTSize is the largest length of the transform. PocketFFT does not have this limit.

Constructors, destructors, assignment and conversion operators

RDFT() defaulted
A default-initialized DFT object is useless. Call Initialize to make it useful.
RDFT(dip::uint size, bool inverse, dip::Option::DFTOptions options = {})
Construct a DFT object, see dip::RDFT::Initialize for the meaning of the parameters. Note that this is not a trivial operation. Not thread safe.

Functions

void Initialize(dip::uint size, bool inverse, dip::Option::DFTOptions options = {})
Re-configure a RDFT object to the given transform size and direction.
void Apply(T* source, T* destination, T scale) const
Apply the transform that the RDFT object is configured for.
auto IsInverse() const -> bool
Returns true if this represents an inverse transform, false for a forward transform.
auto IsInplace() const -> bool
Returns whether the transform is configured to work in place or not. Not meaningful when using PocketFFT.
auto IsAligned() const -> bool
Returns whether the transform is configured to work on aligned buffers or not. Not meaningful when using PocketFFT.
auto TransformSize() const -> dip::uint
Returns the size that the transform is configured for.
void Destroy() private
Frees memory

Function documentation

template<typename T>
void Initialize(dip::uint size, bool inverse, dip::Option::DFTOptions options = {})

Re-configure a RDFT object to the given transform size and direction.

size is the size of the transform. The real-valued pointer passed to dip::RDFT::Apply is expected to point at a buffer with this length. If inverse is true, an inverse transform will be computed (complex to real). The complex buffer has a size of size/2+1.

options determines some properties for the algorithm that will compute the DFT. - dip::Option::DFTOption::InPlace means the input and output pointers passed to dip::RDFT::Apply must be the same. Do note that the complex array has one or two floats more than the real array, the buffer must be large enough. - dip::Option::DFTOption::TrashInput means that the algorithm is free to overwrite the input array. Ignored when working in place. - dip::Option::DFTOption::Aligned means that the input and output buffers are aligned to 16-bit boundaries, which can significantly improve the speed of the algorithm.

When using PocketFFT, all these options are ignored.

Note that this is not a trivial operation, planning an FFT costs time.

This operation is not thread safe.

template<typename T>
void Apply(T* source, T* destination, T scale) const

Apply the transform that the RDFT object is configured for.

source and destination are pointers to contiguous buffers. If configured as a forward transform, source is the real-valued array with dip::RDFT::TransformSize elements, and destination is the complex-valued array with TransformSize() / 2 + 1 elements (presented as a pointer to a real-valued array with twice the number of elements). If configured as an inverse transform, the two descriptions are swapped. These two pointers can point to the same address for in-place operation; otherwise they must point to non-overlapping regions of memory. When using FFTW, the inplace parameter to the constructor or dip::RDFT::Initialize must be true if the two pointers here are the same, or false if they are different.

In the above description, TransformSize() is the value of the size parameter of the constructor or dip::RDFT::Initialize.

The input array is not marked const. If dip::Option::DFTOption::TrashInput` is given when planning, the input array can be overwritten with intermediate data, but otherwise will be left intact.

scale is a real scalar that the output values are multiplied by. It is typically set to 1/size for the inverse transform, and 1 for the forward transform.