EXTAST
Name
EXTAST
Purpose
Extract ASTrometry parameters from a FITS image header.
Explanation
Extract World Coordinate System information
( http://fits.gsfc.nasa.gov/fits_wcs.html ) from a FITS header and
place it into an IDL structure.
Calling Sequence
EXTAST, hdr, [ astr, noparams, ALT= ]
Input
HDR - variable containing the FITS header (string array)
Outputs
ASTR - Anonymous structure containing astrometry info from the FITS
header ASTR always contains the following tags (even though
some projections do not require all the parameters)
.NAXIS - 2 element array giving image size
.CD - 2 x 2 array containing the astrometry parameters CD1_1 CD1_2
in DEGREES/PIXEL CD2_1 CD2_2
.CDELT - 2 element double vector giving physical increment at the
reference pixel
.CRPIX - 2 element double vector giving X and Y coordinates of reference
pixel (def = NAXIS/2) in FITS convention (first pixel is 1,1)
.CRVAL - 2 element double precision vector giving R.A. and DEC of
reference pixel in DEGREES
.CTYPE - 2 element string vector giving projection types, default
['RA---TAN','DEC--TAN']
.LONGPOLE - scalar giving native longitude of the celestial pole
(default = 180 for zenithal projections)
.LATPOLE - scalar giving native latitude of the celestial pole default=0)
.PV2 - Vector of projection parameter associated with latitude axis
PV2 will have up to 21 elements for the ZPN projection, up to 3
for the SIN projection and no more than 2 for any other
projection
.DISTORT - optional substructure specifying any distortion parameters
currently implemented only for "SIP" (Spitzer Imaging
Polynomial) distortion parameters
NOPARAMS - Scalar indicating the results of EXTAST
-1 = Failure - Header missing astrometry parameters
1 = Success - Header contains CROTA + CDELT (AIPS-type) astrometry
2 = Success - Header contains CDn_m astrometry, rec.
3 = Success - Header contains PCn_m + CDELT astrometry.
4 = Success - Header contains ST Guide Star Survey astrometry
(see gsssextast.pro )
Optional Input/output Keywords
ALT - single character 'A' through 'Z' or ' ' specifying an alternate
astrometry system present in the FITS header. The default is
to use the primary astrometry or ALT = ' '. If /ALT is set,
then this is equivalent to ALT = 'A'. See Section 3.3 of
Greisen & Calabretta (2002, A&A, 395, 1061) for information about
alternate astrometry keywords. If not set on input, then
ALT is set to ' ' on output.
Procedure
EXTAST checks for astrometry parameters in the following order:
(1) the CD matrix PC1_1,PC1_2...plus CDELT*, CRPIX and CRVAL
(2) the CD matrix CD1_1,CD1_2... plus CRPIX and CRVAL.
(3) CROTA2 (or CROTA1) and CDELT plus CRPIX and CRVAL.
All three forms are valid FITS according to the paper "Representations
of World Coordinates in FITS by Greisen and Calabretta (2002, A&A, 395,
1061 http://fits.gsfc.nasa.gov/fits_wcs.html ) although form (1) is
preferred.
Notes
1. An anonymous structure is created to avoid structure definition
conflicts. This is needed because some projection systems
require additional dimensions (i.e. spherical cube
projections require a specification of the cube face).
2, Some FITS headers (e.g.from HST/ACS) include SIP forward distortion
coefficients but do not include the reverse coefficients. Currently,
EXTAST only gives a warning that the reverse coefficients (RA,Dec to
X,Y) are not present. EXTAST should actually compute
the inverse coefficients, but this is not yet implemented..
Procedures Called
GSSSEXTAST, ZPARCHECK
Revision History
Written by B. Boothman 4/15/86
Accept CD001001 keywords 1-3-88
Accept CD1_1, CD2_1... keywords W. Landsman Nov. 92
Recognize GSSS FITS header W. Landsman June 94
Get correct sign, when converting CDELT* to CD matrix for right-handed
coordinate system W. Landsman November 1998
Consistent conversion between CROTA and CD matrix October 2000
CTYPE = 'PIXEL' means no astrometry params W. Landsman January 2001
Don't choke if only 1 CTYPE value given W. Landsman August 2001
Recognize PC00n00m keywords again (sigh...) W. Landsman December 2001
Recognize GSSS in ctype also D. Finkbeiner Jan 2002
Introduce ALT keyword W. Landsman June 2003
Fix error introduced June 2003 where free-format values would be
truncated if more than 20 characters. W. Landsman Aug 2003
Further fix to free-format values -- slash need not be present Sep 2003
Default value of LATPOLE is 90.0 W. Landsman February 2004
Allow for distortion substructure, currently implemented only for
SIP (Spitzer Imaging Polynomial) W. Landsman February 2004
Correct LONGPOLE computation if CTYPE = ['*DEC','*RA'] W. L. Feb. 2004
Assume since V5.3 (vector STRMID) W. Landsman Feb 2004
Yet another fix to free-format values W. Landsman April 2004
Introduce PV2 tag to replace PROJP1, PROJP2.. etc. W. Landsman May 2004
Convert NCP projection to generalized SIN W. Landsman Aug 2004
Add NAXIS tag to output structure W. Landsman Jan 2007
.CRPIX tag now Double instead of Float W. Landsman Apr 2007
If duplicate keywords use the *last* value W. Landsman Aug 2008
Fix typo for AZP projection, nonzero longpole N. Cunningham Feb 2009
Give warning if reverse SIP coefficient not present W. Landsman Nov 2011
Allow obsolete CD matrix representations W. Landsman May 2012