fadapt HEADAS help file

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.

USAGE

        fadapt input output counts

PARAMETERS

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.

outfile [file name]

Output FITS file where the smoothed image will be written.

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.

smajor [integer]

The maximum size the semi-major axis of the elliptical top hat, in pixel units.

(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.

(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.

(boundary = "nearest") [double]

The algorithm used to compute the values of the out of bounds pixels. The options are:

nearest: Use the value of the nearest boundary pixel.
constant: Use a constant value.
reflect: Generate a value by reflecting around the boundary.
wrap: Generate a value by wrapping around to the opposite side of the image.

(constant = 0.0) [double]

The constant for constant-valued boundary extension.

(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.

(nullval = 0.0) [double]

Value to substitute for any undefined pixels within the image.

(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.

(copyall=no) [boolean]

If true, all other extensions, including the primary array are copied to the output file.

(clobber = no) [boolean]

If true, an existing output file of the same name will be overwritten.

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.

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

BUGS

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