idlastro / FITS Astrometry and Calibration: FITS_ADXY

[Source code]

NAME
FITS_adxy
PURPOSE
Use a FITS file with astrometry to convert astronomical to pixel coordinates
EXPLANATION
Use astrometry in a FITS file to compute X and Y positions, given the
RA and Dec (or longitude, latitude) in decimal degrees.  
This routine can be used with any FITS file containing WCS (world coordinate
system) information.    But it is especially useful for files using the
         proposed distortion lookup tables (https://fits.gsfc.nasa.gov/wcs/dcs_20040422.pdf)
         which are stored in separate extensions in the FITS file.
CALLING SEQUENCE
FITS_adxy, HDR               ;Prompt for Ra and DEC 
FITS_adxy, hdr, a, d, x, y, [ EXTEN_NO=, /PRINT, ALT= ]
INPUTS
HDR - FITS Image header containing astrometry parameters
OPTIONAL INPUTS
A - Right ascension in decimal DEGREES, scalar or vector
D - Declination in decimal DEGREES, scalar or vector        
If A and D are not supplied, user will be prompted to supply
them in either decimal degrees or HR,MIN,SEC,DEG,MN,SC format.
OPTIONAL OUTPUT
X     - row position in pixels, same number of elements as A and D
Y     - column position in pixels
X and Y will be in standard IDL convention (first pixel is 0) and not
the FITS convention (first pixel is 1).      As in FITS an integral
value corresponds to the center of a pixel.
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
/PRINT - If this keyword is set and non-zero, then results are displayed
        at the terminal.
OPERATIONAL NOTES
If less than 5 parameters are supplied, or if the /PRINT keyword is
set, then the X and Y positions 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.;            
PROCEDURES CALLED
AD2XY, ADSTRING(), EXTAST, FITS_OPEN, FITS_READ, GETOPT(), TEN()
REVISION HISTORY
Adapted from adxy.pro  W. Landsman    October 2017
D2IMARR and WCSDVARR distortion tables  November  2017
urious call to gsssFITS_adxy    June 2020