idlastro / FITS Astrometry and Calibration: HROTATE

[Source code]

NAME
HROTATE
PURPOSE
Apply the IDL ROTATE function and update astrometry in a FITS header
EXPLANATION
Apply the intrinsic IDL ROTATE function to an image and update 
astrometry in the associated FITS header.
CALLING SEQUENCE
HROTATE, oldim, oldhd, newim, newhd, direction
          or
HROTATE, oldim, oldhd, direction 
INPUTS
OLDIM - the original image array                             
OLDHD - the original FITS image header, string array
DIRECTION - Scalar integer (0-7) specifying rotation direction, 
          exactly as specified by the IDL ROTATE function.
   Direction  Transpose?  Rot. CCW  X1  Y1 
  ---------------------------------------- 
  0          No          None     X0  Y0    (no change)
  1          No          90      -Y0  X0 
  2          No          180     -X0 -Y0 
  3          No          270      Y0 -X0 
  4          Yes         None     Y0  X0 
  5          Yes         90      -X0  Y0                   
  6          Yes         180     -Y0 -X0 
  7          Yes         270      X0 -Y0 
OPTIONAL OUTPUTS
NEWIM - the rotated image, with the same dimensions as Oldim 
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 rotated image and updated header.
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.               
EXAMPLE
Rotate an image exactly 90 degrees counterclockwise and update the
FITS image array and header. 
  IDL>  HROT, im, h, im_new, h_new, 1
PROCEDURE
The image array is rotated using the ROTATE function.
The CD (or CROTA) and CRPIX parameters, if present in the FITS header,
are updated for the new rotation.
History records are also added to the header
RESTRICTIONS
Does not work Guide Star Survey (GSS) astrometry.    Use GSSS_STDAST to
first convert 
PROCEDURES USED
CHECK_FITS(), SXADDPAR, EXTAST
MODIFICATION HISTORY
Written,  Mar 1997    W. Landsman,  Hughes STX
Work for non-square images   W. Landsman   June 1998 Raytheon STX
Fix for different plate scales, and CROTA2 defined, November 1998  
Added ERRMSG, Use double precision formatting, W. Landsman April 2000
Consistent conversion between CROTA and CD matrix W. Landsman Oct 2000
Correct update when CROTA keyword present W. Landsman  June 2003
Update CDELT for AIPS-style astrometry headers M. Perrin/WL Jul 2003
Convert GSS astrometry to WCS W. Landsman  November 2004
Work even if no astrometry present, just update NAXIS* WL June 2011
heck # of parameters
Check that input header matches input image
oes user want error msgs returned?
Check for valid 2-D image & header
Update astrometry info if it exists. If GSS astrometry is present, then
convert it to standard WCS astrometry
strometry parameters exist in header?
For non-square images, check if X and Y axes have been flipped
ransformation matrix format
noparams = 1. CROTA+CDELT type
pdate old image and header