idlastro / TV Display Procedures: CURVAL

[Source code]

NAME
CURVAL
PURPOSE
Cursor controlled display of image intensities and astronomical coords
EXPLANATION
CURVAL displays different information depending whether the user 
supplied an image array, and/or a FITS header array
Note that in the usual truecolor mode, the byte intensity returned by 
CURVAL does not correspond to the byte scaled image value but rather 
returns the maximum value in each color gun.
CALLING SEQUENCE(S)
curval          ;Display x,y and byte intensity (inten)
curval, im   ;Display x,y,inten, and also pixel value (from image array)
curval, hdr, [ im, OFFSET= , ZOOM=, FILENAME=, ALT=]        
OPTIONAL INPUTS
Hdr  = FITS Header array
Im  = Array containing values that are displayed.  Any type.
OPTIONAL KEYWORD INPUTS
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.
OFFSET - 2 element vector giving the location of the image pixel (0,0) 
         on the window display.   OFFSET can be positive (e.g if the 
         image is centered in a larger window) or negative (e.g. if the
         only the central region of an image much larger than the window
         is being displayed. 
         Default value is [0,0], or no offset.
 ZOOM - Scalar specifying the magnification of the window with respect
         to the image variable.    Use, for example, if image has been
         REBINed before display.
 FILENAME  = name of file to where CURVAL data can be saved.
         Data will only be saved if left or center mouse button
         are pressed.
OUTPUTS
None.
SIDE EFFECTS
X and Y values, etc., of the pixel under the cursor are constantly
displayed.  
Pressing left or center mouse button prints a line of output, and 
starts a new line.
Pressing right mouse button exits the procedure.
If the keyword FILENAME is defined, the date and time, and a heading 
will be printed in the file before the data.
PROCEDURES CALLED
ADSTRING(), EXTAST, GSSSXYAD, RADEC, SXPAR(), UNZOOM_XY, XY2AD
REVISION HISTORY
Written,  K. Rhode,  STX  May 1990
Added keyword FILENAME  D. Alexander  June 1991
Don't write to Journal file   W. Landsman    March 1993
Use astrometry structure  W. Landsman      Feb 1994
Modified for Mac IDL          I.   Freedman     April 1994
Allow for zoomed or offset image  W. Landsman      Mar 1996
Proper rounding of zoomed pixel values   W. Landsman/R. Hurt  Dec. 1997
Remove unneeded calls to obsolete !ERR   W. Landsman   December 2000
Replace remaining !ERR calls with !MOUSE.BUTTON W. Landsman Jan 2001
Allow for non-celestial (e.g. Galactic) coordinates W. Landsman Apr 2003
Work if RA/Dec reversed in CTYPE keyword  W. Landsman Feb. 2004
Always call UNZOOM_XY for MOUSSE compatibility W. Landsman Sep. 2004
Added ALT keyword  W. Landsman October 2004 
Always test if offset/zoom supplied  W. Landsman  Feb 2008