 |
| |
The CONTOUR procedure draws a contour plot from data stored in a rectangular array or from a set of unstructured points. Both line contours and filled contour plots can be created. Note that outline and fill contours cannot be drawn at the same time. To create a contour plot with both filled contours and outlines, first create the filled contour plot, then add the outline contours by calling CONTOUR a second time with the OVERPLOT keyword.
Contours can be smoothed by using the MIN_CURVE_SURF function on the contour data before contouring.
Using various keywords, described below, it is possible to specify contour levels, labeling, colors, line styles, and other options. CONTOUR draws contours by searching for each contour line and then following the line until it reaches a boundary or closes.
The MIN_CURVE_SURF function can be used to smoothly interpolate both regularly and irregularly sampled surfaces before contouring. This function replaces the older SPLINE keyword to CONTOUR, which was inaccurate and is no longer supported. MIN_CURVE_SURF interpolates the entire surface to a relatively fine grid before drawing the contours.
A one- or two-dimensional array containing the values that make up the contour surface. If arguments X and Y are provided, the contour is plotted as a function of the (X, Y) locations specified by their contents. Otherwise, the contour is generated as a function of the two-dimensional array index of each element of Z .
If the IRREGULAR keyword is set, X, Y, and Z are treated as vectors. Each point has a value of Z i and a location of (X i , Y i )
This argument is converted to single-precision floating-point before plotting. Plots created with CONTOUR are limited to the range and precision of single-precision floating-point values.
A vector or two-dimensional array specifying the X coordinates for the contour surface. If X is a vector, each element of X specifies the X coordinate for a column of Z (e.g., X[0] specifies the X coordinate for Z[0,*]). If X is a two-dimensional array, each element of X specifies the X coordinate of the corresponding point in Z (i.e., X ij specifies the X coordinate for Z ij ).
A vector or two-dimensional array specifying the Y coordinates for the contour surface. If Y a vector, each element of Y specifies the Y coordinate for a row of Z (e.g., Y[0] specifies the Y coordinate for Z[*,0]). If Y is a two-dimensional array, each element of Y specifies the Y coordinate of the corresponding point in Z ( Y ij specifies the Y coordinate for Z ij ).
The label to be drawn on each contour. Usually, contours are labeled with their value. This parameter, a vector of strings, allows any text to be specified. The first label is used for the first contour drawn, and so forth. If the LEVELS keyword is specified, the elements of C_ANNOTATION correspond directly to the levels specified, otherwise, they correspond to the default levels chosen by the CONTOUR procedure. If there are more contour levels than elements in C_ANNOTATION, the remaining levels are labeled with their values.
The size of the characters used to annotate contour labels. Normally, contour labels are drawn at 3/4 of the size used for the axis labels (specified by the CHARSIZE keyword or !P.CHARSIZE system variable. This keyword allows the contour label size to be specified directly. Use of this keyword implies use of the FOLLOW keyword.
The thickness of the characters used to annotate contour labels. Set this keyword equal to an integer value specifying the line thickness of the vector drawn font characters. This keyword has no effect when used with the hardware drawn fonts. The default value is 1. Use of this keyword implies use of the FOLLOW keyword.
The color index used to draw each contour. This parameter is a vector, converted to integer type if necessary. If there are more contour levels than elements in C_COLORS, the elements of the color vector are cyclically repeated.
Specifies which contour levels should be labeled. By default, every other contour level is labeled. C_LABELS allows you to override this default and explicitly specify the levels to label. This parameter is a vector, converted to integer type if necessary. If the LEVELS keyword is specified, the elements of C_LABELS correspond directly to the levels specified, otherwise, they correspond to the default levels chosen by the CONTOUR procedure. Setting an element of the vector to zero causes that contour label to not be labeled. A nonzero value forces labeling.
Use of this keyword implies use of the FOLLOW keyword.
The line style used to draw each contour. As with C_COLORS, C_LINESTYLE is a vector of line style indices. If there are more contour levels than line styles, the line styles are cyclically repeated. See IDL Linestyles on page IDL Linestyles for a list of available styles.
NOTE: The cell drawing contouring algorithm draws all the contours in each cell, rather than following contours. Since an entire contour is not drawn as a single operation, the appearance of the more complicated linestyles will suffer. Use of the contour following method (selected with the FOLLOW keyword) will give better looking results in such cases.
If the FILL keyword is set, this keyword can be set to the angle, in degrees counterclockwise from the horizontal, of the lines used to fill contours. If neither C_ORIENTATION or C_SPACING are specified, the contours are solid filled.
If the FILL keyword is set, this keyword can be used to control the distance, in centimeters, between the lines used to fill the contours.
The line used to draw each contour level. As with C_COLORS, C_THICK is a vector of line thickness values, although the values are floating point. If there are more contours than thickness elements, elements are repeated. If omitted, the overall line thickness specified by the THICK keyword parameter or !P.THICK is used for all contours.
Set this keyword to produce a filled contour plot using a "cell filling" algorithm. Use this keyword instead of FILL when you are drawing filled contours over a map, when you have missing data, or when contours that extend off the edges of the contour plot. CELL_FILL is less efficient than FILL because it makes one or more polygons for each data cell. It also gives poor results when used with patterned (line) fills, because each cell is assigned its own pattern. Otherwise, this keyword operates identically to the FILL keyword, described below.
Set this keyword to close contours that intersect the plot boundaries. After a contour hits a boundary, it is follows the plot boundary until it connects with its other boundary intersection.
Set this keyword to label each contour with short, perpendicular tick marks that point in the "downhill" direction, making the direction of the grade readily apparent. If this keyword is set, the contour following method is used in drawing the contours.
Set this keyword to produce a filled contour plot. The contours are filled with solid or line-filled polygons. For solid polygons, use the C_COLOR keyword to specify the color index of the polygons for each contour level. For line fills, use C_ORIENTATION, C_SPACING, C_COLOR, C_LINESTYLE, and/or C_THICK to specify attributes for the lines.
If the current device is not a pen plotter, each polygon is erased to the background color before the fill lines are drawn, to avoid superimposing one pattern over another.
Contours that are not closed can not be filled because their interior and exterior are undefined. Contours created from data sets with missing data may not be closed; many map projections can also produce contours that are not closed. Filled contours should not be used in these cases.
In IDL version 5, CONTOUR always uses a line-following method. The FOLLOW keyword remains available for compatibility with existing code, but is no longer necessary. As in previous versions of IDL, setting FOLLOW will cause CONTOUR to draw contour labels.
Set this keyword to indicate that the input data is irregularly gridded. Setting IRREGULAR is the same as performing an explicit triangulation. That is:
Set this keyword to force the scaling of the X and Y axes to be equal.
NOTE: The X and Y axes will be scaled isotropically and then fit within the rectangle defined by the POSITION keyword; one of the axes may be shortened. See POSITION for more information.
Specifies a vector containing the contour levels drawn by the CONTOUR procedure. A contour is drawn at each level in LEVELS.
Data points with values above this value are ignored (i.e., treated as missing data) when contouring. Cells containing one or more corners with values above MAX_VALUE will have no contours drawn through them. Note that the IEEE floating-point value NaN is also treated as missing data. (See Special Floating-Point Values for more information on IEEE floating-point values.)
Data points with values less than this value are ignored (i.e., treated as missing data) when contouring. Cells containing one or more corners with values below MIN_VALUE will have no contours drawn through them. Note that the IEEE floating-point value NaN is also treated as missing data. (See Special Floating-Point Values for more information on IEEE floating-point values.)
The number of equally spaced contour levels that are produced by CONTOUR. If the LEVELS parameter, which explicitly specifies the value of the contour levels, is present this keyword has no effect. If neither parameter is present, approximately six levels are drawn. NLEVELS should be an integer between 1 and 29.
Set this keyword to make CONTOUR "overplot". That is, the current graphics screen is not erased, no axes are drawn and the previously established scaling remains in effect. You must explicitly specify either the values of the contour levels or the number of levels (via the NLEVELS keyword) when using this option, unless geographic mapping coordinates are in effect.
Set this keyword to cause the output contour positions to be measured in data units rather than the default normalized units. This keyword is useful only if the PATH_XY or PATH_FILENAME keywords are set.
Specifies the name of a file to contain the contour positions. If PATH_FILENAME is present, CONTOUR does not draw the contours, but rather, opens the specified file and writes the positions, in normalized coordinates, into it. The file consists of a series of logical records containing binary data. Each record is preceded with a header structure defining the contour as follows:
{CONTOUR_HEADER, TYPE:0B, HIGH:0B, LEVEL:0, NUM:0L, VALUE:0.0}
A byte that is 1 if the contour is closed and above its surroundings, and is 0 if the contour is below. This field is meaningless if the contour is not closed.
The contour value. This is a single precision floating point value.
Following the header in each record are NUM X-coordinate values followed by NUM Y-coordinate values, expressed in normalized coordinates.
PATH_XY is ignored if the TRIANGULATION keyword is set. Use of this keyword implies use of the FOLLOW keyword.
Set this keyword to a named variable that will return path information for the contours. This information can be used, along with data stored in a variable named by the PATH_XY keyword, to trace closed contours. If PATH_INFO is present, CONTOUR does not draw the contours, but rather records the path information in an array of structures of the following type:
{CONTOUR_PATH_STRUCTURE, TYPE:0B, HIGH_LOW:0B, $
LEVEL:0, N:0L, OFFSET:0L, VALUE:0.0}
A byte that is zero if the contour is open, and one if it is closed. In the present implementation, all contours are closed.
A byte that is 1 if the contour is above its surroundings, and is 0 if the contour is below.
A short integer indicating the index of the contour level, from zero to the number of levels minus one.
Set this keyword to a named variable that returns the normalized coordinates of a set of closed polygons defining the closed paths of the contours. This information can be used, along with data stored in a variable named by the PATH_INFO keyword, to trace closed contours. If PATH_XY is present, CONTOUR does not draw the contours, but rather records the normalized path coordinates in the named array. PATH_XY is ignored if the TRIANGULATION keyword is set.
See the examples section below for an example using the PATH_INFO and PATH_XY keywords to return contour path information.
See , Graphics Keywords , for the description of graphics and plotting keywords not listed above. BACKGROUND
To create a contour plot with 10 contour levels where every other contour is labeled:
Z = DIST(100) ; Create a simple dataset to plot.
CONTOUR, Z, NLEVELS=10, /FOLLOW, TITLE='Simple Contour Plot'
;
Draw the plot.
The following commands describe a more complicated example that shows the use of polygon filling and smoothing.
First, create a surface to contour:
A = RANDOMU(seed, 5, 6) ; Create a 2D array of random numbers.
; Smooth the dataset before contouring.
TEK_COLOR ; Load discrete colors for contours.
CONTOUR, B, /FILL, NLEVELS=5, C_COLOR=INDGEN(5)+2
;
Draw filled contours.
CONTOUR, B, NLEVELS=5, /DOWNHILL, /OVERPLOT
;
Overplot the contour lines with tickmarks.
CONTOUR, B, C_ORIENTATION=[0, 22, 45]
CONTOUR, B, /OVERPLOT, NLEVELS=5 ; Overplot the contours.
The following program saves the closed path information of a set of contours and plots the result:
A = RANDOMU(seed, 8, 10) ; Create a 2D array of random numbers.
B = MIN_CURVE_SURF(A) ; Smooth the dataset before contouring.
CONTOUR, B, PATH_XY=xy, PATH_INFO=info
;
Compute contour paths.
FOR I = 0, (N_ELEMENTS(info) - 1 ) DO BEGIN
PLOTS, xy(*,INFO(I).OFFSET + S ), /NORM
;
Plot the closed paths.
To contour irregularly-gridded data without having to call TRIGRID, first use the TRIANGULATE procedure to get the Delaunay triangulation of your data, then pass the triangulation array to CONTOUR:
IMAGE_CONT , SHADE_SURF , SHOW3 , SURFACE