%\input skeleton.tex
\def\version{Version 1.4 --- 2/2/90}
\def\chapter{Spatial --- Smoothing}
%\chapterhead{Spatial Smoothing}
\chapterhead{I.~Spatial Smoothing}
\@{Overview}

Spatial smoothing convolves 2D data in an IRAF image (including X-ray
QPOE file, *.qp, or pixel mask file, *.pl) with one of
a choice of spatial functions.  Fast Fourier Transforms are taken
of the data and convolving function.  The real and imaginary parts of
every element of the FFT of the convolving
function should be divided by the spectral density ({\it i.e.}, the
modulus of its Fourier transform in the 0,0 element), the two FFTs are
multiplied, and the inverse FFT gives the result.  The imaginary part
of the inverse FFT should be zero (to machine accuracy), and the
result is given by the real part.  No attempt should
be made to normalize the high-pass filter
(since the normalizing constant will be zero), and for this
filter the sum of counts in the result will be zero instead of the same as in the
original data.
Spatial smoothing will allow a user to save and/or display a
smoothed image.  There should also be the capability to
save and/or display any of the real, imaginary or power-spectrum
arrays of the FFT of the data, the convolving function, or the
product of the functions.  There should also be the ability to
make an FFT of the exposure mask of an image,(the *.exp file, which is
equivalent to a *.pl file), and to convolve the
mask with any of the given convolving functions.

We will use a standard library FFT routine in the analysis.  The
input data may be in the form of reals or integers.  The output
will always be a real IRAF image file.  The sum of the values in the pixels in the
output image should equal the sum in the input data to machine
accuracy.  (If it isn't, then there may be additional normalizations
which need including --- probably something related to $2^N$ ---
because different library FFTs handle these normalizations differently.)

\@{Convolving Functions}

Convolving functions need not be normalized to unity, since the
normalization of the FFT by spectral density should take care of this.

\**{Window/Box Car}

{\list 

The user will specify the lengths of the sides of the rectangle
in units of integer numbers of pixels.

}

\**{Tophat/Circle}

{\list

The user will specify the radius of the circle, $r_o$, in units of
fractional numbers of pixels.  The un-normalized form is

}

$$ f \propto 1 ~~~~~~~~~~~~r < r_o$$
$$ f = 0 ~~~~~~~~~~~~r > r_o$$


\**{Gaussian}

{\list

The user will specify the standard deviation of the Gaussian,
$\sigma$,
in units of (fractional) number of pixels.  The un-normalized form is

}

$$f \propto \exp \left[- {r^2 \over 2 \sigma^2}\right]$$

\**Exponential

{\list

The un-normalized form is

}

$$f \propto \exp -{r \over r_o}$$

\**Power Law

{\list

The un-normalized form is

}

$$f \propto \left( 1 + {r \over r_o}\right) ^{-p}$$

\**King Profile

{\list

The un-normalized form is

}

$$f \propto \left( 1 + \left({r \over r_o}\right)^2 \right) ^{-p}$$

\**Low/High Pass Filtering

{\list

The user inputs the width of the filter in number of bins, $n$.  Suppose
the
size of the image is $N$ bins, then the
FFT of the filter (convolving) function is provided directly as the following:

}

$$k_o = 2 ^N/n$$

For the low pass filter, 
$${\rm FFT} = 1~{\rm for}~ k < k_o$$
$${\rm FFT} = 0~{\rm for}~ k > k_o$$

For the high pass filter, 
$${\rm FFT} = 0~{\rm for}~ k < k_o$$
$${\rm FFT} = 1~{\rm for}~ k > k_o$$

{\list

Some kind of roll-off is appropriate to reduce the ripples in the
resulting smoothed data.  This could be something like a Gaussian.
The Gaussian width [either FWHM (= $\sqrt{8 \ln 2}$) or $\sigma$] should be
a hidden parameter with a default
of a few pixels, and tests should determine the best value for this default.

}
\@{Array Sizes}

Nominally we will use an FFT which requires an input array of size
$2^{N_1} \times 2^{N_2}$, where $N_1$ and $N_2$ are integers.
In this case we should either require the user to provide
sections of a data file which satisfy this condition, or we
may allow padding.  Padding is dangerous in that it will introduce
spurious features into the result.  The magnitude of these features
depends very much on the data and the size of the convolving function.
Probably the best solution would be to pad with the mean value in
nearby pixels.  For the time being, we will pad with values of 0, and
padding will happen automatically.

\@{Display/Output}

There should be the capability to save and/or display a
smoothed image.  There should also be the capability to
save and/or display any of the real, imaginary or power-spectrum
arrays of the FFT of the data, the convolving function, or the
product of the functions.   The user should be allowed to
specify an output file name which is the same as the input
file name if desired.

\@{Error Arrays}

The data should either have an associated error array,
$\epsilon(i,j)$, or the error array will be the square-root of the
data array.  The error array for the result can be found by
multiplying
the FFT of the square of the error (which will just be the same as the FFT of the
data, already performed, if the error array is the square-root of the
data array) by the FFT of the square of the
convolving function, and normalizing by the same value (of spectral
density) as before.  Calculate the inverse FFT to the real plane, and
take the square root for the result.  The filters which are defined in
the Fourier plane only will require an extra FFT for calculation of
the errors.  The sequence will be to take the inverse FFT of the
convolving function back to the real plane, drop the (zero) imaginary
part, square, FFT to the Fourier plane, multiply by the FFT of the
square of the errors, and inverse FFT to the real plane for the
result.
Although the filters can be specified in the real plane by a Jn Bessel
function, application of a roll-off function (to avoid ripples in the
result) will make things sufficiently complicated that the method
outlined above is probably the safest way to proceed.
The user
should have the choice of whether or not error calculations are performed.

\@{Testing}

\**The imaginary part of the result for every pixel should always be
equal to zero, to machine accuracy.  The imaginary part of the FFT of
each of our convolving functions should also be zero, since our
functions are symmetric.

\**The real part of the FFT of a delta function (of intensity $A$)
at position $x,y$ in an array of size
$2^{N_x} \times 2^{N_y}$, is an oblique cosine function. (The
imaginary part is an oblique sin function.)  In an FFT implementation
where the (1,1) pixel is in the corner, the intensity in the
$k_x,k_y$ pixel is given by, $A \cos [2 \pi ( (k_x-1)(x-1)/2^{N_x} +
(k_y-1)(y-1)/2^{N_y} )]$

\**Data represented as a delta function at a given position can be
used to test the whole function.
The result should be the convolving function at the position of the
delta function.

\**Data which represent a Gaussian of width $\sigma_1$ should be
convolved with a Gaussian of width $\sigma_2$.  The result should be a
Gaussian of $\sigma = (\sigma_1^2 + \sigma_2^2)^{1/2}$.

\**The error-array calculation should be checked with uniform data and
a Gaussian convolving function.  See the memo `Error Arrays - Fundamentals'
from DW, dated July 15th 1988, for an order-of-magnitude check on the error
calculation.


\vfill\eject






