Direct Graphics System Variables

The following system variables control various IDL Direct Graphics functions. These system variables are structures that contain many tags. For example, the command

!P.TITLE = 'Cross Section'

sets the default plot title.

Many of the functions of the graphics keywords described in Direct Graphics Keywords are also controlled by the system variables !P, !X, !Y, and !Z.

You can change the default style of plots, fonts, etc., by setting the corresponding field in the appropriate system variable. Also, some effects that persist longer than one call are controlled only by system variables. The field !P.MULTI is one example.

Two-Dimensional Coordinate Conversion

The system variables !D, !P, !X, !Y, and !Z contain the information necessary to convert from one coordinate system to another. The relevant fields of these system variables are explained below, and formulae are given for conversions to and from each coordinate system.

In the following discussion, D is a data coordinate, N is a normalized coordinate, and R is a raw device coordinate.

The fields !D.X_VSIZE and !D.Y_VSIZE always contain the size of the visible area of the currently selected display or drawing surface. Let V_x and V_y represent these two sizes.

The field !X.S is a two-element array that contains the parameters of the linear equation, converting data coordinates to normalized coordinates. !X.S[0] is the intercept, and !X.S[1] is the slope. !X.TYPE is 0 for a linear x-axis and 1 for a logarithmic x-axis. The y- and z-axes are handled in the same manner, using the system variables !Y and !Z.

Also, let D_x be the data coordinate, N_x the normalized coordinate, R_x the device coordinate, V_x the device X size (in device coordinates), and X_i = !X.S_i (the scaling parameter).

With the above variables defined, the linear two-dimensional coordinate conversions for the x coordinate can be written as follows:

Coordinate Conversion	Linear	Logarithmic
Data to normal	N_x = X₀ + X₁D_x	N_x = X₀ + X₁logD_x
Data to device	R_x = V_x(X₀ +X₁D_x)	R_x = V_x(X₀ +X₁logD_x)
Normal to device	R_x = N_xV_x	R_x = N_xV_x
Normal to data	D_x = (N_x - X₀) / X₁	D_x = 10^{(Nx - X0) / X1}
Device to data	D_x = (R_x / V_x - X₀) / X	D_x = 10^{(Rx / Vx - X0) / X}
Device to normal	N_x = R_x/V_x	N_x = R_x/V_x

The y- and z-axis coordinates are converted in exactly the same manner, with the exception that there is no z device coordinate and that logarithmic z-axes are not permitted.

!C

The cursor system variable. Currently, the only function of this system variable is to contain the subscript of the largest or smallest element found by the MAX and MIN functions. That information is better obtained through the optional output arguments to those routines. !C is included only for compatibility with old versions of IDL.

!D

This system variable is a structure that contains information about the current graphics output device (or window, on a windowing system). Fields, in alphabetical order, are:

FILL_DIST

The line interval, in device coordinates, required to obtain a solid fill.

FLAGS

A longword of flags that provide information about the current device. Each bit is a flag encoded as shown in the following table.

Bit	Value	Function
0	1	Device has scalable pixel size (e.g., PostScript).
1	2	Device can output text at an arbitrary angle using hardware.
2	4	Device can control line thickness with hardware.
3	8	Device can display images.
4	16	Device supports color.
5	32	Device supports polygon filling with hardware.
6	64	Device hardware characters are monospace.
7	128	Device can read pixels (i.e., it supports TVRD).
8	256	Device supports windows.
9	512	Device prints black on a white background (e.g., printers are plotters).
10	1024	Device has no hardware characters.
11	2048	Device does line-fill style polygon filling in hardware.
12	4096	Device will apply Hershey-style embedded formatting commands to device fonts.
13	8192	Device is a pen plotter.
14	16384	Device can transfer 16-bit pixels.
15	32768	Device supports Kanji characters.
16	65536	Device supports widgets.
17	131072	Device has Z-buffer.
18	262144	Device supports TrueType fonts.

To test whether a particular bit is set on your system, use an IDL command like the following:

IF (!D.FLAGS AND value) NE 0 THEN PRINT, 'Bit is set.'

where value is the value associated with the bit you wish to examine. For example, to check whether the device supports color, use:

