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

>  Docs Center  >  IDL Reference  >  New Graphics  >  SYMBOL

### SYMBOL

SYMBOL

The SYMBOL function adds a symbol or multiple symbols (with optional text labels) to the current IDL graphic.

## Example

This example draws a map of the western United States with the state capitals.

Note: The symbol location is specified with lon/lat coordinates, and is automatically transformed to the map projection of the data space.

m = MAP('Orthographic', COLOR='light blue', $  LIMIT=[30, -120, 50, -90],$
  CENTER_LONGITUDE=-105, CENTER_LATITUDE=40)
c = MAPCONTINENTS(/USA)
m.mapgrid.ORDER, /SEND_TO_BACK

lon = [-104.98,-104.80,-111.88,-116.22,-112.03, $  -119.75,-100.78,-100.34,-96.68,-95.69,$
  -97.54,-97.53,-105.97,-112.07]
lat = [39.74,41.87,40.75,43.61,46.60, $  39.16,46.82,44.37,40.81,39.06,$
  35.48,30.27,35.67,33.45]
labels = ['CO','WY','UT','ID','MT','NV','ND', $  'SD','NE','KS','OK','TX','NM','AZ']   capitals = SYMBOL( lon, lat, 'Star', /DATA,$

### LABEL_TRANSPARENCY

Set this property to an integer between 0 and 100 that specifies the percent transparency of the text. The default value is 0.

### LINESTYLE

Set this property to an integer or string specifying the line style used to connect the symbols. The default is 'none'.

The following table lists the index values and strings you can use with this property.

 Index Property Description 0 'solid_line', '-'(dash) solid line 1 'dot', ':'(colon) dotted 2 'dash', '--' (double dashes) dashed 3 'dash_dot', '-.' dash dot 4 'dash_dot_dot_dot', '-:' dash dot dot dot 5 'long_dash', '__' (two underscores) long dash 6 'none', ' ' (space) no line

You can also set the line style 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, [2, 'AAAA'X] describes a dashed line with very short dashes of length 2 bits each.

### LINE_COLOR

Set this property to a string or RGB vector that specifies the color of the line connecting the symbols. Note that LINESTYLE must be set to a value other than 6 (no line) for the line to be visible.

Note: When plotting multiple symbols, if SYM_COLOR is set to an array of colors, then the lines connecting the symbols will correspond to the symbol colors and the LINE_COLOR property will be ignored.

### LINE_THICK

Set this property to a value between 0 and 10 that specifies the line thickness for the line connecting the symbols. A thickness of 0 displays a thin hairline on the chosen device. The default value is 1. Note that LINESTYLE must be set to a value other than 6 (no line) for the line to be visible.

### 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).

### SYM_COLOR

Set this property to a string or RGB vector that specifies the color of the symbols or the symbol text. If you are drawing multiple symbols (X and Y are arrays) then SYM_COLOR can be set to either an N-element string array of color names, or to a 3 x N byte array where each row contains the 3-element RGB color for that symbol. If there are less colors than symbols, then the colors are cyclically repeated. If there is only a single color, then all symbols will have the same color.

Note: If SYM_TEXT is set then only the first color within SYM_COLOR will be used to color all of the symbol text.

### SYM_FILLED

Set this property to fill the symbols.

Note: This property is ignored if SYM_TEXT is set.

### SYM_FILL_COLOR

Set this property to a string or RGB vector that specifies the color of the filled portion of the symbol.

If this property is not set, the symbol fill color will match the SYM_COLOR.

Note: This property is ignored if SYM_TEXT is set.

### SYM_FONT_FILL_BACKGROUND

Set this property to 1 to fill the area inside the text box when using a text string as the symbol.

Note: If SYMBOL is being displayed instead of SYM_TEXT, then this property is ignored.

### SYM_FONT_FILL_COLOR

Set this property to a string or RGB vector that specifies the color inside the text box.

Note: If SYMBOL is being displayed instead of SYM_TEXT, then this property is ignored.

### SYM_FONT_NAME

Set this property to a string specifying the name of the IDL or system font to use for the text symbol. The default value is "DejaVuSans".

Note: If SYMBOL is being displayed instead of SYM_TEXT, then this property is ignored.

### SYM_FONT_SIZE

Set this property to an integer or floating-point value giving the font size in points. The default value is 11.

Note: If SYMBOL is being displayed instead of SYM_TEXT, then this property is ignored.

### SYM_FONT_STYLE

An integer or string specifying the text symbol's font style. The valid values are:

 Integer String Resulting Style 0 "Normal" or "rm" Default (Roman) 1 "Bold" or "bf" Bold 2 "Italic" or "it" Italic 3 "Bold italic" or "bi" Bold italic

Note: If SYMBOL is being displayed instead of SYM_TEXT, then this property is ignored.

### SYM_ROTATE

Set this property to an integer specifying the angle in degrees to rotate the symbol text. The angle rotates counterclockwise from the positive x axis. The default value is 0 (no rotation).

Note: If SYMBOL is being displayed instead of SYM_TEXT, then this property is ignored.

### SYM_SIZE

Set this property to a floating point value specifying the plot symbol size. The default value is 1.

Note: This property is ignored if SYM_TEXT is set.

### SYM_TEXT

Set this property to a scalar string or an array of strings to be used as the symbol text. If there are fewer strings than symbol locations, the symbol text will be cyclically repeated. If SYM_TEXT is set to a scalar string, then all symbol locations will have the same symbol text. If this property is set the Symbol argument and the SYMBOL property are ignored. Set this property to an empty string to revert to using the SYMBOL property.

You can also add Greek letters and mathematical symbols using a TeX-like syntax. These symbols need to be enclosed within a pair of "$" characters. See Adding Mathematical Symbols and Greek Letters to the Text String for details on the available symbols. ### SYM_THICK Set this property to a floating point value between 0 and 10 that specifies the thickness (in points) of the lines used to draw the symbols. A value less than 1 displays as one pixel on the screen, but prints as a very thin line. Note: This property is ignored if SYM_TEXT is set. ### SYM_TRANSPARENCY Set this property to an integer between 0 and 100 that specifies the percent transparency of the symbols or the symbol text. The default value is 0. ### SYMBOL Set this property to a string giving the symbol name. See Plot Symbol Values for a list of valid symbol strings. Use the Symbol argument when creating a graphic symbol. Use the SYMBOL property to modify a previously-created symbol. Note: This property is ignored if SYM_TEXT is set. ### UVALUE Set this property to an IDL variable of any data type. ### WINDOW (Get Only) This property retrieves a reference to the WINDOW object which contains the graphic. ## Additional Examples ### Add a symbol to the data space of a plot p = PLOT(/TEST) s = SYMBOL(50, 0, '*', SYM_COLOR='Blue', SYM_SIZE=2,$
  SYM_THICK=3, /DATA, LABEL_STRING='My star')

