STScI Logo

forward stsdas.analysis.fourier


NAME · USAGE · DESCRIPTION · PARAMETERS · EXAMPLES · BUGS · REFERENCES
SEE_ALSO

NAME

forward -- Compute the forward Fourier transform of an image.

USAGE

forward input output

DESCRIPTION

This task computes the Fourier transform of a 1- or 2-dimensional image. The input may consist of both real and imaginary parts, or either part separately.

The output of the forward task is not normalized; for example, the first pixel of the output will be the sum of the input values. The inverse task normalizes by dividing by the number of pixels, so applying forward and then inverse returns an image which is the same as the original, except for roundoff errors.

The output coordinate parameters will be determined from the input parameters. Two additional header keywords, OCRPIX1 and OCRVAL1, will be included in the output in order to save the original (i.e., input) values of CRPIX1 and CRVAL1, respectively. These are used by the inverse task to restore the original values of these keywords. For more information about the coordinate parameters, type "help fourier option=sys".

For 2-D transforms, this task has the option of using scratch images for intermediate results. Using scratch images may take longer, but it allows the task to function even with limited memory.

It took approximately 104 seconds of CPU time (8:12 elapsed) on a VAX 8800 to transform a 1024 x 1024 real*4 image, using scratch images, rather than working in-memory. There was no input imaginary part, but both real and imaginary output parts were created. Working in-memory on a Sun IPX the transform took 26.4 seconds of CPU time (2:38 elapsed).

PARAMETERS

input [file name]
Name of the input data file. See also inreal and inimag, which specify whether the real and imaginary parts are to be read.

If both real and imaginary parts are to be read, the letters "r" and "i" will be appended to input to form the names of the images for real and imaginary parts respectively.

output [file name]
Name of the output data file created by forward.

If both real and imaginary parts are to be created, the letters "r" and "i" will be appended to output to form the names of the images for real and imaginary parts respectively.

(inreal = yes) [boolean]
Use the real part of the input data file? If this is set to yes, the real part must exist.
(inimag = no) [boolean]
Use the imaginary part of the input data file? If this is set to yes, the imaginary part must exist.
(outreal = yes) [boolean]
Save the real part for the output data file?
(outimag = yes) [boolean]
Save the imaginary part for the output data file?
(coord_shift = no) [boolean]
As indicated in the REFERENCES section, the discrete Fourier transform treats the first pixel of the image array as the coordinate origin, the zero point of time or of angular position in space, for example.

If coord_shift=yes, then the origin for the input image is shifted to the location of the reference pixel of that image, as given by CRPIX1 (and CRPIX2 for a 2-D image). This is implemented by adding a linear function to the phase of the transformed image; the function is zero at the origin in the Fourier domain. The amplitude is not affected.

If coord_shift=no, then the coordinate information is not used to modify the data values.

For 2-D images, coord_shift and inmemory must not both be set to yes.

(center = no) [boolean]
Shift the coordinate origin to the middle of the output image?
(inmemory = yes) [boolean]
For a two-dimensional input image, if inmemory = yes the image will be read into a complex array, the Fourier transform will be performed on that array in-memory, and the array will be written to output images for the real and imaginary parts. This requires one complex word for each pixel. The complex array must fit entirely in memory (i.e. no paging) because when performing the Fourier transform the array is accessed both by rows and by columns. If inmemory = no, see the description of len_blk. The parameters inmemory and coord_shift may not both be set to yes for 2-D images.

For 1-D images, inmemory is ignored.

(len_blk = 256) [integer]
Length of block for transposing 2-D images.

For 2-dimensional input images, if inmemory = no this task transposes each image into scratch images before computing the Fourier transform of the second axis. This parameter is the length of the side of a square region that is transposed in one step. The I/O buffers for scratch images can take a lot of memory if len_blk is large, e.g., about 8 megabytes for len_blk = 512. If you get out-of-memory errors, you should flush the process cache (flprcache), reduce the size of len_blk and try again.

This parameter is ignored for 1-D images or if inmemory = yes.

(verbose = yes) [boolean]
Print input and output image names?

Setting verbose=yes shows you the actual names of the image headers, including the "r" & "i" suffixes for real & imaginary parts.

(ftpairs = fourier$ftpairs.dat) [file name]
File defining CTYPE transform pairs.

EXAMPLES

1. Take the forward Fourier transform of the image "civ" (no imaginary part) and put the output (both real and imaginary parts) in the images "tr" and "ti", respectively.

fo> forward civ t inimag=no

BUGS

If the task fails---due to lack of memory or disk space, for example---the output image and temporary images that were created are not deleted.

REFERENCES

Bracewell, R.N.: "The Fourier Transform and Its Applications," McGraw-Hill Publishing Co., New York, 1986.

The implementation of the Fourier transform in the forward task differs from the definition given in Bracewell in that the output from this task is not normalized. In Bracewell the forward transform includes a 1/N factor, and we include that factor in the inverse task instead.

For a 1-D array g[t], the forward Fourier transform G[f] is

	G[f] = sum of g[t] * exp (-2*pi*i * t * f / N)
	from t=0 to t=N-1,

where the indexes t and f run from 0 to N-1. For a 2-D array, a 1-D transform is done for each row, and then the 1-D transform is done for each column.

SEE ALSO

Type "help fourier option=sys" for a higher-level description of the fourier package.


Source Code · Package Help · Search Form · STSDAS