NAME:
  stacker
 PURPOSE:   (one line only)
  Stack (co-add) image while registering images.
 DESCRIPTION:
 CATEGORY:
  CCD data processing
 CALLING SEQUENCE:
  stacker,fnlist,xpos,ypos,image
 INPUTS:
  fnlist - String array of fits files to read, or, 3-d image array, for
           the raw images to be stacked.
  xpos   - Array of x-positions, one per frame of registration point.
  ypos   - Array of y-positions, one per frame of registration point.
 OPTIONAL INPUT PARAMETERS:
 KEYWORD INPUT PARAMETERS:
  ANCHORFRAME - Index into fnlist for the frame to be used as the anchor.
                  Default is the first frame.
  ANCHORPOS - [x,y] position to align registration point to, default is
                the position of the anchor object.
  BAD -       If specified, String array of fits files to read, or, 3-d image 
              array, for badmasks applying to the raw images to be stacked.
  CROP      - [x1,x2,y1,y2] region of image to save.  These values are
                in the pixel coordinate system of the anchor frame.
                Default is the full frame.
  EXTENSION - Image extension to read from image fits files.  This should be
                left off if the file is not a group fits file.  If it
                is a group fits file you will need to specify this number
                to get the right extension.
  JUSTMEDIAN - Only use median combination in avgclip call.
  LAYER  -      2-d subframe to read from image fits files. This should be
                left off if the files are  2-d fits files.  If they
                are 3-d cubes you will need to specify this number
                to get the right part of the image. This applies ONLY
                to IMAGE fits files- BAD mask files are always 2-d.
  JUSTMEDIAN - Only use median combination in avgclip call (ie if ROBUST
               keyword in force).
  NTOPCLIP - (default=0) How many of the brightest pixels to removed
             before the robust statistics.  (see medarr_mwb.pro)
  ROBUST    - Flag, if set requests that a robust average, via avgclip,
                  of the image stack be performed. If the number of images is 
                  2 then this keyword is ignored.

  SILENT    - Flag, if set will suppress all messages to screen.
  SUPERFRAME- Flag, if set, the images will be stacked onto a
              'superframe' which is sufficiently large so that all
              pixels in the individual images will be represented at
              least once. A special badmask is used to mask off unpopulated
              elements of the supercube being stacked.
  DEBUG     - Flag, if set turns on extra debug steps and other information.
                The debug information in not guaranteed to remain static
                from one verion of the program or another.
 OUTPUTS:
  image - Floating point array with stacked image
 KEYWORD OUTPUT PARAMETERS:
  OUTFILE - Name of file to write the image to.  This is output in FITS format
              and the header is derived from the first image with some
              modifications.
  IMAGESTACK   - use this to get the registered stack of individual frames
  STACKOFFSET- a 2 x n matrix giving the  X,Y offsets of each individual
                  frame in the stacked image. That is, stackoffset[*,j]
                  are the X,Y for the lower left corner of the jth frame
                  on the stacked image. Depending on the setting of 
                  SUPERFRAME and the explicit cropping parameters, this
                  may not be located within the dimensions of the stacked
                  image.
  STACKSIZE- a 2 element long vector giving the X,Y dimensions of the
                output stack and output image. In the absence of CROP and 
                SUPERFRAME keywords this will be the dimensions of the anchor 
                frame. 
  IMAGEMEAN - This is the mean of the output image background signal level
                as computed and used inside this routine.
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
 PROCEDURE:
 MODIFICATION HISTORY:
  Written by Marc W. Buie, Lowell Observatory, 2005/07/21
  2005/11/22, MWB, added DEBUG keyword
  2006/10/20, MWB, fixed missing keyword problems
  2007/07/09, MWB, added JUSTMEDIAN and STACK keywords
  2007/08/30, Peter L. Collins, Lowell Observatory, allow data cube as
              variant of fnlist, and fits file as variant of BAD. Add
              SUPERFRAME support and associated keywords.
  2007/09/07, MWB, incorporate into library to be consistent with newest
              avgclip and medarr_mwb, STACK keyword renamed to IMAGESTACK
  2012/12/16, MWB, added NTOPCLIP keyword