NAME

farith -- Read 2 input files and perform the arithmetic operations ADD, SUB, MUL, DIV and MIN & MAX


USAGE

        farith infil1 infil2 outfil ops

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.


PARAMETERS

infil1 [filename]

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.

infil2 [filename]

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.

outfil [filename]

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.

ops [string]

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.

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

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

(blank = 0) [real]
Value to use for integer NULLs. Also value to substitute for NULLs if NULL=no for any variable type.

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

(copyprime = yes) [boolean]
Whether to copy keywords from the primary array of infile1 (or infile2 if infile1 is a command-line vector).

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

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

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

(clobber = no) [boolean]
If true, an existing output file of the same name will be overwritten.


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

             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


BUGS


SEE ALSO

fcarith

CATEGORY

Nov97 ftools.fimage