Axes Properties

The 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, the AmbientLightColor is added to the other light sources.

This property produces a warning message when queried or changed. It has been superseded by the DataAspectRatio[Mode] and PlotBoxAspectRatio[Mode] properties.

Axes box mode. This property 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.

Callback routine interruption. The BusyAction property enables you to control how MATLAB handles events that potentially interrupt executing callback routines. If there is a callback routine executing, subsequently invoked callback routines always attempt to interrupt it. If the Interruptible property of the object whose callback is executing is set to 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. The choices are:

• cancel - discard the event that attempted to execute a second callback routine.
• queue - queue the event that attempted to execute a second callback routine until the current callback finishes.

Button press callback routine. A callback routine that executes whenever you press a mouse button while the pointer is within the Axes, but not over another graphics object displayed in the Axes. For 3-D views, the active area is defined by a rectangle that encloses the Axes.

The location of the camera. This property defines the position from which the camera views the scene. Specify the point in Axes coordinates.

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.

Camera aiming point. This property 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.

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

Camera rotation. This property 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.

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.

The field of view. This property 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.

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

Children of the Axes. A vector containing the handles of all graphics objects rendered within the Axes (whether visible or not). The graphics objects that can be children of Axes are Images, Lights, Lines, Patches, Surfaces, and Text.

Color axis limits. A two-element vector that 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, and cmax is the value of the data mapped to the last color in the colormap. Data values in between are linearly interpolated across the colormap, while data values outside are clamped to either the first or last colormap color, whichever is closest.

Color axis limits mode. In auto mode, MATLAB sets the CLim property to span the CData limits of the graphics objects displayed in the Axes. If CLimMode is 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.

This property has no effect on Axes.

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

Colors to use for multiline plots. ColorOrder is an m-by-3 matrix of RGB values that define 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 to obtain the color for each line plotted. To obtain the current ColorOrder, which may be set during startup, get the property value:

get(gca,'ColorOrder')

Callback routine executed during object creation. This property defines a callback routine that 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','set(gca,''Color'',''b'')')

Location of last button click, in Axes data units. A 2-by-3 matrix containing the coordinates of two points defined by the location of the pointer. These two points lie on the line that is perpendicular to the plane of the screen and passes through the pointer. 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).

Relative scaling of data units. A three-element vector controlling the relative scaling of data units in the x, y, and z directions. For example, setting this property t o [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.

User or MATLAB controlled data scaling. This property 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.

Delete Axes callback routine. A callback routine that executes when the Axes object is deleted (e.g., when you issue a delete or a close command). MATLAB executes the routine before destroying the object's properties so the callback routine can query these values.

Rendering method. This property controls the method MATLAB uses to render graphics objects displayed in the Axes, when the Figure Renderer property is painters.

• normal mode draws objects in back to front ordering based on the current view in order to handle hidden surface elimination and object intersections.
• fast mode 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 may produce undesirable results because it bypasses the hidden surface elimination and object intersection handling provided by normal DrawMode.

Select italic or normal font. This property selects the character slant for Axes text. normal specifies a nonitalic font. italic and oblique specify italic font.

Font family name. The font family name specifying the font to use for Axes labels. To display and print properly, FontName must be a font that your system supports. Note that the x-, y-, and z-axis labels do not display 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.

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. The x-, y-, and z-axis text labels do not display 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.

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.

Select bold or normal font. The character weight for Axes text. The x-, y-, and z-axis text labels do not display 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.

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.

Control access to object's handle by command-line users and GUIs. This property 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).

Selectable by mouse click. HitTest 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 on the Axes. If HiTest is off, clicking on the axes selects the object below it (which is usually the Figure containing it).

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

Draw axis lines below or above graphics objects. This property determines if axis lines and tick marks draw on top or below Axes children objects for any 2-D view (i.e., when you are looking along the x-, y-, or z-axis). This is useful for placing grid lines and tick marks on top of images.

Order of line styles and markers used in a plot. This property specifies which line styles and markers to use and in what order when creating multiple-line plots. For example,

set(gca,'LineStyleOrder', '-*|:|o')

set(gca,'LineStyleOrder',{'-*',':','o'})

Width of axis lines. This property 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).

Where to draw the next plot. This property 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).

Axes parent. The handle of the Axes' parent object. The parent of an Axes object is the Figure in which it is displayed. The utility function gcf returns the handle of the current Axes' Parent. You can reparent Axes to other Figure objects.

Relative scaling of Axes plotbox. A three-element vector controlling 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.

User or MATLAB controlled axis scaling. This property 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 of Axes. A four-element vector specifying a rectangle that locates the Axes within the Figure window. The vector is of the form:

[left bottom width height]

Type of projection. This property selects between two projection types:

• orthographic - This projection maintains the correct relative dimensions of graphics objects with regard to the distance a given point is from the viewer. Parallel lines in the data are drawn parallel on the screen.
• perspective - This projection 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; a distant line segment displays smaller than a nearer line segment of the same length. Parallel lines in the data may not appear parallel on screen.

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 routine to set this property to on, thereby indicating that the axes has been selected.

Objects highlight 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.

User-specified object label. The Tag property provides a means to identify graphics objects with a user-specified label. This is particularly useful when constructing interactive graphics programs that would otherwise need to define object handles as global variables or pass them as arguments between callback routines.

axes('Tag','Special Axes')

axes(findobj('Tag','Special Axes'))

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.

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.

Length of tick marks. A two-element vector specifying 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.

Axes title. The handle of the Text object that is used for the Axes title. You can 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')

set(gca,'Title',text('String','New Title','Color','r'))

title('New Title','Color','r')

Type of graphics object. This property contains a string that identifies the class of graphics object. For Axes objects, Type is always set to 'axes'.

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 (Control-click on Macintosh systems).

Position units. The units used to interpret the Position property. All units are measured from the lower-left corner of the Figure window.

• 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 are absolute units (one point equals 1/72 of an inch).
• Character units are defined by characters from the default system font; the width of one character is the width of the letter x, the height of one character is the distance between the baselines of two lines of text.

User specified data. This property can be any data you want to associate with the Axes object. The Axes does not use this property, but you can access it using the set and get functions.

The functionality provided by the View property is now controlled by the Axes camera properties - CameraPosition, CameraTarget, CameraUpVector, and CameraViewAngle. See the view command.

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.

Location of x-axis tick marks and labels. This property 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.

Location of y-axis tick marks and labels. This property 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. See the plotyy function for a simple way to use two y-axes.

Properties That Control the X-, Y-, or Z-Axis

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 white. See ColorSpec for details on specifying colors.

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.
• 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.
• 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.

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

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(gca,'Xlabel',text('String','axis label'))

Axis limits. A two-element vector specifying the minimum and maximum values of the respective axis.

MATLAB or user-controlled limits. The axis limits mode determines whether MATLAB calculates axis limits based on the data plotted (i.e., 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.

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

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.

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.

set(gca,'XTickLabel',{'One';'Two';'Three';'Four'})

set(gca,'XTickLabel',{'1';'10';'100'})
set(gca,'XTickLabel','1|10|100')
set(gca,'XTickLabel',[1;10;100])
set(gca,'XTickLabel',['1  ';'10 ';'100'])

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.

MATLAB or user determined tick labels. The axis tick mark labeling mode determines 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.