.help imarith Sep86 images.imutil
.ih
NAME
imarith -- binary image arithmetic
.ih
USAGE	
imarith operand1 op operand2 result
.ih
PARAMETERS
.ls operand1, operand2
Lists of images and constants to be used as operands.
Image templates and image sections are allowed.
.le
.ls op    
Operator to be applied to the operands.  The allowed operators
are "+", "-", "*", "/", "min", and "max".
.le
.ls result
List of resultant images.
.le
.ls title = ""
Title for the resultant images.  If null ("") then the title is taken
from operand1 if operand1 is an image or from operand2 otherwise.
.le
.ls divzero = 0.
Replacement value for division by zero.  When the denominator is zero
or nearly zero the result is replaced by this value.
.le
.ls hparams = ""
List of header parameters to be operated upon.  This is primarily
used for adding exposure times when adding images.
.le
.ls pixtype = "", calctype = ""
Pixel datatype for the resultant image and the internal calculation datatype.
The choices are given below.  They may be abbreviated to one character.
.ls ""    
\fICalctype\fR defaults to the highest precedence operand datatype.  If the
highest precedence datatype is an integer type and the operation is
division then the calculation type will be "real".  If the highest
precedence operand is type "ushort", \fIcalctype\fR will default to
"long".  \fIPixtype\fR defaults to \fIcalctype\fR. Users who want type
"ushort" images on output will need to set \fIpixtype\fR to "ushort"
explicitly.
.le
.ls "1", "2"
The pixel datatype of the first or second operand.
.le
.ls "short", "ushort", "integer", "long", "real", "double"
Allowed IRAF pixel datatypes.
.le
.le
.ls verbose = no
Print the operator, operands, calculation datatype, and the resultant image
name, title, and pixel datatype.
.le
.ls noact = no
Like the verbose option but the operations are not actually performed.
.le
.ih
DESCRIPTION
Binary image arithmetic is performed of the form:

	operand1 op operand2 = result

where the operators are addition, subtraction, multiplication,
division, and minimum and maximum.  The division operator checks for
nearly zero denominators and replaces the ratio by the value specified
by the parameter \fIdivzero\fR.  The operands are lists of images and
numerical constants and the result is a list of images.  The number of
elements in an operand list must either be one or equal the number of
elements in the resultant list.  If the number of elements is one then
it is used for each resultant image.  If the number is equal to the
number of resultant images then the elements in the operand list are
matched with the elements in the resultant list.  The only limitation
on the combination of images and constants in the operand lists is that
both operands for a given resultant image may not be constants.  The
resultant images may have the same name as one of the operand images in
which case a temporary image is created and after the operation is
successfully completed the image to be replaced is overwritten by the
temporary image.

If both operands are images the lengths of each axis for the common
dimensions must be the same though the dimensions need not be the
same.  The resultant image header will be a copy of the operand image
with the greater dimension.  If the dimensions are the same then image
header for the resultant image is copied from operand1.  The title of
the resultant image may be changed using the parameter \fItitle\fR.
The pixel datatype for the resultant image may be set using the
parameter \fIpixtype\fR.  If no pixel datatype is specified then the
pixel datatype defaults to the calculation datatype given by the
parameter \fIcalctype\fR.  The calculation datatype defaults to the
highest precedence datatype of the operand images or constants except
that a division operation will default to real for integer images.
The precedence of the datatypes, highest first, is double,
real, long, integer, and short.  The datatype of a constant operand is
either short integer or real.  A real constant has a decimal point.

Arithmetic on images of unequal dimensions implies that the operation
is repeated for each element of the higher dimensions.  For example
subtracting a two dimensional image from a three dimensional image
consists of subtracting the two dimensional image from each band of the
three dimensional image.  This works for any combination of image
dimensions.  As an extreme example dividing a seven dimensional image
by a one dimension image consists of dividing each line of each plane
of each band ... by the one dimensional image.

There are two points to emphasize when using images of unequal
dimensions.  First, a one dimensional image operates on a line
of a two or higher dimension image.  To apply a one dimensional image
to the columns of a higher dimensional image increase the image
dimensionality with \fBimstack\fR, transpose the resultant image,
and then replicate the columns with \fBblkrep\fR (see the EXAMPLE
section).  The second point of confusion is that an image with a
size given by \fBimheader\fR of [20,1] is a two dimensional image
while an image with size of [20] is a one dimensional image.  To
reduce the dimensionality of an image use \fBimcopy\fR.

In addition to operating on the image pixels the image header parameters
specified by the list \fIhparams\fR are also operated upon.  The operation
is the same as performed on the pixels and the values are either the
values associated with named header parameters or the operand constant
values.  The primary purpose of this feature is to add exposure times
when adding images.

The verbose option is used to record the image arithmetic.  The output
consists of the operator, the operand image names, the resultant image
name and pixel datatype, and the calculation datatype.
.ih
EXAMPLES
1. To add two images and the exposure times:

.nf
	cl> imarith ccd1 + ccd2 sum
	>>> hparams="itime,otime,ttime,exposure"
.fi

2. To subtract a constant from an image and replace input image by the
subtracted image:

	cl> imarith m31 - 223.2 m31

Note that the final pixel datatype and the calculation datatype will be at
least of type real because the constant operand is real.

3. To scale two exposures, divide one by the other, and extract the central
portion:

.nf
	cl> imarith exp1[10:90,10:90] * 1.2 temp1
	cl> imarith exp2[10:90,10:90] * 0.9 temp2
	cl> imarith temp1 / temp2 final title='Ratio of exp1 and exp 2'
	cl> imdelete temp1,temp2
.fi

Note that in this example the images temp1, temp2, and final will be
of real pixel datatype (or double if either exp1 or exp2 are of pixel
datatype double) because the numerical constants are real numbers.

4. To divide two images of arbitrary pixel datatype using real arithmetic
and create a short pixel datatype resultant image:

.nf
	cl> imarith image1 / image2 image3 pixtype=short  \
	>>> calctype=real title="Ratio of image1 and image2"
.fi

5. To divide several images by calibration image using the image pixel type of
the numerator images to determine the pixel type of the calibrated images
and the calculation arithmetic type:

.nf
	cl> imarith image1,image2,image3 / calibration \
	>>> image1a,image2a,image3a pixtype=1 calctype=1
.fi

The same operation can be done in place with image template expansion by:

.nf
	cl> imarith image* / calibration image* pixtype=1 calctype=1
.fi

6. To subtract a two dimensional bias from stacked observations (multiple
two dimensional observations stacked to form a three dimensional image):

	cl> imarith obs* - bias obs*//b

Note that the output observations obs101b, ..., will be three dimensional.

7. To divide a 50 x 50 image by the average column:

.nf
	cl> blkavg img avcol 50 1
	cl> blkrep avcol avcol 50 1
	cl> imarith img / avcol flat
.fi

8. To subtract a one dimensional image from the lines of a two dimensional
image:

	cl> imarith im2d - im1d diff

9. To subtract a one dimensional image from the columns of a two dimensional
image:

.nf
	cl> imstack im1d imcol
	cl> imtranspose imcol imcol
	cl> blkrep imcol imcol 100 1
	cl> imarith im2d - imcol diff
.fi

Note the need to make a two dimensional image with each column
replicated since a one dimensional image will operate on the lines
of a two dimensional image.
.ih
SEE ALSO
blkrep, imdivide, imfunction, imstack, imtranspose
.endhelp
