axes

Purpose

Place axes at specified position by creating axes graphics object.

Synopsis

h = axes
axes(h)
h = axes('PropertyName',PropertyValue,...)

axes is a low-level function for creating axes objects. Axes objects are children of figure objects and parents of image, line, patch, surface, and text objects. Axes objects define a frame of reference that orients their children objects within the figure.

h = axes creates the default full-window axes and returns its handle.

axes(h) makes the axes with handle h the current axes.

h = axes('PropertyName',PropertyValue,...) is an object creation function that accepts property name/property value pairs as input arguments. These properties, which control various aspects of axes objects, are described under "Object Properties." You can also set and query property values after creation using the set and get functions.

Specify default axes properties at the axes' parent level, that is, at the figure object. To do so, call the set function, supplying as arguments the handle of the parent figure, a default name string, and the desired default value. Construct the default name string by prepending the string 'DefaultAxes' to the desired axes property name. For example

set(fig_handle,'DefaultAxesColor','red')

sets the default axes rectangle color to red for all axes created in the figure with handle fig_handle.

The axis (not axes) function provides simplified access to commonly used properties that control the scaling and appearance of axes.

Use gca (get current axes) to obtain the handle of the current axes.

Object Properties

This section lists property names along with the type of values each accepts.

AspectRatio: Aspect ratio for two-dimensional axes.

A two-element vector, [axis_ratio data_ratio], where

axis_ratio is the ratio of the length of the horizontal axis to the length of the vertical axis (width divided by height). MATLAB creates the largest axes with this ratio that fits into the rectangle defined by Position.

data_ratio is the ratio of the length of a data unit along the horizontal axis to the length of a data unit along the vertical axis. To create axes with this data_ratio, MATLAB changes the limits of one axis while maintaining the ratio specified in axis_ratio. This change does not affect the corresponding limits property (XLim or YLim).

Specify the ratios as any number in the range [0,Inf]. The default for both is NaN, which specifies no ratio. By default, MATLAB changes either ratio in order create an axes that best fills the figure window.

Box: Axes box mode.

on Enclose graphics area in box (2-D) or cube (3-D).

off (Default.) Do not display enclosing box.

ButtonDownFcn: Callback string, object selection.

Any legal MATLAB expression, including the name of an M-file or function. When you select the object, the string is passed to the eval function to execute the specified function. Initially the empty matrix.

Children: Children of axes.

A read-only vector containing the handles of all objects displayed within the axes. The children objects of axes can be images, lines, patches, surfaces, and text.

CLim: Color limits.

A two-element vector [cmin cmax] that determines how MATLAB maps data values to the colormap. cmin is the data value to map to the first colormap entry, and cmax is the data value to map to the last colormap entry. By default Clim is [0 1], mapping the full range of the colormap to the full range of the data.

Data values less than cmin are mapped to cmin and data values greater than cmax are mapped to cmax. NaNs are clipped by making them transparent. CLim values outside the range of the data cause MATLAB to use a limited portion of the colormap.

CLim affects the rendering of surface and patch objects, but not images, lines, or text.

CLimMode: Color limits mode.

auto (Default.) MATLAB calculates color limits that span the full range of the data of the axes' children.

manual Color limits do not automatically change (see the CLim property). Setting values for CLim sets this property to manual.

Clipping: Data clipping.

on (Default.) No effect for axes objects.

off No effect for axes objects.

Color: Color of the axes rectangle.

ColorSpec A three-element RGB vector or one of MATLAB's predefined names. See the ColorSpec reference page for more information on specifying color.

none (Default.) The same as the figure background color.

ColorOrder: Axes color order.

An m-by-3 matrix of RGB values. If you do not specify a line color with plot and plot3, these functions cycle through the ColorOrder to obtain the color for each line plotted. By default, ColorOrder contains the first six colors in MATLAB's predefined color palette:

yellow
magenta
cyan
red
green
blue

CurrentPoint: 3-D coordinates for a pair of points in the axes' data space.

A 2-by-3 matrix that specifies the end points of a line, in 3-D coordinates, that extends from the front to the back of the axes volume. The format of the matrix is

[xback  yback  zback;  xfront  yfront  zfront]

These coordinates are always relative to the axes volume, even if the pointer is outside the axes. All measurements are in units specified by the Units property.

See the MATLAB Release Notes for more details on the CurrentPoint property.

