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

tcalc