NAME:
  dewarp

 PURPOSE:
  Transforms an image from (x,y) to ($\xi$,$\eta$) accounting for rotation and warping.

 DESCRIPTION:
  Transforms an image from the (x,y) coordinate plane to the ($\xi$,$\eta$)
  coordinate plane. If the image is rotated, the coefficients on the terms
  of the basis can be adjusted to perform the rotation. Photometric pixel
  values in the resulting image are obtained from interpolation if necessary.

 CATEGORY:
  Astrometry

 CALLING SEQUENCE:
  dewarp,ininfo,imgarr,outinfo,imgout,nx,ny

 INPUTS:
  ininfo - Image transformation structure that describes how the input
              image maps to the plane-of-the-sky.  See astxn2xy.pro for
              required information.  Note that this routine only uses
              the FULL transformation option.

           This structure can also be of the type generated from the
              Astronomy Users Libary routine, EXTAST.  If this structure
              is provided it will be automatically detected and ad2xy
              will be called instead of astrd2xy.

  imgarr - Input image (array)
  outinfo - Image transformation structure that describes how the output
              image maps to the plane-of-the-sky.  See astxn2xy.pro for
              required information.  Note that this routine only uses
              the FULL transformation option.
  imgout - Output image (array), may already exist and is added to if /ADD set
  nx     - xsize of the output image, if imgout exists and ADD is set then
              this value defaults to the existing size of imgout.  Without
              /ADD this value is required.
  ny     - ysize of the output image, if imgout exists and ADD is set then
              this value defaults to the existing size of imgout.  Without
              /ADD this value is required.

 OPTIONAL INPUT PARAMETERS:

 KEYWORD INPUT PARAMETERS:
  ADD - Flag, if set indicates the dewarped image should be added to the
           destination,
           Else the dewarped image will be copied to the destination.
  BILINEAR - Flag, if set force the interpolation to using a bilinear
                interpolation method.  If not set, attempts to do something
                similar to sinc interpolation.  Use this option for under
                sampled data.
  ROI     - Region of interest from master image that stack will be built
               to.  The default is to do it for the entire image.  Provide
               a 4-element vector [i0,j0,i1,j1] (lower left hand corner and
               upper right hand corner of region) to use this option.

 OUTPUTS:
  imgout - The transformed photometric array in (x,y) coordinates based on a
           cubic convolution resampling of the original photometric array using
           the transformed coordinates.

 KEYWORD OUTPUT PARAMETERS:
  COUNT - An optional output array with the same dimensions as imgout. Each
   element of the array indicates how many values have been added to the
   corresponding pixel. This information then can be used during an averaging
   process.

 COMMON BLOCKS:

 SIDE EFFECTS:

 RESTRICTIONS:
    There is as yet an unresolved issue with flux normalization between
      input and output images.  At the moment, the input and output should
      be regarded to be on separate photometric systems.
 PROCEDURE:

 MODIFICATION HISTORY:
  2009/11/04, Written by SwRI Clinic Team, Harvey Mudd College
  2009/11/14, MWB, rework with some new logic
  2010/02/28, MWB, minor change to reduce memory footprint
  2011/12/08, MWB, added option to support the Astronomy Users Library
                      tools for astrometric information on the input.
  2011/12/09, MWB, changed to use new astcvt tool.
  2011/12/12, MWB, fixed serious bug that generated incorrect output if
                      the output image was not square.
  2014/03/19, MWB, added BILINEAR keyword
  2016/04/11, MWB, added ROI keyword