MATLAB Function Reference
  Go to function:
    Search    Help Desk 
axes    Examples   See Also

Create Axes graphics object

Syntax

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:

Zoom in and out using the CameraViewAngle:

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,

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,

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:

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:

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)
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
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
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 strin
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 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



[ Previous | Help Desk | Next ]