%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990-2008 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                                          14-NOV-2008  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 300 frames is foreseen. This is an upper 
	  limit for the internal structures. In practice the max. number of
	  frames opened will be limited by FOPEN_MAX and the available memory.
            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 - it may be worth
          to convert the input images to the Midas internal format first.
            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
