The SYMBOL function adds a symbol or multiple symbols (with optional text labels) to the current IDL graphic.
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, $
/SYM_FILLED, SYM_COLOR='red', SYM_SIZE = 2, $
LABEL_STRING=labels )
See Additional Examples for more examples using the SYMBOL function.
Result = SYMBOL(X, Y [, Symbol] [, Keywords=value] [, Properties=variable])
Keywords are applied only during the initial creation of the graphic.
[, /DATA] [, /DEVICE] [, /NORMAL] [, /RELATIVE] [, TARGET=variable]
Properties can be set as keywords to the function during creation, or retrieved or changed using the "." notation after creation.
CLIP, LABEL_COLOR, LABEL_FILL_BACKGROUND, LABEL_FILL_COLOR, LABEL_FONT_NAME, LABEL_FONT_SIZE, LABEL_FONT_STYLE, LABEL_ORIENTATION, LABEL_POSITION, LABEL_SHIFT, LABEL_STRING, LABEL_TRANSPARENCY, LINESTYLE, LINE_COLOR, LINE_THICK, SYM_COLOR, SYM_FILLED, SYM_FILL_COLOR, SYM_FONT_FILL_BACKGROUND, SYM_FONT_FILL_COLOR, SYM_FONT_NAME, SYM_FONT_SIZE, SYM_FONT_STYLE, SYM_ROTATE, SYM_SIZE, SYM_TEXT, SYM_THICK, SYM_TRANSPARENCY, SYMBOL, UVALUE, WINDOW
Note: Unlike other graphics objects, the ::Scale method is not available. To resize or scale a symbol, use the SYM_SIZE or SYM_FONT_SIZE properties.
Returns a reference to the created symbol. Use the reference to manipulate the symbol after creation by changing properties or calling methods.
A scalar or array of x locations where the symbols will be placed. The x coordinates may be specified in data, normal (the default), or device coordinates.
A scalar or array of y locations where the symbols will be placed. The y coordinates may be specified in data, normal (the default), or device coordinates.
An optional scalar string giving the symbol name. See Formatting IDL Graphics Symbols and Linesfor 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.
If the SYM_TEXT property is set, then the Symbol argument is ignored.
Keywords are applied only during the initial creation of the graphic.
Set this keyword to 1 if the input arguments are specified in data coordinates. Setting this keyword inserts the symbol into the data space. Otherwise, the symbol is added to the annotation layer.
If the data space has a map projection, the X and Y arguments are automatically transformed to the projection.
Set this keyword if the X and Y coordinates are specified in device coordinates (pixels).
Set this keyword if the input arguments are specified in normalized (0, 1) coordinates (the default coordinate system).
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.
If points are specified in data coordinates, set this keyword to the graphic object in which to insert the symbol. By default, the current graphic is used.
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.
Set this property to a string or RGB vector that specifies the text color. The default value is 'black'.
Set this property to 1 to fill the area inside the text box.
Set this property to a string or RGB vector that specifies the fill color inside the text box.
Set this property to a string specifying the name of the IDL or system font to use for the text string. The default value is 'Helvetica'.
Set this property to an integer or floating-point value giving the font size in points. The default value is 16.
Set this property to an integer or string specifying the font style to be used for the text string. Allowed 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 |
Set this property to an integer specifying the angle in degrees to rotate the label text. The angle rotates counterclockwise from the positive x axis. The default value is 0 (no rotation).
Set this property to a string that specifies the location of the label string with respect to the symbol. Possible values are:
|
String |
Abbreviation |
|---|---|
|
'Center' |
'C' |
|
'Right' |
'R' |
|
'Bottom Right' |
'BR' |
|
'Top Right' |
'TR' |
|
'Top' |
'T' |
|
'Bottom' |
'B' |
|
'Left' |
'L' |
|
'Top Left' |
'TL' |
| 'Bottom Left' |
'BL' |
The default value is 'Right'.
Set this property to a 2-element array specifying an amount to shift the location of the label in the X and Y directions. If the symbol is in the data space, these values should be specified using data coordinates. If the symbol is in the annotation layer, these values should be specified in normal coordinates.
Set this property to a scalar string or an array of strings containing the label text. If there are less labels than symbols, then the labels are cyclically repeated. If LABEL_STRING is set to a scalar string, then all symbols will have the same label.
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.
Set this property to an integer between 0 and 100 that specifies the percent transparency of the text. The default value is 0.
Set this property to an integer or string specifying the line style used to connect the symbols. The allowed values are:
| Index | String (case insensitive) |
|---|---|
| 0 | 'solid' or '-'(dash) |
| 1 | 'dot' or ':'(colon) |
| 2 | 'dash' or '--' (double dashes) |
| 3 | 'dash dot' or '-.' |
| 4 | 'dash dot dot dot' or '-:' |
| 5 | 'long dash' or '__' (double underscores) |
| 6 | 'none' or ' ' (space) |
The default value is 6 (no line).
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.
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.
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.
Set this property to fill the symbols.
Note: This property is ignored if SYM_TEXT is set.
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.
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.
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.
Set this property to a string specifying the name of the IDL or system font to use for the text symbol.
Note: If SYMBOL is being displayed instead of SYM_TEXT, then this property is ignored.
Set this property to an integer or floating-point value giving the font size (in points). The default value is 12.
Note: If SYMBOL is being displayed instead of SYM_TEXT, then this property is ignored.
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.
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.
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.
Set this property to a scalar string or an array of strings to be used as the symbol text. If there are less strings than symbol locations, then 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 then 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.
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.
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.
Set this property to a string giving the symbol name. See Formatting IDL Graphics Symbols and Linesfor 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.
Set this property to an IDL variable of any data type.
This property retrieves a reference to the WINDOW object which contains the graphic.
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.
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.
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.
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.
| 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. |