% @(#)averagimag.hlq 17.1.1.1 (ESO-IPG) 01/25/02 17:43:16 %++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ %.COPYRIGHT (c) 1990 European Southern Observatory %.IDENT averagimag.hlq %.AUTHOR KB, IPG/ESO %.KEYWORDS MIDAS, help files, AVERAGE/IMAGES %.PURPOSE On-line help file for the command: AVERAGE/IMAGES %.VERSION 1.0 12-OCT-1983 : Creation, KB %.VERSION 1.1 11-OCT-1991 : Update, KB %.VERSION 2.0 26-MAR-1992 : Complete overhaul, KB %---------------------------------------------------------------- \se SECTION./IMAG \es\co AVERAGE/IMAGES 01-FEB-2001 KB \oc\su AVERAGE/IMAGES out = in_specs [merge] [null] [av_option] [dat_intval] average images \us\pu Purpose: Calculate the average of images - size of result frame is either intersection or union of all image sizes. \up\sy Syntax: AVERAGE/IMAGES out = in_specs [merge] [null] [av_option] [dat_intval] \ys\pa out = result frame \ap\pa in_specs = specification of input frames, either in1,in2,...inj or catalog.cat = name of catalog containing the input frames or 3-dim image cube, averaging will be done over all xy-planes \ap\pa merge = M (for Merge), size of result frame will be set to the union of all input frames, else the size will be the intersection of all input frames; defaulted to N (No merge) \ap\pa null = value for undefined pixels, also the real keyword NULL(2) will be updated accordingly; if set to `+', undefined pixels are set to the value of the pixel calculated before; defaulted to the actual contents of keyword NULL(2) \ap\pa av_option = av_spec,av_low,av_hi,av_switch; av_spec - Average (a), Minimum (b), Maximum (c) or Median (d), (a) take average of of all valid pixels; (b) take minimum of of all valid pixels; (c) take maximum of of all valid pixels; for (b) + (c) av_low may be set to indicate that the average (instead of the min/max) should be taken of minimum/maximum and `av_low' next higher/lower pixels (d) take median of all valid pixels; for (d) av_low, av_hi may be set to indicate that the average (instead of the median) should be taken of all the pixels in an interval around the median pixel, to indicate if the interval refers to the indices (order) of the pixels or their values, av_switch is set to INDEX or DATA, if `av_switch' not given, it is used as INDEX; except for (d) with av_switch = DATA, `av_low' and `av_hi' must be non-negative values; defaulted to AV \ap\pa dat_intval = rlow,rhigh - optional interval for input pixels; if omitted (the default) all pixels in the input frames are used for the calculations \ap\sa See also: AVERAGE/WEIGHTS, AVERAGE/ROW, AVERAGE/WINDOW \as\no Note: Undefined pixels result from non-overlapping areas when using the Merge option or from the constraints specified in the average options and data interval. Overlapping areas will be determined via the world coordinates of the frames, i.e. via descriptors START and STEP. The input frames are all opened simultaneously to speed up the averaging process. Thus, the no. of frames we can work on depends on a system variable (FOPEN_MAX on Unix systems, stored in stdio.h). In `averag.exe' a max. of 64 frames is foreseen which is the value of FOPEN_MAX on many Unix systems. But since there are also other files open already (e.g. keyword file, logfile) the practical limit is about 54 files. However, if like in Solaris the max. no. of opened files is set to 20, only 12 or 13 frames can be opened simultaneously. Therefore, 54 is only the upper limit. If you use FITS files directly, e.g. in your catalog, please, keep in mind, that FITS files are always mapped totally into memory, so you could end up allocating a lot of memory... If the keyword MID$SPEC contains the string `DEBUG', a MIDAS image named `averdumy.dum' will be created containing the valid pixel count for each x,y position of the result frame. If av_option=median, the index of the median pixel is calculated as nopix/2 for even nopix (nopix = no. of pixels used) and (nopix+1)/2 for odd nopix. \on\exs Examples: \ex AVERAGE/IMAGES av1 = ccd01,ccd02,ccdrbv,flata,flatb,flatc,flatd Compute average of given input frames on their overlapping area. Size of result frame `av1.bdf' will be the overlapping part of all input frames. \\ If the above input frames had entries in the image catalog `ccdflat.cat', and only these, \\ "AVERAGE/IMAGES av1 = ccdflat.cat" would do the same... \\ If the above input frames had been all stored as the planes of a 3-dim image cube `bigcube.bdf', \\ "AVERAGE/IMAGES av1 = bigcube" would do the same... \xe\ex AVERAGE/IMAGES av1 = ccdflat.cat ? -99.9 min 0.3,7.23 Take minimum of input frames, but use only pixels in the interval [0.3,7.23] for finding the minimum. If for a pixel all corresponding input pixels are outside the given interval, the pixel is set to -99.9. \xe\ex AVERAGE/IMAGES av1 = ccdflat.cat ? -99.9 min,2 0.3,7.23 As above, but resulting pixel will be the average of the 3 lowest pixels. Less than 3 pixels may be used for the averaging depending upon how many valid pixels exist at a given x,y position of the result frame. \\ For example, if the first pixels in the 7 input frames had the values 1.0, 4.4, 2.1, 3.0, 2.0, 4.0, 5.6 then the first pixel in the result frame would be calculated as (1.0 + 2.0 + 2.1)/3 . \xe\ex AVERAGE/IMAGES av1 = ccdflat.cat ? -99.9 max,4 0.3,7.23 As above, but resulting pixel will be the average of the 5 highest pixels. \xe\ex AVERAGE/IMAGES av1 = ccdflat.cat ? + max,4 0.3,7.23 As above, but undefined pixels are set to the value of the pixel calculated before. If the very first result pixel is an undefined pixel, it is set to 0.0 . \xe\ex AVERAGE/IMAGES av1 = ccdflat.cat ? + median,1,2 0.3,7.23 As above, but resulting pixel will be the average of (if possible) the 4 pixels in the ordered interval [median-1,median+2]. Using the numbers from the example above, the first result pixel would be \\ (2.1 + 3.0 + 4.0 + 4.4)/4 = 3.375 (median is 3.0). \xe\ex AVERAGE/IMAGES av1 = ccdflat.cat ? + median,1,2,data 0.3,7.23 As above, but resulting pixel will be the average of all pixels within the interval [median_val-1.0,median_val+2.0]. Using the same numbers as above, the first result pixel would be \\ (2.0 + 2.1 + 3.0 + 4.0 + 4.4)/5 = 3.10 \xe\ex AVERAGE/IMAGES av2 = ccdflat.cat M 0.33 Compute average of given input frames on their combined area. Size of result frame `av2.bdf' will be the union of all frames with entries in image catalog `ccdflat.cat'. Undefined pixels are set to 0.33 \\ Here only pixels at x,y-positions with no corresponding input pixels are undefined, since parameters `av_option' and `dat_intval' are not given. \xe \sxe