In this case, if you change the plot range by moving the plot with the mouse or using the XRANGE/YRANGE properties, the symbol will move with the plot.

### Add a symbol to the annotation layer of a plot

p = PLOT(/TEST)
s = SYMBOL(0.5, 0.5, '*', SYM_COLOR='Blue', SYM_SIZE=2, $  SYM_THICK=3, /NORMAL, LABEL_STRING='My annotation') In this case, changing the plot range does not affect the position of the symbol; it remains fixed in the window. ### Add a character symbol to a map m = MAP('orthographic',$
  LIMIT=[35.86, -110.51, 42.58, -100.01], $  CENTER_LONGITUDE=-105, CENTER_LATITUDE=40) c = MAPCONTINENTS(/USA) m.MAPGRID.HIDE = 1   s1 = SYMBOL(-104.48, 39.58, SYM_TEXT='$\alpha$',$
  SYM_COLOR='Green', LABEL_STRING='Primary Site', $  /DATA, LABEL_POSITION='Top',$
  SYM_FONT_SIZE=20)

s2 = SYMBOL(-106.21, 39.38, SYM_TEXT='$\beta$', $  SYM_COLOR='Green', LABEL_STRING='Backup Site',$
  /DATA, LABEL_POSITION='Bottom', $  SYM_FONT_SIZE=20) See Adding Mathematical Symbols and Greek Letters to the Text String for details on the available symbols. ### Add a Unicode character symbol to a plot p = PLOT( FINDGEN(10), XSTYLE=1, YSTYLE=1) s2 = SYMBOL( 0.3, 0.7, /NORMAL, SYM_TEXT='!Z(7546)',$
  LABEL_STRING='Unicode Symbol', SYM_FONT_SIZE=20, \$
  SYM_FONT_NAME='Arial Unicode MS')

For an explanation of the !Z syntax for choosing a Unicode character, refer to Positioning Commands.

Note: The Arial Unicode MS font used in this example may not be available on your system, but the syntax for choosing a Unicode character is the same for all platforms.

## Version History

 8.1 Introduced 8.2 Added the following properties: CLIP, LINESTYLE, LINE_COLOR, LINE_THICK, SYM_TEXT. Added support for multiple symbols to the X and Y arguments, and to the LABEL_STRING, SYM_COLOR, and SYM_TEXT properties. Added the GetData and SetData methods. 8.2.2 Added POSITION property. 8.2.3 Added the ability to use a stippling pattern for LINESTYLE. 8.5 Added HIDE property. 8.6 Changed default font name and font size.