DrawMode: Draw mode.

normal (Default.) Draw objects from back to front based on the current view.

fast Draws objects in the order in which you originally specified them. This disables the three-dimensional sorting usually performed by MATLAB, resulting in faster rendering.

FontAngle: Italics for axes text.

normal (Default.) Regular font angle.

italic Italics.

oblique Italics on some systems.

See the MATLAB Release Notes for more details on the FontAngle property.

FontName: Font family.

A string specifying the name of the font to use for axes tick labels. To display and print properly, this must be a font that your system supports. Axes labels do not display in a new font until you manually redisplay them (by setting the XLabel, YLabel, and ZLabel properties). The default font is Helvetica.

FontSize: Font point size.

An integer specifying the font size, in points, to use for axes labels and titles. The default point size is 12.

FontWeight: Bolding for axes text.

normal (Default.) Regular font weight.

bold Bold weight.

GridLineStyle: Grid line style.

A string specifying the line type for grid lines. The string consists of a single character, in quotes, specifying solid lines (-), dashed lines (- -), dotted lines(:), or dash-dot lines (-.). The default grid line style is dotted.

Interruptible: Callback interruptibility.

yes The callback specified by ButtonDownFcn is interruptible by other callbacks.

no (Default.) The ButtonDownFcn callback is not interruptible.

See the MATLAB Release Notes for more details on the Interruptible property.

LineStyleOrder: Axes line style order.

A string specifying line styles in the order used to plot multiple lines in the axes. Specify up to four line styles in the format

'linestyle1|linestyle2...'

where each linestyle is a character string specifying solid lines (-), dashed lines (- -), dotted lines(:), or dash-dot lines(-.). The default line style order is solid lines only. Some plotting functions, such as plot, overrule this property with their own default line style order.

LineWidth: Width of x-, y-, and z-axis lines.

The width, in points, of the lines that represent each axis. The default line width is 0.5 points.

NextPlot: Axes handling for subsequent plots.

new Create a new axes before drawing.

add Add new objects to the current axes. Setting hold to on sets NextPlot to add.

replace (Default.) Destroy the current axes (and its contents) and create a new axes at the same position before drawing. Setting hold to off sets NextPlot to replace.

This property is used by the built-in high-level graphing functions plot, plot3, fill, fill3, and the M-file graphing functions mesh, surf, bar, and so on. The M-file newplot is a preamble for handling the NextPlot property. M-file graphing functions like mesh, surf, and bar call newplot to control this property before drawing their respective graphs. When creating M-files that implement graphing commands, use newplot at the beginning of the file. See the M-file pcolor for an example. Also see the NextPlot property of figure objects.

Parent: Handle of the axes' parent object.

A read-only property that contains the handle of the axes' parent object. The parent of an axes object is the figure in which it is displayed. The utility function gcf also returns the handle of the current axes' parent figure.

Position: Size and position of axes.

A four-element vector, [left bottom width height], where left and bottom are the distance from the lower-left corner of the figure window to the lower-left corner of the axes. width and height are the dimensions of the axes rectangle. All measurements are in units specified by the Units property.

TickDir: Tick mark direction

in Tick marks are directed inward from the axis lines (default for 2-D plotting).

out Tick marks are directed outward from the axis lines (default for three-dimensional plotting functions unless hold is on).

TickLength: Tick mark length.

A two-element vector [2Dlength 3Dlength] that specifies the length of the axes' tick marks, where

2Dlength is the length of tick marks used for two-dimensional views.

3Dlength is the length of tick marks used for three-dimensional views.

Each element is in units normalized relative to the dimensions of the rectangle defined by the axes. Specifying a tick length of 0.1 draws a tick mark that is 1/10 of the width or height of the rectangle. The default vector is [0.01 0.025].

Title: Axes title.

The handle of the text object that defines the axes title. First create the text object in order to obtain its handle. The following statement performs both steps:

set(gca,'title',text(0,0,'axes title'))

While the text function requires location data, it is not used to place the text. Instead, MATLAB centers the string 'axes title' above the axes.

You can also define a text object at an arbitrary location and pass its handle directly. In this case MATLAB moves the text string to the correct location for an axes title. The title function provides a simpler means to create a title by encapsulating this procedure.

Type: Type of graphics object.

A read-only string; always 'axes' for an axes object.

Units: Unit of measurement.

pixels Screen pixels.

