matlab axes property

 
Axes Properties


Modify axes properties
Creating Axes Objects


Use axes to create axes objects.
Modifying Properties


You can set and query graphics object properties in two ways:

The Property Editor is an interactive tool that enables you to see and change object property values.

The set and get commands let you set and query the values of properties.

To change the default values of properties, see Setting Default Property Values in the Handle Graphics Objects documentation.
Axes Property Descriptions


This section provides a description of properties. Curly braces { } enclose default values.
ActivePositionProperty
    

{outerposition} | position

Use OuterPosition or Position property for resize. Specifies which property MATLAB uses to determine the size of the axes when you resize the figure (interactively or during a printing or exporting operation).

See OuterPosition and Position for related properties.

See Automatic Axes Resize for a discussion of how to use axes positioning properties.
ALim
    

[amin, amax]

Alpha axis limits. Determines how MATLAB maps the AlphaData values of surface, patch, and image objects to the figure's alphamap.

amin — Value of the data mapped to the first alpha value in the alphamap.

amax — Value of the data mapped to the last alpha value in the alphamap.

MATLAB linearly interpolates data values in between across the alphamap and clamps data values outside to either the first or last alphamap value, whichever is closest.

If the axes contains multiple graphics objects, MATLAB sets ALim to span the range of all objects' AlphaData (or FaceVertexAlphaData for patch objects).

See the alpha function reference page for additional information.
ALimMode
    

{auto} | manual

Alpha axis limits mode.

auto — MATLAB sets the ALim property to span the AlphaData limits of the graphics objects displayed in the axes.

manual — MATLAB does not change the value of ALim when the AlphaData limits of axes children change.

Setting the ALim property sets ALimMode to manual.
AmbientLightColor
    

ColorSpec

Background light in a scene. Ambient light is a directionless light that shines uniformly on all objects in the axes. However, if there are no visible light objects in the axes, MATLAB does not use AmbientLightColor. If there are light objects in the axes, MATLAB adds the AmbientLightColor to the other light sources.
AspectRatio
    

(Obsolete)

This property produces a warning message when queried or changed. The DataAspectRatio[Mode] and PlotBoxAspectRatio[Mode] properties have superseded it.
BeingDeleted
    

on | {off} (read-only)

This object is being deleted. Mechanism to determine if objects are in the process of being deleted. MATLAB sets the BeingDeleted property to on when the object's delete function callback is called (see the DeleteFcn property). It remains set to on while the delete function executes, after which the object no longer exists.

For example, an object's delete function calls other functions that act on a number of different objects. If a function does not need to perform an action on an about-be-deleted object, it can check the object's BeingDeleted property before acting.

See the close and delete function reference pages for related information.
Box
    

on | {off}

Axes box mode. Specifies whether to enclose the axes extent in a box for 2-D views or a cube for 3-D views. The default is to not display the box.
BusyAction
    

cancel | {queue}

Callback routine interruption. Controls how MATLAB handles events that potentially interrupt executing callbacks.

'queue' — Queue the event that attempted to execute a second callback routine until the current callback finishes.

'cancel' — Discard the event that attempted to execute a second callback routine.

If there is a callback function executing, callbacks invoked later always attempt to interrupt it. If the Interruptible property of the object whose callback is executing is on (the default), then interruption occurs at the next point where the event queue is processed. If the Interruptible property is off, the BusyAction property (of the object owning the executing callback) determines how MATLAB handles the event.
ButtonDownFcn
    

function handle | cell array containing function handle and additional arguments | string (not recommended)

Button press callback function. Executes whenever you press a mouse button while the pointer is within the axes, but not over another graphics object parented to the axes. For 3-D views, the active area is a rectangle that encloses the axes.

See the figure's SelectionType property to determine whether modifier keys were also pressed.

Set this property to a function handle that references the callback. The function must define at least two input arguments (handle of axes associated with the button down event and an event structure, which is empty for this property).

See Function Handle Callbacks for information on how to use function handles to define the callback function.

Some Plotting Functions Reset the ButtonDownFcn

Most MATLAB plotting functions clear the axes and reset a number of axes properties, including the ButtonDownFcn before plotting data. To create an interface that lets users plot data interactively, consider using a control device such as a push button (uicontrol), which plotting functions do not affect. See Example — Using Function Handles in GUIs for an example.

If you must use the axes ButtonDownFcn to plot data, then you should use low-level functions such as line, patch, and surface and manage the process with the figure and axes NextPlot properties.

See High-Level Versus Low-Level Functions for information on how plotting functions behave.

See Preparing Figures and Axes for Graphics for more information.
Camera Properties


See View Control with the Camera Toolbar for information related to the Camera properties.

See Defining Scenes with Camera Graphics for information on the camera properties.

See View Projection Types for information on orthogonal and perspective projections.
CameraPosition
    

[x, y, z] axes coordinates