IF (!D.FLAGS AND 16) NE 0 THEN PRINT, 'Bit is set.'

N_COLORS

The number of allowed color values. In the case of devices with windows, this field is set after the window system is initialized. For a monochrome system, !D.N_COLORS is 2. For TrueColor displays, !D.N_COLORS is 2^24 (roughly 16.7 million colors).

The low 8 bits, bits 0 to 7, of the color index are written to the red channel; bits 8 to 15 are written to the green; and bits 16 to 23 are written to the blue. For example, a given RGB, the index is R + 256(G + 256B). To create a plot with a given color (assuming linear lookup tables), use the following statement:

PLOT, X, Y, COLOR = R + 256L * (G + 256L * B)

NAME

A string containing the name of the device.

ORIGIN

A two-element integer array containing the current pan/scroll offset. An offset of (0, 0) is normal. Positive offsets shift the display memory to the right and upwards. This field has relevance only with devices with hardware pan and scroll abilities.

TABLE_SIZE

The number of color table indices.

Note: For TrueColor visuals, !D.TABLE_SIZE will always be 256. If the visual depth is less than 24 bits, IDL emulates 256 entries.

UNIT

The logical number of the file open for output by the current graphics device. This field only has meaning for devices that write to a file if the file is accessible to the user from IDL, and is 0 if no file is open.

For example, the PostScript driver fills this field with the unit number of the file open for PostScript output. In the case of Tektronix output to a file, !D.UNIT may be set to either + or – the logical unit number. In the case of the Metafile device (Windows Metafile Format) output, !D.UNIT is always 0, because the file is not accessible to the user from IDL.

WINDOW

The index of the currently open window. This field is set to -1 if no window is currently open. This field is used only with devices that support windows.

X_CH_SIZE

Y_CH_SIZE

The width and height of the rectangle that encloses the “average” character in the current font, in device units (usually pixels).

These values describe the size of the rectangle that contains the “average” character in the current font. (It is not important what the “average” character is; it is used only to calculate a scaling factor that will be applied to all of the characters in the font.) The first element specifies the width of the rectangle in device units (usually pixels), and the second element specifies the height.

For vector and TrueType fonts, the height of the “average” character is determined by the width of the rectangle. The aspect ratio of the “average” character remains fixed; the character is scaled so that its width is the value of X_CH_SIZE. The resulting scale factor is then applied to all of the characters in the font. The amount of spacing between lines is determined explicitly by the value of Y_CH_SIZE.

For device fonts, the character size is fixed. When the device font system is in use, the value of X_CH_SIZE is silently ignored, and only the Y_CH_SIZE value is used.

X_PX_CM

Y_PX_CM

The approximate number of pixels per centimeter in the X and Y directions.

X_SIZE

Y_SIZE

The total size of the display or window in the X and Y directions, in device units.

X_VSIZE

Y_VSIZE

The size of the visible area of the display or window. This area can be smaller than the total size fields.

ZOOM

This field contains the current X and Y zoom factors for the display or window. This field has relevance only with devices equipped with hardware zoom. A zoom factor of [1, 1] is normal.

!ORDER

Controls the direction of image transfers when using the TV, TVSCL, and TVRD procedures. If !ORDER is 0, images are transferred from bottom to top, i.e. the row with a 0 subscript is written on the bottom. Setting !ORDER to 1, transfers images from top to bottom.

!P

The main plotting system variable structure. All fields, except !P.MULTI, have a directly corresponding keyword parameter in the plot procedures: PLOT, OPLOT, CONTOUR, and SURFACE. Fields, in alphabetical order, are:

BACKGROUND

The background color index or 24-bit color value. When erasing the screen or page, all pixels are set to this color. The default value is 0. Not all devices support this feature.

Note: If !P.NOERASE (or the NOERASE keyword) is set, the value of !P.BACKGROUND (or the BACKGROUND keyword) is ignored.

CHANNEL

The default source or destination channel. This field has meaning only on graphics devices that contain multiple display channels, and is device dependent. It may contain either a channel mask or index.

CHARSIZE

