idlastro / FITS Astrometry and Calibration: HCONGRID

[Source code]

NAME
HCONGRID
PURPOSE
CONGRID an image and update astrometry in a FITS header
EXPLANATION
Expand or contract an image using CONGRID and update the 
associated FITS header array.
CALLING SEQUENCE
HCONGRID, oldhd                       ;Update FITS header only
HCONGRID, oldim, oldhd, [ newim, newhd, newx, newy, /HALF_HALF
                          CUBIC = , INTERP=, OUTSIZE=, ERRMSG=, ALT= ]
INPUTS
OLDIM - the original image array
OLDHD - the original image FITS header, string array
OPTIONAL INPUTS
NEWX - size of the new image in the X direction
NEWY - size of the new image in the Y direction
        The OUTSIZE keyword can be used instead of the 
        NEWX, NEWY parameters
OPTIONAL OUTPUTS
NEWIM - the image after expansion or contraction with CONGRID
NEWHD - header for newim containing updated astrometry info
        If output parameters are not supplied, the program
        will modify the input parameters OLDIM and OLDHD
        to contain the new array and updated header.
OPTIONAL KEYWORD INPUTS
ALT - Single character 'A' through 'Z' or ' ' specifying which astrometry
    system to modify in the FITS header.    The default is to use the
    primary astrometry of ALT = ' '.    See Greisen and Calabretta (2002)
    for information about alternate astrometry keywords.
 CUBIC - If set and non-zero, then cubic interpolation is used.   Valid
         ranges are  -1 <= Cubic < 0.   Setting /CUBIC is equivalent to
         CUBIC = -1 and also equivalent to INTERP = 2.   See INTERPOLATE
         for more info.    Setting CUBIC = -0.5 is recommended.
 ERRMSG - If this keyword is supplied, then any error mesasges 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.               
 /HALF_HALF - Due to edge effects, the default behaviour of CONGRID is 
     to introduce a slight shift in the image center.  Craig Markwardt
     (http://cow.physics.wisc.edu/~craigm/idl/misc.html) has written
     a modified version of CONGRID called CMCONGRID that when used with
     the /HALF_HALF keyword eliminates any shift.   The use of the 
     /HALF keyword emulates CMCONGRID and eliminates any shift in the
     image centroid. 
 INTERP   - 0 for nearest neighbor, 1 for bilinear interpolation
         (default), 2 for cubic (=-1) interpolation.   
 OUTSIZE - Two element integer vector which can be used instead of the
         NEWX and NEWY parameters to specify the output image dimensions
OPTIONAL KEYWORD OUTPUT
ERRMSG - If this keyword is supplied, then any error mesasges 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.               
PROCEDURE
Expansion or contraction is done using the CONGRID function, unless
HALF_HALF is set. 
The parameters BSCALE, NAXIS1, NAXIS2, CRPIX1, and CRPIX2 and
the CD (or CDELT) parameters are updated for the new header.
NOTES
A FITS header can be supplied as the first parameter without having
to supply an image array.   The astrometry in the FITS header will be
updated to be appropriate to the specified image size.
If the FITS header contains astrometry from a ST Guide Star image,
then the astrometry will be converted to an approximately equivalent
tangent projection before applying CONGRID.
EXAMPLE
Congrid an 512 x 512 image array IM and FITS header H to size 300 x 300
using cubic interpolation.   Use the HALF_HALF keyword to avoid 
a shift of the image centroid
IDL> hcongrid, IM ,H, OUT = [300, 300], CUBIC = -0.5, /HALF
The variables IM and H will be modified to the new image size.
PROCEDURES CALLED
CHECK_FITS, CONGRID(), EXTAST, GSSS_STDAST, SXADDHIST, 
SXADDPAR, SXPAR(), ZPARCHECK
MODIFICATION HISTORY
Written, Aug. 1986 W. Landsman, STI Corp.
Added interp keywords, J. Isensee, July, 1990
Add cubic interpolation W. Landsman HSTX   January 1994
Recognize a GSSS FITS header   W. Landsman   June 1994
Fix case where header but not image supplied  W. Landsman  May 1995
Remove call to SINCE_VERSION()   W. Landsman   March 1996
Assume since IDL V3.5, add CUBIC keyword      W. Landsman   March 1997
Update BSCALE even if no astrometry present   W. Landsman   May 1997
Converted to IDL V5.0   W. Landsman   September 1997
Added HALF_HALF keyword  W. Landsman  February 2000
Added ERRMSG keyword, use double precision formatting W.L.  April 2000
Recognize PC00n00m astrometry format  W. Landsman   December 2001
Now works when both /INTERP and /HALF are set W. Landsman January 2002
Fix output astrometry for non-equal plate scales for PC matrix or
CROTA2 keyword, added ALT keyword.   W. Landsman May 2005
Update distortion parameters if present  W. Landsman January 2008
Don't update BSCALE/BZERO for unsigned integer W.Landsman Mar 2008
Write CRPIX as Double precision if necessary W. Landsman Oct 2012
heck # of parameters
Check for valid 2-D image & header
easures change in aspect ratio.
Update astrometry info if it exists
atio of pixel areas
Adjust the PC matrix if non-equal plate scales. See equation 187 in
Calabretta & Greisen (2002)
an no longer use the simple CROTA2 convention, change to PC keywords
Adjust BZERO and BSCALE for new pixel size, unless these values are used
to define unsigned integer data types.