NAME

ftpixcalc - create a new FITS image from a combination one or more input images.

USAGE

ftpixcalc outfile expr a=image1.fits b=image2.fits ...

DESCRIPTION

ftpixcalc is a general image calculator program that creates a new output FITS image from a mathematical combination of one or more input FITS images. Each pixel value in the output image is calculated as a function (only) of the corresponding pixel in each of the input images. Note that if the output image value depends in some way on the location of the pixel in the image (either in pixel or world coordinates) then the ftimgcalc program should be used instead of ftpixcalc. The main advantage for using ftpixcalc is that it requires a smaller amount of computer memory, and in principle at least, may run faster than ftimgcalc.

The mathematical expression, given by the expr parameter, may be an arbitrarily complex function of the input image values. By default, the input images are represented in the expression by the letters a, b, c, etc. For example to add the first 2 images and divide the sum by a third image, the expression would be "(a+b)/c". One can also define more meaningful names for the images, and then use those names in the expression, as shown in the following example,

    ftpixcalc out.fits 'DATA-MODEL' a="DATA=in1.fits" b="MODEL=in2.fits"
Here the names 'DATA' and 'MODEL' are used in the expression to represent the 2 input images.

The expression may contain conditional logic as long as the expression as a whole evaluates to a numeric value. A C-like syntax is used for the if-then-else conditional expressions:

    (expression1 ? expression2 : expression3)
If expression1 evaluates to true (not zero) then expression2 is evaluated, otherwise expression3 is evaluated. This usage is further illustrated in the Examples section of this help file. For a complete list of the functions that are allowed in the expression, see the calc_express help file.

The output image will have the same dimensions as the first input image (given by the 'a' parameter). All the header keywords in this first image are copied to the output image. By default, the output image will have the same data type (as given by the BITPIX keyword) as the first image, but this can be overridden using the bitpix parameter. Any other FITS extensions in the input files are ignored, so the output FITS file always consists of only a primary array image, with no following FITS extensions.

Under normal circumstances, all the input images will have the same size dimensions, however if any of the images have fewer total number of pixels than in the first image, those images will be effectively padded out with NULL pixels when calculating the pixel values in the output image.

Note: For simple expressions involving only a single input image, CFITSIO's on-the-fly pixel filtering capabilities can be used instead of ftpixcalc or ftimgcalc (see the pixfilter help file). For example

    ftcopy 'infile.fits[pix sqrt(x)]' outfile.fits
computes the square root of each input pixel value (in this case, the letter 'x' is used to represent the input image pixel value) and copies it to the output file.

PARAMETERS

outfile [filename]
The name of the output image file.

expr [string]
An arbitrary mathematical expression used to calculate the value of the pixels in the output image. By default the letters 'a', 'b', 'c', etc, are used to represent the value of the corresponding pixel in each input image, however, alternate image names may be assigned when specifying the name of each input file (see the description of the next parameter).

(letters a - z = "NONE") [string] (26 individual parameters)
input filename (and optional extension name or number enclosed in square brackts) for up to 26 input FITS images. The names of these parameters are 'a' to 'z', as in 'a=image1.fits' and 'b=image2.fits'. In this case the letters 'a' and 'b' are used in the calculator expression to represent the pixel value in each image.

One may optionally specify a mnemonic name for each image, as in a="DATA=infile.fits" b="MODEL=infile2.fits" (note that the quotes are required in this case). The mnemonic names are then used in the calculator expression to represent each image. The mnemonic names are interpreted as case-insensitive.

The 'f' and 't' filename parameters must always be used with the additional mnemonic name because otherwise these 2 characters would be interpreted as the Boolean TRUE or FALSE value by the parser of the input 'expr' mathematical expression.

(bitpix = 0) [integer]
BITPIX data type code value for the output image. Allowed values are 0 (use the same BITPIX value as in the first input image), 8 (unsigned byte), 16 (signed 2-byte integer), 32 (signed 4-byte integer), -32 (single precision 4-byte floating point) or -64 (double precision floating point).
(bunit = "NONE") [string]
value for the optional BUNIT keyword in the output image that describes the physical units of the pixel values. If the value is 'NONE' then the keyword will not be written (or modified if it was already copied from the the first input file).
(clobber = no) [boolean]
Overwrite existing output files?
(chatter = 1) [integer, 0 - 5]
Standard HEAdas verbosity parameter.
(history = yes) [boolean]
Write parameter history?

EXAMPLES

1. Sum the two images i1.fits and i2.fits


    ftpixcalc output.img A+B a=i1.fits  b=i2.fits
2. Sum the 5th and 6th image extensions from the same input file

    ftpixcalc output.img A+B a='in.fits[5]'  b='in.fits[6]'
3. Compute the absolute value of the function (a-b)/c, where each of the terms are input images.

    ftpixcalc output.img "ABS((a-b)/c)" \
      a="data.fits b=model.fits c=error.fits
4. Same as the previous example except it uses more meaningful names in the expression, and it forces the data type of the output image to be single precision floating point (BITPIX = -32).

    ftpixcalc output.img "ABS((DATA-MODEL)/ERROR)" \
      a="DATA=data.fits" b="MODEL=model.fits" c="ERROR=error.fits" \
      bitpix=-32
5. Example of a conditional expression which copies the pixel value from either the 'a' or the 'b' image to the output image depending on whether or not the value in the 'c' image (which effectively serves as a mask) is greater than zero.

    ftpixcalc output.img "c>0 ? a : b" a=in1.fits b=in2.fits c=mask.fits
6. Copy the input image, but change any pixels that have a value less than zero to the FITS null value (a reserved IEEE NaN "not-a-number" value in the case of floating point images). Note: if the output image has an integer data type, then the BNULL keyword must exist in the image header to define what integer value to use to represent null pixels.

    ftpixcalc output.img "a<0 ? #NULL : a" a=in.fits bitpix=-32
7. Copy the input image, but reset any null pixels to have a value of -99.

    ftpixcalc output.img "isnull(a) ? -99 : a" a=in.fits

SEE ALSO

ftimgcalc, pixfilter, calc_express, filenames

LAST MODIFIED

May 2006