The POLYGON function adds a polygon annotation to an existing IDL Graphic.

Example

The following lines create the plot shown at the right.

data = RANDOMU(s,51)*15-5
upper = data + RANDOMU(s,51)*2 + 6
bottom = data - RANDOMU(s,51)*3 - 7
year = INDGEN(51) + 1950
 
p = PLOT(year, data, XRANGE=[1950,2000], YRANGE=[-15,20], $
  YTITLE='Soil Heat Accumulation [MJ m$^{-2}$]', THICK=2)
poly = POLYGON([year,reverse(year)], [upper,reverse(bottom)], $
  [REPLICATE(-0.01,102)], /DATA, /FILL_BACKGROUND, $
  FILL_COLOR="light steel blue", PATTERN_ORIENTATION=45, $
  PATTERN_SPACING=4)

Additional Examples

See Annotations examples for additional examples using the POLYGON function.

Syntax

graphic = POLYGON(X, Y, [, Z] [, Format] [, Keywords=value][Properties=value])

Keywords

Keywords are applied only during the initial creation of the graphic.

[, CONNECTIVITY=array] [, /DATA] [, /DEVICE] [, /NORMAL] [, /RELATIVE] [, TARGET=value]

Properties

Properties can be set as keywords to the function during creation, or retrieved or changed using the "." notation after creation.

ANTIALIAS, CLIP, COLOR, FILL_BACKGROUND, FILL_COLOR, FILL_TRANSPARENCY, HIDE, LINESTYLE, NAME, PATTERN_BITMAP, PATTERN_ORIENTATION, PATTERN_SPACING, PATTERN_THICK, POSITION, RGB_TABLE, THICK, TRANSPARENCY, UVALUE, VERT_COLORS, WINDOW

Methods

Close

ConvertCoord

CopyWindow

Delete

Erase

GenerateCode

GetData

GetValueAtLocation

MapForward

MapInverse

Order

Print

Refresh

Rotate

Save

Scale

Select

SetData

Translate

Note: The GetValueAtLocation method is not supported for POLYGON.

Return Value

The POLYGON function returns a reference to the created annotation. Use the returned reference to manipulate the annotation after creation by changing properties or by calling methods.

Arguments

X

Y

Z

The vertices of the polygon. The vectors X, Y, [and Z] must be of equal length. Unless Z is specified, a 2-D polygon is created.

Format

A string that sets line format properties using short tokens to represent color, linestyle, and thickness values. For example, to create a solid red line with a thickness value of 2, you would use the following:

p = POLYGON(x, y, '-r2')

Tokens in the Format string represent values of the LINESTYLE, COLOR, and THICK properties. From one to three tokens can be present, and the tokens may be in any order. Tokens are case sensitive. For more information about the syntax of the Format argument, see Formatting IDL Graphics Symbols and Lines.

Keywords

Keywords are applied only during the initial creation of the graphic.

CONNECTIVITY

A vector defining individual polygons of the form: [n, i0, i1, ..., in-1, n, i0, i1, ..., in-1], where n is the number of vertices that define a polygon, and i0..in-1 are indices into a polygon vertex list. Connectivity allows you to insert multiple polygons with a single call. All of the polygons will share the same properties.

DATA

Set this keyword if the input arguments are specified in data coordinates. Setting this keyword inserts the polygon into the data space, otherwise the polygon is added to the annotation layer.

DEVICE

Set this keyword if values are specified in device coordinates (pixels) for the MARGIN and POSITION properties. (Normalized coordinates are the default for these properties.)

NORMAL

Set this keyword if the input arguments are specified in normalized ( [0, 1] ) coordinates (the default).

RELATIVE

Set this keyword to indicate that the input arguments are specified in normalized [0,1] coordinates, relative to the axis range of the TARGET's dataspace. If the TARGET keyword is not specified, then setting /RELATIVE is the same as setting /NORMAL.

Note: When using /RELATIVE, even though the coordinates are relative to the TARGET's dataspace, the graphic is added to the annotation layer, not to the dataspace.

TARGET

Set this keyword to the graphic object to use if points are specified in data coordinates. By default, the current graphic is used.

Properties

ANTIALIAS

By default anti-aliasing is used when drawing lines and polygons. Set this property to 0 to disable anti-aliasing.

CLIP

Set this property to 1 to clip portions of the graphic that lie outside of the dataspace range, or to 0 to disable clipping. The default is 1. This property is ignored unless the DATA property is set.

COLOR

Set this property to a string or RGB vector that specifies the color of the polygon. The default is "black".

FILL_BACKGROUND

A value of 1 fills the area inside the polygon.

FILL_COLOR

Set this property to a string or RGB vector that specifies the fill color inside the polygon.

FILL_TRANSPARENCY

An integer between 0 and 100 that specifies the percent transparency of the inside of the polygon. The default value is the same as the TRANSPARENCY property.

HIDE

Set this property to 1 to hide the graphic. Set HIDE to 0 to show the graphic.

LINESTYLE

Set this property to an integer or string specifying the line style for the outline.

The following table lists the index values, strings, and characters you can use with the LINESTYLE property, and the equivalent characters and strings you can use in the Format string argument.

Index

LINESTYLE Property

Format Argument

Description

0

'solid_line', '-'(dash)

'-' (dash)

