/astrom                                                  December 2001

This directory contain IDL procedures for manipulating FITS images which
include header keywords specifying the coordinate system.   The FITS header
must follow the specification in the FITS draft proposal "Representations of
Celestial Coordinates in FITS"  by Eric Greisen and Mark Calabretta.   
Documentation for this proposal can be obtained  from
http://www.aoc.nrao.edu/~egreisen/ or http://www.atnf.csiro.au/~mcalabre/.    

Users should be aware that FITS defines the center of the first pixel in the
array to have coordinates (1,1).    This differs from the IDL convention where
the first pixel has coordinates (0,0).    Whenever an (X,Y) position is
extracted or inserted into a FITS header then this difference must be accounted
for.

Several procedures use an IDL structure than contains astrometry information in
the following tags:

  .CD	-  2 x 2 array containing the astrometry parameters CD1_1 CD1_2
	   in DEGREES/PIXEL				      CD2_1 CD2_2
  .CDELT - 2 element vector giving physical increment at the reference pixel
  .CRPIX - 2 element 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 longitude of north pole (default = 180) 
  .PROJP1 - Scalar parameter needed in some projections
  .PROJP2 - Scalar parameter needed in some projections

The procedures EXTAST and PUTAST can be used, respectively, to extract
astrometry information from a FITS header and place it into an astrometry
structure, and to put the information from an astrometry structure into a FITS
header.  

      IDL> extast, hdr, astr     ;Extract astrometry from a FITS header
      IDL> putast, hdr, astr     ;Put astrometry info into a FITS header 

(1) Following the discussion in Section 5 of the Greisen & Calabretta paper,
this software supports both the current WCS format (PC matrix) and the old-style
AIPS (CDELT + CROTA) notation.
The CDELT tag is not used in the current CD matrix format,
and is normally set to [1.0, 1.0].    However, for an AIPS-style header, the
CDELT values are stored in the CDELT tag, and the CROTA value is stored in the
CD matrix     

cd = [ [ cos(crota), -sin(crota) ] , [ sin(crota), cos(crota)] ] 

If either element of the CDELT tag differs from 1.0 then this signals that the
astrometry came from an AIPS type header.    Programs using the astrometry
structure should always use the following code 

 if N_elements(CDELT) GE 2 then if (cdelt[0] NE 1.0) then begin
        cd[0,0] = cd[0,0]*cdelt[0] & cd[0,1] =  cd[0,1]*cdelt[0]
        cd[1,1] = cd[1,1]*cdelt[1] & cd[1,0] =  cd[1,0]*cdelt[1]
 endif

(Note that the IF statement is not really needed).

(2) Earlier draft versions of the World Coordinate System paper represented the
CD matrix in a FITS header with names such as 'CD001001' rather than CD1_1, and
made use of both the CD matrix and the CDELT values.   This notation is no
longer recognized, though the software will still be able to read (but not
write) it.

(3) The CRPIX value is stored in the astrometry structure the same way as it is
in the FITS header, i.e. in FORTRAN (first pixel is 1) convention.    

Special astrometry procedures are required for the Digitized Sky Survey Images
which were released on CD-Rom in early 1994.    Information about the Guidestar
images can be obtained from http://archive.stsci.edu/dss/
and the Guidestar images can also be obtained from the SKYVIEW facility
at http://skyview.gsfc.nasa.gov/skyview.html.  The Schmidt plates used in
this survey have a highly nonlinear plate solution that is not covered
by the Greisen & Calabretta conventions.     The procedures GSSSEXTAST, 
GSSSXYAD and GSSSADXY are the Guidestar survey analogues of the procedures
EXTAST, XY2AD, and ADXY for standard astrometry.     All the astrometry
procedures in the library will test for a Guidestar image header (by looking
for the 'PPO1' keyword) and call the appropriate procedures.    The procedure
GSSS_STDAST will convert the astrometry in a guidestar image header to 
an standard tangent projection with very slightly degraded accuracy.   

The procedures in this directory will call the procedures wcssph2xy.pro
and wcsxy2sph.pro in the /astro directory 

A couple of procedures in other directories also use the FITS world coordinate
system including
  IMCONTOUR - (in /astro) Contour plots with astronomical labeling (either 
               RA,Dec or arc distance from the image center
  IMDBASE - (in /database) Find all catalog sources within the field of an 
            image (given a FITS header with astrometry)