%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990-2009 European Southern Observatory
%.IDENT      averagweig.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, AVERAGE/WEIGHTS
%.PURPOSE    On-line help file for the command: AVERAGE/WEIGHTS
%.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./WEIG
\es\co
AVERAGE/WEIGHTS						29-JUL-2009  KB
\oc\su
AVERAGE/WEIGHTS out = in_specs [merge] [null] 
	average weighted images
\us\pu
Purpose: 
          Calculate the weighted average of images - size of result frame is
          either the intersection or the union of all image sizes.
\up\sy
Syntax: 
          AVERAGE/WEIGHTS out = in_specs [merge] [null] 
\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;
\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;
             defaulted to the actual contents of keyword NULL(2)
\ap\sa
See also:
          AVERAGE/IMAGES, COMPUTE/WEIGHTS
\as\no
Note:
          The weights of the input frames are taken from real descriptor
          WEIGHT (of 1 element) of each frame, this descriptor may either be
          filled via the command WRITE/DESCR for each frame individually or 
          via the command COMPUTE/WEIGHTS for a group of frames.
          Undefined pixels result from non-overlapping areas when using the
          Merge option.
          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).
          Currently, 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.
          If you use FITS files directly, e.g. in your catalog, the limit is
          max. 20 FITS files. 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 weight sum 
          for each x,y position of the result frame.
\on\exs
Examples:
\ex
          AVERAGE/WEIGHTS av1 = ccd01,ccd02,ccdrbv,flata,flatb,flatc,flatd
           Compute weighted 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/WEIGHTS av1 = ccdflat.cat"
           would be an equivalent command.
\xe \sxe
