| MATLAB Function Reference | |
Syntax
axes
axes('PropertyName',PropertyValue,...)
axes(h)
h = axes(...)
Description
axes is the low-level function for creating axes graphics objects.
axes
creates an axes graphics object in the current figure using default property values.
axes('PropertyName',PropertyValue,...)
creates an axes object having the specified property values. MATLAB uses default values for any properties that you do not explicitly define as arguments.
axes(h)
makes existing axes h the current axes. It also makes h the first axes listed in the figure's Children property and sets the figure's CurrentAxes property to h. The current axes is the target for functions that draw image, line, patch, surface, and text graphics objects.
h = axes(...)
returns the handle of the created axes object.
Remarks
MATLAB automatically creates an axes, if one does not already exist, when you issue a command that draws image, light, line, patch, surface, or text graphics objects.
The axes function accepts property name/property value pairs, structure arrays, and cell arrays as input arguments (see the set and get commands for examples of how to specify these data types). These properties, which control various aspects of the axes object, are described in the "Axes Properties" section.
Use the set function to modify the properties of an existing axes or the get function to query the current values of axes properties. Use the gca command to obtain the handle of the current axes.
The axis (not axes) function provides simplified access to commonly used properties that control the scaling and appearance of axes.
While the basic purpose of an axes object is to provide a coordinate system for plotted data, axes properties provide considerable control over the way MATLAB displays data.
By default, MATLAB stretches the axes to fill the axes position rectangle (the rectangle defined by the last two elements in the Position property). This results in graphs that use the available space in the rectangle. However, some 3-D graphs (such as a sphere) appear distorted because of this stretching, and are better viewed with a specific three-dimensional aspect ratio.
Stretch-to-fill is active when the DataAspectRatioMode, PlotBoxAspectRatioMode, and CameraViewAngleMode are all auto (the default). However, stretch-to-fill is turned off when the DataAspectRatio, PlotBoxAspectRatio, or CameraViewAngle is user-specified, or when one or more of the corresponding modes is set to manual (which happens automatically when you set the corresponding property value).
This picture shows the same sphere displayed both with and without the stretch-to-fill. The dotted lines show the axes Position rectangle.
When stretch-to-fill is disabled, MATLAB sets the size of the axes to be as large as possible within the constraints imposed by the Position rectangle without introducing distortion. In the picture above, the height of the rectangle constrains the axes size.
Examples
Zoom in using aspect ratio and limits:
sphere set(gca,'DataAspectRatio',[1 1 1],... 'PlotBoxAspectRatio',[1 1 1],'ZLim',[-0.6 0.6])
Zoom in and out using the CameraViewAngle:
sphere set(gca,'CameraViewAngle',get(gca,'CameraViewAngle')-5) set(gca,'CameraViewAngle',get(gca,'CameraViewAngle')+5)
Note that both examples disable MATLAB's stretch-to-fill behavior.
Positioning the Axes
The axes Position property enables you to define the location of the axes within the figure window. For example,
h = axes('Position',position_rectangle)
creates an axes object at the specified position within the current figure and returns a handle to it. Specify the location and size of the axes with a rectangle defined by a four-element vector,
position_rectangle = [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:
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.
See Also
axis, cla, clf, figure, gca, grid, subplot, title, xlabel, ylabel, zlabel, view
Object Hierarchy
Setting Default Properties
You can set default axes properties on the figure and root levels:
set(0,'DefaultAxesPropertyName',PropertyValue,...) set(gcf,'DefaultAxesPropertyName',PropertyValue,...)
where PropertyName is the name of the axes property and PropertyValue is the value you are specifying. Use set and get to access axes properties.
The following table lists all axes properties and provides a brief description of each. The property name links take you an expanded description of the properties.
| Property Name |
Property Description |
Property Value |
| Controlling Style and Appearance | ||
Box |
Toggle axes plot box on and off |
Values: on, off Default: off |
Clipping |
This property has no effect; axes are always clipped to the figure window |
|
GridLineStyle |
Line style used to draw axes grid lines |
Values: -, --, :, -., none Default: : (dotted line) |
Layer |
Draw axes above or below graphs |
Values: bottom, top Default: bottom |
LineStyleOrder |
Sequence of line styles used for multiline plots |
Values: LineSpec Default: - (solid line for) |
LineWidth |
Width of axis lines, in points (1/72" per point) |
Values: number of points Default: 0.5 points |
SelectionHighlight |
Highlight axes when selected (Selected property set to on) |
Values: on, off Default: on |
TickDir |
Direction of axis tick marks |
Values: in, out Default: in (2-D), out (3-D) |
TickDirMode |
Use MATLAB or user-specified tick mark direction |
Values: auto, manual Default: auto |
TickLength |
Length of tick marks normalized to axis line length, specified as two-element vector |
Values: [2-D 3-D] Default: [0.01 0.025} |
Visible |
Make axes visible or invisible |
Values: on, offDefault: on |
XGrid, YGrid, ZGrid |
Toggle grid lines on and off in respective axis |
Values: on, off Default: off |
| General Information About the Axes | ||
Children |
Handles of the images, lights, lines, patches, surfaces, and text objects displayed in the axes |
Values: vector of handles |
CurrentPoint |
Location of last mouse button click defined in the axes data units |
Values: a 2-by-3 matrix |
HitTest |
Specify whether axes can become the current object (see figure CurrentObject property) |
Values: on, offDefault: on |
Parent |
Handle of the figure window containing the axes |
Values: scalar figure handle |
Position |
Location and size of axes within the figure |
Values: [left bottom width height] Default: [0.1300 0.1100 0.7750 0.8150] in normalized Units |
Selected |
Indicate whether axes is in a "selected" state |
Values: on, off Default: on |
Tag |
User-specified label |
Values: any string Default: '' (empty string) |
Type |
The type of graphics object (read only) |
Value: the string 'axes' |
Units |
Units used to interpret the Position property |
Values: inches, centimeters, characters, normalized, points, pixels Default: normalized |
UserData |
User-specified data |
Values: any matrix Default: [] (empty matrix) |
| Selecting Fonts and Labels | ||
FontAngle |
Select italic or normal font |
Values: normal, italic, oblique Default: normal |
FontName |
Font family name (e.g., Helvetica, Courier) |
Values: a font supported by your system or the string FixedWidthDefault: Typically Helvetica |
FontSize |
Size of the font used for title and labels |
Values: an integer in FontUnits Default: 10 |
FontUnits |
Units used to interpret the FontSize property |
Values: points, normalized, inches, centimeters, pixels Default: points |
FontWeight |
Select bold or normal font |
Values: normal, bold, light, demi Default: normal |
Title |
Handle of the title text object |
Values: any valid text object handle |
XLabel, YLabel, ZLabel |
Handles of the respective axis label text objects |
Values: any valid text object handle |
XTickLabel, YTickLabel, ZTickLabel |
Specify tick mark labels for the respective axis |
Values: matrix of strings Defaults: numeric values selected automatically by MATLAB |
XTickLabelMode, YTickLabelMode, ZTickLabelMode |
Use MATLAB or user-specified tick mark labels |
Values: auto, manual Default: auto |
| Controlling Axis Scaling | ||
XAxisLocation |
Specify the location of the x-axis |
Values: top, bottom Default: bottom |
YAxisLocation |
Specify the location of the y-axis |
Values: right left Default: left |
XDir, YDir, ZDir |
Specify the direction of increasing values for the respective axes |
Values: normal, reverse Default: normal |
XLim, YLim, ZLim |
Specify the limits to the respective axes |
Values: [min max] Default: min and max determined automatically by MATLAB |
XLimMode, YLimMode, ZLimMode |
Use MATLAB or user-specified values for the respective axis limits |
Values: auto, manual Default: auto |
XScale, YScale, ZScale |
Select linear or logarithmic scaling of the respective axis |
Values: linear, log Default: linear (changed by plotting commands that create nonlinear plots) |
XTick, YTick, ZTick |
Specify the location of the axis ticks marks |
Values: a vector of data values locating tick marks Default: MATLAB automatically determines tick mark placement |
XTickMode, YTickMode, ZTickMode |
Use MATLAB or user-specified values for the respective tick mark locations |
Values: auto, manual Default: auto |
| Controlling the View | ||
CameraPosition |
Specify the position of point from which you view the scene |
Values: [x,y,z] axes coordinates Default: automatically determined by MATLAB |
CameraPositionMode |
Use MATLAB or user-specified camera position |
Values: auto, manual Default: auto |
CameraTarget |
Center of view pointed to by camera |
Values: [x,y,z] axes coordinates Default: automatically determined by MATLAB |
CameraTargetMode |
Use MATLAB or user-specified camera target |
Values: auto, manual Default: auto |
CameraUpVector |
Direction that is oriented up |
Values: [x,y,z] axes coordinates Default: automatically determined by MATLAB |
CameraUpVectorMode |
Use MATLAB or user-specified camera up vector |
Values: auto, manual Default: auto |
CameraViewAngle |
Camera field of view |
Values: angle in degrees between 0 and 180 Default: automatically determined by MATLAB |
CameraViewAngleMode |
Use MATLAB or user-specified camera view angle |
Values: auto, manual Default: auto |
Projection |
Select type of projection |
Values: orthographic, perspective Default: orthographic |
| Controlling the Axes Aspect Ratio | ||
DataAspectRatio |
Relative scaling of data units |
Values: three relative values [dx dy dz]Default: automatically determined by MATLAB |
DataAspectRatioMode |
Use MATLAB or user-specified data aspect ratio |
Values: auto, manual Default: auto |
PlotBoxAspectRatio |
Relative scaling of axes plot box |
Values: three relative values [dx dy dz] Default: automatically determined by MATLAB |
PlotBoxAspectRatioMode |
Use MATLAB or user-specified plot box aspect ratio |
Values: auto, manual Default: auto |
| Controlling Callback Routine Execution | ||
BusyAction |
Specify how to handle events that interrupt execution callback routines |
Values: cancel, queue Default: queue |
ButtonDownFcn |
Define a callback routine that executes when a button is pressed over the axes |
Values: string Default: an empty string |
CreateFcn |
Define a callback routine that executes when an axes is created |
Values: string Default: an empty string |
DeleteFcn |
Define a callback routine that executes when an axes is created |
Values: string Default: an empty string |
Interruptible |
Control whether an executing callback routine can be interrupted |
Values: on, off Default: on |
UIContextMenu |
Associate a context menu with the axes |
Values: handle of a Uicontextmenu |
| Specifying the Rendering Mode | ||
DrawMode |
Specify the rendering method to use with the Painters renderer |
Values: normal, fast Default: normal |
| Targeting Axes for Graphics Display | ||
HandleVisibility |
Control access to a specific axes' handle |
Values: on, callback, off Default: on |
NextPlot |
Determine the eligibility of the axes for displaying graphics |
Values: add, replace, replacechildren Default: replace |
| Properties that Specify Transparency | |
|
ALim |
Alpha axis limits |
Values: [amin amax] |
ALimMode |
Alpha axis limits mode |
Values: auto | manualDefault: auto |
| Properties that Specify Color | ||
AmbientLightColor |
Color of the background light in a scene |
Values: ColorSpecDefault: [1 1 1] |
CLim |
Control how data is mapped to colormap |
Values: [cmin cmax] Default: automatically determined by MATLAB |
CLimMode |
Use MATLAB or user-specified values for CLim |
Values: auto, manual Default: auto |
Color |
Color of the axes background |
Values: none, ColorSpec Default: none |
ColorOrder |
Line colors used for multiline plots |
Values: m-by-3 matrix of RGB values Default: depends on color scheme used |
XColor, YColor, ZColor |
Colors of the axis lines and tick marks |
Values: ColorSpec Default: depends on current color scheme |
| | aviread | Axes Properties | |
