The IDL Direct Graphics routines, CURSOR, ERASE, PLOTS, POLYFILL, TV (and TVSCL), TVCRS, TVRD, and XYOUTS, and the plotting procedures, AXIS, CONTOUR, PLOT, OPLOT, SHADE_SURF, and SURFACE, accept a number of common keywords. Therefore, instead of describing each keyword along with the description of each routine, this section contains a brief summary of each graphics keyword. Routine-specific keywords are documented in the description of the routine.
The graphics keywords are described below. The name of each keyword is followed by a list of routines that accept that keyword. Keywords that have a direct correspondence to fields in a system variable (usually
The keywords that control the plot axes are prefixed with the character `X', `Y', or `Z' depending on the axis in question. These keywords correspond to fields in the axis system variables:
The system variable fields that control this are
The following graphics keywords are discussed in this section:
Accepted by: CONTOUR, PLOT, SURFACE.
System variable equivalent:
The background color index to which all pixels are set when erasing the screen or page. The default is 0 (black). Not all devices support erasing the background to a specified color index.
For example, to produce a black plot with a white background on a color display:
PLOT, Y, BACKGROUND = 255, COLOR = 0
Accepted by: ERASE, TV, TVRD. System variable equivalent:
This keyword specifies the memory channel for the operation. This parameter is ignored on display systems that have only one memory channel. When using a "decomposed" display system, the red channel is 1, the green channel is 2, and the blue channel is 3. Channel 0 indicates all channels. If omitted,
| Note |
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE, XYOUTS. System variable equivalent:
The overall character size for the annotation when Hershey fonts are selected. This keyword does not apply when hardware (i.e. PostScript) fonts are selected. A CHARSIZE of 1.0 is normal. The size of the annotation on the axes may be set, relative to CHARSIZE, with xCHARSIZE, where x is X, Y, or Z. The main title is written with a character size of 1.25 times this parameter.
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE, XYOUTS. System variable equivalent:
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.
Accepted by: CONTOUR, DRAW_ROI, OPLOT, PLOT, PLOTS, POLYFILL, SURFACE, XYOUTS. System variable equivalent:
The coordinates of a rectangle used to clip the graphics output. The rectangle is specified as a vector of the form [X0, Y0, X1, Y1], giving coordinates of the lower left and upper right corners, respectively. The default clipping rectangle is the plot window, the area enclosed within the axes of the most recent plot. Coordinates are specified in data units unless an overriding coordinate unit specification keyword is present (i.e., NORMAL or DEVICE). If the clipping is provided in data or normalized units, the actual clipping rectangle is computed by converting those values to device units. The clipping itself always occurs in device space.
| Note |
For example, to draw a vector using normalized coordinates with its contents clipped within a rectangle covering the upper left quadrant of the display:
PLOTS, X, Y, CLIP=[0.,.5,.5,1.0], /NORM, NOCLIP=0
Accepted by: AXIS, CONTOUR, DRAW_ROI, ERASE, OPLOT, PLOT, PLOTS, POLYFILL, SHADE_SURF, SURFACE, XYOUTS. System variable equivalent:
The color index of the data, text, line, or solid polygon fill to be drawn. If this keyword is omitted,
When used with the PLOTS, POLYFILL, or XYOUTS procedure, this keyword parameter can be set to a vector to specify multiple color indices.
Gouraud shading of polygons is performed with the Z-buffer graphics output device and POLYFILL procedure when COLOR contains an array of color indices, one for each vertex.
Accepted by: AXIS, CONTOUR, CURSOR, DRAW_ROI, PLOT, PLOTS, POLYFILL, SHADE_SURF, SURFACE, TV, TVCRS, XYOUTS.
Set this keyword to indicate that the clipping and/or positioning coordinates supplied are specified in the data coordinate system. The default coordinate system is DATA if no other coordinate-system specifications are present.
AXIS, CONTOUR, CURSOR, DRAW_ROI, PLOT, PLOTS, POLYFILL, SHADE_SURF, SURFACE, TV, TVCRS, XYOUTS.
Set this keyword to indicate that the clipping and/or positioning coordinates supplied are specified in the device coordinate system. The default coordinate system is DATA if no other coordinate-system specifications are present.
For example, the following code displays an image contained in the variable A and then draws a contour plot of pixels [100:499, 100:399] over the correct section of the image:
;Display the image. TV,A ;Draw the contour plot, specify the coordinates of the plot, in ;device coordinates, do not erase, set the X and Y axis styles to ;EXACT. CONTOUR, A[100:499, 100:399], $ POS = [100,100, 499,399], /DEVICE, $ /NOERASE, XSTYLE=1, YSTYLE=1
Note that in the above example, the keyword specification /DEVICE is equivalent to DEVICE = 1.
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE, XYOUTS. System variable equivalent:
An integer that specifies the graphics text font system to use. Set FONT equal to -1 to selects the Hershey character fonts, which are drawn using vectors. Set FONT equal to 0 (zero) to select the device font of the output device. Set FONT equal to 1 (one) to select the TrueType font system. See Fonts for a complete description of IDL's font systems.
Accepted by: DRAW_ROI, OPLOT, PLOT, PLOTS, SURFACE. System variable equivalent:
This keyword indicates the line style used to draw lines; it indicates the line style of the lines used to connect the data points. This keyword should be set to the appropriate index for the desired linestyle as described in the following table.
Accepted by: CONTOUR, DRAW_ROI, OPLOT, PLOT, PLOTS, POLYFILL, SURFACE, XYOUTS. System variable equivalent:
Set this keyword to suppress clipping of the plot. The clipping rectangle is contained in
| Note |
With PLOTS, POLYFILL, and XYOUTS, this keyword controls the clipping of vectors and vector-drawn text. The default is to disable clipping, so to enable clipping include the parameter NOCLIP = 0. To explicitly disable clipping set this parameter to one.
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE.
If this keyword is set, only the axes, titles, and annotation are drawn. No data points are plotted.
For example, to draw an empty set of axes between some given values:
PLOT, [XMIN, XMAX],[YMIN, YMAX], /NODATA
Accepted by: AXIS, CONTOUR, PLOT, SURFACE. System variable equivalent:
Specifies that the screen or page is not to be erased. By default, the screen is erased, or a new page is begun, before a plot is produced.
Accepted by: AXIS, CONTOUR, CURSOR, DRAW_ROI, PLOT, PLOTS, POLYFILL, SHADE_SURF, SURFACE, TV, TVCRS, XYOUTS.
Set this keyword to indicate that the clipping and/or positioning coordinates supplied are specified in the normalized coordinate system, and range from 0.0 to 1.0. The default coordinate system is DATA if no other coordinate-system specifications are present.
Accepted by: DRAW_ROI, POLYFILL, XYOUTS.
Specifies the counterclockwise angle in degrees from horizontal of the text baseline and the lines used to fill polygons.When used with the POLYFILL procedure, this keyword forces the "linestyle" type of fill, rather than solid or patterned fill.
Accepted by: CONTOUR, MAP_SET, PLOT, SHADE_SURF, SURFACE. System variable equivalent:
Allows direct specification of the plot window. POSITION is a 4-element vector giving, in order, the coordinates [(X0, Y0), (X1, Y1)], of the lower left and upper right corners of the data window. Coordinates are expressed in normalized units ranging from 0.0 to 1.0, unless the DEVICE keyword is present, in which case they are in actual device units. The value of POSITION is never specified in data units, even if the DATA keyword is present.
When setting the position of the window, be sure to allow space for the annotation, which resides outside the window. IDL outputs the message "% Warning: Plot truncated." if the plot region is larger than the screen or page size. The plot region is the rectangle enclosing the plot window and the annotation.
When plotting in three dimensions, the POSITION keyword is a 6-element vector with the first four elements describing, as above, the XY position, and with the last two elements giving the minimum and maximum Z coordinates. The Z specification is always in normalized coordinate units.
When making more than one plot per page it is more convenient to set
For example, the following statement produces a contour plot with data plotted in only the upper left quarter of the screen:
CONTOUR, Z, POS=[0., 0.5, 0.5, 1.0]
Because no space on the left or top edges was allowed for the axes or their annotation, the above described warning message results.
Accepted by: DRAW_ROI, OPLOT, PLOT, PLOTS. System variable equivalent:
The symbol used to mark each data point. Normally, PSYM is 0, data points are connected by lines, and no symbols are drawn to mark the points. Set this keyword, or the system variable
|
PSYM Value
|
Plotting Symbol
|
|---|---|
| 1 |
Plus sign (+)
|
| 2 |
Asterisk (*)
|
| 3 |
Period (.)
|
| 4 |
Diamond
|
| 5 |
Triangle
|
| 6 |
Square
|
| 7 |
X
|
| 8 |
User-defined. See USERSYM procedure.
|
| 9 |
Undefined
|
| 10 |
Histogram mode. Horizontal and vertical lines connect the plotted points, as opposed to the normal method of connecting points with straight lines.
|
Negative values of PSYM cause the symbol designated by PSYM to be plotted at each point with solid lines connecting the symbols. For example, a value of -5 plots triangles at each data point and connects the points with lines. Histogram mode is the exception to this rule; since the points are already connected when PSYM=10, specifying the value -10 is meaningless, and will result in an error.
The following IDL code plots an array using points, and then overplots the smoothed array, connecting the points with lines:
;Plot using points. PLOT, A, PSYM=3 ;Overplot smoothed data. OPLOT, SMOOTH(A,7)
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE. System variable equivalent:
A text string to be used as a subtitle for the plot. Subtitles appear below the X axis.
Accepted by: DRAW_ROI, OPLOT, PLOT, PLOTS.
Specifies the size of the symbols drawn when PSYM is set. The default size of 1.0 produces symbols approximately the same size as a character.
Accepted by: AXIS, CONTOUR, DRAW_ROI, MAP_SET, OPLOT, PLOT, PLOTS, POLYFILL, SHADE_SURF, SURFACE, TV, TVCRS, XYOUTS. System variable equivalent:
Set this keyword to indicate that the generalized transformation matrix in
| Note |
Accepted by: AXIS, DRAW_ROI, OPLOT, PLOT, PLOTS, POLYFILL, SHADE_SURF, SURFACE. System variable equivalent:
Indicates the line thickness. THICK overrides the setting of
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE. System variable equivalent:
Controls the length of the axis tick marks, expressed as a fraction of the window size. The default value is 0.02. TICKLEN of 1.0 produces a grid, while a negative TICKLEN makes tick marks that extend outside the window, rather than inwards.
For example, to produce outward-going tick marks of the normal length:
PLOT, X, Y, TICKLEN = -0.02
To provide a new default tick length, set
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE. System variable equivalent:
Produces a main title centered above the plot window. The text size of this main title is larger than the other text by a factor of 1.25. For example:
PLOT, X, Y, TITLE = 'Final Results'
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE. System variable equivalents:
The size of the characters used to annotate the axis and its title when Hershey fonts are selected. This keyword does not apply when hardware (i.e. PostScript) fonts are selected. This field is a scale factor applied to the global scale factor set by
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE
The index of the linestyle to be used for plot tickmarks and grids (i.e., when [XYZ]TICKLEN is set to 1.0). See LINESTYLE for a list of linestyles.
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE. System variable equivalent:
A 2-element array specifying the margin on the left (bottom) and right (top) sides of the plot window, in units of character size. Default margins are 10 and 3 for the X axis, and 4 and 2 for the Y axis. The ZMARGIN keyword is present for consistency and is currently ignored.
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE. System variable equivalent:
The number of minor tick mark intervals.
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE. System variable equivalent:
The desired data range of the axis, a 2-element vector. The first element is the axis minimum, and the second is the maximum. IDL will frequently round this range. This override can be defeated using the [XYZ]STYLE keywords.
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE. System variable equivalent:
This keyword allows specification of axis options such as rounding of tick values and selection of a box axis. Each option is described in the following table:
Note that this keyword is set bitwise, so multiple effects can be set by adding values together. For example, to make an X axis that is both exact (value 1) and suppresses the box style (setting 8), set the XAXIS keyword to 1+8, or 9.
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE. System variable equivalent:
This keyword controls the thickness of the lines forming the axis and tick marks. A value of 1.0 is the default.
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE.
A named variable in which to return the values of the tick marks for the designated axis. The result is a double precision floating-point array with the same number of elements as ticks.
For example, to retrieve in the variable V the values of the tick marks selected by IDL for the Y axis:
PLOT, X, Y, YTICK_GET = V
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE. System variable equivalent:
Set this keyword to a string or a vector of strings. If a vector is provided, each string corresponds to a level of the axis. The [XYZ]TICKUNITS keyword determines the number of levels for an axis.
Each string is one of the following:
If the string begins with an open parenthesis, it is treated as a standard format string. See Format Codes for more information on format codes.
Example 1: Display the X axis tick values using a format of F6.2 (six characters, with 2 places after the decimal point):
PLOT, X, Y, XTICKFORMAT='(F6.2)'
Example 2: Display the Y tick values using the "dollars and cents" format $dddd.dd:
PLOT, X, Y, YTICKFORMAT='("$", F7.2)'
Set [XYZ]TICKFORMAT to the string 'LABEL_DATE' to create axes with date labels. The formatting of the labels is specified by first calling LABEL_DATE with the DATE_FORMAT keyword. See LABEL_DATE for more information.
Example: Use the LABEL_DATE function as the callback function to display the X tick values in a date/time format:
dummy = LABEL_DATE(DATE_FORMAT='%M %Z') mytimes = TIMEGEN(12, UNITS='MONTHS', START=JULDAY(1,1,2000)) y = FINDGEN(12) PLOT, mytimes, y, XTICKUNITS='Time', XTICKFORMAT='LABEL_DATE'
If the string does not begin with an open parenthesis, it is interpreted as the name of a callback function to be used to generate tick mark labels. This function is defined with either three or four parameters, depending on whether [XYZ]TICKUNITS is specified:
If [XYZ]TICKUNITS is not specified, the callback function is called with three parameters, Axis, Index, and Value, where:
| Note |
If [XYZ]TICKUNITS is specified, the callback function is called with four parameters, Axis, Index, Value, and Level, where:
Example 1: Use a callback function to display the Y tick values as a percentage of a fixed value. Note that because we don't specify [XYZ]TICKUNITS, we do not include the Level parameter in our function definition:
FUNCTION YTICKS, axis, index, value fixvalue = 389.0d pvalue = (value/fixvalue) * 100.0d RETURN, STRING(pvalue, FORMAT='(D5.2,"%")') END PRO use_callback Y = FINDGEN(10) PLOT, Y, YTICKFORMAT='YTICKS' END
Example 2: Create a two-level X axis. Display the X tick values in a customized date/time format that shows the number of days open for business for each month on one level, and marks leap years with an asterisk on another level:
FUNCTION XTICKS, axis, index, value, level
CASE level OF
0: BEGIN ; months
; Number of days open for business in given month:
CALDAT, value, month
open = [18,19,23,20,22,22,19,10,20,21,22,14]
nbdays = open[month]
; Return a string containing the month name plus
; the number of business days in parentheses:
RETURN, STRING(value, nbdays, $
FORMAT='(C(CMoA), "(", I2, ")")')
END
1: BEGIN ; years
; Generate a string for the year.
yrStr = STRING(value, FORMAT='(C(CYI))')
; Determine if a leap year. If so,
; append an asterisk to the string.
CALDAT, value, mo, da, yr
IF (yr MOD 4 EQ 0) THEN BEGIN
IF (yr MOD 100 EQ 0) THEN $
isLeap = (yr MOD 400) EQ 0 $
ELSE $
IsLeap = 1b
ENDIF ELSE $
isLeap = 0b
IF (isLeap NE 0b) THEN $
yrStr = yrStr + '*'
RETURN, yrStr
END
ENDCASE
END
PRO plot_sales
myDates = TIMEGEN(12, UNITS='Months', START=JULDAY(1,1,2000))
sales = [180,190,230,200,220,220,190,100,200,210,220,140]
PLOT, myDates, sales, XTICKUNITS=['Months', 'Years'], $
XTICKFORMAT='XTICKS', XTITLE = 'Date (* = Leap Year)', $
YTITLE='Sales (units)', POSITION = [0.2, 0.2, 0.9, 0.9]
END
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE
variable equivalent:
Set this keyword to a scalar indicating the interval between major tick marks for the first axis level. The default value is computed according to the axis range ([XYZ]RANGE) and the number of major tick intervals ([XYZ]TICKS). This keyword takes precedence over [XYZ]TICKS.
For example, if TICKUNITS=["Seconds", "Hours", "Days"], and XTICKINTERVAL=30, then the interval between major ticks for the first axis level will be 30 seconds.
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE. System variable equivalent:
Set this keyword to a scalar that indicates the tick layout style to be used to draw each level of the axis.
Valid values include:
| Note |
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE. System variable equivalent:
This keyword controls the lengths of tick marks (expressed in normal coordinates) for the individual axes. This keyword, if nonzero, overrides the global tick length specified in
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE. System variable equivalent:
A string array of up to 30 elements that controls the annotation of each tick mark.
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE. System variable equivalent:
The number of major tick intervals to draw for the axis. If this keyword is omitted, IDL selects from three to six tick intervals. Setting this field to n, where n > 1, produces exactly n tick intervals, and n+1 tick marks. Setting this field equal to 1 suppresses tick marks.
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE. System variable equivalent:
Set this keyword to a string or a vector of strings indicating the units to be used for axis tick labeling. If a vector of strings is provided, the axis will be drawn in multiple levels, where each string represents one level in the specified units.
| Note |
The order in which the strings appear in the vector determines the order in which the corresponding unit levels will be drawn. The first string corresponds to the first level (the level nearest to the primary axis line).
Valid unit strings include:
If any of the time units are utilized, the tick values are interpreted as Julian date/time values.
Note that the singular form of each of the time value strings is also acceptable (e.g, TICKUNITS='Day' is equivalent to TICKUNITS='Days').
| Note |
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE. System variable equivalent:
The data values for each tick mark, an array of up to 60 elements.
| Note |
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE. System variable equivalent:
A string that contains a title for the specified axis.
Accepted by: PLOTS, POLYFILL, TV, TVCRS, XYOUTS.
Provides the Z coordinate if a Z parameter is not present in the call. This is of use only if the three-dimensional transformation is in effect (i.e., the T3D keyword is set).
Accepted by: AXIS, CONTOUR, MAP_SET, OPLOT, PLOT, SHADE_SURF, SURFACE.
Sets the Z coordinate, in normalized coordinates in the range of 0 to 1, of the axis and data output from PLOT, OPLOT, and CONTOUR.
This keyword has effect only if