.help farith Nov97 ftools.fimage
.ih
NAME
farith -- Read 2 input files and perform the arithmetic operations
          ADD, SUB, MUL, DIV and  MIN & MAX
.ih
USAGE
farith infil1 infil2 outfil ops
.ih
DESCRIPTION
This task will read images from 2 different input FITS files (or
optionally vectors defined on the command line) and perform any one of
the operations ADD, SUB, MUL, DIV, MIN, MAX and write the output into
an output FITS file's primary array.  The arithmetic operation can
take place on images of arbitrary, and even different, dimensions.
When one image has a smaller (or absent) dimension, the image will be
expanded to the required size, cyclicly copying its terms.
In other words, the images "wrap-around" for out-of-bounds indices.
The output datatype is determined by the normal FORTRAN precedence,
unless the users specifies the type with the datatype parameter.  The
one exception is that by default, division has real output, even for
integer inputs.

.ih
PARAMETERS
.ls infil1 [filename]
.le
The name and extension of the FITS file containing the first input
image.  If the file does not exist, farith will try to interpret this
parameter as a comma-separated list of numbers to be used
as the first vector.  Unless the DIM1 parameter is defined, the vector
will be one-dimensional. The numbers are treated as reals.
.le
.ls infil2 [filename]
.le
The name and extension of the FITS file containing the second input image.
This cannot be the same file as INFIL1.  If the file does not exist,
farith will try to interpret this
parameter as a comma-separated list of numbers to be used
as the second vector.  Unless the DIM2 parameter is defined, the vector
will be one-dimensional. The numbers are treated as reals.  Both
filenames can be vectors.
.le
.ls outfil [filename]
.le
The name of the output FITS file.  The calculated image will
automatically be placed in the primary array.  If preceeded with a !,
an existing file of the same name will be overwritten.  The image's
dimensions will be the greater of the two input
vectors, considering each dimension separately.
.le
.ls ops [string]
.le
The requested type of calculation.  The value can be either the words
ADD, SUB, MUL, DIV, MIN or MAX or the mathematical symbols +, -, * or /.  Extra
characters on the words (MULT for example) are ignored.   The SUB operation 
is defined as infil1 - infile2, and the DIV operation is 
defined as infile1 / infile2.
.le
.ls (datatype = " ") [string]
The datatype (or bits/pixel) of the output image.  If blank or "-", 
defaults are to the
appropriate datatype:  int + short = int, int/int = real, etc.
Acceptable inputs are (b,8), (i,short,16), (j,integer,int,long,32),
(r,f,e,real,float,-32) and (d,double,-64).
.le
.ls (overflow = no) [boolean]
Whether to ignore the overflow and underflow in the output file.
If true, the overflow and underflow elements of the output image
array will be ignored and replaced with the maximum and minimum
of the corresponding data type. If false, these elements 
will throw an error and terminate the program. This option is only 
relevant for byte, short and integer images.
.le
.ls (blank = 0) [real]
Value to use for integer NULLs.  Also value to substitute for NULLs if
NULL=no for any variable type.
.le
.ls (null = no) [boolean]
Whether to write NULLs into the output file.  If true, NaN will be written for
real and double data types, and BLANK for integer and the values will be
flagged an NULLs by FITSIO.  If false, the value in
BLANK will be used for all data types, and the values will not be flagged
as NULLs by FITSIO.
.le
.ls (copyprime = yes) [boolean]
Whether to copy keywords from the primary array of infile1 (or infile2
if infile1 is a command-line vector).
.le
.ls (dim1 = "") [string]
New dimensions with which to interpret the first image.  This is
primarily intended to be used with a vector supplied on the command
line, although it can also be used to override dimensions defined in
the FITS file.  The number of data elements defined by the new
dimensions (ie, the factor of the dimensions) must be the same as are
present in the input.
.le
.ls (dim2 = "") [string]
New dimensions with which to interpret the second image.  This is
primarily intended to be used with a vector supplied on the command
line, although it can also be used to override dimensions defined in
the FITS file.  The number of data elements defined by the new
dimensions (ie, the factor of the dimensions) must be the same as are
present in the input.
.le
.ls (evenvec = yes) [boolean]
If true, the two input vectors must have dimensions which are even
multiples of each other, such as the vectors 10x20 and 5x4.  If a
vector needs to be expanded, then, the vector boundaries will always
be aligned.  If false,
the vectors will be wrapped without concern for mismatched bounds.
.le
.ls (clobber = no) [boolean]
If true, an existing output file of the same name will be overwritten.
.le
.ih
EXAMPLES 
1.  Read the image values of INFILE1 and INFILE2 and then write the
    sum into an output FITS file called OUTFIL.

    ft> farith INFILE1[0] INFILE2[0] OUTFIL +

2.  Multiply an image by a constant value.

    ft> farith INFILE1[0] 4.5 OUTFIL *

3.  Multiply each layer of a 3-D data cube by a different number.
    Note that if the input image contains only 1 layer, ie is a 2-D
    image, the result will still be a 3-D cube, but with each layer
    being the original single image multiplied by the different
    numbers.

    ft> farith image.fits 3.2,4.2,0.4,0.2 out.fits MUL dim2=1,1,4

4.  Create a meaningless 4x3 matrix of integers.

    ft> farith 1,2,4,8,7,6 1,2,3,4 out.fits SUB dim1=2,3 datatype=I

.nf
        produces:
                 1 2 1 2     1 2 3 4     0  0 -2 -2
                 4 8 4 8  -  1 2 3 4  =  3  6  1  4
                 7 6 7 6     1 2 3 4     6  4  4  2
.fi
.ih
BUGS
.ih
SEE ALSO
fcarith
.endhelp