Location of the camera. Position from which the camera views the scene. Specify the point in axes coordinates.

If you fix CameraViewAngle, you can zoom in and out on the scene by changing the CameraPosition, moving the camera closer to the CameraTarget to zoom in and farther away from the CameraTarget to zoom out. As you change the CameraPosition, the amount of perspective also changes, if Projection is perspective. You can also zoom by changing the CameraViewAngle; however, this does not change the amount of perspective in the scene.
CameraPositionMode
    

{auto} | manual

Auto or manual CameraPosition. When set to auto, MATLAB automatically calculates the CameraPosition such that the camera lies a fixed distance from the CameraTarget along the azimuth and elevation specified by view. Setting a value for CameraPosition sets this property to manual.
CameraTarget
    

[x, y, z] axes coordinates

Camera aiming point. Specifies the location in the axes that the camera points to. The CameraTarget and the CameraPosition define the vector (the view axis) along which the camera looks.
CameraTargetMode
    

{auto} | manual

Auto or manual CameraTarget placement. When this property is auto, MATLAB automatically positions the CameraTarget at the centroid of the axes plot box. Specifying a value for CameraTarget sets this property to manual.
CameraUpVector
    

[x, y, z] axes coordinates

Camera rotation. Specifies the rotation of the camera around the viewing axis defined by the CameraTarget and the CameraPosition properties. Specify CameraUpVector as a three-element array containing the x, y, and z components of the vector. For example, [0 1 0] specifies the positive y-axis as the up direction.

The default CameraUpVector is [0 0 1], which defines the positive z-axis as the up direction.
CameraUpVectorMode
    

{auto} | manual

Default or user-specified up vector. When CameraUpVectorMode is auto, MATLAB uses a value of [0 0 1] (positive z-direction is up) for 3-D views and [0 1 0] (positive y-direction is up) for 2-D views. Setting a value for CameraUpVector sets this property to manual.
CameraViewAngle
    

scalar greater than 0 and less than or equal to 180 (angle in degrees)

Field of view. Determines the camera field of view. Changing this value affects the size of graphics objects displayed in the axes, but does not affect the degree of perspective distortion. The greater the angle, the larger the field of view, and the smaller objects appear in the scene.
CameraViewAngleMode
    

{auto} | manual

Auto or manual CameraViewAngle. When in auto mode, MATLAB sets CameraViewAngle to the minimum angle that captures the entire scene (up to 180°).

The following table summarizes MATLAB camera behavior using various combinations of CameraViewAngleMode, CameraTargetMode, and CameraPositionMode:CameraViewAngleModeCameraTargetModeCameraPositionModeBehaviorautoautoauto

Sets CameraTarget to plot box centroid, sets CameraViewAngle to capture entire scene, sets CameraPosition along the view axis.autoautomanual

Sets CameraTarget to plot box centroid, sets CameraViewAngle to capture entire scene.automanualauto

Sets CameraViewAngle to capture entire scene, sets CameraPosition along the view axis.automanualmanual

Sets CameraViewAngle to capture entire scene.manualautoauto

Sets CameraTarget to plot box centroid, sets CameraPosition along the view axis.manualautomanual

Sets CameraTarget to plot box centroid.manualmanualauto

Sets CameraPosition along the view axis.manualmanualmanual

User specifies all camera properties.


Children
    

vector of graphics object handles

Handles of all graphics objects rendered within the axes (whether visible or not). The graphics objects that can be children of axes are image, light, line, patch, rectangle, surface, and text. Change the order of the handles to change the stacking of the objects on the display.

The text objects used to label the x-, y-, and z-axes and the title are also children of axes, but their HandleVisibility properties are set to off. This means their handles do not show up in the axes Children property unless you set the Root ShowHiddenHandles property to on.

When an object's HandleVisibility property is off, its parent's Children property does not list it. See HandleVisibility for more information.
CLim
    

[cmin, cmax]

Color axis limits. Determines how MATLAB maps the CData values of surface and patch objects to the figure's Colormap. cmin is the value of the data mapped to the first color in the colormap. cmax is the value of the data mapped to the last color in the colormap. MATLAB linearly interpolates data values in between across the colormap and clamps data values outside to either the first or last alphamap colormap color, whichever is closest.

When CLimMode is auto (the default), MATLAB assigns cmin the minimum data value and cmax the maximum data value in the graphics object's CData. This maps CData elements with minimum data value to the first colormap entry and with maximum data value to the last colormap entry.

If the axes contains multiple graphics objects, MATLAB sets CLim to span the range of all objects' CData.

See the caxis function reference page for related information.
CLimMode
    

{auto} | manual

Color axis limits mode.

auto — MATLAB sets the CLim property to span the CData limits of the graphics objects displayed in the axes.

manual — MATLAB does not change the value of CLim when the CData limits of axes children change.

Setting the CLim property sets this property to manual.
Clipping
    

{on} | off

