.. _saltfpmask:

**********
saltfpmask
**********


Name
====

saltfpmask -- Mask the pixels outside the circular entrance aperture in
a Fabry-Perot image.  The mask value may be a specified constant or the
biweight of the pixel values in a specified annulus of the image.

Usage
=====

saltfpmask images methodout prefix/suffix/outfile maskmethod maskvalue masklogfile logfile useconfig configfile verbose

Parameters
==========


*images*
    String. List of FITS images to prepare. Data can be provided as a
    comma-separated list, or a string with a wildcard
    (e.g. 'images=S20061210*.fits'), or a foreign file containing an ascii
    list of image filenames. For the ascii list option, the filename
    containing the list must be provided preceded by a '@' character,
    e.g. 'images=@listoffiles.lis'. The list can contain data files from
    multiple SALT instruments.

*outimage*
    String. A list of images. Data can be provided as a comma-separated
    list, or a string with a wildcard (e.g. 'outimages=rS20061210*.fits'), or
    a foreign file containing an ascii list of image filenames. For ascii
    list option, the filename containing the list must be provided
    preceded by a '@' character, e.g. 'outimages=@listoffiles.lis'. This list
    must be of the same size as the images argument list.

*outpref*
    String. If the outpref string is non-zero in length and contains
    characters other than a blank space, it will override any value of the
    outimages argument. Output file names will use the name list provided
    in the images argument, but adding a prefix to each output file
    defined by outpref. An absolute or relative directory path can be
    included in the prefix, e.g. 'outpref=/Volumes/data/p'.

*axc*
    Float. Estimate of the aperture central x pixel value.

*ayc*
    Float. Estimate of the aperture central y pixel value.

*arad*
    Float. Estimate of the image aperture radius in pixels.

*maskmethod*
    String. Method to determine the mask value. Either a 'constant' mask value or a value derived from a specified 'region'.

*maskvalue*
    Float. If the user chooses to mask the image with a particular value, the input the mask value.

*radi*
    Float. Inner radius for maskvalue calculation. If the user chooses to use a mask value drawn from the bi-weight of the pixel values in a specified annulus of the image, they will imput the inner and outer radii of of the region radi and rado and the routine will calculate the mask value derived from the specified annulus.

*rado*
    Float. Outer radius for maskvalue calculation. If the user chooses to use a mask value drawn from the bi-weight of the pixel values in a specified annulus of the image, they will imput the inner and outer radii of of the region radi and rado and the routine will calculate the mask value derived from the specified annulus.

*(clobber)*
    Hidden boolean. If set to 'yes' files contained within the outpath
    directory will be overwritten by newly created files of the same
    name.

*logfile*
    String. Name of an ascii file for storing log and error messages
    written by the task. The file may be new, or messages can also be
    appended to a pre-existing file.

*verbose*
    Boolean. Verbose (yes) or quiet (no) execution of the routine.

Description
===========

This program masks the pixels outside the circular entrance aperture in
a Fabry-Perot image.  The pixels are replaced with a specified constant
or the mean of a annulus of pixels values as specificied by the user.

The program will mask all pixels beyond the radius of
arad based on the center of the image being at axc, ayc.   If the user
selects maskmethod='constant', a constant value specified by maskvalue will
be used for all of the pixels.   If the user selects maskmethod='region', the mean
value for all of the pixels in the region between radi to rado will be used
to replace the pxiels.



Examples
========

1. To mask an image using input axc and axy parameters contained in the parameter file pfp.par::

    --> saltfpmask images=test.fits outimages=maskedtest.fits outpref=''
    maskmethod=r radi=500.0 rado=600.0 clobber=y logfile=salt.log verbose=yes

Time and disk requirements
==========================

Individual unbinned full frame RSS image files can be 112MB in
size. It is recommended to use workstations with a minimum of 512MB
RAM. On a linux machine with 2.8 Ghz processor and 2 Gb of RAM, one
2051x2051 image in 0.85 sec.

Bugs and limitations
====================

Send feedback and bug reports to salthelp@saao.ac.za

See also
========

 :ref:`TBD`