axes (MATLAB Functions)

Create axes graphics object

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.

Stretch-to-Fill

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

Zooming

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 the MATLAB 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

Axes Operations for related functions

Axes Properties for more examples

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.

Property List

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)

MinorGridLineStyle
Line style used to draw axes minor 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, off
Default: 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, off
Default: 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 FixedWidth
Default: 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

XMinorGrid,YMinorGrid, ZMinorGrid
Determines whether MATLAB displays gridlines connecting minor tick marks in the respective axis.
Values: on, off
Default: off

XMinorTick,YMinorTick,ZMinorTick
Determines whether MATLAB displays minor tick marks in the respective axis.
Values: on, off
Default: off

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 or function handle
Default: an empty string

CreateFcn
Define a callback routine that executes when an axes is created
Values: string or function handle
Default: an empty string

DeleteFcn
Define a callback routine that executes when an axes is created
Values: string or function handle
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 | manual
Default: auto

Properties that Specify Color

AmbientLightColor
Color of the background light in a scene
Values: ColorSpec
Default: [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

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)
`MinorGridLineStyle`	Line style used to draw axes minor 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`, `off` Default: `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`, `off` Default: `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 `FixedWidth` Default: 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`
XMinorGrid,YMinorGrid, ZMinorGrid	Determines whether MATLAB displays gridlines connecting minor tick marks in the respective axis.	Values: `on`, `off` Default: `off`
XMinorTick,YMinorTick,ZMinorTick	Determines whether MATLAB displays minor tick marks in the respective axis.	Values: `on`, `off` Default: `off`
`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 or function handle Default: an empty string
`CreateFcn`	Define a callback routine that executes when an axes is created	Values: string or function handle Default: an empty string
`DeleteFcn`	Define a callback routine that executes when an axes is created	Values: string or function handle 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` `\|` `manual` Default: auto
Properties that Specify Color
`AmbientLightColor`	Color of the background light in a scene	Values: `ColorSpec` Default: `[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