POLAR_CONTOUR Procedure

The POLAR_CONTOUR procedure draws a contour plot from data in polar coordinates. Data can be regularly- or irregularly-gridded. All of the keyword options supported by CONTOUR are available to POLAR_CONTOUR.

This routine is written in the IDL language. Its source code can be found in the file polar_contour.pro in the lib subdirectory of the IDL distribution.

Examples

This example uses POLAR_CONTOUR with regularly-gridded data:

;Handle TrueColor displays:
DEVICE, DECOMPOSED=0
;Load color table
TEK_COLOR
nr = 12 ; number of radii
nt = 18 ; number of Thetas
; Create a vector of radii:
r = FINDGEN(nr)/(nr-1)
; Create a vector of Thetas:
theta = 2*!PI * FINDGEN(nt)/(nt-1)
; Create some data values to be contoured:
z = COS(theta*3) # (r-0.5)^2
; Create the polar contour plot:
POLAR_CONTOUR, z, theta, r, /FILL, c_color=[2, 3, 4, 5]

Syntax

POLAR_CONTOUR, Z, Theta, R [, C_ANNOTATION=vector_of_strings] [, C_CHARSIZE=value] [, C_CHARTHICK=integer] [, C_COLORS=vector] [, C_LINESTYLE=vector] [, /FILL | , CELL_FILL [, C_ORIENTATION=degrees] [, C_SPACING=value]] [, C_THICK=vector] [, /CLOSED] [, /IRREGULAR] [, /ISOTROPIC] [, LEVELS=vector | NLEVELS=integer{1 to 29}] [, MAX_VALUE=value] [, MIN_VALUE=value] [, /OVERPLOT] [, TRIANGULATION=variable] [, /XLOG] [, /YLOG] [, /ZAXIS] [, SHOW_TRIANGULATION=color_index]

Graphics Keywords:[, BACKGROUND=color_index] [, CHARSIZE=value] [, CHARTHICK=integer] [, CLIP=[X₀, Y₀, X₁, Y₁]] [, COLOR=value] [, /DATA| , /DEVICE| , /NORMAL] [, FONT=integer] [, /NOCLIP] [, /NODATA] [, /NOERASE] [, POSITION=[X₀, Y₀, X₁, Y₁]] [, SUBTITLE=string] [, /T3D] [, THICK=value] [, TICKLEN=value] [, TITLE=string]
[, {X | Y | Z} CHARSIZE=value]
[, {X | Y | Z} GRIDSTYLE=integer{0 to 5}]
[, {X | Y | Z}MARGIN=[left, right]]
[, {X | Y | Z}MINOR=integer]
[, {X | Y | Z}RANGE=[min, max]]
[, {X | Y | Z}STYLE=value]
[, {X | Y | Z}THICK=value]
[, {X | Y | Z}TICK_GET=variable]
[, {X | Y | Z}TICKFORMAT=string]
[, {X | Y | Z}TICKINTERVAL= value]
[, {X | Y | Z}TICKLAYOUT=scalar]
[, {X | Y| Z}TICKLEN=value]
[, {X | Y | Z}TICKNAME=string_array]
[, {X | Y | Z}TICKS=integer]
[, {X | Y| Z}TICKUNITS=string]
[, {X | Y | Z}TICKV=array]
[, {X | Y | Z}TITLE=string]
[, ZVALUE=value{0 to 1}]

Arguments

Z

The data values to be contoured. If the data is regularly gridded, Z must have the dimensions (N_ELEMENTS(Theta), N_ELEMENTS(R). Note that the ordering of the elements in the array Z is opposite that used by the POLAR_SURFACE routine.

Theta

A vector of angles in radians. For regularly-gridded data, Theta must have the same number of elements as the first dimension of Z. For a scattered grid, Theta must have the same number of elements as Z.

R

A vector of radius values. For regularly-gridded data, R must have the same number of elements as the second dimension of Z. For a scattered grid, R must have the same number of elements as Z.

Keywords

C_ANNOTATION

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 POLAR_CONTOUR procedure. If there are more contour levels than elements in C_ANNOTATION, the remaining levels are labeled with their values.

Note: This keyword has no effect if the FILL or CELL_FILL keyword is set (i.e., if the contours are drawn with solid-filled or line-filled polygons).

C_CHARSIZE

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.

C_CHARTHICK

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.

C_COLORS

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.

C_LINESTYLE

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 LINESTYLE for a list of available styles.

C_ORIENTATION

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 nor C_SPACING are specified, the contours are solid filled.

C_SPACING

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.

C_THICK

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.

CELL_FILL

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.

Tip: In order for POLAR_CONTOUR to fill the contours properly when using a map projection, the X and Y arrays (if supplied) must be arranged in increasing order. This ensures that the polygons generated will be in counterclockwise order, as required by the mapping graphics pipeline.

Note: Do not draw filled contours over the poles on Cylindrical map projections. In this case, the polar points map to lines on the map, and the interpolation becomes ambiguous, causing errors in filling. One possible work-around is to limit the latitudes to the range of -89.9 degrees to + 89.9 degrees, avoiding the poles.

CLOSED

Set this keyword to a nonzero value to close contours that intersect the plot boundaries. After a contour hits a boundary, it follows the plot boundary until it connects with its other boundary intersection.

FILL

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 cannot 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. Do not use filled contours in these cases.

Do not use this keyword when you are drawing filled contours over a map, when you have missing data, or when contours extend off the edges of the contour plot. In these cases, use CELL_FILL instead.

Note: If the current graphics device is the Z-buffer, the algorithm used when the FILL keyword is specified will not work when a Z value is also specified with the graphics keyword ZVALUE. In this situation, use the CELL_FILL keyword instead of the FILL keyword.

IRREGULAR

Set this keyword to indicate that the input data is irregularly gridded. Setting IRREGULAR is the same as performing an explicit triangulation.

ISOTROPIC

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.

LEVELS

Specifies a vector containing the contour levels drawn by the POLAR_CONTOUR procedure. A contour is drawn at each level in LEVELS.

MAX_VALUE

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.

MIN_VALUE

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.

NLEVELS

The number of equally spaced contour levels that are produced by POLAR_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 a positive integer.

OVERPLOT

Set this keyword to make POLAR_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.

Note: When specifying overplot levels with the NLEVELS keyword, keep in mind that the levels are calculated according to the range set by the original POLAR_CONTOUR call. If the overplot dataset has a different range, you might want to set your levels more explicitly with the NLEVELS keyword.

SHOW_TRIANGULATION

Set this keyword to a color index to be used in overplotting the triangulation between datapoints.

TRIANGULATION

Set this keyword to a variable that contains an array of triangles returned from the TRIANGULATE procedure. Providing triangulation data allows you to contour irregularly gridded data directly, without gridding.

XLOG

Set this keyword to specify a logarithmic X axis.

YLOG

Set this keyword to specify a logarithmic Y axis.

ZAXIS

Set this keyword to an integer value to draw a Z axis for the POLAR_CONTOUR plot. POLAR_CONTOUR draws no Z axis by default. This keyword is of use only if a three-dimensional transformation is established. Possible values are:

0 - No Z axis is drawn (the default).
1 - Draws Z axis from the lower right-hand corner of the plot
2 - Draws Z axis from the lower left-hand corner of the plot
3 - Draws Z axis from the upper left-hand corner of the plot
4 - Draws Z axis from the upper right-hand corner of the plot

Version History

4.0	Introduced