Clipping mode. This property has no effect on axes.
Color
    

{none} | ColorSpec

Color of the axes back planes. Setting this property to none means that the axes is transparent and the figure color shows through. A ColorSpec is a three-element RGB vector or one of the MATLAB predefined names. Note that while the default value is none, the matlabrc.m startup file might set the axes Color to a specific color.
ColorOrder
    

m-by-3 matrix of RGB values

Colors to use for multiline plots. Defines the colors used by the plot and plot3 functions to color each line plotted. If you do not specify a line color with plot and plot3, these functions cycle through the ColorOrder property to obtain the color for each line plotted. To obtain the current ColorOrder, which might be set during startup, get the property value:
get(gca,'ColorOrder')


Note that if the axes NextPlot property is replace (the default), high-level functions like plot reset the ColorOrder property before determining the colors to use. If you want MATLAB to use a ColorOrder that is different from the default, set NextPlot to replacechildren. You can also specify your own default ColorOrder.
CreateFcn
    

function handle | cell array containing function handle and additional arguments | string (not recommended)

Callback function executed during object creation. Executes when MATLAB creates an axes object. You must define this property as a default value for axes. For example, the statement:
set(0,'DefaultAxesCreateFcn',@ax_create)


defines a default value on the Root level that sets axes properties whenever you (or MATLAB) create an axes.
function ax_create(src,evnt)
 set(src,'Color','b',...
 'XLim',[1 10],...
 'YLim',[0 100])
end


MATLAB executes this function after setting all properties for the axes. Setting the CreateFcn property on an existing axes object has no effect.

MATLAB passes the handle of the object whose CreateFcn is being executed as the first argument to the callback function and is also accessible through the Root CallbackObject property, which can be queried using gcbo.

See Function Handle Callbacks for information on how to use function handles to define the callback function.
CurrentPoint
    

2-by-3 matrix

Location of last button click, in axes data units. Contains the coordinates of two points defined by the location of the pointer at the last mouse click. MATLAB returns the coordinates with respect to the requested axes.

Clicking Within the Axes — Orthogonal Projection

The two points lie on the line that is perpendicular to the plane of the screen and passes through the pointer. This is true for both 2-D and 3-D views.

The 3-D coordinates are the points, in the axes coordinate system, where this line intersects the front and back surfaces of the axes volume (which is defined by the axes x, y, and z limits).

The returned matrix is of the form:



where front defines the point nearest to the camera position. Therefore, if the CurrentPoint property returns the cp matrix , then the first row,
cp(1,:)


specifies the point nearest the viewer and the second row,
cp(2,:)


specifies the point furthest from the viewer.

Clicking Outside the Axes — Orthogonal Projection

When you click outside the axes volume, but within the figure, the returned values are:

Back point — a point in the plane of the camera target (which is perpendicular to the viewing axis).

Front point — a point in the camera position plane (which is perpendicular to the viewing axis).

These points lie on a line that passes through the pointer and is perpendicular to the camera target and camera position planes.

Clicking Within the Axes — Perspective Projection

The values of the current point when using perspective project can be different from the same point in orthographic projection because the shape of the axes volume can be different.

Clicking Outside the Axes — Perspective Projection

Clicking outside of the axes volume returns the front point as the current camera position at all times. Only the back point updates with the coordinates of a point that lies on a line extending from the camera position through the pointer and intersecting the camera target at the point.

Related Information

See the figure CurrentPoint property for more information.
DataAspectRatio
    

[dx dy dz]

Relative scaling of data units. Controls the relative scaling of data units in the x, y, and z directions. For example, setting this property to [1 2 1] causes the length of one unit of data in the x-direction to be the same length as two units of data in the y-direction and one unit of data in the z-direction.

Note that the DataAspectRatio property interacts with the PlotBoxAspectRatio, XLimMode, YLimMode, and ZLimMode properties to control how MATLAB scales the x-, y-, and z-axis. Setting the DataAspectRatio disables the stretch-to-fill behavior if DataAspectRatioMode, PlotBoxAspectRatioMode, and CameraViewAngleMode are all auto.

The following table describes the interaction between properties when you disable stretch-to-fill behavior.

Interaction Between Properties With Stretch-to-Fill Disabled

X-, Y-, Z-LimitModes

DataAspectRatio

PlotBoxAspectRatio

Behavior

auto

auto

auto

Limits chosen to span data range in all dimensions.

auto

auto

manual

Limits chosen to span data range in all dimensions. MATLAB modifies DataAspectRatio to achieve the requested PlotBoxAspectRatio within the limits the software selected.

auto

manual

auto

Limits chosen to span data range in all dimensions. MATLAB modifies PlotBoxAspectRatio to achieve the requested DataAspectRatio within the limits the software selected.

auto

manual

manual

Limits chosen to completely fit and center the plot within the requested PlotBoxAspectRatio given the requested DataAspectRatio (this might produce empty space around 2 of the 3 dimensions).

