DATAMANIP commands


PROGRAM NAME

kfft - Fast Fourier Transform (Forward and Inverse)

DESCRIPTION

kfft performs a multidimensional FFT on the input object specified by Input File. The dimensions along which the FFT is taken are specified using the -w,-h,-d,-t and -e flags. A 1D FFT is evaluated along each of the specified dimensions. For example, if the -w and -h flags are set for an image then the FFT is first taken along each width of the image and it is taken again for each height of the image resulting from the first FFT. This is equivalent to taking the 2D FFT of the image. Thus kfft can perform up to a 5D FFT on the input object depending on the number of flags set by the user. The size of each dimension specified must be a power of 2 and greater than 1. The dimensions for which the FFT is not calculated can have any size. The FFT is evaluated for all the primitives of the specified dimension. For example, if the input object has size (w,h,d,t,e) and the -w flag is specified then the FFT is calculated for all h*d*t*e width primitives in the object.

This program will compute either a forward or inverse FFT, depending on the direction requested with the -dir option. A -dir value of 0 or FALSE will result in a forward FFT, and a -dir value of 1 or TRUE will result in an inverse FFT. The default is a -dir value of 0 or FALSE (forward FFT).

Input File The input object is assumed of type complex. However if the data type of the object is not complex, then it is assumed that this object represents only the real part of the data. The imaginary part of the complex pair is assumed to be zero.

Centering The program also has the option (-center) of shifting the FFT result so that the DC component is at (W/2,H/2,D/2,T/2,E/2) instead of (0,0,0,0,0) for the 5-D case. This option is supplied because the center-shifted frequency domain representation is much easier to visualize and filter, particularly for image processing applications. For a forward FFT, the center-shifted option multiplies the input data by (-1)**(w+h+d+t+e) where (w,h,d,t,e) is the coordinate. For the inverse FFT case, the data is multiplied by (-1)**(w+h+d+t+e) AFTER the FFT processing, accounting for the fact that the input frequency domain data was center-shifted by the forward FFT.

Note that you must keep track of how the transform was centered in the forward FFT in order to know how to de-center it during the inverse FFT. For example, if the forward FFT was centered, then you must also ask that the inverse FFT be centered or you'll end up with your output data being multiplied by an alternating +1 / -1 sequence. Likewise, a non-centered forward FFT must be followed by a non-centered inverse FFT or you will end up with data multiplied by an alternating +1 / -1 sequence. Look out for the possibility of hiding the +1 / -1 multiplication due to the use of the magnitude operator to inspect the results!

Output Scaling The scaling factor can also be specified. The user can choose from no (unity) scaling (-scale 1), scaling by a factor of 1/N (-scale 2) per transform axis, or scaling by a factor of 1/sqrt(N) (-scale 3) per transform axis, where N is the dimension of the axis along which the FFT is being taken.

It is the responsibility of the user to make sure that the data going through multiple FFT's remains properly scaled. Since scaling can be done on both the forward and inverse FFTs, the aggregate scale factor is the product of the scaling done during the forward and inverse processing steps. Fox example, if the forward FFT is along a single axis of length N and scaling of 1/sqrt(N) is selected, and the reverse FFT is along the same axis again with scaling of 1/sqrt(N), then the aggregate scale factor would be (1/sqrt(n))*(1/sqrt(n)) or 1/N, which is the correct scaling for a combined set of forward and inverse operations.

In general, the aggregate scale factor after forward and inverse processing should be arranged to be 1/Ni per axis where Ni is the size of the i'th axis along which the transform is being taken. This means that for an NxM 2D data set, the combination of forward and inverse FFT scale factors should be arranged to be 1/(M*N). This can be done three ways; unity forward and 1/N inverse, or 1/N forward and unity inverse, or 1/sqrt(n) forward and 1/sqrt(n) inverse.

Output File The output of the FFT is a set of complex numbers. The data type representation can be selected as single precision complex (COMPLEX) or double precision complex (DCOMPLEX), both of which are floating point formats.

REQUIRED ARGUMENTS

-i
type: infile
desc: complex input object
-o
type: outfile
desc: complex output object

OPTIONAL ARGUMENTS

-dir
type: boolean
desc: FFT direction (0 is forward, 1 is inverse)
default: false
-center
type: boolean
desc: select to center (1) or not to center (0) the transform
default: true
-scale
type: integer toggle
desc: scale FFT by 1, 1/N or 1/sqrt(N)
default: 3
allowed values:
-type
type: cycle
desc: Output object data type
default: 12 "Complex"

Mutually Exclusive Group; if desired, specify ONE of:

-whole
type: flag
desc: compute FFT along all dimensions
OR

AT LEAST ONE OF the Group:

-w
type: flag
desc: if set, FFT is taken along the width dimension
AND/OR
-h
type: flag
desc: if set, FFT is taken along the height dimension
AND/OR
-d
type: flag
desc: if set, FFT is taken along the depth dimension
AND/OR
-t
type: flag
desc: if set, FFT is taken along the time dimension
AND/OR
-e
type: flag
desc: if set, FFT is taken along the element dimension

EXAMPLES

1.  Consider a 1D image of dimension N. If you take the forward transform
with:
 
    Scaling set to:             The scale factor is:
         1 (no scaling)                 1
         2 (1/N per axis)               1/N
         3 (1/sqrt(N) per axis)         1/sqrt(N)
 
where the scale factor is applied to the result of the forward discrete
summation that forms the FFT kernel before the data is written to the
output object.
 
2.  Consider a 2D image of dimensions NxM. If you take the forward transform
with:
 
    Scaling set to:             The scale factor is:
         1 (no scaling)                 1
         2 (1/N per axis)               (1/N)*(1/M)=1/(M*N)
         3 (1/sqrt(N) per axis)         (1/sqrt(N))*(1/sqrt(M))
 
where the scale factor is applied to the result of the forward discrete
summation that forms the FFT kernel before the data is written to the
output object.
 
3.  Consider a 5D image of dimensions NxMxPxQxR. If you take the forward 
transform with:
 
    Scaling set to:             The scale factor is:
         1 (no scaling)                 1
         2 (1/N per axis)               1/(M*N*P*Q*R)
         3 (1/sqrt(N) per axis)         (1/sqrt(N))*(1/sqrt(M))*(1/sqrt(P))*
                                                    (1/sqrt(Q))*(1/sqrt(R))
 
where the scale factor is applied to the result of the forward discrete
summation that forms the FFT kernel before the data is written to the
output object.
 
The same relationships hold for the inverse transform case.
 
In general, one needs to have the product of the scale factors for the forward
and reverse transforms to be 1/N per axis for conservation of energy. Thus for
a 2D case, with an NxN image, you can use:
        Forward scale factor       Inverse scale factor
          1 per axis                  1/N per axis
    or    1/sqrt(N) per axis          1/sqrt(N) per axis
    or    1/N per axis                1 per axis
 
There is a nice example of the 3rd case shown in Gonzalez and Wintz at the 
bottom of page 69 (second Edition).

SEE ALSO

RESTRICTIONS

kfft cannot operate on objects that have either of the mask, location or time segments in addition to the value segment.

The IEEE FFT used internally is limited to a maximum vector size of 32768 data points. This means that no object dimension can be larger than this number. This restriction will be removed in a later release when the IEEE FFT is replaced. This FFT is currently used because it is trusted and fast, although that fact may be hidden by data services overhead.

REFERENCES

COPYRIGHT

Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.