NAME

imsum -- sum, average, or median images

USAGE

imsum input output

PARAMETERS

input

Input images.

output

Output image.

title = ""

Image title for the outpu image. If null ("") then the title of the first image is used.

hparams = ""

List of image header parameters to be summed or averaged. This feature is only used when summing or averaging and no correction is made for rejected pixels. It is primarily used to sum exposure times.

pixtype = ""

Pixel datatype for the output image. The pixel datatypes are "double", "real", "long", "integer", "ushort", and "short" in order of precedence. If null ("") then the calculation type is used. The datatypes may be abbreviated to a single character.

calctype = ""

Calculation type. The calculation types are "double", "real", "long", "integer", and "short" in order of precedence. If null ("") then the highest precedence datatype of the input images is used. If there is a mixture of "short" and "ushort" images then the highest precedence datatype will be "int". The calculation types may be abbreviated to a single character.

option = "sum"

Output options are "sum", "average", or "median". The "median" of an even number of images takes pixel nimages/2 + 1, where nimages is the number of images.

low_reject = 0

If the option is sum or average then when this parameter is less than 1 reject this fraction of low pixels from the sum or average otherwise reject this number of low pixels from the sum or average.

high_reject = 0

If the option is sum or average then when this parameter is less than 1 reject this fraction of high pixels from the sum or average otherwise reject this number of high pixels from the sum or average.

verbose = no

Print a log of the operation?

DESCRIPTION

The input images are summed, averaged, or medianed pixel by pixel and the result recorded in the output image. All input images must be the same size but not necessarily of the same pixel datatype. For the sum or average option a selected fraction or number of pixels may be rejected. The output option "average" divides the sum by the number of pixels in the sum. The pixel datatype of the output image may be selected or defaulted to the calculation datatype. The calculation type may be selected or defaulted to the highest precedence datatype of the input images. Note that a mixture of "short" and "ushort" images has a highest precedence datatype of "int". If all the image pixel datatypes are the same and agree with the calculation type then this operation is maximally efficient. However, beware of integer overflows with images of datatype short or ushort. A log of the task name, the input image names, the output image name, the output pixel datatype, the output option, and the pixel rejection parameters is printed when the verbose parameter is yes.

In addition to summing the pixels the specified image header parameters may be summed or averaged. This is primarily used for summing image exposure times. No correction is made for rejected pixels.

EXAMPLES

1. To sum three images:

im> imsum frame1,frame2,frame3 sum hparams="itime,exposure"

2. To make a median image of a set of images:

im> imsum obs* median option=median

where * is a template wildcard.

3. To reject the lowest and highest 2 pixels and average the rest:

im> imsum obs* avg option=average low=2 high=2

REVISIONS

IMSUM V2.11

Now allows "ushort" data types.

TIME REQUIREMENTS

The following timings are for 512 x 512 short images in which the output image is also short and the calculation type is short.

	    OPERATION		      CPU(sec)
	1. Sum of 3			 7.4
	2. Average of 3			13.0
	3. Median of 3			 9.9
	4. Sum of 5			13.0
	5. Median of 5			23.0
	6. Sum of middle 3 of 5		45.5
	7. Median of 7			77.8

NOTES

Any number of images may be used. However, there is a maximum number of images which may be open at one time. If the number of images (of dimension >= 2) exceeds this maximum and median or pixel rejection is used then the performance of this task will suffer due to the need to repeatedly open and close the excess images. The maximum number is a configurable paramenter in the include file "imsum.h".

This task has been largely replaced by the task imcombine . It is still available but may be removed in the future. Imcombine is specially designed to deal with the case of large numbers of images.

BUGS

It is an error for the output image to have the same name as an existing image. Beware of integer overflows when summing short images.

SEE ALSO

imcombine