The overall character size of all annotations when Hershey fonts are selected. This field has no effect on the character size when hardware (device) fonts are selected, except for devices that support scalable pixel sizes (i.e., Postscript). Note, however, that !P.CHARSIZE always affects the layout and scaling of a plot, regardless of the font system being used. The default size is 1.0.

CHARTHICK

An integer specifying the thickness of the lines used to draw the characters when using the vector drawn fonts. This field has no effect on the appearance of characters drawn with the hardware fonts. Normal thickness is 1.

CLIP

The device coordinates of the clipping window, a 6-element vector of the form [x₀, y₀, x₁, y₁, z₀, z₁], specifying two opposite corners of the volume to be displayed. In the case of two-dimensional displays, the Z coordinates can be omitted. Normally, the clipping window coordinates are implicitly set by PLOT, CONTOUR, SHADE_SURF, and SURFACE to correspond to the plot window. You can also manually set !P.CLIP to specify a different rectangular clipping window or if the clipping coordinates have not yet been set in the current IDL session.

COLOR

The default color index or 24-bit color value. Color index values are specified with a single integer between 0 and 255. 24-bit color values are specified using a hexidecimal value specifying the blue, green, and red values in a string with the following format:

'bbggrr'x

where bb is a hexidecimal number specifying the blue value, gg is a hexidecimal number specifying the green value, and rr is a hexidecimal number specifying the red value.

To set the color used for all subsequent plots to color index 160, use the following statement:

!P.COLOR = 160

To specify that all subsequent plots should be drawn in pure blue on a system that uses 24-bit color, use the following statement:

!P.COLOR = 'FF0000'x

Most plotting routines also accept a COLOR keyword that overrides the value of !P.COLOR for the current routine. To set the color of a plot to color-index 120, regardless of the value of !P.COLOR, use the following statement:

PLOT, INDGEN(30), COLOR = 120

By default, !P.COLOR is set to the number of available colors minus one. See N_COLORS for more information on defining a color.

The interpretation of the color index varies among the devices supported by IDL. With indexed color video displays, this index selects a color (normally a red, green, blue (RGB) triple stored in a device table). You can control the color selected by each color index with the TVLCT procedure which loads the device color tables.

Other devices have a fixed color associated with each color index. With plotters, for example, the correspondence between colors and color index is established by the order of the pens in the carousel.

FONT

An integer that specifies the graphics text font system to use. Set FONT equal to -1 to select 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.

LINESTYLE

The default style of the lines used to connect points. A line style index of 0 yields a solid line. See LINESTYLE for a description of the linestyles.

MULTI

!P.MULTI allows making multiple plots on a page or screen. It is a 5-element integer array defined as follows:

!P.MULTI[0] contains the number of plots remaining on the page. If !P.MULTI[0] is less than or equal to 0, the page is cleared, the next plot is placed in the upper left hand corner, and !P.MULTI[0] is reset to the number of plots per page.

Setting !P.MULTI[0] to a value greater than zero can be used to manually set the plotting area to a specific row and column. For example, to plot in the lower left corner of a window of two rows and two columns, set !P.MULTI as follows:

!P.MULTI=[2,2,2]

PLOT, X, Y

!P.MULTI[1] is the number of plot columns per page. If this value is less than or equal to 0, one is assumed. If more than two plots are ganged in either the X or Y direction, the character size is halved.

!P.MULTI[2] is the number of rows of plots per page. If this value is less than or equal to 0, one is assumed.

!P.MULTI[3] contains the number of plots stacked in the Z dimension.

!P.MULTI[4] is 0 to make plots from left to right (column major), and top to bottom, and is 1 to make plots from top to bottom, left to right (row major).

Note: If !P.MULTI[0] is zero, an erase will occur before the current plot is displayed (unless the /NOERASE keyword is set). This is true no matter whether !P.POSITION and/or !P.REGION are set.

For example, to gang two plots across the page:

!P.MULTI = [0, 2, 0, 0, 0]

PLOT, X0, Y0 ;Make left plot.

PLOT, X1, Y1 ;Right plot.

To gang two plots vertically:

!P.MULTI = [0, 0, 2, 0, 0]

PLOT, X0, Y0 ;Make top plot.

PLOT, X1, Y1 ;Bottom plot.

