NAME:
     TVIMAGE

 PURPOSE:
     This purpose of TVIMAGE is to allow you to display an image
     on the display or in a PostScript file in a particular position.
     The position is specified by means of the POSITION keyword. In
     this respect, TVIMAGE works like other IDL graphics commands.
     Moreover, the TVIMAGE command works identically on the display
     and in a PostScript file. You don't have to worry about how to
     "size" the image in PostScript. The output on your display and
     in the PostScript file will be identical. The major advantage of
     TVIMAGE is that it can be used in a natural way with other IDL
     graphics commands in resizeable IDL graphics windows. TVIMAGE
     is a replacement for TV and assumes the image has been scaled
     correctly when it is passed as an argument.

 AUTHOR:
       FANNING SOFTWARE CONSULTING:
       David Fanning, Ph.D.
       2642 Bradbury Court
       Fort Collins, CO 80521 USA
       Phone: 970-221-0438
       E-mail: davidf@dfanning.com
       Coyote's Guide to IDL Programming: http://www.dfanning.com

 CATEGORY:
     Graphics display.

 CALLING SEQUENCE:

     TVIMAGE, image

 INPUTS:
     image:    A 2D or 3D image array. It should be byte data.

       x  :    The X position of the lower-left corner of the image.
               This parameter is only recognized if the TV keyword is set.

       y  :    The Y position of the lower-left corner of the image.
               This parameter is only recognized if the TV keyword is set.

 KEYWORD PARAMETERS:

     BACKGROUND:   This keyword specifies the background color. Note that
               the keyword ONLY has effect if the ERASE keyword is also
               set or !P.MULTI is set to multiple plots and TVIMAGE is
               used to place the *first* plot.

     ERASE:    If this keyword is set an ERASE command is issued
               before the image is displayed. Note that the ERASE
               command puts the image on a new page in PostScript
               output.

     _EXTRA:   This keyword picks up any TV keywords you wish to use.

     HALF_HALF: If set, will tell CONGRID to extrapolate a *half* row
               and column on either side, rather than the default of
               one full row/column at the ends of the array.  If you
               are interpolating images with few rows, then the
               output will be more consistent with this technique.
               This keyword is intended as a replacement for
               MINUS_ONE, and both keywords probably should not be
               used in the same call to CONGRID.

     KEEP_ASPECT_RATIO: Normally, the image will be resized to fit the
               specified position in the window. If you prefer, you can
               force the image to maintain its aspect ratio in the window
               (although not its natural size) by setting this keyword.
               The image width is fitted first. If, after setting the
               image width, the image height is too big for the window,
               then the image height is fitted into the window. The
               appropriate values of the POSITION keyword are honored
               during this fitting process. Once a fit is made, the
               POSITION coordiates are re-calculated to center the image
               in the window. You can recover these new position coordinates
               as the output from the POSITION keyword.

     MARGIN:   A single value, expressed as a normalized coordinate, that
               can easily be used to calculate a position in the window.
               The margin is used to calculate a POSITION that gives
               the image an equal margin around the edge of the window.
               The margin must be a number in the range 0.0 to 0.333. This
               keyword is ignored if the POSITION keyword is used.

     MINUS_ONE: The value of this keyword is passed along to the CONGRID
               command. It prevents CONGRID from adding an extra row and
               column to the resulting array, which can be a problem with
               small image arrays.

     MULTI:    If this keyword is set, the image output honors the
               !P.MULTI system variable. It is no longer necessary to set
               this keyword to recognize the !P.MULTI system variable.

     NOINTERPOLATION: Setting this keyword disables the default bilinear
               interpolation done to the image when it is resized. Nearest
               neighbor interpolation is done instead. This is preferred
               when you do not wish to change the pixel values of the image.
               This keyword must be set, for example, when you are displaying
               GIF files that come with their own non-IDL color table vectors.

     NORMAL:   Setting this keyword means image position coordinates x and y
               are interpreted as being in normalized coordinates. This keyword
               is only valid if the TV keyword is set.

     OVERPLOT: Setting this keyword causes the POSITION keyword to be ignored
               and the image is positioned in the location established by the
               last graphics command. For example:

                    Plot, Findgen(11), Position=[0.1, 0.3, 0.8, 0.95]
                    TVImage, image, /Overplot

     POSITION: The location of the image in the output window. This is
               a four-element floating array of normalized coordinates of
               the type given by !P.POSITION or the POSITION keyword to
               other IDL graphics commands. The form is [x0, y0, x1, y1].
               The default is [0.0, 0.0, 1.0, 1.0]. Note that this can
               be an output parameter if the KEEP_ASPECT_RATIO keyword is
               used.

     TV:       Setting this keyword makes the TVIMAGE command work much
               like the TV command, although better. That is to say, it
               will still set the correct DECOMPOSED state depending upon
               the kind of image to be displayed (8-bit or 24-bit). It will
               also allow the image to be "positioned" in the window by
               specifying the coordinates of the lower-left corner of the
               image. The NORMAL keyword is activated when the TV keyword
               is set, which will indicate that the position coordinates
               are given in normalized coordinates rather than device
               coordinates.

               Setting this keyword will ensure that the keywords
               KEEP_ASPECT_RATIO, MARGIN, MINUS_ONE, MULTI, and POSITION
               are ignored.

 OUTPUTS:
     None.

 CALLED BY:
	CIndex, XMAP [1], XMAP [2], XZOOM, xwhisker [1], xwhisker [2]
 SIDE EFFECTS:
     Unless the KEEP_ASPECT_RATIO keyword is set, the displayed image
     may not have the same aspect ratio as the input data set.

 RESTRICTIONS:
     If the POSITION keyword and the KEEP_ASPECT_RATIO keyword are
     used together, there is an excellent chance the POSITION
     parameters will change. If the POSITION is passed in as a
     variable, the new positions will be returned as an output parameter.

     If the image is 2D then color decomposition is turned OFF
     for the current graphics device (i.e., DEVICE, DECOMPOSED=0).

     If a 24-bit image is displayed on an 8-bit display, the
     24-bit image must be converted to an 8-bit image and the
     appropriate color table vectors. This is done with the COLOR_QUAN
     function. The TVIMAGE command will load the color table vectors
     and set the NOINTERPOLATION keyword if this is done. Note that the
     resulting color table vectors are normally incompatible with other
     IDL-supplied color tables. Hence, other graphics windows open at
     the time the image is display are likely to look strange.

 EXAMPLE:
     To display an image with a contour plot on top of it, type:

        filename = FILEPATH(SUBDIR=['examples','data'], 'worldelv.dat')
        image = BYTARR(360,360)
        OPENR, lun, filename, /GET_LUN
        READU, lun, image
        FREE_LUN, lun

        TVIMAGE, image, POSITION=thisPosition, /KEEP_ASPECT_RATIO
        CONTOUR, image, POSITION=thisPosition, /NOERASE, XSTYLE=1, $
            YSTYLE=1, XRANGE=[0,360], YRANGE=[0,360], NLEVELS=10

 MODIFICATION HISTORY:
      Written by:     David Fanning, 20 NOV 1996.
      Fixed a small bug with the resizing of the image. 17 Feb 1997. DWF.
      Removed BOTTOM and NCOLORS keywords. This reflects my growing belief
         that this program should act more like TV and less like a "color
         aware" application. I leave "color awareness" to the program
         using TVIMAGE. Added 24-bit image capability. 15 April 1997. DWF.
      Fixed a small bug that prevented this program from working in the
          Z-buffer. 17 April 1997. DWF.
      Fixed a subtle bug that caused me to think I was going crazy!
          Lession learned: Be sure you know the *current* graphics
          window! 17 April 1997. DWF.
      Added support for the PRINTER device. 25 June 1997. DWF.
      Extensive modifications. 27 Oct 1997. DWF
          1) Removed PRINTER support, which didn't work as expected.
          2) Modified Keep_Aspect_Ratio code to work with POSITION keyword.
          3) Added check for window-able devices (!D.Flags AND 256).
          4) Modified PostScript color handling.
      Craig Markwart points out that Congrid adds an extra row and column
          onto an array. When viewing small images (e.g., 20x20) this can be
          a problem. Added a Minus_One keyword whose value can be passed
          along to the Congrid keyword of the same name. 28 Oct 1997. DWF
      Changed default POSITION to fill entire window. 30 July 1998. DWF.
      Made sure color decomposition is OFF for 2D images. 6 Aug 1998. DWF.
      Added limited PRINTER portrait mode support. The correct aspect ratio
          of the image is always maintained when outputting to the
          PRINTER device and POSITION coordinates are ignored. 6 Aug 1998. DWF
      Removed 6 August 98 fixes (Device, Decomposed=0) after realizing that
          they interfere with operation in the Z-graphics buffer. 9 Oct 1998. DWF
      Added a MARGIN keyword. 18 Oct 1998. DWF.
      Re-established Device, Decomposed=0 keyword for devices that
         support it. 18 Oct 1998. DWF.
      Added support for the !P.Multi system variable. 3 March 99. DWF
      Added DEVICE, DECOMPOSED=1 command for all 24-bit images. 2 April 99. DWF.
      Added ability to preserve DECOMPOSED state for IDL 5.2 and higher. 4 April 99. DWF.
      Added TV keyword to allow TVIMAGE to work like the TV command. 11 May 99. DWF.
      Added the OVERPLOT keyword to allow plotting on POSITION coordinates
         estabished by the preceding graphics command. 11 Oct 99. DWF.
      Added automatic recognition of !P.Multi. Setting MULTI keyword is no
         longer required. 18 Nov 99. DWF.
      Added NOINTERPOLATION keyword so that nearest neighbor interpolation
         is performed rather than bilinear. 3 Dec 99. DWF
      Changed ON_ERROR condition from 1 to 2. 19 Dec 99. DWF.
      Added Craig Markwardt's CMCongrid program and removed RSI's. 24 Feb 2000. DWF.
      Added HALF_HALF keyword to support CMCONGRID. 24 Feb 2000. DWF.
      Fixed a small problem with image start position by adding ROUND function. 19 March 2000. DWF.
      Updated the PRINTER device code to take advantage of available keywords. 2 April 2000. DWF.
      Reorganized the code to handle 24-bit images on 8-bit displays better. 2 April 2000. DWF.
      Added BACKGROUND keyword. 20 April 2000. DWF.
      Fixed a small problem in where the ERASE was occuring. 6 May 2000. DWF.