idlastro / FITS Astrometry and Calibration: HEULER

[Source code]

NAME
HEULER 
PURPOSE
Change the coordinate system of a FITS header or astrometry structure
EXPLANATION
Converts a FITS header or a astrometry structure containing WCS (world 
coordinate system) information between celestial, ecliptic, and 
Galactic coordinates
CALLING SEQUENCE
HEULER, hdr, [/GALACTIC, /CELESTIAL, /ECLIPTIC, ALT_IN = , ALT_OUT=]  
               or
HEULER, astr, /GALACTIC, /CELESTIAL, /ECLIPTIC
INPUT/OUTPUT PARAMETERS
hdr - FITS header (string array) containing WCS information
                     or
Astr - Astrometry structure as extracted from a FITS header
      by extast.pro (See EXTAST for more info).
Header or astrometry structure will be modified by the program to 
contain astrometry in the new coordinates system.
REQUIRED INPUT KEYWORDS
One of the following exclusive keywords is *required*
/GALACTIC - Convert the header to Galactic coordinates
/CELESTIAL - Convert the header to celestial (RA & Dec) coordinates
/ECLIPTIC - Convert the header to ecliptic coordinates
OPTIONAL INPUT KEYWORDS
The following two keywords apply if the FITS header contains multiple
WCS keywords. See Section 3.3 of Greisen & Calabretta (2002, A&A, 395, 
1061) for information about alternate astrometry keywords.
ALT_IN -  single character 'A' through 'Z' or ' ' specifying an 
    alternate astrometry system present in the input FITS header.  The 
    default isto use the primary astrometry or ALT = ' '.   If /ALT_IN 
    is set, then this is equivalent to ALT_IN = 'A'.
ALT_OUT - single character specifying the alternate WCS keywords 
    to write the *output* astrometry.    If not specified, then ALT_OUT
    is set equal to ALT_IN.
RESTRICTIONS
Currently assumes that celestial and ecliptic coordinates are in
J2000.   Use HPRECESS if this is not the case.
ST Guide Star (DSS) image headers are first converted to a standard
tangent projection, prior to the coordinate conversion
METHOD
The algorithm used is described in Section 2.7 of Calabretta & Greisen
(2002, A&A, 395, 1077).    The CRVAL coordinates are transformed
directly using EULER.    The new LONPOLE and LATPOLE values are then
determined by transforming the pole of the new system to the old, and
converted to native coordinates using WCS_ROTATE. 
EXAMPLE
A FITS header, hdr, has a standard tangent projection WCS information.
Add an alternate 'G' Galactic projection.    Note that the original
WCS information will be left unchanged 
IDL> heuler, hdr, /Galactic, alt='G'
PROCEDURES USED
EULER, EXTAST, GSSS_STDAST, PUTAST, SXADDHIST, WCS_ROTATE
REVISION HISTORY
Written    W. Landsman                  June 2003
Use PV2 tag in astrometry structure rather than PROJP1 W. L. May 2004
Use double precision to compute new North pole  W.L. Aug 2005
Check for non-standard CTYPE value W.L. Sep 2012