IDL

AXIS

AXIS

The AXIS function adds an axis to an existing IDL Graphic.

Example


The following lines create the graphic shown on the right.

tstart = JULDAY(1,1,2000,0,0,0)
tend = JULDAY(1,5,2000,0,0,0)
time = TIMEGEN(START=tstart, FINAL=tend, UNITS='Hours')
data = 20*BESELJ(FINDGEN(97)/4, 1)
p = PLOT(time, data, MARGIN=[0.15,0.25,0.15,0.1], $
  AXIS_STYLE=1, FILL_COLOR="light blue", $
  FILL_BACKGROUND=1, FILL_LEVEL=0, $
  YTITLE='$Temperature (\deg C)$', $
  XSTYLE=1, XTICKFORMAT='(C(CDI,1x,CMoA))')
 
; Insert another X axis with time in hours.
; Same units, just a different TICKFORMAT.
xaxis = AXIS('X', LOCATION=-15, $
  TITLE='Hour', TICKINTERVAL=0.5, $
  MINOR=1, TICKFORMAT='(C(CHI),"h")')
 
; Insert a Y axis with temperature in Fahrenheit.
; Use COORD_TRANSFORM to convert to different units.
; Use AXIS_RANGE to restrict the axis length.
yaxis = AXIS('Y', LOCATION='right', $
  TITLE='$(\deg F)$', $
  COORD_TRANSFORM=[32, 9.0/5.0], $
  AXIS_RANGE=[20,50])

Syntax


graphic = AXIS(Direction, ] [, Keywords=value] [, Properties=variable])

Keywords

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

[, LOCATION=value] [, TARGET=variable]

Properties

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

ANTIALIAS, AXIS_RANGE, CLIP, COLOR, COORD_TRANSFORM, DATA, GRIDSTYLE, HIDE, LOG, MAJOR, MINOR, NAME, SHOWTEXT, SUBGRIDSTYLE, SUBTICKLEN, TEXT_COLOR, TEXT_ORIENTATION, TEXTPOS, THICK, TICKDIR, TICKFONT_NAME, TICKFONT_SIZE, TICKFONT_STYLE, TICKFORMAT, TICKINTERVAL, TICKLAYOUT, TICKLEN, TICKNAME, TICKUNITS, TICKVALUES, TITLE, TRANSPARENCY, UVALUE, WINDOW

Methods


Close

ConvertCoord

CopyWindow

Delete

Order 

Print

Refresh

Rotate

Save

Scale

Select

Translate

Return Value


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

Arguments


Direction

Set this argument to a string or an integer giving the axis direction. Possible values are:

  • 0 or 'X' - Create an x-axis.
  • 1 or 'Y' - Create a y-axis.
  • 2 or 'Z' - Create a z-axis.

The LOCATION property may be used to set the axis location.

Keywords


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

LOCATION

Set this keyword to a scalar number, a string, or a vector giving the location of the new axis in data coordinates.

For a two-dimensional graphic, the LOCATION should be set to one of the following:

  • A scalar number giving the location along the direction perpendicular to the axis. For example, for an x-axis, specify the y location. For a y-axis, specify the x location.
  • A scalar string giving the location. For an x-axis, the possible location strings are "bottom," "center," or "top." For a y-axis, the possible location strings are "left," "center," or "right."

For a three-dimensional graphic, the LOCATION should be set to one of the following:

  • A two-element vector giving the location along the two directions that are orthogonal to the axis. For example, for an x-axis, you would specify [y, z]. For a y-axis, you would specify [x, z]. For a z-axis, you would specify [x, y].
  • A two-element string array giving the location along the two orthogonal directions. Valid strings are "left," "right," "bottom," "top," and "center." For example, assume your 3D plot has axis ranges given by xrange, yrange, and zrange. The values "left" and "bottom" are interchangeable and correspond to xrange[0], yrange[0], and zrange[0]. The values "right" and "top" are interchangeable and correspond to xrange[1], yrange[1], and zrange[1]. For example, to add a new Z axis to a 3D plot, you could specify LOCATION=["right", "bottom"] to position the axis at location (xrange[1], yrange[0]).

Note: If you specify LOCATION as a string, then AXIS will automatically choose the tick direction and text position that best fits that axis. For example, for an x-axis on a plot, if you set LOCATION='top', then your axis will have ticks that point downward (TICKDIR=1) and text above the axis (TEXTPOS=1).

TARGET

Set this keyword to the graphic to which the axis should be associated. If TARGET is not specified then the current graphic will be used.

Properties


