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