To make four plots per page, two across and two up and down:

!P.MULTI = [0, 2, 2, 0, 0]

and then call plot four times.

To reset !P.MULTI back to the normal one plot per page:

!P.MULTI = 0

See Multiple Plots on a Page for additional examples. See Specifying the Location of the Plot for information on how !P.MULTI relates to plot location.

NOCLIP

A field which, if set, inhibits the clipping of the graphic vectors and vector-drawn text. By default, most routines clip to the plotting window, with the exception of PLOTS and XYOUTS. !P.CLIP contains the clipping rectangle.

NOERASE

Set this field to a non-zero value to inhibit erasing the screen before plotting.

Note: If !P.NOERASE (or the NOERASE keyword) is set, the value of !P.BACKGROUND (or the BACKGROUND keyword) is ignored.

NSUM

The number of adjacent points to average to obtain a plotted point.

POSITION

Specifies the normalized coordinates of the rectangular plot window. This is a four element floating point vector (x₀, y₀, x₁, y₁) containing the normalized coordinates of the plot-data window, where (x₀, y₀) is the origin, and (x₁, y₁) is the upper right corner.

!P.POSITION determines the plotting window. This variable is ignored if x₀ equals x₁(that is, if !P.POSITION[0] EQ !P.POSITION[2], which is the default), or if the POSITION keyword is present. If set, it overrides the effect of the MARGIN and !P.MULTI variables and keywords.

Note: If !P.POSITION (or the POSITION keyword) or !P.REGION is set, all but the first element of !P.MULTI are ignored.

See Specifying the Location of the Plot for more information.

PSYM

The default plotting symbol index. Each point drawn by PLOT, PLOTS, and OPLOT is marked with a symbol if this field is non-zero. If this field is set equal to a positive value less than 10, no lines are drawn connecting the data points. See PSYM for a list of symbols and the behavior of positive and negative values.

REGION

A four element vector that specifies the normalized coordinates of the rectangle enclosing the plot region, which includes the plot data window and its surrounding annotation area. It is in the same form as !P.POSITION, (x₀, y₀, x₁, y₁), where (x₀, y₀) is the origin, and (x₁, y₁) is the upper right corner. It is ignored if !P.REGION[0] is equal to !P.REGION[2].

Note: !P.POSITION (or the POSITION keyword) takes precedence over !P.REGION.

See Specifying the Location of the Plot for more information.

SUBTITLE

The plot subtitle, placed under the X axis label.

T

Contains the homogeneous 4 x 4 transformation matrix. This field is a two-dimensional array of double-precision floating-point values.

T3D

Enables the three-dimensional to two-dimensional transformation contained in the homogeneous 4 by 4 matrix !P.T. Note that if T3D is set, !P.T must contain a valid transformation matrix.

THICK

The thickness of the lines connecting points. 1.0 is normal.

TITLE

The main plot title.

TICKLEN

The length of the tick marks, expressed as a fraction of the plot size (from 0.0 to 1.0). The default is 0.02. A value of 0.5 makes a grid. Negative values make the tick marks point outward.

!X, !Y, !Z

The system variables !X, !Y, and !Z, are structures of type AXIS, that affect the appearance and scaling of the three axes. The fields for !X, !Y, and !Z have identical fields with identical meanings and usage. In addition, almost all fields have corresponding keyword parameters, with identical function, but with temporary effect. For example, to suppress the minor tick marks on the X axis using the !X system variable, you could use the command:

!X.MINOR = -1

To suppress the tick marks for just one call to plot, you could use the command:

PLOT, X, Y, XMINOR = -1

The name of the keyword parameter is the name of the system variable field, prefixed with the letter X, Y, or Z.

The fields for these system variables, in alphabetical order are:

CHARSIZE

The size of the characters used to annotate the axis and its title when Hershey fonts are selected. This field has no meaning when hardware (i.e. PostScript) fonts are selected. This field is a scale factor applied to the global scale factor. For example, setting !P.CHARSIZE to 2.0, and !X.CHARSIZE to 0.5 results in a character size of 1.0 for the X axis.

CRANGE