manual

auto

auto

MATLAB honors limits and modifies the DataAspectRatio and PlotBoxAspectRatio as necessary.

manual

auto

manual

MATLAB honors limits and PlotBoxAspectRatio and modifies DataAspectRatio as necessary.

manual

manual

auto

MATLAB honors limits and DataAspectRatio and modifies the PlotBoxAspectRatio as necessary.

1 manual

2 auto

manual

manual

MATLAB selects the 2 automatic limits to honor the specified aspect ratios and limit. See "Examples."

2 or 3 manual

manual

manual

MATLAB honors limits and DataAspectRatio while ignoringPlotBoxAspectRatio.



See Understanding Axes Aspect Ratio for more information.
DataAspectRatioMode
    

{auto} | manual

User or MATLAB controlled data scaling. Controls whether the values of the DataAspectRatio property are user-defined or selected automatically by MATLAB. Setting values for the DataAspectRatio property automatically sets this property to manual. Changing DataAspectRatioMode to manual disables the stretch-to-fill behavior if DataAspectRatioMode, PlotBoxAspectRatioMode, and CameraViewAngleMode are all auto.
DeleteFcn
    

function handle | cell array containing function handle and additional arguments | string (not recommended)

Delete axes callback function. Executes when you delete the axes object (for example, when you issue a delete or clf command). MATLAB executes the routine before destroying the object's properties so the callback can query these values.

MATLAB passes the handle of the object whose DeleteFcn is executing as the first argument to the callback function. The handle is also accessible through the Root CallbackObject property, which can be queried using gcbo.

See Function Handle Callbacks for information on how to use function handles to define the callback function.
DrawMode
    

{normal} | fast

Rendering mode. Controls the way MATLAB renders graphics objects displayed in the axes when the figure Renderer property is painters.

normal — Draws objects in back to front ordering based on the current view in order to handle hidden surface elimination and object intersections.

fast — Draws objects in the order in which you specify the drawing commands, without considering the relationships of the objects in three dimensions. This results in faster rendering because it requires no sorting of objects according to location in the view, but can produce undesirable results because it bypasses the hidden surface elimination and object intersection handling provided by normal DrawMode.

When the figure Renderer property is zbuffer, MATLAB ignores DrawMode and always provides hidden surface elimination and object intersection handling.
FontAngle
    

{normal} | italic | oblique

Select italic or normal font. Selects the character slant for axes text. normal specifies a nonitalic font. italic and oblique specify italic font.
FontName
    

name (such as Courier) | FixedWidth

Font family name. Specifies the font to use for axes labels. To display and print properly, FontName must be a font that your system supports. Note that MATLAB does not display the x-, y-, and z-axis labels in a new font until you manually reset them (by setting the XLabel, YLabel, and ZLabel properties or by using the xlabel, ylabel, or zlabel command). Tick mark labels change immediately.

Specifying a Fixed-Width Font

If you want an axes to use a fixed-width font that looks good in any locale, set FontName to the string FixedWidth:
set(axes_handle,'FontName','FixedWidth')


This eliminates the need to hardcode the name of a fixed-width font, which might not display text properly on systems that do not use ASCII character encoding (such as in Japan, where character sets can be multibyte). A properly written MATLAB application that needs to use a fixed-width font should set FontName to FixedWidth (note that this string is case sensitive) and rely on FixedWidthFontName to be set correctly in the end user's environment.

End users can adapt a MATLAB application to different locales or personal environments by setting the root FixedWidthFontName property to the appropriate value for that locale from startup.m.

Note that setting the root FixedWidthFontName property causes an immediate update of the display to use the new font.
FontSize
    

Font size specified in FontUnits

Font size. An integer specifying the font size to use for axes labels and titles, in units determined by the FontUnits property. The default point size is 12 and the maximum allowable font size depends on your operating system. MATLAB does not display x-, y-, and z-axis text labels in a new font size until you manually reset them (by setting the XLabel, YLabel, or ZLabel properties or by using the xlabel, ylabel, or zlabel command). Tick mark labels change immediately.
FontUnits
    

{points} | normalized | inches | centimeters | pixels

Units used to interpret the FontSize property. When set to normalized, MATLAB interprets the value of FontSize as a fraction of the height of the axes. For example, a normalized FontSize of 0.1 sets the text characters to a font whose height is one tenth of the axes' height. The default units (points), are equal to 1/72 of an inch.

If you set both the FontSize and the FontUnits in one function call, you must set the FontUnits property first so that MATLAB correctly interprets the specified FontSize.
FontWeight
    

{normal} | bold | light | demi

Select bold or normal font. The character weight for axes text. MATLAB does not display the x-, y-, and z-axis text labels in bold until you manually reset them (by setting the XLabel, YLabel, and ZLabel properties or by using the xlabel, ylabel, or zlabel commands). Tick mark labels change immediately.
GridLineStyle
    