normalized (Default.) Normalized coordinates. The lower-left corner of the figure window maps to (0,0) and the upper-right corner to (1.0,1.0).

inches Inches.

cent Centimeters.

points Points. Each point is equivalent to 1/72 of an inch.

If you change the value of Units, return it to its default value after completing your computation so as not to affect other functions that assume Units is set to the default value.

UserData: User-specified data.

Any matrix you want to associate with the axes object. The object does not use this data, but you can retrieve it using the get command.

View: Viewpoint of axes.

A two-element vector, [az,el], that establishes a viewpoint used to transform three-dimensional plots into the two-dimensional space of the screen. The viewpoint is the location of the eye of an observer looking at the three-dimensional plot, where

az is the azimuth. The azimuth revolves around the z-axis, with positive values causing the viewpoint to rotate in a counter-clockwise direction.

el is the elevation. The elevation specifies an angle above or below the object. Positive values of elevation cause the viewpoint to move above the object (that is, to look down on it); negative values cause the viewpoint to move below the object.

Specify each element in degrees. Changing the View property alters the XForm property's transformation matrix. The default View vector is [0 90].

Visible: Axes visibility.

on (Default.) Axes lines, tick marks, and labels are visible on the screen.

off Axes lines, tick marks, and labels are not drawn.

The children of the axes are not affected by the axes' Visible property.

XForm: View transformation matrix.

A 4-by-4 matrix that defines the transformation from three-dimensional plots to the two-dimensional screen. Specify the transformation matrix directly with this property, or indirectly by specifying the azimuth and elevation of the viewpoint using the View property.

Changing the View property changes XForm as well. XForm, however, can define views that you cannot define using only azimuth and elevation (such as perspective views). It is also possible to specify scaling and translations in the same matrix. Such transforms are discussed in most books on computer graphics. The default XForm matrix is the 4-by-4 identity matrix.

Properties That Control the X-Axis

XColor: Color of x-axis.

A three-element vector specifying an RGB triple, or a predefined MATLAB color string. This property determines the display color for the x-axis, tick marks, tick mark labels, and the x-axis grid lines.The default axis color is white. See the ColorSpec reference page for details on specifying colors.

XDir: Direction of increasing x values.

normal (Default.) X values increase from left to right (right-handed coordinate system).

reverse X values increase from right to left.

XGrid: X-axis gridline mode.

on MATLAB draws grid lines perpendicular to the x-axis at each tick mark (i.e., along lines of constant x values).

off (Default.) Grid lines are not drawn.

XLabel: X-axis label.

The handle of the text object used to label the x-axis. First create the text object in order to obtain its handle. The following statement performs both steps:

set(gca,'xlabel',text(0,0,'axis label'))

While the text function requires location data, it is not used to place the text. Instead, MATLAB places the string 'axis label' appropriately for an x-axis label.

You can also define a text object at an arbitrary location and pass its handle directly. In this case MATLAB moves the text string to the correct location for an axis label. The xlabel function provides a simpler means to label the x-axis by encapsulating this procedure.

XLim: X-axis limits.

A two-element vector [xmin xmax] that specifies the minimum and maximum x-axis values, where

xmin is the minimum x-axis value.

xmax is the maximum x-axis value.

Changing XLim affects the scale of the x-dimension as well as the placement of labels and tick marks on the x-axis. The default for XLim is [0 1].

XLimMode: X-axis limits mode.

auto (Default.) MATLAB calculates x-axis limits (XLim) that span the XData of the axes' children and produce round numbers for the x-axis limits.

manual MATLAB takes x-axis limits from XLim; the limits do not depend on the XData in the children objects. Setting values for XLim sets this property to manual.

XScale: X-axis scaling.

linear (Default.) Linear scaling for the x-axis.

log Logarithmic scaling for the x-axis.

XTick: X-axis tick mark spacing.

A vector of values that correspond to the x-data values at which you want to place tick marks. If you do not want tick marks displayed, set XTick to the empty vector, [].

XTickLabelMode: X-axis tick mark labeling mode.

auto (Default.) MATLAB calculates x-axis tick labels (XTickLabels) that span the XData of the axes' children.

manual MATLAB takes x-axis tick labels from XTickLabels; it does not depend on the XData in the children objects. Setting values for XTickLabels sets this property to manual.

XTickLabels: X-axis tick mark labels.

