- 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