- | - -| {:} | -. | none

Line style used to draw grid lines. The line style is a string consisting of a character, in quotes, specifying solid lines (-), dashed lines (--), dotted lines(:), or dash-dot lines (-.). The default grid line style is dotted. To turn on grid lines, use the grid command.
HandleVisibility
    

{on} | callback | off

Control access to object's handle. Determines when an object's handle is visible in its parent's list of children. HandleVisibility is useful for preventing command-line users from accidentally drawing into or deleting a figure that contains only user interface devices (such as a dialog box).

on — Handles are always visible.

callback — Handles are visible from within callback routines or functions invoked by callback routines, but not from within functions invoked from the command line. This provides a means to protect GUIs from command-line users, while allowing callback routines to have access to object handles.

off — Handles are invisible at all times. Use this option when a callback invokes a function that could damage the GUI (such as evaluating a user-typed string). This option temporarily hides its own handles during the execution of that function.

When a handle is not visible in its parent's list of children, functions that obtain handles by searching the object hierarchy or querying handle properties cannot return it. This includes get, findobj, gca, gcf, gco, newplot, cla, clf, and close.

When you restrict a handle's visibility by using callback or off, the object's handle does not appear in its parent's Children property, figures do not appear in the Root's CurrentFigure property, objects do not appear in the Root's CallbackObject property or in the figure's CurrentObject property, and axes do not appear in their parent's CurrentAxes property.

You can set the Root ShowHiddenHandles property to on to make all handles visible regardless of their HandleVisibility settings (this does not affect the values of the HandleVisibility properties).

Handles that are hidden are still valid. If you know an object's handle, you can set and get its properties, and pass it to any function that operates on handles.
HitTest
    

{on} | off

Selectable by mouse click. Determines if the axes can become the current object (as returned by the gco command and the figure CurrentObject property) as a result of a mouse click the axes. If HitTest is off, clicking the axes selects the object below it (which is usually the figure containing it).
Interruptible
    

{on} | off

Callback routine interruption mode. Controls whether an axes callback routine can be interrupted by subsequently invoked callback routines. The Interruptible property only affects callback routines defined for the ButtonDownFcn . MATLAB checks for events that can interrupt a callback only when it encounters a drawnow, figure, getframe, or pause command in the routine. See the BusyAction property for related information.

Setting Interruptible to on allows any graphics object's callback routine to interrupt callback routines originating from an axes property. Note that MATLAB does not save the state of variables or the display (for example, the handle returned by the gca or gcf command) when an interruption occurs.
Layer
    

{bottom} | top

Draw axis lines below or above graphics objects. Determines whether to draw axis lines and tick marks on top or below axes children objects for any 2-D view (for example, when you are looking along the x-, y-, or z-axis). Use this property to place grid lines and tick marks on top of images.
LineStyleOrder
    

LineSpec {a solid line '-'}

Order of line styles and markers used in a plot. Specifies which line styles and markers to use and in what order when creating multiple-line plots. For example:
set(gca,'LineStyleOrder', '-*|:|o')


sets LineStyleOrder to solid line with asterisk marker, dotted line, and hollow circle marker. The default is (-), which specifies a solid line for all data plotted. Alternatively, you can create a cell array of character strings to define the line styles:
set(gca,'LineStyleOrder',{'-*',':','o'})


MATLAB supports four line styles, which you can specify any number of times in any order. MATLAB cycles through the line styles only after using all colors defined by the ColorOrder property. For example, the first eight lines plotted use the different colors defined by ColorOrder with the first line style. MATLAB then cycles through the colors again, using the second line style specified, and so on.

You can also specify line style and color directly with the plot and plot3 functions or by altering the properties of the line or lineseries objects after creating the graph.

High-Level Functions and LineStyleOrder

Note that, if the axes NextPlot property is replace (the default), high-level functions like plot reset the LineStyleOrder property before determining the line style to use. If you want MATLAB to use a LineStyleOrder that is different from the default, set NextPlot to replacechildren.

Specifying a Default LineStyleOrder

You can specify your own default LineStyleOrder. For example:
set(0,'DefaultAxesLineStyleOrder',{'-*',':','o'})



creates a default value for the axes LineStyleOrder that high-level plotting functions will not reset.
LineWidth
    

line width in points

Width of axis lines. Specifies the width, in points, of the x-, y-, and z-axis lines. The default line width is 0.5 points 1 point = 1/72 inch.
MinorGridLineStyle
    

- | - -| {:} | -. | none

Line style used to draw minor grid lines. The line style is a string consisting of one or more characters, in quotes, specifying solid lines (-), dashed lines (--), dotted lines (:), or dash-dot lines (-.). The default minor grid line style is dotted. To turn on minor grid lines, use the grid minor command.
NextPlot
    

add | {replace} | replacechildren

Where to draw the next plot. Determines how high-level plotting functions draw into an existing axes.

