idlastro / Astronomical Utilities: IMCONTOUR

[Source code]

NAME
IMCONTOUR
PURPOSE
Make a contour plot labeled with astronomical coordinates.
EXPLANATION
The type of coordinate display is controlled by the keyword TYPE
Set TYPE=0 (default) to measure distances from the center of the image
(IMCONTOUR will decide whether the plotting units will be in
arc seconds, arc minutes, or degrees depending on image size.)
Set /TYPE for standard RA and Dec labeling
By using the /NODATA keyword, IMCONTOUR can also be used to simply
provide astronomical labeling of a previously displayed image.
CALLING SEQUENCE
IMCONTOUR, im, hdr,[ /TYPE, /PUTINFO, XDELTA = , YDELTA =, _EXTRA = 
                     XMID=, YMID= ]
INPUTS
IM - 2-dimensional image array
HDR - FITS header associated with IM, string array, must include
        astrometry keywords.   IMCONTOUR will also look for the
        OBJECT and IMAGE keywords, and print these if found and the 
        PUTINFO keyword is set.
OPTIONAL PLOTTING KEYWORDS
/TYPE - the type of astronomical labeling to be displayed.   Either set
        TYPE = 0 (default), distance to center of the image is
        marked in units of Arc seconds, arc minutes, or degrees
        TYPE = 1 astronomical labeling with Right ascension and 
        declination.
/PUTINFO - If set, then IMCONTOUR will add information about the image
        to the right of the contour plot.  Information includes image
        name, object, image center, image center, contour levels, and
        date plot was made
XDELTA, YDELTA - Integer scalars giving spacing of labels for TYPE=1.  
        Default is to label every major tick (XDELTA=1) but if 
        crowding occurs, then the user might wish to label every other
        tick (XDELTA=2) or every third tick (XDELTA=3)
XMID, YMID - Scalars giving the X,Y position from which offset distances
        will be measured when TYPE=0.   By default, offset distances 
        are measured from the center of the image.
/OVERLAY - If set, then IMCONTOUR is assumed to overlay an image.
        This requires 1 extra pixel be included on the X and Y axis,
        to account for edge effects in the image display.    Setting
        OVERLAY provide a better match of the contour and underlying
        image but is not as aesthetically pleasing because the contours
        will not extend to the axes. 
Any keyword accepted by CONTOUR may also be passed through IMCONTOUR
since IMCONTOUR uses the _EXTRA facility.     IMCONTOUR uses its own
defaults for the XTITLE, YTITLE XMINOR, YMINOR, and SUBTITLE keywords
but these may be overridden.    Note in particular the /NODATA keyword
which can be used if imcontour.pro is to only provide labeling.
NOTES
(1) The contour plot will have the same dimensional ratio as the input
    image array
(2) To contour a subimage, use HEXTRACT before calling IMCONTOUR
(3) Use the /NODATA keyword to simply provide astronomical labeling
    of a previously displayed image.
(4) The IMCONTOUR display currently does not indicate the image 
    rotation in any way, but only specifies coordinates along the 
    edges of the image 
EXAMPLE
Overlay the contour of an image, im2, with FITS header, h2, on top
of the display of a different image, im1.   Use RA, Dec labeling, and
seven equally spaced contour levels.    The use of a program like
David Fanning's cgImage  http://www.idlcoyote.com/programs/cgimage.pro
is suggested to properly overlay plotting and image coordinates.  The
/Keep_aspect_ratio keyword must be used.
IDL> cgimage,im1,/keep_aspect, position = pos
IDL> imcontour,im2,h2,nlevels=7,/Noerase,/TYPE,position = pos
PROCEDURES USED
CHECK_FITS, EXTAST, GETROT, TICPOS, TICLABEL, TIC_ONE, TICS, XYAD
CONS_RA(), CONS_DEC(), ADSTRING()
REVISION HISTORY
Written   W. Landsman   STX                    May, 1989
Fixed RA,Dec labeling  W. Landsman             November, 1991
Fix plotting keywords  W.Landsman             July, 1992
Recognize GSSS headers  W. Landsman            July, 1994
Removed Channel keyword for V4.0 compatibility June, 1995
Add _EXTRA CONTOUR plotting keywords  W. Landsman  August, 1995
Add XDELTA, YDELTA keywords  W. Landsman   November, 1995
Use SYSTIME() instead of !STIME                August, 1997
Remove obsolete !ERR system variable W. Landsman   May 2000 
Added XMID, YMID keywords to specify central position (default is still
   center of image)  W. Landsman               March 2002     
Recognize Galactic coordinates, fix Levels display when /PUTINFO set
    W. Landsman                May 2003
Correct conversion from seconds of RA to arcmin is 4 not 15.
 M. Perrin                                       July 2003
Fix integer truncation which appears with tiny images WL  July 2004
Changed some keyword_set() to N_elements WL  Sep 2006
Work to 1 pixels level when overlaying an image,added /OVERLAY keyword
 Use FORMAT_AXIS_VALUES()  W. Landsman   Jan 2008 
Make /OVERLAY  always optional   W. Landsman  Feb 2008
Check if RA crosses 0 hours  WL  Aug 2008
Use Coyote Graphics WL Feb 2011