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.
nx     - xsize of the output image, if imgout exists and ADD is set then
this value defaults to the existing size of imgout.  Without
ny     - ysize of the output image, if imgout exists and ADD is set then
this value defaults to the existing size of imgout.  Without

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.