add — Use the existing axes to draw graphics objects.

replace — Reset all axes properties except Position to their defaults and delete all axes children before displaying graphics (equivalent to cla reset).

replacechildren — Remove all child objects, but do not reset axes properties (equivalent to cla).

The newplot function simplifies the use of the NextPlot property and is useful for functions that draw graphs using only low-level object creation routines. Note that figure graphics objects also have a NextPlot property.
OuterPosition
    

four-element vector

Position of axes including labels, title, and a margin. Specifies a rectangle that locates the outer bounds of the axes, including axis labels, the title, and a margin. The vector is as follows:
[left bottom width height]


where left and bottom define the distance from the lower-left corner of the figure window to the lower-left corner of the rectangle. width and height are the dimensions of the rectangle.

The following picture shows the region defined by the OuterPosition enclosed in a yellow rectangle.



When ActivePositionProperty is OuterPosition (the default), resizing the figure will not clip any of the text. The default value of [0 0 1 1] (normalized units) includes the interior of the figure.

The Units property specifies all measurement units.

See the TightInset property for related information.

See Automatic Axes Resize for a discussion of how to use axes positioning properties.
Parent
    

figure or uipanel handle

Axes parent. The handle of the axes' parent object. The parent of an axes object is the figure which displays it or the uipanel object that contains it. The utility function gcf returns the handle of the current axes Parent. You can reparent axes to other figure or uipanel objects.

See Objects That Can Contain Other Objects for more information on parenting graphics objects.
PlotBoxAspectRatio
    

[px py pz]

Relative scaling of axes plot box. Controls the relative scaling of the plot box in the x, y, and z directions. The plot box is a box enclosing the axes data region as defined by the x-, y-, and z-axis limits.

Note that the PlotBoxAspectRatio property interacts with the DataAspectRatio, XLimMode, YLimMode, and ZLimMode properties to control the way MATLAB displays graphics objects. Setting the PlotBoxAspectRatio disables stretch-to-fill behavior, if DataAspectRatioMode, PlotBoxAspectRatioMode, and CameraViewAngleMode are all auto.
PlotBoxAspectRatioMode
    

{auto} | manual

User or MATLAB controlled axis scaling. Controls whether the values of the PlotBoxAspectRatio property are user-defined or selected automatically by MATLAB. Setting values for the PlotBoxAspectRatio property automatically sets this property to manual. Changing the PlotBoxAspectRatioMode to manual disables stretch-to-fill behavior if DataAspectRatioMode, PlotBoxAspectRatioMode, and CameraViewAngleMode are all auto.
Position
    

four-element vector

Position of axes. Specifies a rectangle that locates the axes within its parent container (figure or uipanel). The vector is of the form:
[left bottom width height]


where left and bottom define the distance from the lower-left corner of the container to the lower-left corner of the rectangle. width and height are the dimensions of the rectangle. The Units property specifies the units for all measurements.

When you enable axes stretch-to-fill behavior (when DataAspectRatioMode, PlotBoxAspectRatioMode, and CameraViewAngleMode are all auto), MATLAB stretches the axes to fill the Position rectangle. When you disable stretch-to-fill, MATLAB makes the axes as large as possible, while obeying all other properties, without extending outside the Position rectangle.

See the OuterPosition property for related information.

See Automatic Axes Resize for a discussion of how to use axes positioning properties.
Projection
    

{orthographic} | perspective

Type of projection. Selects one of the following projection types:

orthographic — Maintains the correct relative dimensions of graphics objects regarding the distance a given point is from the viewer and draws parallel lines in the data parallel on the screen.

perspective — Incorporates foreshortening, which allows you to perceive depth in 2-D representations of 3-D objects. Perspective projection does not preserve the relative dimensions of objects; it displays a distant line segment smaller than a nearer line segment of the same length. Parallel lines in the data might not appear parallel on screen.
Selected
    

on | {off}

Is object selected? When you set this property to on, MATLAB displays selection "handles" at the corners and midpoints if the SelectionHighlight property is also on (the default). You can, for example, define the ButtonDownFcn callback to set this property to on, thereby indicating that the axes has been selected.
SelectionHighlight
    

{on} | off

Highlights objects when selected. When the Selected property is on, MATLAB indicates the selected state by drawing four edge handles and four corner handles. When SelectionHighlight is off, MATLAB does not draw the handles.
Tag
    

string

User-specified object label. Provides a means to identify graphics objects with a user-specified label. The default is an empty string.

Use the Tag property and the findobj function to manipulate specific objects within a plotting hierarchy.

For example, suppose you want to direct all graphics output from a file to a particular axes, regardless of user actions that might have changed the current axes. To do this, identify the axes with a Tag:
axes('Tag','Special Axes')


Then make that axes the current axes before drawing by searching for the Tag with findobj:
axes(findobj('Tag','Special Axes'))

