idlastro / FITS Astrometry and Calibration: HASTROM

[Source code]

NAME
HASTROM
PURPOSE
Transformation of an image to align it with a reference image
EXPLANATION
A  transformation is applied (using POLY_2D) to an image so that   
its astrometry is identical with that in a reference header.  This
procedure can be used to align two images.
CALLING SEQUENCE
HASTROM, oldim, oldhd, newim, newhd, refhd, [MISSING =, INTERP = ]
                     or
HASTROM, oldim, oldhd, refhd, [MISSING =, INTERP ={0,1,2}, NGRID =, 
                               CUBIC =, DEGREE = ]
INPUTS
OLDIM - Image array to be manipulated.  If only 3 parameters are
        supplied then OLDIM and OLDHD will be modified to contain 
        the output image array and header
OLDHD - FITS header array for OLDIM, containing astrometry parameters
REFHD - Reference header, containing astrometry parameters.  OLDIM
        will be rotated, shifted, and compressed or expanded until
        its astrometry matches that in REFHD.
OUTPUTS
NEWIM - Image array after transformation has been performed.
        The dimensions of NEWIM will be identical to the NAXIS1 and 
        NAXIS2 keywords specified in REFHD.  Regions on the reference 
        image that do not exist in OLDIM can be assigned a value with
        the MISSING keyword.
NEWHD - Updated FITS image header associated with NEWIM
OPTIONAL INPUT KEYWORDS
CUBIC - a scalar value between -1 and 0 specifying cubic interpolation
        with the specified value as the cubic interpolation parameter.
       (see poly_2d for info).    Setting CUBIC to a value greater 
        than zero is equivalent to setting CUBIC = -1. 
DEGREE - Integer scalar specifying the degree of the transformation.
        See the routine POLYWARP for more info.   Default = 
        1 (linear transformation) unless polynomial ('SIP') distortion 
        parameters are present in either the input or reference FITS
        header.    In that case, the default degree is equal to the
        degree of the distortion polynomial.
INTERP - Scalar, one of 0, 1, or 2 determining type of interpolation
        0 nearest neighbor, 1 (default) bilinear interpolation, 
        2 cubic interpolation.
MISSING - Set this keyword to a scalar value which will be assigned
        to pixels in the output image which are out of range of the
        supplied imput image.  If not supplied, then linear 
        extrapolation is used.   See the IDL manual on POLY_2D.
        ***NOTE: A bug was introduced into the POLY_2D function in IDL 
        V5.5 (fixed in V6.1) such that the MISSING keyword
        may not work properly with floating point data***
NGRID -  Integer scalar specifying the number of equally spaced grid 
        points on each axis to use to specify the transformation.   
        The value of NGRID must always be greater than DEGREE + 1.
        The default is DEGREE + 2 which equals 3 (9 total points) for
        DEGREE=1 (linear warping).
SILENT - If set, then some informational error messages are suppressed.
OPTIONAL OUTPUT KEYWORD
ERRMSG - If this keyword is supplied, then any error messages will be
        returned to the user in this parameter rather than depending on
        on the MESSAGE routine in IDL.   If no errors are encountered
        then a null string is returned.               
NOTES
(1) The 3 parameter calling sequence is less demanding on virtual 
        memory.
(2) The astrometry in OLDHD will be precessed to match the equinox
         given in REFHD.
(3) If an ST Guidestar image is used for the reference header, then the
         output header will be converted to standard astrometry.  
EXAMPLE
Suppose one has an image array, IM, and an associated FITS header H.
One desires to warp the image array so that it is aligned with another
image with a FITS header, HREF.    Both headers contain astrometry info.
Set pixel values to 0 where there is no overlap between the input and
reference image, and use linear interpolation (default)
IDL> hastrom, IM, H, HREF, MISSING = 0
PROCEDURES USED
ad2xy, check_FITS, extast, get_EQUINOX(), gsssextast, hprecess,
putast, sxaddpar, sxaddhist, sxpar(), xy2ad, zparcheck
REVISION HISTORY
Written  W. Landsman, STX Co.              Feb, 1989
Updated to CHECK_FITS                      Dec, 1991
New astrometry keywords                    Mar, 1994
Recognize GSSS header   W. Landsman        June, 1994
Added CUBIC keyword     W. Landsman        March, 1997
Accept INTERP=0, Convert output GSS header to standard astrometry
                        W. Landsman        June 1998
Remove calls to obsolete !ERR system variable   March 2000
Added ERRMSG output keyword  W. Landsman    April 2000
Need to re-extract astrometry after precession  W. Landsman Nov. 2000
Check for distortion parameters in headers, add more FITS HISTORY
information                        W. Landsman   February 2005
Use different coefficient for nearest neighbor to avoid half-pixel
shift with POLY_2D      W. Landsman   Aug 2006
Return ERRMSG if no overlap between images  W. Landsman  Nov 2007
Use V6.0 notation  W. Landsman  Jan 2012