ANTIALIAS

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

AXIS_RANGE

A two-element vector giving the visible range of the axis. By default the axis covers the entire dataspace range. Set this property to [0, 0] to revert back to the default behavior. See Axes for an example.

  • If COORD_TRANSFORM is also set, then this property should be set in the "transformed" axis units, not the dataspace units.
  • Setting this property has no effect on the dataspace range of the graphic. The [XYZ]RANGE properties may be used to control the dataspace range.
  • If the AXIS_RANGE lies partially outside of the dataspace range, then the axis range will be clamped to the dataspace range. If the AXIS_RANGE lies completely outside of the dataspace range, then the property will be ignored and the axis will cover the entire dataspace range.

CLIP

Set this property to 1 to clip portions of the axis 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 giving the axis color. If the COLOR and the TEXT_COLOR were previously the same, then setting COLOR will also set TEXT_COLOR to the same value. The default is "black".

COORD_TRANSFORM

Set this property to a two-element vector, [a, b], giving the coordinate transform between the dataspace coordinates (in the direction of this axis) and the axis coordinates. The a and b describe a simple linear transform:

AxisCoord = a + b * DataCoord

The default is [0.0, 1.0], which indicates that no transform will take place. The COORD_TRANSFORM is useful for creating an axis where the axis tick units are different than the original graphic units. For example, if your data is in degrees Celcius, you could add a new Y axis with units in degrees Fahrenheit by specifying COORD_TRANSFORM = [32, 9.0/5]. See Axes for an example.

DATA

Set this property to 1 to lock the axis location to the dataspace position. In this case, if the dataspace range changes, the axis will move along with the data. The default is 0, which locks the axis location to the position within the window. See Axes for an example.

Note: If DATA is set, then the axis and tick labels will automatically be clipped when they extend past the edge of the graphic's data range. You can set CLIP=0 to disable this behavior.

GRIDSTYLE

Set this property to an integer or string giving the linestyle to be used for the major tickmarks.

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.

HIDE

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

LOG

Set this property to specify a logarithmic axis. The minimum value of the axis range must be greater than zero.

MAJOR

Set this property to an integer representing the number of major tick marks. The default value is -1, specifying that IDL will compute the number of tickmarks. Setting MAJOR equal to 0 suppresses major tickmarks entirely.

MINOR

Set this property to an integer representing the number of minor tick marks. The default value is -1, specifying that IDL will compute the number of tickmarks. Setting MINOR equal to 0 suppresses minor tickmarks entirely.

NAME

Set this property to 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.

SHOWTEXT

Set this property to 1 to show text labels or to 0 to hide text labels.

SUBGRIDSTYLE

Set this property to an integer or string giving the linestyle to be used for the minor tick marks. The default is 0, which gives solid lines for the minor ticks. You can also set this property to -1, to force the minor ticks to have the same linestyle as the major ticks.

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.

SUBTICKLEN

Set this property to a floating point scale ratio specifying the length of minor tick marks relative to the length of major tick marks. The default value is 0.5, specifying that the minor tick mark is one-half the length of the major tick mark. The length of the major tick marks can be changed with the TICKLEN property.

TEXT_COLOR

Set this property to a string or RGB vector containing the axis text color. The default value is the same color as the COLOR property.

TEXT_ORIENTATION

Set this property to the angle (in degrees) of the tick mark labels. The default is 0.

TEXTPOS

Set this property to 1 to position the tick labels and axis title above the axis. The default is 0, below the axis.

Tip: The TICKDIR property may be used to control the direction of axis tick marks.

THICK

Set this property to a value between 0 and 10 that specifies the line thickness of the plotted lines. The default value is 1.

TICKDIR

Set this property to 1 to draw the tickmarks facing outwards. The default is 0, facing inwards.

Tip: The TEXTPOS property may be used to control the position of tick mark data values and axis titles.

TICKFONT_NAME

Set this property to a string specifying the IDL or system font for the tick labels and axis title.

TICKFONT_SIZE

Set this property to a floating-point number representing the point size of the axis text. The default value is 12 points.

TICKFONT_STYLE

Set this property to an integer or a string specifying the font style for the axis labels and title. Allowed values are: "normal" or "rm" (0), "bold" or "bf" (1), "italic" or "it" (2), and "bold italic" or "bi" (3).

TICKFORMAT

Set this property to a string which represents a format string or the name of a function to be used to format the tick mark labels. TICKFORMAT can also be set to an array of format strings for each tick mark. If an array is provided, each string corresponds to a level of the axis. The TICKUNITS property determines the number of levels for an axis.