A matrix of strings to use as labels for tick marks along the x-axis. These labels replace the numeric labels generated by MATLAB. If you do not specify enough text labels for all the tick marks, MATLAB uses all of the labels specified, and then labels the remaining tick marks by reusing the specified labels. The command

set(gca,'XTickLabels',['Old Data';'New Data'])

labels the first two tick marks on the x-axis 'Old Data' and 'New Data' respectively. Each character string must have an equal number of characters because of the way MATLAB stores strings.

This property does not control the number of tick marks or their locations.

XTickMode: X-axis tick mark mode.

auto (Default.) MATLAB calculates x-axis tick mark spacing (XTick) that spans the XData of the axes' children.

manual MATLAB takes x-axis tick spacing from XTick; it does not depend on the XData in the children objects. Setting values for XTick sets this property to manual.

Properties That Control the Y-Axis

YColor: Color of y-axis.

A three-element vector specifying an RGB triple, or a predefined MATLAB color string. This property determines the display color for the y-axis, tick marks, tick mark labels, and the y-axis grid lines. The default axis color is white. See the ColorSpec reference page for details on specifying colors.

YDir: Direction of increasing y values.

normal (Default.) Y values increase from bottom to top (right-handed coordinate system).

reverse Y values increase from top to bottom.

YGrid: Y-axis gridline mode.

on MATLAB draws grid lines perpendicular to the y-axis at each tick mark (i.e., along lines of constant y values).

off (Default.) Grid lines are not drawn.

YLabel: Y-axis label.

The handle of the text object used to label the y-axis. First create the text object in order to obtain its handle. The following statement performs both steps:

set(gca,'ylabel',text(0,0,'axis label'))

While the text function requires location data, it is not used to place the text. Instead, MATLAB places the string 'axis label' appropriately for a y-axis label.

You can also define a text object at an arbitrary location and pass its handle directly. In this case MATLAB moves the text string to the correct location for an axis label. The ylabel function provides a simpler means to label the y-axis by encapsulating this procedure.

YLim: Y-axis limits.

A two-element vector [ymin ymax] that specifies the minimum and maximum y-axis values, where

ymin is the minimum y-axis value.

ymax is the maximum y-axis value.

Changing YLim affects the scale of the y-dimension as well as the placement of labels and tick marks on the y-axis. The default for YLim is [0 1].

YLimMode: Y-axis limits mode.

auto (Default.) MATLAB calculates y-axis limits (YLim) that span the YData of the axes' children and produce round numbers for the y-axis limits.

manual MATLAB takes y-axis limits from YLim; the limits do not depend on the YData in the children objects. Setting values for YLim sets this property to manual.

YScale: Y-axis scaling.

linear (Default.) Linear scaling for the y-axis.

log Logarithmic scaling for the y-axis.

YTick: Y-axis tick mark spacing.

A vector of values that correspond to the y-data values at which you want to place tick marks. If you do not want tick marks displayed, set YTick to the empty vector, [].

YTickLabelMode: Y-axis tick mark labeling mode.

auto (Default.) MATLAB calculates y-axis tick labels (YTickLabels) that span the YData of the axes' children.

manual MATLAB takes y-axis tick labels from YTickLabels; it does not depend on the YData in the children objects. Setting values for YTickLabels sets this property to manual.

YTickLabels: Y-axis tick mark labels.

A matrix of strings to use as labels for tick marks along the y-axis. These labels replace the numeric labels generated by MATLAB. If you do not specify enough text labels for all the tick marks, MATLAB uses all of the labels specified, and then labels the remaining tick marks by reusing the specified labels. The command

set(gca,'YTickLabels',['Old Data';'New Data'])

labels the first two tick marks on the y-axis 'Old Data' and 'New Data' respectively. Each character string must have an equal number of characters because of the way MATLAB stores strings.

This property does not control the number of tick marks or their locations.

YTickMode: Y-axis tick mark mode.

auto (Default.) MATLAB calculates y-axis tick mark spacing (YTick) that spans the YData of the axes' children.

manual MATLAB takes y-axis tick spacing from YTick; it does not depend on the YData in the children objects. Setting values for YTick sets this property to manual.

Properties That Control the Z-Axis

ZColor: Color of z-axis.

A three-element vector specifying an RGB triple, or a predefined MATLAB color string. This property determines the display color for the z-axis, tick marks, tick mark labels, and the z-axis grid lines. The default axis color is white. See the ColorSpec reference page for details on specifying colors.

