idlastro / FITS Astrometry and Calibration: STARAST

[Source code]

NAME
STARAST 
PURPOSE
Compute astrometric solution using positions of 2 or 3 reference stars
EXPLANATION
Computes an exact astrometric solution using the positions and 
coordinates from 2 or 3 reference stars and assuming a tangent 
(gnomonic) projection.   If 2 stars are used, then
the X and Y plate scales are assumed to be identical, and the
axis are assumed to be orthogonal.   Use of three stars will
allow a unique determination of each element of the CD matrix.
CALLING SEQUENCE
starast, ra, dec, x, y, cd, [/Righthanded, HDR = h, PROJECTION=]
INPUTS
RA - 2 or 3 element vector containing the Right Ascension in DEGREES
DEC- 2 or 3 element vector containing the Declination in DEGREES
X -  2 or 3 element vector giving the X position of reference stars
Y -  2 or 3 element vector giving the Y position of reference stars
OUTPUTS
CD - CD (Coordinate Description) matrix (DEGREES/PIXEL) determined 
        from stellar positions and coordinates.
OPTIONAL INPUT KEYWORD
/RightHanded - If only 2 stars are supplied, then there is an ambiguity
        in the orientation of the coordinate system.   By default,
        STARAST assumes the astronomical standard left-handed system
        (R.A. increase to the left).   If /Right is set then a 
        righthanded coordinate is assumed.  This keyword has no effect
        if 3 star positions are supplied.
 PROJECTION - Either a 3 letter scalar string giving the projection
        type (e.g. 'TAN' or 'SIN') or an integer 1 - 25 specifying the
        projection as given in the WCSSPH2XY procedure.   If not 
        specified then a tangent projection is computed.
OPTIONAL INPUT-OUTPUT KEYWORD
HDR - If a FITS header string array is supplied, then an astrometry 
      solution is added to the header using the CD matrix and star 0
      as the reference pixel (see example).   Equinox 2000 is assumed.
EXAMPLE
To use STARAST to add astrometry to a FITS header H;
IDL> starast,ra,dec,x,y,cd       ;Determine CD matrix
IDL> crval = [ra[0],dec[0]]      ;Use Star 0 as reference star
IDL> crpix = [x[0],y[0]] +1      ;FITS is offset 1 pixel from IDL
IDL> putast,H,cd,crpix,crval     ;Add parameters to header
This is equivalent to the following command:
IDL> STARAST,ra,dec,x,y,hdr=h      
METHOD
The CD parameters are determined by solving the linear set of equations
relating position to local coordinates (l,m)
For highest accuracy the first star position should be the one closest
to the reference pixel.
REVISION HISTORY
Written, W. Landsman             January 1988
Converted to IDL V5.0   W. Landsman   September 1997
Added /RightHanded and HDR keywords   W. Landsman   September 2000
Write CTYPE values into header   W. Landsman/A. Surkov  December 2002
CD matrix was mistakenly transpose in 3 star solution
Added projection keyword    W. Landsman   September 2003
Test for singular matrix W. Landsman  August 2011