If the string begins with an open parenthesis, it is treated as a standard format string.

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 TICKUNITS is specified.

If TICKUNITS is not specified:

  • The callback function is called with three parameters: Axis, Index, and Value, where:
  • Axis is the axis number (0 for X axis, 1 for Y axis, 2 for Z axis)
  • Index is the tick mark index (indices start at 0)
  • Value is the data value at the tick mark (a double-precision floating point value)

If TICKUNITS is specified:

The callback function is called with four parameters: Axis, Index, Value, and Level, where:

  • Axis, Index, and Value are the same as described previously.
  • Level is the index of the axis level for the current tick value to be labeled. (Level indices start at 0.)

TICKINTERVAL

Set this property to a floating-point number indicating the interval between major tick marks for the first axis level. The default value is computed according to the axis range and the number of major tick marks (MAJOR). If this property is set then the MAJOR property is ignored.

For example, if TICKUNITS = ['S', 'H', 'D'], and TICKINTERVAL = 30, then the interval between major ticks for the first axis level will be 30 seconds.

TICKLAYOUT

Set this property to an integer that indicates the tick layout style to be used to draw each level of the axis. Set this property to 0 (the default) to draw the axis line, tick marks, and tick labels. Set to 1 to only draw the labels. Set to 2 to draw a box around the tick labels.

Note: If no tick labels are being displayed (SHOWTEXT=0), then you can only set TICKLAYOUT to 0. Other values will be ignored.

Note: For all tick layout styles, at least one tick label will appear on each level of the axis (even if no major tick marks fall along the axis line). If there are no major tick marks, the single tick label will be centered along the axis.

TICKLEN

Set this property to a floating point value between 0.0 and 1.0 that specifies the length of each major tick mark, relative to the width or height of the graphic. For example, when creating a Y axis, setting TICKLEN=0.1 will create tick marks that are 10% of the width of the plot. If TICKLEN is not specified, then IDL will calculate a default tick mark length based upon the aspect ratio of the graphic.

Tip: If you have axes on both the left and right sides (or the top and bottom) of your graphic, set the tick length to 0.5 on both axes to create tick marks that stretch across the entire graphic. If you only have a single axis, then set the tick length to 1 to produce tick marks that stretch across the entire graphic. In either case, you may want to set SUBTICKLEN to a smaller value than the default of 0.5.

TICKNAME

Set this property to a string array of up to 30 elements that controls the annotation of each tick mark. Set this property to an empty string to set the tick labels back to their default values.

TICKUNITS

Set this property to a string (or a vector of strings) indicating the units to be used for axis tick labeling. If more than one unit is provided, the axis will be drawn in multiple levels, one level per unit. 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: "" (the default), "Years", "Months", "Days", "Hours", "Minutes", "Seconds", or "Time", "exponent" for exponential notation, or "scientific" for scientific notation..

If any of the time units are utilized, then 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 (for example, TICKUNITS = 'Day' is equivalent to TICKUNITS = 'Days').

Note: Julian values must be in the range -1095 to 1827933925, which corresponds to calendar dates 1 Jan 4716 B.C.E. and 31 Dec 5000000 C.E., respectively.

TICKVALUES

Set this property to an array of tick mark locations. If TICKVALUES is set to 0 (the default value), IDL computes the tick values based on the axis range and the number of major ticks.

TITLE

Set this property to a string representing the title of the specified axis. 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.

TRANSPARENCY

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

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.

Version History


8.0 Introduced
8.1

Added the following properties: UVALUE, SHOWTEXT, TICKNAME

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

Added the Delete method

8.2 Added the COORD_TRANSFORM and TEXT_ORIENTATION properties
8.2.1 [XYZ]TICKUNITS accepts exponent as a value
8.2.2 Improve LOCATION keyword to accept scalar values and strings. The old LOCATION behavior (with a 3-element vector) is no longer documented, but will continue to work.
8.2.3

Added SUBGRIDSTYLE property. By default minor ticks now have a solid linestyle, regardless of the linestyle of the major ticks.

Added the ability to use a stippling pattern for GRIDSTYLE.

See Also


!COLORAxes, Axis References in IDL GraphicsIMAGE, SURFACE, Using IDL graphics



Notes


This page has no user notes yet. Be the first one!


This information is not subject to the controls of the International Traffic in Arms Regulations (ITAR) or the Export Administration Regulations (EAR). However, it may be restricted from transfer to various embargoed countries under U.S. laws and regulations.
© 2014 Exelis Visual Information Solutions