STScI Logo

imsmooth xray.xspatial


NAME · USAGE · DESCRIPTION · PARAMETERS · SMOOTHING_FUNCTIONS
EXAMPLE · TIME_REQUIREMENTS · BUGS · SEE_ALSO

NAME

imsmooth -- smooth an image using convolution and FFT's

USAGE

imsmooth input_image output_image function arg1 select(debug mode only)

DESCRIPTION

Imsmooth convolves the input image with a smoothing function using discrete Fourier techniques. In most cases, both the image and the smoothing function are FFT'd and then multiplied (pixel by pixel) in k space. The result is inverse FFT'd and the real of the resulting complex image is written out. Depending on the FFT algorithm in use, the internal image may be padded out to the next power of 2 dimensions. All operations are performed using real*4 arithmetic, thus errors on the order of 2**-24 (1.0E-8) can be expected.

Data at the edge will be smoothed onto the opposite edge. This effect is called wrap-around. The amount of wrap-around is determined by the radius of the smoothing function and the magnitude of the difference between the data on one edge and that on the opposite edge. Because of wrap-around, the smoothed values near the edge will always be corrupted to some extent.

PARAMETERS

input_image = "dev$pix" prompt = name of input image

The image file to be smoothed. This can be any valid IRAF image file with or without subsection specification.

output_image = "" prompt = root name for output file [root_smo.tab]

The name of the output file. The output file is a standard IRAF image file with real*4 data. Its dimensions will be that of the input (after any subsection and/or blocking reductions).

function = "gauss" prompt = type of convolving function

The name of the smoothing function. The meaningful choices are: boxcar, expo, gauss, lorentz, king, power, tophat, file, mymod, hipass, lopass, kfile, and mykmod. The first seven functions, above, are drawn in x-y space, FFT'd, and then normalized. The last four functions are drawn in k space and convolved directly with the FFT of the image. File and kfile convolve the input image with another image read from an IRAF image file (see below). Mymod and mykmod are used in the special case where you have linked in your own subroutine to draw the smoothing function. The function name can be given by any unique abbreviation (e.g. gau). The appropriate parameters will then be requested (see below).

arg= 2.0 prompt = function radius, sigma or width

The first of two parameters to define a model function. arg1 is used for the x axis width of boxcars, the radius of exponential, king, and power profiles, and tophat, high-pass and low-pass filters, the sigma of a gaussian, and the gamma of a lorentzian. See smoothing function explanations below for more specifics.

select = prompt = (debug mode only) write one of the above

This automatic paramter is ONLY prompted for in debug mode. It allows the user a choice of how to write intermediate files. Note that debug mode is activated when the display paramter is set >= 5. If you are running the program and are not in debug mode, you will not have to worry about this paramter.

(arg= "") prompt = function power or height

The second of the two parameters used to shape model functions. It is used for the y axis height of boxcars, and the power parameter for king and power profiles. arg2 is not used by gauss, lorentz, expo, tophat, and high- and low- pass filters. See smoothing function explanations below for specific details.

(model_file = "") prompt = file containing convolving function

The name of the file used by the file and kfile model types. See explanation of file under smoothing function explanations, below.

(block = 1) [int]

The input image can be summed to smaller dimensions by combining the counts from adjacent input pixels into a single pixel. For block=2, each 2x2 square of pixels in the image file is summed to form a single pixel of the input. When the blocking does not divide evenly into the image dimension, the incomplete row or column on the end is omitted. (See imcompress)

(padding = 0) [int]

The number of zero valued pixels to place beyond the end of the data in both directions. FFT convolution wraps around, meaning that where it expects a pixel after the last one in a row or column, it continues with the beginning of that row or column. By placing zeroes at the ends of rows and columns, smoothed values near the edges of the image will not be affected by values from the opposite edge. Padding should be greater than the effective radius of the smoothing function, but no more than the largest dimension of the actual image. When the edges of the input image are zero for at least the width of the smoothing function, no padding is needed.

(clobber = no) [boolean]

Overwrite the existing image file if one exists with the same name as that given by output_image.

(errors = no) prompt = compute and output error array
from existing error array

When yes, imsmooth will compute the error range of each pixel in the smoothed image and output the result as a separate image file. Error calculation involves convolving the square of the original data errors with the square of the smoothing function. If the smoothing function is given in k-space, it will be inverse FFT'd and then treated as a spatial smoothing function for the error calculation.

(errarray = "") prompt = name of existing error array

Name of the image file containing an error array for the input image. If no input is given (or ""), imsmooth looks for a file having the same name root as the input image and an "_err" extension. (Note that if both errarray and error_out are left to default to the input image name root with an "_err" extension, the error_out file will attempt to overwrite the errarray file, and will fail or succeed according to the setting of the clobber parameter.) If an image name is given without a ".imh" extension, imsmooth appends "_err.imh" to the name. If the blocking option is selected, the errors are also blocked. By convention, error files contain the squares of the errors.

(error_out = "") prompt = name of output error array

Name to give output error file. If no name is given, output is written to a file having the same root as the smoothed image output file and an "_err" extension. (Note that if both errarray and error_out are left to default to the input image name root with an "_err" extension, the error_out file will attempt to overwrite the errarray file, and will fail or succeed according to the setting of the clobber parameter.) By convention, error files contain the squares of the errors.

(display = 1) [int]

Level of feedback and debug option. If 0, imsmooth prints no messages as it processes the image and/or errors. This is useful when imsmooth is run off line. When imsmooth is run at a console on large images, it is reassuring to know what imsmooth is doing, as it may take 10 or more minutes to smooth an image. If display is set to 1, imsmooth makes an announcement at the beginning of each phase of processing.

