.help fadapt May94 ftools.fimage
.ih
NAME
fadapt -- Smooth a FITS image with a circular or elliptical top hat
filter of adaptive size in order to achieve a minimal number of counts
under the filter.  
.ih
USAGE
fadapt input output counts
.ih
PARAMETERS
.ls infile [file name]
Input FITS file name and extension number of the image to be convolved
with the elliptical top hat filter.  FADAPT is designed to work with
integer datatype images containing zero or positive pixel values.
.le
.ls outfile [file name]
Output FITS file where the smoothed image will be written. 
.le
.ls counts [integer]
Integer number of counts desired under the filter before smoothing
occurs.  At each image pixel location, the diameter of the smoothing
kernel will be iteratively varied until it just encloses at least this
many integrated counts.  If the input image pixel has a value greater
than or equal to counts then the pixel value will be copied to the output
image without any smoothing.
.le
.ls smajor [integer]
The maximum size the semi-major axis of the elliptical top hat, in
pixel units.
.le
.ls (ratio = 1.0) [double]
The axis ratio (minor axis divided by major axis) of the elliptical top
hat filter, in the range 0. to 1.  FADAPT will generally execute much
faster with a circular filter, which has a ratio = 1.
.le
.ls (theta = 0.0) [double]
The position angle of the semi-major axis of the elliptical top hat.
\fITheta\fR is measured counter-clockwise from the x axis and must be between
0 and 180 degrees.
.le
.ls (boundary = "nearest") [double]
The algorithm used to compute the values of the out of bounds pixels. The
options are:
.ls nearest
Use the value of the nearest boundary pixel.
.le
.ls constant
Use a constant value.
.le
.ls reflect
Generate a value by reflecting around the boundary.
.le
.ls wrap
Generate a value by wrapping around to the opposite side of the image.
.le
.le
.ls (constant = 0.0) [double]
The constant for constant-valued boundary extension.
.le
.ls (datatype = "-") [character]
The data type for the resulting smoothed image. Normally the output
image must have a floating point datatype ('E' or 'D') to preserve the
precision of the smoothed values.  A "-" or " " results in storing the
smoothed image with the same data type as the original input image. The
letter B or b represents byte, the letter I or i represents short
integer, the letter J or j represents integer, the letter E or e
represents single precision reals and the letter D or d represents
double precision reals.
.le
.ls (nullval = 0.0) [double]
Value to substitute for any undefined pixels within the image.
.le
.ls (copyprime=yes) [boolean]
If true, all of the primary header keywords, the primary array (if any) 
and all of the extension keywords of the first input file are copied to 
the output file.  If false, only minimal headers are created.
.le
.ls (copyall=no) [boolean]
If true, all other extensions, including the primary array are copied
to the output file.
.le
.ls (clobber = no) [boolean]
If true, an existing output file of the same name will be overwritten.
.le

.ih
DESCRIPTION

FADAPT convolves the input FITS image with a circular or elliptical top
hat kernel and writes the smoothed image to the \fIoutput\fR FITS
file.  The diameter of the top hat kernel is iteratively varied at each
image pixel location until it encloses, as closely as possible, at
least the specified number of counts.  The maximum size of the top hat
kernel is constrained by the \fIsmajor\fR parameter.  Any pixels in the
input image which have a value greater than or equal to the counts
value will be copied to the output image without any smoothing.  In
cases where the input image represents the integer number of photon
events detected within each pixel, this task has the effect of
producing a smoothed image in which each pixel has a minimum signal to
noise ratio approximately given by the square root of the counts
value.

This task is designed to operate on input images with positive integer
(or zero) pixel values;  if a floating point input image is given, then
the pixel values will be truncated to integers.  Out of bounds pixels
are computed using the algorithm specified by \fIboundary\fR. The FITS
image to be smoothed can be in either the primary array or in an image
extension. The resulting smoothed image will be placed in either the
output files primary array or in an image extension depending on three
things; the location of the image in the input file, the value of the
copyprime flag and the value of the copyall flag.

If the input image is in the primary array then the resulting image
will always be placed in the primary array. In this case, if the
copyprime flag is \fIyes\fR then all the keywords from the input
primary header will be copied to the output primary header, otherwise
only the required keywords will be placed in the output primary header.
Setting the copyall flag will cause all the FITS extensions in the
input FITS file to be copied over to the output FITS file.

If the input image is in an image extension then the resulting image
will be placed in one of three places depending on the values of the
copyprime and copyall flags. If the copyprime flag is \fIno\fR the the
resulting smoothed image will always appear in the primary array. If
the copyall flag is also set then all extension will be copied to the
output FITS file and the input primary array will be stored in the
image extension that the image was originally stored in the input FITS
file. If the copyprime flag is \fIyes\fR  then the primary array of the
input FITS file will always be copied over to the primary array of the
output FITS file. In this case, if the copyall flag is \fIno\fR then
the smoothed image will be stored in the first extension of the output
FITS file, otherwise the smoothed image will appear in the same
extension in both the input and output FITS file and all other
extensions will be copied to the output FITS file.

.ih
EXAMPLES

1. Convolve an image with a circular top hat where at least 10 counts go into 
each convolution integral.

    cl> fadapt image.fits gimage.fits 10

2. Convolve an image with an elliptical top hat where at least 50 counts go 
into each convolution integral.

    cl> fadapt img.fits gimg.fits 50 ratio=0.667

3. Convolve an image in the 3rd extension with a circular top hat where at least 24 counts go into each convolution integral using reflect boundary 
extension and store the resulting image in the primary array.

    cl> fadapt imgx.fits[3] gimg.fits 25 boundary=reflect copyprime=no

.ih
BUGS

FADAPT is designed to operate on integer datatype input images.  It may
give misleading results on floating point input images.

.ih
SEE ALSO
fboxcar fgauss florentz
.endhelp