TickDir
    

in | out

Direction of tick marks. For 2-D views, the default is to direct tick marks inward from the axis lines; 3-D views direct tick marks outward from the axis line.
TickDirMode
    

{auto} | manual

Automatic tick direction control. In auto mode, MATLAB directs tick marks inward for 2-D views and outward for 3-D views. When you specify a setting for TickDir, MATLAB sets TickDirMode to manual. In manual mode, MATLAB does not change the specified tick direction.
TickLength
    

[2DLength 3DLength]

Length of tick marks. Specifies the length of axes tick marks. The first element is the length of tick marks used for 2-D views and the second element is the length of tick marks used for 3-D views. Specify tick mark lengths in units normalized relative to the longest of the visible x-, y-, or z-axis annotation lines.
TightInset
    

[left bottom right top] Read only

Margins added to Position to include text labels. Specifies the distances between the bounds of the Position property and the extent of the axes text labels and title. When added to the Position width and height values, the TightInset defines the tightest bounding box that encloses the axes and its labels and title.

See Automatic Axes Resize for more information.
Title
    

handle of text object

Axes title. The handle of the text object used for the axes title. Use this handle to change the properties of the title text or you can set Title to the handle of an existing text object. For example, the following statement changes the color of the current title to red:
set(get(gca,'Title'),'Color','r')


To create a new title, set this property to the handle of the text object you want to use:
set(gca,'Title',text('String','New Title','Color','r'))


However, it is simpler to use the title command to create or replace an axes title:
title('New Title','Color','r') % Make text color red
title({'This title','has 2 lines'}) % Two line title

Type
    

string (read-only)

Type of graphics object. String that identifies the class of the graphics object. Use this property to find all objects of a given type within a plotting hierarchy. For axes objects, Type is always 'axes'.
UIContextMenu
    

handle of uicontextmenu object

Associate a context menu with the axes. Assign this property the handle of a uicontextmenu object created in the axes' parent figure. Use the uicontextmenu function to create the context menu. MATLAB displays the context menu whenever you right-click over the axes.
Units
    

inches | centimeters | {normalized} | points | pixels | characters

Axes position units. The units used to interpret the Position property. MATLAB measures all units from the lower left corner of the figure window.

Note   The Units property controls the positioning of the axes within the figure. This property does not affect the data units used for graphing. See the axes XLim, YLim, and ZLim properties to set the limits of each axis data units.

normalized — Units map the lower left corner of the figure window to (0,0) and the upper right corner to (1.0, 1.0).

inches, centimeters, and points — Absolute units. 1 point = 1/72 inch.

characters — Based on the size of characters in the default system font. The width of one characters unit is the width of the letter x, and the height of one characters unit is the distance between the baselines of two lines of text.

When specifying the units as property/value pairs during object creation, you must set the Units property before specifying the properties that you want to use these units.
UserData
    

matrix

User-specified data. Data you want to associate with the axes object. The default value is an empty array. MATLAB does not use this data, but you can access it using the set and get commands.
View
    

Obsolete

The axes camera properties now controls the functionality provided by the View property — CameraPosition, CameraTarget, CameraUpVector, and CameraViewAngle. See the view command.
Visible
    

{on} | off

Visibility of axes. By default, axes are visible. Setting this property to off prevents axis lines, tick marks, and labels from being displayed. The Visible property does not affect children of axes.
XAxisLocation
    

top | {bottom}

Location of x-axis tick marks and labels. Controls where MATLAB displays the x-axis tick marks and labels. Setting this property to top moves the x-axis to the top of the plot from its default position at the bottom. This property applies to 2–D views only.
YAxisLocation
    

right | {left}

Location of y-axis tick marks and labels. Controls where MATLAB displays the y-axis tick marks and labels. Setting this property to right moves the y-axis to the right side of the plot from its default position on the left side. This property applies to 2–D views only. See the plotyy function for a simple way to use two y-axes.
Properties That Control the X-, Y-, or Z-Axis

XColor, YColor, ZColor
    

ColorSpec

Color of axis lines. A three-element vector specifying an RGB triple, or a predefined MATLAB color string. This property determines the color of the axis lines, tick marks, tick mark labels, and the axis grid lines of the respective x-, y-, and z-axis. The default axis color is black. See ColorSpec for details on specifying colors.
XDir, YDir, ZDir
    

{normal} | reverse

Direction of increasing values. A mode controlling the direction of increasing axis values. Axes form a right-hand coordinate system. By default:

x-axis values increase from left to right. To reverse the direction of increasing x values, set this property to reverse.
set(gca,'XDir','reverse')


y-axis values increase from bottom to top (2-D view) or front to back (3-D view). To reverse the direction of increasing y values, set this property to reverse.
set(gca,'YDir','reverse')


z-axis values increase pointing out of the screen (2-D view) or from bottom to top (3-D view). To reverse the direction of increasing z values, set this property to reverse.
set(gca,'ZDir','reverse')

