NAME:
  frmdxdy
 PURPOSE:
  Given two lists of source on field, find the dx,dy offset between lists.
 DESCRIPTION:

 CATEGORY:
  Astrometry
 CALLING SEQUENCE:
  frmdxdy,x1,y1,x2,y2,xoff,yoff,error
 INPUTS:
  x1 - X coordinate from list 1, in pixels.
  y1 - Y coordinate from list 1, in pixels.
  x2 - X coordinate from list 2, in pixels.
  y2 - Y coordinate from list 2, in pixels.
 OPTIONAL INPUT PARAMETERS:

 KEYWORD INPUT PARAMETERS:
  NX - maximum extent in X to consider (default is max([x1,x2]))
  NY - maximum extent in Y to consider (default is max([y1,y2]))
  MAXERR - maximum error allowed in initial spread test of position.
              (default=3)
  FNDRAD - Size of the aperture used for the final offset measurement.
              DEFAULT VALUE = 12 pixels
           The default is provided based on its historical value.  In most
              cases this appears to work pretty well and should generally
              be left alone.  However, some data have been seen to get
              confused with a value that is this big.  Changing this value
              will require knowing a better value for a specific dataset.
  SCALEFAC - Scaling factor to apply on the initial crude offset.  The
               default is 1.0.  This control is used for images where the
               pixel scale is very oversampled and very small on an absolute
               astrometric basis.  One particular case where this was
               needed is in Magellan IMACS f/4 data where the image scale
               is 0.111 arcsec/pixel.  With seeing of 1 arcsec the offset
               calculation does not get a good correlation peak.  Binning
               the result makes the peak sharper and easier to find.  For
               this case a scalefactor of 0.5 or 0.3 worked quite well.

 OUTPUTS:
  xoff - X offset (2-1) between positions in each list.
  yoff - Y offset (2-1) between positions in each list.
  error - Code, set if something went wrong in correlating the lists.
            0 - everything appears to be good.
            1 - failure during input validation
            2 - spread in the initial x offset is too big (>maxerr)
            3 - spread in the initial y offset is too big (>maxerr)
            4 - correlation spot has negative "flux" or fwhm
            5 - Final pass on x offset excluded all points in robomean
            6 - Final pass on y offset excluded all points in robomean
            7 - All of the final pass x offsets were bigger than 1.5*xsize
 KEYWORD OUTPUT PARAMETERS:
    FOM - Figure of merit, a number than can be used (differentially) to
           measure how good the spatial correlation is.  This number is
           approximately the fraction of objects in the shortest list that
           ended up spatially correlated.  A number close to 1 should be
           good.
   INDEX- index into list 2 for points in list1, ie, list2[index[i]] is the
         closest, or one of a group of closest points, in list 2 to the
         ith element of list 1, given the xoff, yoff determined.
         If SPATIAL is specified, elements of the index may be invalidated
         by setting to -1- these represent invalid matches from list 1.
         On return, if error is set, the index output should be ignored.
 SPATIAL- Filtering parameters to frmdxdy - a vector or scalar of either 1 
           or 2 elements- the first is the max distance in pixels from the
           mean correlation dx,dy for a match to be valid, and the 2nd is
           the maximum threshold in sigma from the mean correlation dx,dy
           for a match to be valid. If SPATIAL is specified, invalid matches
           will be excluded (via an initial distance test and robomean) from 
           both the IDX 
           outputs and the final dx,dy result- if not specified, the distance
           and sigma criteria will be defaulted by frmdxdy.  In this case, 
           invalid matches will be excluded from the final dx,dy result but
           INCLUDED in the IDX output. Note that if only the first element of
           SPATIAL is specified, the second is defaulted to 3.0. The default
           assumed for spatial[0] is 3.0.

 COMMON BLOCKS:

 SIDE EFFECTS:

 RESTRICTIONS:
 It is conventional (and faster) for list 1 to be the shorter
 of the two lists.   Success is independent of the order in which lists 
 are presented, although if list 1 is longer than list 2, the index generated
 will not be unique (many->1).

 PROCEDURE:

 MODIFICATION HISTORY:
  99/03/22, Written by Marc W. Buie, Lowell Observatory
  2005/06/21, MWB, changed called to robomean to trap errors.
  2007/11/21, MWB, merged with alternate code buried in astrom.pro
  2009/07/23, MWB, modified so that x,y input arrays do not have to be
                    positivie definite.
  2009/07/24, MWB, added XOUT,YOUT optional output.
  2010/02/14, MWB, merged with alternate version from Peter Collins, this
                     brings in the INDEX and SPATIAL keywords.
  2010/07/19, MWB, minor tweak to ensure that the error flag is set for
                     all cases of premature return.  Added FNDRAD keyword.
  2012/12/03, MWB, error code 3 never returned, fixed.
                     Added SCALEFAC keyword