When display is set to 5, imsmooth's debug facility is activated. The debug facility gives the user the options of shifting the center of the smoothing function, and writing out as the output image, any intermediate states of the smoothing function or image. At each step, you will be queried as to what, if anything, you would like to write out, and whether you wish to procede. As the internal images are all in complex data type, the output options cover the modulus, phase, real part, and imaginary part of the image or smoothing function. The output image is always a real*4 (4 byte real) data type IRAF image and uses the name given as output_image (above). The intermediate images are written with the internal image dimension (including padding). All remaining parameters in the imsmooth .par file refer to debug mode.

SMOOTHING FUNCTIONS

boxcar arg1=width arg2=height

A boxcar function is an orthogonal rectangle in x-y space. The width and height should be odd. Even dimensions cannot be precisely centered with discrete pixels, resulting in a small phase error (shift of the output image). The units are image pixels.

expo arg1=radius

The exponential (expo) function has a circularly symmetric profile given by e**(-radius/expo_radius). The units are image pixels.

gauss arg1=sigma

The gaussian (gauss) function has a circularly symmetric profile given by e**(-(radius**2)/(2*(gauss_sigma**2))). The units are image pixels.

lorentz arg1=gamma

The lorentzian (lorentz) function has a circularly symmetric profile given by (gamma/2)/((radius**2)+(gamma/2)**2). The units are output image pixels.

king arg1=radius arg2=power

The king function has a circularly symmetric profile given by 1/((1+(radius/king_radius)**2)**king_power). The units are image pixels.

power arg1=radius arg2=power

The power function has a circularly symmetric profile given by 1/((1+(radius/power_radius))**power_power). The units are image pixels.

tophat arg1=radius

The tophat function is a constant within a radius of tophat_radius. The units are image pixels.

model model_file=filename

The smoothing function data is read in from an IRAF image file. The function data must be centered on the pixel at ((file_width/2+1), (file_height/2+1)). In a 320x512 file, the center is (161,257). Note: this differs from the same function in immodel. If the function is not centered on that pixel, the input image will be shifted (possibly completely out of the output image). If this problem occurs, use the debug features to shift the center and check the results. There are no restrictions on the dimensions or data type of the model file. After being read in, the data is FFT'd and then normalized (scaled such that the k-space origin has the value 1.0).

hipass arg1=radius

Hipass is a high pass filter applied in k space. Slow (smooth) changes in data values are filtered out, leaving the faster data fluctuation trends. The hipass function is a tophat in k space with radius in pixels. The period of the cutoff "frequency" is hipass_radius pixels.

lopass arg1=radius

Lopass is a low pass filter applied in k space. Rapid changes in data values are filtered out, leaving only slower (smoother) data fluctuation trends. The lopass function is an inverse tophat (circularly symmetrical hole) in kspace with radius in pixels. The period of the cutoff "frequency" is lopass_radius pixels.

kfile model_file=filename

The smoothing function data is read in from an IRAF image file. The k space origin is assumed to be at ((file_width/2+1), (file_height/2+1)) in the file from which the function is read. No restrictions are placed on the size of the function file. Note: if the function file is smaller than the internal image size used by imsmooth, the pixels outside the function image as read are all set to zero. If the file is not of type complex, the imaginary part is set to zero. The debug facilities may prove useful in this venture (see below). No normalization is applied to the data.

mymod arg1=? arg2=?

When using your own subroutine, the two arg values will be passed to it along with the other parameters. Your may use them as runtime parameters for your own needs; however arg1 must be given a value greater than 1.0 (there is a valid radius check in immodel ). imsmooth will normalize your function for you. See discussion of USER FUNCTIONS in the immodel help file.

mykmod arg1=? arg2=?

Mykmod is equivalent to mymod except that the function is not FFT'd before being convolved with the image data in k-space.

EXAMPLE

sp> imsmooth block=8  errors+ errarray=i296.qp
name of input image (dev$pix): i296
output image (foo): smi296
delete old copy of output image (no): yes

	input image dimensions: 1024x1024
	resultant output image dimensions: 128x128

number of zeroes to pad for both dimensions (30):

	internal image dimensions for FFT: 256x256

type of smoothing function (gauss): king
function radius, sigma, or width (2.):
function power or height (2.): 3.0
compute and output error array (yes): 
name of existing error array or none: none
name of output error array: 

	status of imsmooth process:
	modeling smoothing function
	FFTing smoothing function
	reading data file
	FFTing data
	convolving data
	inverse FFTing data
	writing smoothed image to: smi296

	computing errors:
	modeling smoothing function 
        FFTing smoothing function squares
        convolving function and error squares
        inverse FFTing new errors
        writing error array to: smi296_err

TIME REQUIREMENTS

The time required is directly proportional to the size (number of pixels) of the internal image. A 512x512 FFT takes 4 times as long as a 256x256 FFT. On slower machines, this time may be painfully long (many minutes). Computing the errors about doubles the time required.

BUGS

Real*4 arithmetic has an inherent error of 2E-7 per operation. As the debug facility always writes to the same file, a separate concurrent display facility is needed (as exists in ximage).

SEE ALSO

Documentation on errcreate which generates an error array from an input data array.

Documentation on error calculation (help explain_errorss ) for a description of PROS error algorithm.

Documentation on immodel (which uses many of the same subroutines).

Documentation on coordinates (help coords ) for a description of PROS coordinate conventions.


Source Code · Search Form · STSDAS