.help fmaskfilt Apr93 ftools.fimage
.ih
NAME
fmaskfilt --  Filter an event list based on an input mask image
.ih
USAGE
fmaskfilt infile maskfile outfile
.ih
DESCRIPTION

This task will create a new event list containing only events which
fall in the include regions (any value not equal to zero)
of the input mask file.  Since the mask file
is in pixel coordinates rather than the coordinates of the events file,
FMASKFILT will translate the values using the keywords: CRVALn, CRPIXn
and CDELTn, as well as the names of the columns corresponding to the
axes of the mask (XCOLNAME and YCOLNAME).  The task F2DHISTO writes
the correct values of these keywords in the primary array header.
If keywords are
missing from the primary header of the input imagefile, they
can be supplied to this task via hidden parameters.  The default
hidden parameters correspond to no transformation.  If the keywords
are present in the mask file, the hidden parameter values are
ignored.
.ih
PARAMETERS
.ls infile [filename]
The name and extension of the input events file to be filtered.
.le
.ls maskfile [filename]
The name and extension of the file containing the mask.  
The default extension is the primary array.
.le 
.ls outfile [filename] 
The name of the output filtered events file.
.le
.ls (xcolname="X") [string]
The name of the column corresponding to the X axis of the mask.
.le
.ls (ycolname = "Y") [string]
The name of the column corresponding to the Y axis of the mask.
.le
.ls (crval1 = 1.) [real]
Coordinate value of X reference pixel
.le
.ls (crval2 = 1.) [real]
Coordinate value of Y reference pixel
.le
.ls (crpix1 = 1.) [real]
X axis reference pixel number
.le
.ls (crpix2 = 1.) [real]
Y axis reference pixel number
.le
.ls (cdelt1 = 1.) [real]
X axis coordinate increment
.le
.ls (cdelt2 = 1.) [real]
Y axis coordinate increment
.le
.ls (inverse = no) [boolean]
Whether to use the mask as an inverse filter,i.e., take the events 
whose positions corresponding to the zero pixels. 
filtered file.
.le
.ls (copyprime = yes) [boolean]
Whether to copy the primary header from the input events file to the output
filtered file.
.le
.ls (copyall = yes) [boolean]
Whether to copy all other extension from the input events file to the output
filtered file.
.le
.ls (clobber = no) [boolean]
If true, an existing output file of the same name will be overwritten.

.ih
EXAMPLES
1.  Filter in event file allevent.fits with the mask in the primary array
of mask.fits, and write it to the file filtered.fits
.nf

     ft> fmaskfilt allevent.fits mask.fits filtered.fits
.fi
.ih
BUGS
.ih
SEE ALSO
fmrgmsk, f2dhisto
.endhelp
