Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


  >  Docs Center  >  Libraries  >  Markwardt  >  PLOTIMAGE

PLOTIMAGE

PLOTIMAGE

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.
  PLOTIMAGE keeps separate the notions of the image coordinate
  system and the displayed coordinate system, which allows any input
  image to be "cropped," "zoomed," or "flipped."
  PLOTIMAGE allows the user to express image extents in physical
  units rather than pixel units.
  The image coordinate system specifies the physical coordinates of
  original image data, IMG. The image is considered to be a 2D
  array (IMG = ARRAY(NX,NY)), where the values are attached to the
  midpoint of each geometric pixel. The image has NX columns and NY
  rows. Physical coordinates are attached to each pixel by using
  the IMGXRANGE and IMGYRANGE keywords. The IMGXRANGE keyword is a
  two-element array specifying the "left" and "right" boundaries of
  the image pixels in physical units; the IMGYRANGE keyword
  specifies the "top" and "bottom" boundaries of the image. This is
  illustrated in Figure 1 for a simplified case.
                                  ___
        +-----------+-----------+ ^ IMGYRANGE[1]
        | | | |
        | IMG[0,1] | IMG[1,1] | |
        | + | + | |
        | | | |
        | | | |
        +-----------+-----------+ |
        | | | |
        | IMG[0,0] | IMG[1,0] | |
        | + | + | |
        | | | |
        | | | v
        +-----------+-----------+ ___ IMGYRANGE[0]
        | |
        |<----------------------->|
        IMGXRANGE[0] IMGXRANGE[1]
      Figure 1. Simplified example of a 2x2 input image,
      demonstrating that IMG[*,*] values refer to the pixel
      mid-points, and that IMGXRANGE and IMGYRANGE ranges specify the
      physical coordinates of the outer edges of the image extent in
      X and Y, respectively.
 
  The displayed plot coordinate system is entirely independent of
  the native image coordinates. Users can set up the plot scale
  using any combination of {X,Y}RANGE, {X,Y}STYLE and/or {X,Y}LOG,
  as they would for any IDL plot, using physical units. The input
  image will then be overlayed on this coordinate system.
  If the displayed plot coordinates are narrower than the native
  image coordinates, then the displayed portion of the image will be
  cropped to fit. If the displayed coordinates are wider than the
  native image coordinates, then the image will be displayed with
  blank spaces on either side (see Figure 2). A mirror "flip" is
  also possible in X and/or Y, if XRANGE or YRANGE are specified in
  reverse order.
                                                ___
      +---------------------------------------+ ^
      | ___ | |
      | ^ +---------------+ | |
      | | | | | |
      | | | | | |
      | IMGYRANGE| | IMG | | | YRANGE
      | | | | | |
      | v | | | |
      | ___ +---------------+ | |
      | |<-- IMGXRANGE -->| | |
      | | v
      +---------------------------------------+ ___
    |<------------- XRANGE -------------->|
    Figure 2. Example of an image whose native image coordinates
    are embedded in a wider plot display range.
  The standard [XY]STYLE keywords can be used to style either axis.
  However at the very least [XY]STYLE=1 is always implied, i.e. the
  plot limits exactly obey the [XY]RANGE keyword values.
  If XLOG or YLOG are set, then the image is assumed to be sampled
  on a logarithmic grid, and logarithmic axes are displayed
  accordingly. PLOTIMAGE does not attempt to resample the image
  from linear scale to logarithmic scale, or reverse.
  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, and then PLOTIMAGE will
        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: IMGXRANGE = [0,NX]
                                  IMGYRANGE = [0,NY]
  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: XRANGE=IMGXRANGE
                            YRANGE=IMGYRANGE
  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 independently in X and Y in order
                        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 have a
            resolution of 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. However, it's usually more straightforward to set
            XSTYLE=4 or YSTYLE=4, which is the standard IDL way to
            disable coordinate axes.
  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
  Enable XLOG and YLOG keywords, for logarithmic axes;
    doesn't actually resample the image from linear<->log, CM
    21 Jan 2009
  Documentation, CM, 21 Jan 2009
  Allow reverse color scale, CM, 13 Nov 2010
  $Id: plotimage.pro,v 1.15 2010/11/13 09:53:39 cmarkwar Exp $



© 2018 Harris Geospatial Solutions, Inc. |  Privacy Policy
My Account    |    Store    |    Contact Us