XGrid, YGrid, ZGrid
    

on | {off}

Axis gridline mode. When you set any of these properties to on, MATLAB draws grid lines perpendicular to the respective axis (for example, along lines of constant x, y, or z values). Use the grid command to set all three properties on or off at once.
set(gca,'XGrid','on')

XLabel, YLabel, ZLabel
    

handle of text object

Axis labels. The handle of the text object used to label the x-, y-, or z-axis, respectively. To assign values to any of these properties, you must obtain the handle to the text string you want to use as a label. This statement defines a text object and assigns its handle to the XLabel property:
set(get(gca,'XLabel'),'String','axis label')



MATLAB places the string 'axis label' appropriately for an x-axis label and moves any text object whose handle you specify as an XLabel, YLabel, or ZLabel property to the appropriate location for the respective label.

Alternatively, you can use the xlabel, ylabel, and zlabel functions, which generally provide a simpler means to label axis lines.

Note that using a bitmapped font (for example, Courier is usually a bitmapped font) might cause the labels to rotate improperly. As a workaround, use a TrueType font (for example, Courier New) for axis labels. See your system documentation to determine the types of fonts installed on your system.
XLim, YLim, ZLim
    

[minimum maximum]

Axis limits. Specifies the minimum and maximum values of the respective axis. The data you plot determines these values.

Changing these properties affects the scale of the x-, y-, or z-dimension as well as the placement of labels and tick marks on the axis. The default values for these properties are [0 1].

See the axis, datetick, xlim, ylim, and zlim commands to set these properties.
XLimMode, YLimMode, ZLimMode
    

{auto} | manual

MATLAB or user-controlled limits. The axis limits mode determines whether MATLAB calculates axis limits based on the data plotted (for example, the XData, YData, or ZData of the axes children) or uses the values explicitly set with the XLim, YLim, or ZLim property, in which case, the respective limits mode is set to manual.
XMinorGrid, YMinorGrid, ZMinorGrid
    

on | {off}

Enable or disable minor gridlines. When set to on, MATLAB draws gridlines aligned with the minor tick marks of the respective axis. Note that you do not have to enable minor ticks to display minor grids.
XMinorTick, YMinorTick, ZMinorTick
    

on | {off}

Enable or disable minor tick marks. When set to on, MATLAB draws tick marks between the major tick marks of the respective axis. MATLAB automatically determines the number of minor ticks based on the space between the major ticks.
XScale, YScale, ZScale
    

{linear} | log

Axis scaling. Linear or logarithmic scaling for the respective axis. See also loglog, semilogx, and semilogy.
XTick, YTick, ZTick
    

vector of data values locating tick marks

Tick spacing. A vector of x-, y-, or z-data values that determine the location of tick marks along the respective axis. If you do not want tick marks displayed, set the respective property to the empty vector, [ ]. These vectors must contain monotonically increasing values.
XTickLabel, YTickLabel, ZTickLabel
    

string

Tick labels. A matrix of strings to use as labels for tick marks along the respective 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, then reuses the specified labels.

For example, the statement:
set(gca,'XTickLabel',{'One';'Two';'Three';'Four'})


labels the first four tick marks on the x-axis and then reuses the labels for the remaining ticks.

Labels can be cell arrays of strings, padded string matrices, string vectors separated by vertical slash characters, or numeric vectors (where MATLAB implicitly converts each number to the equivalent string using num2str). All of the following are equivalent:
set(gca,'XTickLabel',{'1';'10';'100'})
set(gca,'XTickLabel','1|10|100')
set(gca,'XTickLabel',[1;10;100])
set(gca,'XTickLabel',['1  ';'10 ';'100'])


Note that tick labels do not interpret TeX character sequences (however, the Title, XLabel, YLabel, and ZLabel properties do).
XTickMode, YTickMode, ZTickMode
    

{auto} | manual

MATLAB or user-controlled tick spacing. The axis tick modes determine whether MATLAB calculates the tick mark spacing based on the range of data for the respective axis (auto mode) or uses the values explicitly set for any of the XTick, YTick, and ZTick properties (manual mode). Setting values for the XTick, YTick, or ZTick properties sets the respective axis tick mode to manual.
XTickLabelMode, YTickLabelMode, ZTickLabelMode
    

{auto} | manual

MATLAB or user-determined tick labels. The axis tick mark labeling modes determine whether MATLAB uses numeric tick mark labels that span the range of the plotted data (auto mode) or uses the tick mark labels specified with the XTickLabel, YTickLabel, or ZTickLabel property (manual mode). Setting values for the XTickLabel, YTickLabel, or ZTickLabel property sets the respective axis tick label mode to manual.
See Also


axes  
Was this topic helpful?   
 

 


© 1984-2010 The MathWorks, Inc. • Terms of Use • Patents • Trademarks • Acknowledgments