## NAME

imcalc -- Perform general arithmetic operations on images.

## USAGE

`imcalc input output equals`

## DESCRIPTION

Arithmetic operations are performed on one or more images,
and an output image is generated.
Operations are performed on all groups
unless a group specifier is explicitly part of the image name.
All input images must be of the same size, number of dimensions,
and number of groups.
The expression contains constants, variable names, or both.
Constants can be integers or floating point values
(exponential notation is allowed).
There are two kinds of variables: the first type represents
the first through eighth image and is named `im1` through `im8`,
the second type represents the index of the corresponding dimension,
and is named `x`, `y`, or `z`.
For example at pixel [12,100,2] in an image, `x=12`, `y=100`, and `z=2`.
The expression is evaluated according to the data types of the variables
and constants in the expression and then converted to the type of the
output image.

The following Fortran-type arithmetic operators are supported. If the second argument of the exponentiation is not an integer, the result will be undefined if the first argument is not positive. Remember that integer division truncates.

+ addition - subtraction * multiplication / division - negation ** exponentiation

The following logical operators are supported. Logical operators will return a value of 1 if true or 0 if false. Logical operators are supported in both their Fortran and SPP form.

Fortran SPP Operation ------------------------------------------ .or. || Logical or .and. && Logical and .eq. == Equality .ne. != Inequality .lt. < Less than .gt. > Greater than .le. <= Less than or equal .ge. >= Greater than or equal .not. ! Not

The following functions are supported. These functions all take a single argument, which may be an expression. The argument or result of trigonometric functions are in radians.

abs absolute value acos arc cosine asin arc sine atan arc tangent cos arc cosine cosh hyperbolic cosine cube third power double convert to double exp E raised to power int convert to integer log natural logarithm log10 common logarithm nint nearest integer real convert to real sin sine sinh hyperbolic sine sqr second power sqrt square root tan tangent tanh hyperbolic tangent

The following functions take two arguments.

atan2 arc tangent dim positive difference max maximum min minimum mod modulus sign sign transfer

Conditional expressions of the form "if expr then expr else expr" are supported. The expression after the "else" may be another conditional expression. The words "if", "then", and "else" must be surrounded by blanks.

## PARAMETERS

- input [file name template]
- The image names that are to be used in the arithmetic expression. These image names will be substituted for the corresponding strings "im1", etc., in the expression in the order that they occur in this parameter. All images (or sections) must be the same size, have the same number of dimensions, and number of groups.

- output [file name]
- Name of the output image file created by this task.
The header and data type of
`output`will be that of the first image in`input`.

- equals [string]
- The arithmetic expression to evaluate. If the expression is too long to pass as a parameter, place the expression in a file and set the value of this parameter to the file name preceded by an "@" character; for example, "@filename".

- (pixtype = "old") [string, allowed values: old | short | ushort | int |
- real | double ]
The pixel type of the output image. If the type is set to "old", the output image will have the same type as the first input image.

- (nullval = 0.0) [real]
- Whenever a calculation contains an illegal operation, this value is substituted for the result of the calculation. Examples of illegal operations are division by zero and taking the square root of a negative number.

- (verbose = yes) [boolean]
- Print a message showing the percent of the calculations done?

## EXAMPLES

1. Create a new image in which each pixel is equal to 10.0**(-x/2.5), where "x" represents the corresponding pixel value in the image file someimage.hhh. This is related to the conversion of stellar magnitude to flux.

im> imcalc someimage.hhh outim.hhh "10.0**(-im1/2.5)"

2. Replace all values above 200 with the value 200, and all values below 100 with 100.

im> imcalc image.fits outim.fits "min(200,max(im1,100))"

3. Take the average of three images:

im> imcalc image1,image2,image3 out.fits "(im1+im2+im3)/3."

4. Divide in1.fits by in2.fits, except that we want the result to be the value from in1.fits for any pixel where in2.fits is less than or equal to zero. Note that the following will not work as expected:

im> imcalc in1.fits,in2.fits out.fits \ "if im2 .gt. 0. then im1/im2 else im1"

The result will be the value from in1.fits where in2.fits is negative,
as intended, but it will be `nullval` where in2.fits is zero.
The division by zero takes precedence, in some sense, over the conditional.
This can be handled by a two-step process,
where a temporary image is created that is a copy of in2.fits
except that it is -1 where in2.fits is zero.

im> imcalc in2.fits temp.fits "if im1 .eq. 0. then -1. else im1" im> imcalc in1.fits,temp.fits out.fits \ "if im2 .gt. 0. then im1/im2 else im1"

5. Set the 4 border pixels in a 512 by 512 image to zero.
The expression is stored in the file `exp.dat`:

im> imcalc image.fits out.fits @exp.dat

The contents of `exp.dat` are:

if x .gt. 4 .and. x .lt. 509 .and. y .gt. 4 .and. y .lt. 509 then im1 else 0.0

## BUGS

When an expression involves an invalid operation,
such as divide by zero,
the result is likely to be `nullval` regardless of
conditional expressions that check for the invalid operation.
See the examples section for a specific example.

## SEE ALSO