Description Continued..

axes

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