idlastro / FITS Astrometry and Calibration: PUTAST

[Source code]

NAME
PUTAST
PURPOSE
Put WCS astrometry parameters into a given FITS header.
CALLING SEQUENCE
putast, hdr              ;Prompt for all values
          or
putast, hdr, astr, [EQUINOX =, CD_TYPE =, ALT= , NAXIS=]
          or
putast, hdr, cd,[ crpix, crval, ctype], [ EQUINOX =, CD_TYPE =, ALT= ]    
INPUTS
HDR -  FITS header, string array.   HDR will be updated to contain
        the supplied astrometry.
ASTR - IDL structure containing values of the astrometry parameters
       CDELT, CRPIX, CRVAL, CTYPE, LONGPOLE, and PV2
       See EXTAST.PRO for more info about the structure definition
                       or
CD   - 2 x 2 array containing the astrometry parameters CD1_1 CD1_2
                                                        CD2_1 CD2_2
         in units of DEGREES/PIXEL
CRPIX - 2 element vector giving X and Y coord of reference pixel
         BE SURE THE COORDINATES IN CRPIX ARE GIVEN IN FITS STANDARD
         (e.g. first pixel in image is [1,1] ) AND NOT IDL STANDARD
         (first pixel in image is [0,0]
CRVAL - 2 element vector giving R.A. and DEC of reference pixel 
          in degrees
CTYPE - 2 element string vector giving projection types for the two axes.
        For example, to specify a tangent projection one should set
        ctype = ['RA---TAN','DEC--TAN'] 
Fields added for version 2:
 .PV1 - Vector of projection parameters associated with longitude axis
 .AXES  - 2 element integer vector giving the FITS-convention axis 
          numbers associated with astrometry, in ascending order. 
          Default [1,2].
 .REVERSE - byte, true if first astrometry axis is Dec/latitude
 .COORDSYS - 1 or 2 character code giving coordinate system, including
            'C' = RA/Dec, 'G' = Galactic, 'E' = Ecliptic, 'X' = unknown.
 .RADECSYS - String giving RA/Dec system e.g. 'FK4', 'ICRS' etc.
 .EQUINOX  - Double giving the epoch of the mean equator and equinox
 .DATEOBS  - Text string giving (start) date/time of observations
 .MJDOBS   - Modified julian date of start of observations.
 .X0Y0     - Not written to header.
OUTPUTS
HDR - FITS header now contains the updated astrometry parameters
         A brief HISTORY record is also added.
OPTIONAL KEYWORD INPUTS
ALT -  single character 'A' through 'Z' or ' ' specifying an alternate 
       astrometry system to write in the FITS header.    The default is
       to write 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.
CD_TYPE - Integer scalar, either 0, 1 or 2 specifying how the CD matrix
         is to be written into the header
        (0) write PCn_m values along with CDELT values
        (1) convert to rotation and write as a CROTA2 value (+ CDELT)
        (2) as CDn_m values (IRAF standard) 
     All three forms are valid representations according to Greisen &
     Calabretta (2002, A&A, 395, 1061), also available at 
     http://fits.gsfc.nasa.gov/fits_wcs.html ) although form (0) is 
     preferred.   Form (1) is the former AIPS standard and is now  
     deprecated and cannot be used if any skew is present.
     If CD_TYPE is not supplied, PUTAST will try to determine the 
     type of astrometry already in the header.   If there is no 
     astrometry in the header then the default is CD_TYPE = 2.
QUINOX - numeric scalar giving the year of equinox  of the reference 
         coordinates.  Keyword value takes precedence over value in
         astrometry structure which takes precedence over value in 
         header; if none of these present then default is 2000.
AXIS - By default, PUTAST does not update the NAXIS keywords in the
     FITS header.    If NAXIS is set, and an astrometry structure is
     supplied then the NAXIS1 and NAXIS2 keywords in the FITS header 
     will be updated with the .NAXIS structure tags values.     If an 
     astrometry structure is not supplied, then one can set NAXIS to a 
     two element vector to update the NAXIS1, NAXIS2 keywords. 
NOTES
The recommended use of this procedure is to supply an astrometry
structure. This can be produced with MAKE_ASTR.    
If parameters are supplied by keyword, the full range of
astrometry header info is not supported by PUTAST.
PUTAST does not delete astrometry parameters already present in the 
header, unless they are explicity overwritten.   
If present in the astrometry structure, PUTAST will add SIP 
 http://fits.gsfc.nasa.gov/registry/sip.html ) or TPV 
( http://fits.gsfc.nasa.gov/registry/tpvwcs.html ) distortion parameters
to a FITS header.  
PROMPTS
If only a header is supplied, the user will be prompted for a plate 
scale, the X and Y coordinates of a reference pixel, the RA and
DEC of the reference pixel, the equinox of the RA and Dec and a 
rotation angle.
PROCEDURES USED
ADD_DISTORT, GETOPT(), GET_COORDS, GET_EQUINOX(), SXADDPAR, SXPAR(), 
TAG_EXIST(), ZPARCHECK
REVISION HISTORY
Written by W. Landsman 9-3-87
Major rewrite, use new astrometry structure   March, 1994
Use both CD and CDELT to get plate scale for CD_TYPE=1   September 1995
Use lower case for FITS keyword Comments  W.L.    March 1997
Fixed for CD_TYPE=1 and CDELT = [1.0,1.0]   W.L   September 1997
Default value of CD_TYPE is now 2, Use GET_COORDS to read coordinates
to correct -0 problem           W.L.  September 1997
Update CROTA1 if it already exists  W.L. October 1997
Convert rotation to degrees for CD_TYPE = 1  W. L.   June 1998
Accept CD_TYPE = 0 keyword input   W.L   October 1998
Remove reference to obsolete !ERR  W.L.  February 2000
No longer support CD001001 format, write default tangent CTYPE value
consistent conversion between CROTA and CD matrix W.L. October 2000
Use GET_EQUINOX to get equinox value  W.L.  January 2001
Update CTYPE keyword if previous value is 'LINEAR'  W.L. July 2001
Use SIZE(/TNAME) instead of DATATYPE()  W.L.   November 2001
Allow direct specification of CTYPE W.L.        June 2002
Don't assume celestial coordinates W. Landsman  April 2003
Make default CD_TYPE = 2  W. Landsman   September 2003
Add projection parameters, e.g. PV2_1, PV2_2 if present in the 
input structure   W. Landsman    May 2004
Correct interactive computation of image center W. Landsman Feb. 2005
Don't use CROTA (CD_TYPE=1) if a skew exists W. Landsman  May 2005
Added NAXIS keyword  W. Landsman   January 2007
Update PC matrix, if CD_TYPE=0 and CD matrix supplied W.L. July 2007
Don't write PV2 keywords for WCS types that don't use it W.L. Aug 2011
Add SIP distortion parameters if present W.L. April 2012
Work if empty distortion structure present  W.L. November 2012
Spurious error message introduced April 2012 if CD matrix rather
  than structure supplied  W.L.  January 2013 
Allow for version 2 astrometry structure J. P. Leahy July 2013
Bug fix in interactive use JPL Aug 2013.
Support IRAF TNX projection  M. Sullivan U. of Southamptom March 2014
PV1_3, PV1_4 keywords take precedence over LONPOLE, LATPOLE keywords
            WL, August 2014