The output axis range. Setting this variable has no effect; set ![XYZ].RANGE to change the range. ![XYZ].CRANGE[0]) always contains the minimum axis value, and ![XYZ].CRANGE[1] contains the maximum axis value of the last plot before extending the axes.

Note: If the axis is logarithmic, the CRANGE field reports the log (base 10) of the minimum and maximum axis values.

Example 1:

;Create a 10-element array.

a = INDGEN(10)

;Plot the straight line.

PLOT, a

;Print the minimum and maximum axis values.

PRINT, !X.CRANGE

IDL prints:

0.00000 10.0000

Example 2:

;Plot a with logarithmic scaling on the X axis.

PLOT, a, /XLOG

;Print the minimum and maximum axis values.

PRINT, !X.CRANGE

The axis is scaled from 10^-12 to 10². IDL prints:

-12.0000 2.00000

GRIDSTYLE

The index of the linestyle to be used for tick marks and grids. See LINESTYLE for a description of the linestyles

MARGIN

A 2-element array specifying the margin on the left (bottom) and right (top) sides of the plot window, in units of character size. The plot window is the rectangular area that contains the plot data, i.e. the area enclosed by the axes.

The default values for !X.MARGIN are [10, 3] yielding a 10-character wide left margin and a 3-character wide right margin. The values for !Y.MARGIN are [4, 2], for a 4-character high bottom margin and a 2-character high top margin. While specifying !Z.MARGIN will not cause an error, Z margins are currently ignored.

When calculating the size and position of the plot window, IDL first determines the plot region, the area enclosing the window plus the axis annotation and titles. It then subtracts the appropriate margin from each side, obtaining the window.

Setting !P.POSITION, or specification of the POSITION parameter overrides the effect of this field. See Specifying the Location of the Plot for more information.

MINOR

The number of minor tick mark intervals. If !X.MINOR is 0, the default, the number of minor tick intervals is automatically determined from the tick mark increment. You can force a given number of minor tick intervals by setting this field to the desired number. To suppress minor tick marks, set !X.MINOR to -1.

OMARGIN

A 2-element array specifying the “outer” margin on the left (bottom) and right (top) sides of a multi-plot window, in units of character size. A multi-plot window is created by setting the !P.MULTI system variable field. OMARGIN controls the amount of space around the entire plot area, including individual plot margins set with !X.MARGIN and !Y.MARGIN. The default values for !X.OMARGIN and !Y.OMARGIN are [0, 0].

When calculating the size and position of the individual plots, IDL first determines the plot region, the area enclosing the window plus the axis annotation and titles. It then subtracts the appropriate margin from each side, obtaining the window.

Setting !P.POSITION, or specification of the POSITION parameter overrides the effect of this field.

RANGE

The input axis range, a 2-element vector. The first element is the axis minimum, and the second is the maximum. Set this field, or use the corresponding keyword parameter, to specify the data range to plot. If axis end point rounding is selected (see STYLE above), the final axis range may not be equal to this input range. The field !X.CRANGE contains the axis range used for the plot before extending the axes. Set both elements equal to 0 for automatic axis ranges:

!X.RANGE = 0

For example, to force the X axis to run from 5.5 to 8.3:

!X.RANGE = [5.5, 8.3]

PLOT, X, Y

Alternatively, by using keywords:

PLOT, X, Y, XRANGE=[5.5, 8.3]

Note that even though the range was set to (5.5, 8.3), the resulting plot has a range of (5.5, 8.5), because axis rounding is the default.

REGION

Contains the normalized coordinates of the region. This field is similar to WINDOW, in that it is set by the graphics procedures and is a 2-element floating point array. To change the default plotting region, set !P.REGION.

S

The scaling factors for converting between data coordinates and normalized coordinates (a 2-element array). The formula for conversion from data (X_d) to normalized (X_n) coordinates is X_n = S₁X_d + S₀

If logarithmic scaling is in effect, substitute log₁₀(X_d) for X_d.

The CONVERT_COORD function can be used to convert between coordinate systems. The user should save and restore these fields when switching between windows or devices with different sizes and/or scaling.

STYLE

The style of the axis encoded as bits in a longword. The axis style can be set to exact, extended, none, or no box using this field. The following table lists the axis style bit values:

