idlastro / FITS Astrometry and Calibration: GETROT

[Source code]

NAME
GETROT
PURPOSE
Return the rotation and plate scale of an image from its FITS header
EXPLANATION
Derive the counterclockwise rotation angle, and the X and Y scale
factors of an image, from a FITS image header.   The input parameter 
may be either a FITS image header or an astrometry structure (as 
obtained by extast.pro)
CALLING SEQUENCE
GETROT, Hdr, [ Rot, CDelt, /SILENT, DEBUG =  ]   
        or 
GETROT, Astr, Rot, CDelt, /SILENT, DEBUG = ]       
INPUT PARAMETERS
HDR - FITS Image header (string array).  Program will extract the 
        astrometry structure
         or
ASTR -  ASTROMETRY structure, of the type returned by EXTAST.
        See the documentation for EXTAST.PRO for details.
OPTIONAL OUTPUT PARAMETERS
ROT - Scalar giving the counterclockwise rotation of NORTH in DEGREES 
        from the +Y axis of the image.
CDELT- 2 element vector giving the scale factors in DEGREES/PIXEL in 
        the X and Y directions.   CDELT[1] is always positive, whereas
        CDELT[0] is negative for a normal left-handed coordinate system,
        and positive for a right-handed system. 
If no output variables are supplied (or /DEBUG is set), then GETROT 
will display the rotation and plate scale at the terminal.
OPTIONAL INPUT KEYWORD
ALT - single character 'A' through 'Z' or ' ' specifying an alternate
      astrometry system present in the FITS header.   See extast.pro
      for more information on the ALT keyword.    Ignored if an
      astrometry structure rather than FITS header is supplied.
DEBUG - if DEBUG is set, GETROT will print the rotation for both the 
    X and Y axis when these values are unequal.  If DEBUG is set to 2, 
    then the output parameter ROT will contain both X and Y rotations.
/SILENT - if set, then do not provide a warning about a right-handed
    coordinate system
PROCEDURE
If the FITS header already contains CDELT (and CD or CROTA) keyword,
(as suggested by the Calabretta & Greisen (2002, A&A, 395, 1077) FITS 
standard) then this is used for the scale factor.
If the header contains CD keywords but no CDELT keywords (as in IRAF
headers) then the scale factor is derived from the CD matrix.
In case of skew (different rotations of the X and Y axes), the rotations
are averaged together if they are less than 2 degrees.   Otherwise,
a warning is given and the X rotation is used.  
PROCEDURES USED
EXTAST, GSSS_EXTAST
REVISION HISTORY
Written W. Landsman STX January 1987 
Option to return both rotations added.  J. D. Offenberg, STX, Aug 1991
Use new astrometry structure   W. Landsman  Mar 1994
Recognize a GSSS header        W. Landsman  June 1994
Correct rotation determination with unequal CDELT values WL October 1998
Consistent conversion between CROTA and CD matrix  WL  October 2000
Correct CDELT computations for rotations near 90 deg WL November 2002
Preserve sign in the CDELT output  WL June 2003
Check if latitude/longitude reversed in CTYPE  WL  February 2004
Fix problem in latitude check  M.Lombardi/W.Landsman Sep 2004
Added ALT keyword W. Landsman May 2005
Account for any rotation of the native system by examining the value
 of LONGPOLE       H. Taylor/W. Landsman
Account for case where X,Y rotations differ by 2*!pi WL. Aug 2011