----- file created by makedoc on: Thu Nov  5 15:14:57 2009

----- Documentation for /scisoft/xop2.3/extensions/shadowvui/src/lib/plotimage.pro -----
 NAME:
   PLOTIMAGE

 AUTHOR:
   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
   craigm@lheamail.gsfc.nasa.gov

 PURPOSE:
   Displays an image via a "PLOT"-like interface.

 CALLING SEQUENCE:
   PLOTIMAGE, img, [xrange=xrange,] [yrange=yrange,] ...

 DESCRIPTION:

   PLOTIMAGE displays an image (or slice of an image) on the current
   graphics device.  The syntax is very similar to the PLOT command,
   in the sense that an XRANGE and YRANGE for the plot can be
   specified.

   More importantly, coordinate ranges can be specified for the
   *image* itself, and then PLOTIMAGE will intelligently crop the
   image so that only the part that falls within the XRANGE and
   YRANGE is displayed.  Images often have physical units (other than
   pixels) assigned to their X and Y dimensions.  PLOTIMAGE allows
   you to slice the image appropriately and display appropriate
   coordinate axes.

   Image coordinates are specified via the IMGXRANGE and IMGYRANGE
   keywords.  IMGXRANGE specifies the x-values for the first and last
   pixels in each row.  IMGYRANGE gives the y-values for the first
   and last pixels in each column.  Default image coordinates are in
   units of pixels.

   Plot coordinates are specified in the usual XRANGE and YRANGE
   keywords.  The [XY]RANGE may specify a range smaller than the
   image size, so that the image is cropped; or a range larger than
   the image size, in which case the appropriate portion of the image
   is displayed.

   Psuedocolor images may be of any type, but must rescaled to a byte
   range by using the RANGE keyword.  By default the color range used
   in the rescaling operation is 0 to !D.N_COLORS - 3B.  The extra
   two color values are reserved for the background and default pen
   colors.  This behavior can be adjusted by specifying the BOTTOM
   and/or NCOLORS keywords.

   Truecolor images must always be of type BYTE and one of their
   dimensions must have 3 elements, corresponding to the three color
   planes of the image.


 INPUTS:

   IMG - Array to be displayed.  For single-plane images (i.e.,
         pseudocolor), the image must be two dimensional and of any
         real numeric type.  For images that are not of BYTE type,
         the RANGE keyword must be supplied to rescale the image
         values to a byte range.

         An image declared as ARRAY(NX,NY) will be NX pixels in the
         x-direction and NY pixels in the y-direction.  The image is
         resampled to fill the desired display region (and optionally
         smoothed).

         For three-plane images (i.e., truecolor) the image must be
         of type BYTE.  One of the dimensions of the array must have
         three elements.  Hence it must be one of BYTARR(NX, NY, 3),
         BYTARR(NX, 3, NY) or BYTARR(3, NX, NY).  The 3-element
         dimension is recognized automatically.

 OPTIONAL INPUTS:
   NONE

 INPUT KEYWORD PARAMETERS:

   IMGXRANGE, IMGYRANGE - Each is a two component vector that
                          describes the X and Y position of the outer
                          edges of the first and last pixels.
                          Default: [0, NUM_[XY]PIX] for IMG[XY]RANGE

   XRANGE, YRANGE - Each is a two component vector that specifies the
                    X and Y plot ranges, respectively.  These values
                    are not required to coincide with IMG[XY]RANGE.
                    Default: IMG[XY]RANGE

   POSITION - Position of the inner plot window in the standard
              graphics keyword format.  Overrides PANEL and SUBPANEL.

   INTERP - if set, interpolate (smooth) the image before displaying.
            This keyword applies to the screen displays.  For printed
            images that are coarser than MIN_DPI, the image is
            implicitly interpolated regardless of INTERP.

   PRESERVE_ASPECT - if set, preserve the aspect ratio of the
                     original image (in pixels).  The result will be
                     the largest image that fits in the display
                     region while maintaining approximately square
                     pixels.  However, PIXEL_ASPECT_RATIO overrides
                     PRESERVE_ASPECT.  The POSITION keyword will be
                     reset upon output to the ultimate image
                     position.
                     DEFAULT: not set (image will fill POSITION rectangle)

   PIXEL_ASPECT_RATIO - The ratio of width to height for each pixel.
                        If specified, then the image will be scaled
                        so that each pixel has the specified aspect
                        ratio.  If not specified, then the image will
                        be scaled to fill the POSITION rectangle.
                        NOTE: If you want to change the overall image
                        aspect ratio, then use the POSITION keyword.
                  DEFAULT: undefined (image will fill POSITION rectangle)

   MIN_DPI - if printing, the minimum dot-per-inch pixel resolution
             for the resulting image.  Output images that would be
             coarser than this value are resampled to be at least
             MIN_DPI and smoothed.  Some common resolutions are:
             screen, 90 dpi; dot matrix, 72 dpi; laser printer
             300-600 dpi.  Note that large values of MIN_DPI will
             produce very large output files.
             Default: 0 (i.e., the output image will not be smoothed)

   RANGE - a two element vector.  If the image is single plane (i.e.,
           pseudocolor) the input image can be of any real numeric
           type, and then must be rescaled into byte range with this
           keyword.  In contrast, truecolor images must always be of
           type BYTE.  Values are scaled into byte range with the
           following statement:
              RESULT = BYTSCL(INPUT, MIN=RANGE(0), MAX=RANGE(1), $
                              TOP=NCOLORS-1) + BOTTOM
           so that pixels with an intensity RANGE(0) are set to
           BOTTOM; those with RANGE(1) are set to the maximum color.
           Default: no range scaling occurs (and the image must hence
                    be of type BYTE -- otherwise an error occurs)

   NCOLORS - number of color table values be used in the byte
             rescaling operation.
             Default: !D.N_COLORS - BOTTOM - 1 (for default pen color)

   BOTTOM - bottom-most value of the color table to be used in the
            byte rescaling operation.
            Default: 1 (for default background color)

   NOERASE - If set, the display is not erased before graphics
             operations.

   NODATA - If set, the image is not actually displayed, but
            coordinate axes may be drawn.

   NOAXES - An attempt is made to render the image without coordinate
            axes.  This is possible if POSITION, PANEL, or SUBPANEL
            are  given.

   ORDER - same interpretation as the !ORDER system variable; 
           if ORDER=0, then the first pixel is drawn in the lower
           left corner; if ORDER=1, then the first pixel is drawn in
           the upper left corner.
           Default: 0


   PANEL, SUBPANEL - An alternate way to more precisely specify the
                     plot and annotation positions.  See SUBCELL.

   PLOTIMAGE will pass other keywords directly to the PLOT command
   used for generating the plot axes.  XSTYLE=1 and YSTYLE=1 are
   enforced.

 OUTPUTS:
   NONE

 PROCEDURE:

 EXAMPLE:

   This example constructs an image whose values are found by
       z(x,y) = cos(x) * sin(y)
   and x and y are in the range [-2,2] and [4,8], respectively.
   The image is then plotted, with appropriate axes.

   x = findgen(20)/5. - 2. + .1   ; 0.1 = half-pixel
   y = findgen(20)/5. + 4. + .1
   zz = cos(x) # sin(y)
   imgxrange = [-2.,2.]           ; extend to pixel edges
   imgyrange = [4.,8.]
   plotimage, bytscl(zz), imgxrange=imgxrange, imgyrange=imgyrange

   This second example plots the same image, but with a plot range
   much larger than the image's.

   xr=[-10.,10]
   yr=[-10.,10]
   plotimage, bytscl(zz), imgxrange=imgxrange, imgyrange=imgyrange, $
      xrange=xr, yrange=yr

 SEE ALSO:

   OPLOTIMAGE, BYTSCL

 EXTERNAL SUBROUTINES:

   SUBCELL, DEFSUBCELL

 MODIFICATION HISTORY:
   Written, CM, 1997
   Correct various one-off problems, 02 Feb 1999, CM
   Made self-contained with some pre-processing, 17 Oct 1999, CM
   Corrected bug in newly introduced CONGRID functions, 18 Oct 1999, CM
   Correct behavior with no POSITION keyword, 17 Nov 1999, CM
   Simplified axis plotting, 17 Nov 1999, CM
   Use _EXTRA keyword in first PLOT, but with blank TITLEs, 11 Jan
     2000, CM
   Correct implementation of X/YSTYLE in first PLOT, 11 Feb 2000, CM
   Correct CONGRID implementation (small effect when enlarging most
     images), 14 Feb 2000, CM
   Major changes: 19 Apr 2000
      - now handle decomposed color, automatic color mapping via
        RANGE, and 24-bit multiplane images
      - new PRESERVE_ASPECT keyword to keep square pixels
      - removed legacy TVIMAGE code
      - smoothing is more configurable, esp. for printers, but is not
        done by default; more printers are supported
   Corrected INTERPOLATE behavior (thanks to Liam Gumley
     <Liam.Gumley@ssec.wisc.edu>), other minor tweaks, CM 20 Apr 2000
   Added ability to use PRESERVE_ASPECT with POSITION, PANEL or
     SUBPANEL keywords CM 20 Oct 2000
   Oops, a typo is now fixed, CM 23 Oct 2000
   Add fix for MacIntoshes and DECOMPOSED color, Tupper, 02 Aug 2001
   Better behavior with fractional pixels (ie, when the image pixels
     are very large compared to the screen), 23 Aug 2001
   Add support for Z buffer, CM, 20 Oct 2002
   Memory conservation: use REVERSE() to reverse IMG; rewrote
     PLOTIMAGE_RESAMP to rescale entire image instead of each color plane
     separately.  Jeff Guerber, 30 July 2003
   Add PIXEL_ASPECT_RATIO keyword, 22-25 Nov 2005
   Check for the case of an 1xNXxNY 3D image and treat it as a 2D
     image.  The "1" dimension can be anywhere, CM, 03 Sep 2006
   Add the ORDER keyword parameter, CM, 20 Mar 2007

   $Id: plotimage.pro,v 1.1 2007/06/11 13:53:00 srio Exp $