ZDir: Direction of increasing z values.

normal (Default.) Z values increase pointing out of the screen (two-dimensional) or from bottom to top (three-dimensional), corresponding to a right-handed coordinate system.

reverse Z values increase pointing into the screen (two-dimensional) or from top to bottom (three-dimensional).

ZGrid: Z-axis gridline mode.

on MATLAB draws grid lines perpendicular to the z-axis at each tick mark (i.e., along lines of constant z values).

off (Default.) Grid lines are not drawn.

ZLabel: Z-axis label.

The handle of the text object used to label the z-axis. First create the text object in order to obtain its handle. The following statement performs both steps:

set(gca,'zlabel',text(0,0,'axis label'))

While the text function requires location data, it is not used to place the text. Instead, MATLAB places the string 'axis label' appropriately for a z-axis label.

You can also define a text object at an arbitrary location and pass its handle directly. In this case MATLAB moves the text string to the correct location for an axis label. The zlabel function provides a simpler means to label the z-axis by encapsulating this procedure.

ZLim: Z-axis limits.

A two-element vector [zmin zmax] that specifies the minimum and maximum z-axis values, where

zmin is the minimum z-axis value.

zmax is the maximum z-axis value.

Changing ZLim affects the scale of the z-dimension as well as the placement of labels and tick marks on the z-axis. The default for ZLim is [0 1].

ZLimMode: Z-axis limits mode.

auto (Default.) MATLAB calculates z-axis limits (ZLim) that span the ZData of the axes' children and produce round numbers for the z-axis limits.

manual MATLAB takes z-axis limits from ZLim; the limits do not depend on the ZData in the children objects. Setting values for ZLim sets this property to manual.

ZScale: Z-axis scaling.

linear (Default.) Linear scaling for the z-axis.

log Logarithmic scaling for the z-axis.

ZTick: Z-axis tick mark spacing.

A vector of values that correspond to the z-data values at which you want to place tick marks. If you do not want tick marks displayed, set ZTick to the empty vector, [].

ZTickLabelMode: Z-axis tick mark labeling mode.

auto (Default.) MATLAB calculates z-axis tick labels (ZTickLabels) that span the ZData of the axes' children.

manual MATLAB takes z-axis tick labels from ZTickLabels; it does not depend on the ZData in the children objects. Setting values for ZTickLabels sets this property to manual.

ZTickLabels: Z-axis tick mark labels.

A matrix of strings to use as labels for tick marks along the z-axis. These labels replace the numeric labels generated by MATLAB. If you do not specify enough text labels for all the tick marks, MATLAB uses all of the labels specified, and then labels the remaining tick marks by reusing the specified labels. The command

set(gca,'ZTickLabels',['Old Data';'New Data'])

labels the first two tick marks on the z-axis 'Old Data' and 'New Data' respectively. Each character string must have an equal number of characters because of the way MATLAB stores strings.

This property does not control the number of tick marks or their locations.

ZTickMode: Z-axis tick mark mode.

auto (Default.) MATLAB calculates z-axis tick mark spacing (ZTick) that spans the ZData of the axes' children.

manual MATLAB takes z-axis tick spacing from ZTick; it does not depend on the ZData in the children objects. Setting values for ZTick sets this property to manual.

Examples

An important axes property is Position. It allows you to define the location of the axes within the figure window. For example,

 h = axes('Position',rect)

creates an axes object at the specified position within the current figure window and returns a handle to it. You specify the location and size of the axes with a rectangle defined by a four element vector,

rect = [left, bottom, width, height]

The left and bottom elements of this vector define the distance from the lower-left corner of the figure to the lower-left corner of the rectangle. The width and height elements define the dimensions of the rectangle. You specify these values in units determined by the Units property. By default, MATLAB uses normalized units where (0,0) is the lower-left corner and (1.0,1.0) is the upper-right corner of the figure window.

You can define multiple axes in a single figure window:

clf
axes('position',[.1  .1  .8  .6])
mesh(peaks(20));
axes('position',[.1  .7  .8  .2])
pcolor([1:10;1:10]);

In this example, the first plot occupies the bottom two-thirds of the figure, and the second occupies the top third.

axes

Purpose

Synopsis

Description

Object Properties

Properties That Control the X-Axis

Properties That Control the Y-Axis

Properties That Control the Z-Axis

Examples

See Also