solid line

1

'dot', ':'(colon)

':'(colon)

dotted

2

'dash', '--' (double dashes)

'--' (double dashes)

dashed

3

'dash_dot', '-.'

'-.'

dash dot

4

'dash_dot_dot_dot', '-:'

'-:'

dash dot dot dot

5

'long_dash', '__' (two underscores)

'__' (double underscores)

long dash

6

'none', ' ' (space)

' ' (space)

no line

Note: If you use the LINESTYLE value or Format string '-.', the linestyle is set to dash-dot and the plot symbol is not set.

Note: You can also set LINESTYLE to a two-element vector, [repeat, bitmask], specifying a stippling pattern. The repeat indicates the number of times that individual bits in the bitmask should be repeated. (That is, if three consecutive 0’s appear in the bitmask and the value of repeat is 2, then the line that is drawn will have six consecutive bits turned off.) The value of repeat must be an integer between 1 and 255. The bitmask indicates which pixels are drawn and which are not along the length of the line. The bitmask should be specified as a 16-bit hexadecimal value. For example, LINESTYLE = [2, 'F0F0'X] describes a dashed line (8 bits on, 8 bits off, 8 bits on, 8 bits off).

NAME

A string that specifies the name of the graphic. The name can be used to retrieve the graphic using the brackets array notation. If NAME is not set then a default name is chosen based on the graphic type.

PATTERN_BITMAP

By default the polygon is filled with a solid color given by FILL_COLOR. Instead, you can specify a fill pattern as a 32x32 bit array (bitmap). The bitmap must be constructed as a 4x32 "bitmap byte array" as created by the CVTTOBM function. Each bit that is a 1 is drawn, each bit that is 0 is not drawn. Each bit in this array represents a 1 point by 1 point square area of pixels on the destination device.

Note: To turn off pattern fill set PATTERN_BITMAP to a scalar 0.

PATTERN_ORIENTATION

By default the polygon is filled with a solid color given by FILL_COLOR. By setting any of the PATTERN_ORIENTATION, PATTERN_SPACING, or PATTERN_THICK properties, your polygon will be filled with a line pattern. Set PATTERN_ORIENTATION to the angle (in degrees counterclockwise from horizontal) of the lines. The default is 0 degrees.

Note: To turn off line fill set PATTERN_SPACING to 0.

PATTERN_SPACING

By default the polygon is filled with a solid color given by FILL_COLOR. By setting any of the PATTERN_ORIENTATION, PATTERN_SPACING, or PATTERN_THICK properties, your polygon will be filled with a line pattern. Set PATTERN_SPACING to the distance (in points) between the lines in the line fill. The default is 0.0 points.

Note: To turn off line fill set PATTERN_SPACING to 0.

PATTERN_THICK

By default the polygon is filled with a solid color given by FILL_COLOR. By setting any of the PATTERN_ORIENTATION, PATTERN_SPACING, or PATTERN_THICK properties, your polygon will be filled with a line pattern. Set PATTERN_THICK to a value between 0.0 and 10.0 that specifies the line thickness (in points) for the line fill. A thickness of 0 displays a thin hairline. The default is 1.0 points.

Note: To turn off line fill set PATTERN_SPACING to 0.

POSITION

Set this property to a two or four-element vector that determines the position of the graphic within the window. If two elements are provided, the center of the graphic will be translated to that position. For four elements, the coordinates [X1, Y1, X2, Y2] define the lower left and upper right corners of the graphic. Coordinates are expressed in normalized units ranging from 0.0 to 1.0. On creation, if the DEVICE keyword is set, the units are given in device units (pixels).

RGB_TABLE

The number of the predefined IDL color table, or a 3 x 256 or 256 x 3 byte array containing color values to use for vertex colors. Use the VERT_COLORS property to specify indices that select colors from the values specified with RGB_TABLE.

THICK

Set this property to a value between 0 and 10 that specifies the thickness of the polygon outline. A thickness of 0 displays a thin hairline on the chosen device. The default value is 1.

TRANSPARENCY

An integer between 0 and 100 that specifies the percent transparency of the polygon. The default value is 0.

UVALUE

Set this property to an IDL variable of any data type.

VERT_COLORS

A vector of indices into the color table for the color of each vertex (polygon data point). Alternately, a 3 x N (RGB) or 4 x N (RGBA) byte array containing vertex color values. If indices are supplied but no colors are provided with the RGB_TABLE property, a default grayscale ramp is used. If a 3 x N or 4 x N array of colors is provided, the colors are used directly and the color values provided with RGB_TABLE are ignored.

WINDOW (Get Only)

This property retrieves a reference to the WINDOW object which contains the graphic.

Version History

8.0

Introduced

8.1

Added the UVALUE property

The THICK property was changed to accept a value between 0 and 10

Added the following methods: Delete, GetData, SetData

8.2.1

Added RGB_VALUE and VERT_COLORS properties.

8.2.2

Added POSITION property.

8.2.3

Added the ability to use a stippling pattern for LINESTYLE.
8.5 Added PATTERN_BITMAP, PATTERN_ORIENTATION, PATTERN_SPACING, and PATTERN_THICK properties.

See Also

!COLOR, Formatting IDL Graphics Symbols and Lines, PLOT, POLYLINE, Using IDL graphics