idlastro / FITS Astrometry and Calibration: FITS_XYAD

[Source code]

NAME
FITS_XYAD
PURPOSE
Use a FITS file with astrometry to convert pixel (X,Y) to world coordinates
EXPLANATION
Use astrometry in a FITS file to compute world coordinates in decimal degrees from
X and Y pixel coordinates.
This routine can be used with any FITS file containing WCS (world coordinate
system) information.    But it is especially useful for files using the
         distortion lookup tables (https://fits.gsfc.nasa.gov/wcs/dcs_20040422.pdf)
         which are stored in separate extensions in the FITS file.    An example of such 
files are the Wide Field Camera 3 (WFC3) _flt files from Hubble 
If spherical coordinates (Calabretta & Greisen 2002, A&A, 395, 1077) are 
not present, then FITS_XYAD will still perform the transformation specified
by the CD, CRVAL, and CRPIX keywords.
CALLING SEQUENCE
FITS_XYAD, filename_or_fcb              ;Prompt for X and Y positions
FITS_XYAD, filename_or_fcb, X, Y, A, D, [ /PRINT, /Galactic, /Celestial, /Ecliptic, 
                         ALT =, PRECISION=]
INPUTS
FILENAME_or_FCB - either the FITS Control Block (FCB) structure returned by FITS_OPEN
                 or a scalar string giving the name of the FITS file.    If FITS_XYAD is to be
                 used repeatedly with the same file, then it is more efficient to first obtain a 
                 FCB structure with FITS_OPEN, and then pass this structure to FITS_XYAD.
OPTIONAL INPUTS
X     - row position in pixels, scalar or vector
Y     - column position in pixels, scalar or vector
X and Y should be in IDL convention, (first pixel is [0,0] where
the integral value corresponds to the center of the pixel.)
OPTIONAL OUTPUT
A - Output longitude in decimal DEGREES (for spherical coordinates), 
        same number of elements as X and Y.    For celestial 
        coordinates, this is the Right ascension.
D - Output latitude in decimal DEGREES.   For celestial coordinates,
        this is the declination.
OPTIONAL KEYWORD INPUT
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.
         EXTEN_NO - Extension number of FITS file containing the astrometric
                 information.   By default, the first extension is used, if present,
                 otherwise the primary header (EXTEN_NO=0) is used.
EXTNAME - string name of the extname to read
EXTVER - integer version number to read
EXTLEVEL - integer extension level to read
/NODISTORT - If set, then do not apply the distortion lookup tables
/NOSIP - If set, then do not apply the polynomial SIP distortions 
PRECISION - Integer scalar (0-4) specifying the number of digits 
      displayed after the decimal of declination.   The RA is
      automatically one digit more.   See ADSTRING() for more info.
      Default value is 1, and the keyword is ignored if results are not 
      displayed at the terminal 
/PRINT - If this keyword is set and non-zero, then results are displayed
        at the terminal in both decimal and sexagesimal notation.
The default for XYAD is to return the coordinate system present in
in the FITS header.    However, the following mutually exclusive 
keywords can be used to convert to a particular coordinate system:
/CELESTIAL - Output is Right Ascension and declination
/ECLIPTIC - Output is Ecliptic longitude and latitude
/GALACTIC - Output is Galactic longitude and latitude
            Celestial & Ecliptic coords depend on the reference
            equinox, set to either B1950 (=FK4) or J2000 (=FK5,ICRS)
            according to the header or standard FITS WCS defaults.
            Note that astrometry at the sub-arcsec level requires
            fine distinctions that are not handled here.
OPERATIONAL NOTES
If less than 5 parameters are supplied, or if the /PRINT keyword is
set, then the computed astronomical coordinates are displayed at the 
terminal.
If this procedure is to be used repeatedly with the same file,
then it is quicker to call FITS_OPEN once and pass the file control block
         FCB on each call to FITS_XYAD.
How to specify which extension in the FITS file to use
        case 1: EXTEN_NO specified. EXTEN_NO will give the number of the
                extension to read.  The primary data unit is refered
                to as extension 0. If EXTEN_NO is specified, XTENSION,
                EXTNAME, EXTVER, and EXTLEVEL parameters are ignored.
        case 2: if EXTEN_NO is not specified, the first extension
                with the specified XTENSION, EXTNAME, EXTVER, and
                EXTLEVEL will be read.  If any of the 4 parameters
                are not specified, they will not be used in the search.
                Setting EXTLEVEL=0, EXTVER=0, EXTNAME='', or
                XTENSION='' is the same as not supplying them.
        case 3: if none of the keyword parameters, EXTEN_NO, XTENSION,
                EXTNAME, EXTVER, or EXTLEVEL are supplied.  FITS_XYAD
                will read the next extension in the file.  If the
                primary data unit (PDU), extension 0 has no astrometry, the
                first call to FITS_XYAD will read the first extension
                of the file.
EXAMPLE
A FITS file wfc3.fits contains astrometric information in celestial
coordinates.   Find the RA and Dec corresponding to position X=23.3
 Y = 100.2 on an image
         IDL> FITS_open, 'icau21u3q_flt.fits', fcb
         IDL> FITS_xyad, fcb, 10, 10, aa, dd
PROCEDURES CALLED
ADSTRING(), EULER, EXTAST, FITS_OPEN, GSSSXYAD, REPCHR(), XY2AD
REVISION HISTORY
Adapted from XYAD W. Landsman  October 2017 
Use both D2IMARR and WCSDVARR distortion tables  November  2017
xtract astrometry structure