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