Bit	Value	Function
0	1	Exact. By default, the end points of the axis are rounded in order to obtain even tick increments. Setting this bit inhibits rounding, making the axis fit the data range exactly.
1	2	Extend. If this bit is set, the axes are extended by 5% in each direction, leaving a border around the data.
2	4	None. If this bit is set, the axis and its annotation are not drawn.
3	8	No box. Normally, PLOT and CONTOUR draw a box-style axis with the data window surrounded by axes.
4	16	Inhibits setting the Y axis minimum value to zero when the data are all greater than 0. The keyword YNOZERO sets this bit temporarily.

Note that this system variable field 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 !X.STYLE system variable to 1+8, or 9.

For example, to set the Y axis style to exact using the !Y system variable:

!Y.STYLE = 1

or by using a keyword parameter:

PLOT, X, Y, YSTYLE = 1

THICK

The thickness of the axis line. 1.0 is normal.

TICKFORMAT

Set this field to a format string or a string containing the name of a function that returns a string to be used to format the axis tick mark labels.

See [XYZ]TICKFORMAT for more information.

TICKINTERVAL

A scalar indicating the interval between major tick marks for the first axis level. This setting takes precedence over ![XYZ].TICKS.

For example, if !X.TICKUNITS=[“Seconds”, “Hours”, “Days”], and !X.TICKINTERVAL=30, then the interval between major ticks for the first axis level will be 30 seconds.

See [XYZ]TICKINTERVAL for more information.

TICKLAYOUT

Set this keyword to a scalar that indicates the tick layout style to be used to draw each level of the axis.

See [XYZ]TICKLAYOUT for more information.

TICKLEN

The lengths of tick marks (expressed in normal coordinates) for the individual axes.

TICKNAME

The annotation for each tick. A string array of up to 60 elements. Setting elements of this array allows direct specification of the tick label. If this element contains an empty string, the default value, IDL annotates the thick with its numeric value. Setting the element to a 1-blank string suppresses the tick annotation.

For example, to produce a plot with an abscissa labeled with the days of the week:

;Set up X axis tick labels.

!X.TICKNAME = ['SUN', 'MON', 'TUE', 'WED', $

'THU', 'FRI', 'SAT']

;Use six tick intervals, requiring seven tick labels.

!X.TICKS = 6

;Plot the data, this assumes that Y contains 7 elements.

PLOT, Y

The same plot can be produced, using keyword parameters, with:

;Set fields, as above, only temporarily.

PLOT, Y, XTICKN = ['SUN', 'MON', 'TUE', 'WED',$

'THU', 'FRI', 'SAT'], XTICKS = 6

TICKS

The number of major tick intervals to draw for the axis. If !X.TICKS is set to 0, the default, IDL will select 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.

TICKUNITS

Set this keyword to a string (or a vector of strings) indicating the units to be used for axis tick labeling.

Note: The singular form of each of the time value strings is also acceptable (e.g, !X.TICKUNITS='Day' is equivalent to !X.TICKUNITS='Days').

Note: To set the ![XYZ].TICKUNITS field to a single string, the following approach is recommended:

!X.TICKUNITS = '' ; Clear all previous tick unit strings. !X.TICKUNITS = ['Days'] ;Single unit string in array.

The following:

!X.TICKUNITS = 'Days'

will copy the 'Days' string to all levels, resulting in a multi-level axis.

See [XYZ]TICKUNITS for more information.

TICKV

An array of up to 60 elements containing the data values for each tick mark. You can directly specify the location of each tick by setting !X.TICKS to the number of tick marks (the number of intervals plus 1) and storing the data values of the tick marks in !X.TICKV. If, as is true by default, !X.TICKV[0] is equal to !X.TICKV[1], IDL automatically determines the value of the tick marks.

TITLE

A string containing the axis title.

TYPE

The type of axis, 0 for linear, 1 for logarithmic.

WINDOW

Contains the normalized coordinates of the axis end points, the plot data window. This field is set by PLOT, CONTOUR, SHADE_SURF, and SURFACE. Changing its value has no effect. A 2-element floating point array. To change the default plotting window, set !P.POSITION. The keyword parameter POSITION sets the plot data window on a per call basis.