# axes

## Purpose

Place axes at specified position by creating axes graphics object.

## Synopsis

    h = axes
    axes(h)
    h = axes('PropertyName',PropertyValue,...)

## Description

`axes` is a low-level function for creating axes objects. Axes objects are children of figure objects and parents of image, line, patch, surface, and text objects. Axes objects define a frame of reference that orients their children objects within the figure.

`h = axes` creates the default full-window axes and returns its handle.

`axes(h)` makes the axes with handle `h` the current axes.

`h = axes('PropertyName',PropertyValue,...)` is an object creation function that accepts property name/property value pairs as input arguments. These properties, which control various aspects of axes objects, are described under "Object Properties." You can also set and query property values after creation using the `set` and `get` functions.

Specify default axes properties at the axes' parent level, that is, at the figure object. To do so, call the `set` function, supplying as arguments the handle of the parent figure, a default name string, and the desired default value. Construct the default name string by prepending the string `'DefaultAxes'` to the desired axes property name. For example

    set(fig_handle,'DefaultAxesColor','red')

sets the default axes rectangle color to red for all axes created in the figure with handle `fig_handle`.

The `axis` (not `axes`) function provides simplified access to commonly used properties that control the scaling and appearance of axes.

Use `gca` (get current axes) to obtain the handle of the current axes.

## Object Properties

This section lists property names along with the type of values each accepts.

`AspectRatio`
  Aspect ratio for two-dimensional axes.

  A two-element vector, `[axis_ratio data_ratio]`, where
  - `axis_ratio` is the ratio of the length of the horizontal axis to the length of the vertical axis (width divided by height). MATLAB creates the largest axes with this ratio that fits into the rectangle defined by `Position`.
  - `data_ratio` is the ratio of the length of a data unit along the horizontal axis to the length of a data unit along the vertical axis. To create axes with this `data_ratio`, MATLAB changes the limits of one axis while maintaining the ratio specified in `axis_ratio`. This change does not affect the corresponding limits property (`XLim` or `YLim`).
  Specify the ratios as any number in the range [`0,Inf`]. The default for both is `NaN`, which specifies no ratio. By default, MATLAB changes either ratio in order create an axes that best fills the figure window.

`Box`
  Axes box mode.

  `on` Enclose graphics area in box (2-D) or cube (3-D).
  `off` (Default.) Do not display enclosing box.

`ButtonDownFcn`
  Callback string, object selection.

  Any legal MATLAB expression, including the name of an M-file or function. When you select the object, the string is passed to the `eval` function to execute the specified function. Initially the empty matrix.

`Children`
  Children of axes.

  A read-only vector containing the handles of all objects displayed within the axes. The children objects of axes can be images, lines, patches, surfaces, and text.

`CLim`
  Color limits.

  A two-element vector `[cmin cmax]` that determines how MATLAB maps data values to the colormap. `cmin` is the data value to map to the first colormap entry, and `cmax` is the data value to map to the last colormap entry. By default `Clim` is [0 1], mapping the full range of the colormap to the full range of the data.
  Data values less than `cmin` are mapped to `cmin` and data values greater than `cmax` are mapped to `cmax`. `NaN`s are clipped by making them transparent. `CLim` values outside the range of the data cause MATLAB to use a limited portion of the colormap.
  `CLim` affects the rendering of surface and patch objects, but not images, lines, or text.

`CLimMode`
  Color limits mode.

  `auto` (Default.) MATLAB calculates color limits that span the full range of the data of the axes' children.
  `manual` Color limits do not automatically change (see the `CLim` property). Setting values for `CLim` sets this property to `manual`.

`Clipping`
  Data clipping.

  `on` (Default.) No effect for axes objects.
  `off` No effect for axes objects.

`Color`
  Color of the axes rectangle.

  `ColorSpec` A three-element RGB vector or one of MATLAB's predefined names. See the ``ColorSpec reference page for more information on specifying color.
  `none` (Default.) The same as the figure background color.

`ColorOrder`
  Axes color order.

  An `m`-by-3 matrix of RGB values. 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. By default, `ColorOrder` contains the first six colors in MATLAB's predefined color palette:
  1. yellow
  2. magenta
  3. cyan
  4. red
  5. green
  6. blue

`CurrentPoint`
  3-D coordinates for a pair of points in the axes' data space.

  A 2-by-3 matrix that specifies the end points of a line, in 3-D coordinates, that extends from the front to the back of the axes volume. The format of the matrix is

    [xback  yback  zback;  xfront  yfront  zfront]

  These coordinates are always relative to the axes volume, even if the pointer is outside the axes. All measurements are in units specified by the `Units` property.
  See the MATLAB Release Notes for more details on the `CurrentPoint` property.

`DrawMode`
  Draw mode.

  `normal` (Default.) Draw objects from back to front based on the current view.
  `fast` Draws objects in the order in which you originally specified them. This disables the three-dimensional sorting usually performed by MATLAB, resulting in faster rendering.

`FontAngle`
  Italics for axes text.

  `normal` (Default.) Regular font angle.
  `italic` Italics.
  `oblique` Italics on some systems.
  See the MATLAB Release Notes for more details on the `FontAngle` property.

`FontName`
  Font family.

  A string specifying the name of the font to use for axes tick labels. To display and print properly, this must be a font that your system supports. Axes labels do not display in a new font until you manually redisplay them (by setting the `XLabel`, `YLabel`, and `ZLabel` properties). The default font is Helvetica.

`FontSize`
  Font point size.

  An integer specifying the font size, in points, to use for axes labels and titles. The default point size is 12.

`FontWeight`
  Bolding for axes text.

  `normal` (Default.) Regular font weight.
  `bold` Bold weight.

`GridLineStyle`
  Grid line style.

  A string specifying the line type for grid lines. The string consists of a single character, in quotes, specifying solid lines (`-`), dashed lines (`-` `-`), dotted lines(`:`), or dash-dot lines (`-`.). The default grid line style is dotted.

`Interruptible`
  Callback interruptibility.

  `yes` The callback specified by `ButtonDownFcn` is interruptible by other callbacks.
  `no` (Default.) The `ButtonDownFcn` callback is not interruptible.
  See the MATLAB Release Notes for more details on the `Interruptible` property.

`LineStyleOrder`
  Axes line style order.

  A string specifying line styles in the order used to plot multiple lines in the axes. Specify up to four line styles in the format

    'linestyle1|linestyle2...'

  where each `linestyle` is a character string specifying solid lines (`-`), dashed lines (`-` `-`), dotted lines(`:`), or dash-dot lines(`-.`). The default line style order is solid lines only. Some plotting functions, such as `plot`, overrule this property with their own default line style order.

`LineWidth`
  Width of x-, y-, and z-axis lines.

  The width, in points, of the lines that represent each axis. The default line width is 0.5 points.

`NextPlot`
  Axes handling for subsequent plots.

  `new` Create a new axes before drawing.
  `add` Add new objects to the current axes. Setting `hold` to `on` sets `NextPlot` to `add`.
  `replace` (Default.) Destroy the current axes (and its contents) and create a new axes at the same position before drawing. Setting `hold` to `off` sets `NextPlot` to `replace`.
  This property is used by the built-in high-level graphing functions `plot`, `plot3`, `fill`, `fill3`, and the M-file graphing functions `mesh`, `surf`, `bar`, and so on. The M-file `newplot` is a preamble for handling the `NextPlot` property. M-file graphing functions like `mesh`, `surf`, and `bar` call `newplot` to control this property before drawing their respective graphs. When creating M-files that implement graphing commands, use `newplot` at the beginning of the file. See the M-file `pcolor` for an example. Also see the `NextPlot` property of figure objects.

`Parent`
  Handle of the axes' parent object.

  A read-only property that contains 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` also returns the handle of the current axes' parent figure.

`Position`
  Size and position of axes.

  A four-element vector, `[left bottom width height]`, where `left` and `bottom` are the distance from the lower-left corner of the figure window to the lower-left corner of the axes. `width` and `height` are the dimensions of the axes rectangle. All measurements are in units specified by the `Units` property.

`TickDir`
  Tick mark direction

  `in` Tick marks are directed inward from the axis lines (default for 2-D plotting).
  `out` Tick marks are directed outward from the axis lines (default for three-dimensional plotting functions unless `hold` is `on`).

`TickLength`
  Tick mark length.

  A two-element vector `[2Dlength 3Dlength]` that specifies the length of the axes' tick marks, where
  - `2Dlength` is the length of tick marks used for two-dimensional views.
  - `3Dlength` is the length of tick marks used for three-dimensional views.
  Each element is in units normalized relative to the dimensions of the rectangle defined by the axes. Specifying a tick length of 0.1 draws a tick mark that is 1/10 of the width or height of the rectangle. The default vector is [0.01 0.025].

`Title`
  Axes title.

  The handle of the text object that defines the axes title. First create the text object in order to obtain its handle. The following statement performs both steps:

    set(gca,'title',text(0,0,'axes title'))

  While the `text` function requires location data, it is not used to place the text. Instead, MATLAB centers the string `'axes title'` above the axes.
  You can also define a text object at an arbitrary location and pass its handle directly. In this case MATLAB moves the text string to the correct location for an axes title. The `title` function provides a simpler means to create a title by encapsulating this procedure.

`Type`
  Type of graphics object.

  A read-only string; always `'axes'` for an axes object.

`Units`
  Unit of measurement.

  `pixels` Screen pixels.
  `normalized` (Default.) Normalized coordinates. The lower-left corner of the figure window maps to (0,0) and the upper-right corner to (1.0,1.0).
  `inches` Inches.
  `cent` Centimeters.
  `points` Points. Each point is equivalent to 1/72 of an inch.
  If you change the value of `Units`, return it to its default value after completing your computation so as not to affect other functions that assume `Units` is set to the default value.

`UserData`
  User-specified data.

  Any matrix you want to associate with the axes object. The object does not use this data, but you can retrieve it using the `get` command`.`

`View`
  Viewpoint of axes.

  A two-element vector, `[az,el]`, that establishes a viewpoint used to transform three-dimensional plots into the two-dimensional space of the screen. The viewpoint is the location of the eye of an observer looking at the three-dimensional plot, where
  - `az` is the azimuth. The azimuth revolves around the z-axis, with positive values causing the viewpoint to rotate in a counter-clockwise direction.
  - `el` is the elevation. The elevation specifies an angle above or below the object. Positive values of elevation cause the viewpoint to move above the object (that is, to look down on it); negative values cause the viewpoint to move below the object.
  Specify each element in degrees. Changing the `View` property alters the `XForm` property's transformation matrix. The default `View` vector is [0 90].

`Visible`
  Axes visibility.

  `on` (Default.) Axes lines, tick marks, and labels are visible on the screen.
  `off` Axes lines, tick marks, and labels are not drawn.
  The children of the axes are not affected by the axes' `Visible` property.

`XForm`
  View transformation matrix.

  A 4-by-4 matrix that defines the transformation from three-dimensional plots to the two-dimensional screen. Specify the transformation matrix directly with this property, or indirectly by specifying the azimuth and elevation of the viewpoint using the `View` property.
  Changing the `View` property changes `XForm` as well. `XForm`, however, can define views that you cannot define using only azimuth and elevation (such as perspective views). It is also possible to specify scaling and translations in the same matrix. Such transforms are discussed in most books on computer graphics. The default `XForm` matrix is the 4-by-4 identity matrix.

#### Properties That Control the X-Axis

`XColor`
  Color of x-axis.

  A three-element vector specifying an RGB triple, or a predefined MATLAB color string. This property determines the display color for the x-axis, tick marks, tick mark labels, and the x-axis grid lines.The default axis color is white. See the `ColorSpec` reference page for details on specifying colors.

`XDir`
  Direction of increasing x values.

  `normal` (Default.) X values increase from left to right (right-handed coordinate system).
  `reverse` X values increase from right to left.

`XGrid`
  X-axis gridline mode.

  `on` MATLAB draws grid lines perpendicular to the x-axis at each tick mark (i.e., along lines of constant x values).
  `off` (Default.) Grid lines are not drawn.

`XLabel`
  X-axis label.

  The handle of the text object used to label the x-axis. First create the text object in order to obtain its handle. The following statement performs both steps:

    set(gca,'xlabel',text(0,0,'axis label'))

  While the `text` function requires location data, it is not used to place the text. Instead, MATLAB places the string `'axis label'` appropriately for an x-axis label.
  You can also define a text object at an arbitrary location and pass its handle directly. In this case MATLAB moves the text string to the correct location for an axis label. The `xlabel` function provides a simpler means to label the x-axis by encapsulating this procedure.

`XLim`
  X-axis limits.

  A two-element vector `[xmin xmax]` that specifies the minimum and maximum x-axis values, where
  - `xmin` is the minimum x-axis value.
  - `xmax` is the maximum x-axis value.
  Changing `XLim` affects the scale of the x-dimension as well as the placement of labels and tick marks on the x-axis. The default for `XLim` is [0 1].

`XLimMode`
  X-axis limits mode.

  `auto` (Default.) MATLAB calculates x-axis limits (`XLim`) that span the `XData` of the axes' children and produce round numbers for the x-axis limits.
  `manual` MATLAB takes x-axis limits from `XLim`; the limits do not depend on the `XData` in the children objects. Setting values for `XLim` sets this property to `manual`.

`XScale`
  X-axis scaling.

  `linear` (Default.) Linear scaling for the x-axis.
  `log` Logarithmic scaling for the x-axis.

`XTick`
  X-axis tick mark spacing.

  A vector of values that correspond to the x-data values at which you want to place tick marks. If you do not want tick marks displayed, set `XTic`k to the empty vector, `[]`.

`XTickLabelMode`
  X-axis tick mark labeling mode.

  `auto` (Default.) MATLAB calculates x-axis tick labels (`XTickLabels`) that span the `XData` of the axes' children.
  `manual` MATLAB takes x-axis tick labels from `XTickLabels`; it does not depend on the `XData` in the children objects. Setting values for `XTickLabels` sets this property to `manual`.

`XTickLabels`
  X-axis tick mark labels.

  A matrix of strings to use as labels for tick marks along the x-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, and then labels the remaining tick marks by reusing the specified labels. The command

    set(gca,'XTickLabels',['Old Data';'New Data'])

  labels the first two tick marks on the x-axis `'Old Data'` and `'New Data'` respectively. Each character string must have an equal number of characters because of the way MATLAB stores strings.
  This property does not control the number of tick marks or their locations.

`XTickMode`
  X-axis tick mark mode.

  `auto` (Default.) MATLAB calculates x-axis tick mark spacing (`XTick`) that spans the `XData` of the axes' children.
  `manual` MATLAB takes x-axis tick spacing from `XTick`; it does not depend on the `XData` in the children objects. Setting values for `XTick` sets this property to `manual`.

#### Properties That Control the Y-Axis

`YColor`
  Color of y-axis.

  A three-element vector specifying an RGB triple, or a predefined MATLAB color string. This property determines the display color for the y-axis, tick marks, tick mark labels, and the y-axis grid lines. The default axis color is white. See the `ColorSpec` reference page for details on specifying colors.

`YDir`
  Direction of increasing y values.

  `normal` (Default.) Y values increase from bottom to top (right-handed coordinate system).
  `reverse` Y values increase from top to bottom.

`YGrid`
  Y-axis gridline mode.

  `on` MATLAB draws grid lines perpendicular to the y-axis at each tick mark (i.e., along lines of constant y values).
  `off` (Default.) Grid lines are not drawn.

`YLabel`
  Y-axis label.

  The handle of the text object used to label the y-axis. First create the text object in order to obtain its handle. The following statement performs both steps:

    set(gca,'ylabel',text(0,0,'axis label'))

  While the `text` function requires location data, it is not used to place the text. Instead, MATLAB places the string `'axis label'` appropriately for a y-axis label.
  You can also define a text object at an arbitrary location and pass its handle directly. In this case MATLAB moves the text string to the correct location for an axis label. The `ylabel` function provides a simpler means to label the y-axis by encapsulating this procedure.

`YLim`
  Y-axis limits.

  A two-element vector `[ymin ymax]` that specifies the minimum and maximum y-axis values, where
  - `ymin` is the minimum y-axis value.
  - `ymax` is the maximum y-axis value.
  Changing `YLim` affects the scale of the y-dimension as well as the placement of labels and tick marks on the y-axis. The default for `YLim` is [0 1].

`YLimMode`
  Y-axis limits mode.

  `auto` (Default.) MATLAB calculates y-axis limits (`YLim`) that span the `YData` of the axes' children and produce round numbers for the y-axis limits.
  `manual` MATLAB takes y-axis limits from `YLim`; the limits do not depend on the `YData` in the children objects. Setting values for `YLim` sets this property to `manual`.

`YScale`
  Y-axis scaling.

  `linear` (Default.) Linear scaling for the y-axis.
  `log` Logarithmic scaling for the y-axis.

`YTick`
  Y-axis tick mark spacing.

  A vector of values that correspond to the y-data values at which you want to place tick marks. If you do not want tick marks displayed, set `YTic`k to the empty vector, `[]`.

`YTickLabelMode`
  Y-axis tick mark labeling mode.

  `auto` (Default.) MATLAB calculates y-axis tick labels (`YTickLabels`) that span the `YData` of the axes' children.
  `manual` MATLAB takes y-axis tick labels from `YTickLabels`; it does not depend on the `YData` in the children objects. Setting values for `YTickLabels` sets this property to `manual`.

`YTickLabels`
  Y-axis tick mark labels.

  A matrix of strings to use as labels for tick marks along the y-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, and then labels the remaining tick marks by reusing the specified labels. The command

    set(gca,'YTickLabels',['Old Data';'New Data'])

  labels the first two tick marks on the y-axis `'Old Data'` and `'New Data'` respectively. Each character string must have an equal number of characters because of the way MATLAB stores strings.
  This property does not control the number of tick marks or their locations.

`YTickMode`
  Y-axis tick mark mode.

  `auto` (Default.) MATLAB calculates y-axis tick mark spacing (`YTick`) that spans the `YData` of the axes' children.
  `manual` MATLAB takes y-axis tick spacing from `YTick`; it does not depend on the `YData` in the children objects. Setting values for `YTick` sets this property to `manual`.

#### Properties That Control the Z-Axis

`ZColor`
  Color of z-axis.

  A three-element vector specifying an RGB triple, or a predefined MATLAB color string. This property determines the display color for the z-axis, tick marks, tick mark labels, and the z-axis grid lines. The default axis color is white. See the `ColorSpec` reference page for details on specifying colors.

`ZDir`
  Direction of increasing z values.

  `normal` (Default.) Z values increase pointing out of the screen (two-dimensional) or from bottom to top (three-dimensional), corresponding to a right-handed coordinate system.
  `reverse` Z values increase pointing into the screen (two-dimensional) or from top to bottom (three-dimensional).

`ZGrid`
  Z-axis gridline mode.

  `on` MATLAB draws grid lines perpendicular to the z-axis at each tick mark (i.e., along lines of constant z values).
  `off` (Default.) Grid lines are not drawn.

`ZLabel`
  Z-axis label.

  The handle of the text object used to label the z-axis. First create the text object in order to obtain its handle. The following statement performs both steps:

    set(gca,'zlabel',text(0,0,'axis label'))

  While the `text` function requires location data, it is not used to place the text. Instead, MATLAB places the string `'axis label'` appropriately for a z-axis label.
  You can also define a text object at an arbitrary location and pass its handle directly. In this case MATLAB moves the text string to the correct location for an axis label. The `zlabel` function provides a simpler means to label the z-axis by encapsulating this procedure.

`ZLim`
  Z-axis limits.

  A two-element vector `[zmin zmax]` that specifies the minimum and maximum z-axis values, where
  - `zmin` is the minimum z-axis value.
  - `zmax` is the maximum z-axis value.
  Changing `ZLim` affects the scale of the z-dimension as well as the placement of labels and tick marks on the z-axis. The default for `ZLim` is [0 1].

`ZLimMode`
  Z-axis limits mode.

  `auto` (Default.) MATLAB calculates z-axis limits (`ZLim`) that span the `ZData` of the axes' children and produce round numbers for the z-axis limits.
  `manual` MATLAB takes z-axis limits from `ZLim`; the limits do not depend on the `ZData` in the children objects. Setting values for `ZLim` sets this property to `manual`.

`ZScale`
  Z-axis scaling.

  `linear` (Default.) Linear scaling for the z-axis.
  `log` Logarithmic scaling for the z-axis.

`ZTick`
  Z-axis tick mark spacing.

  A vector of values that correspond to the z-data values at which you want to place tick marks. If you do not want tick marks displayed, set `ZTic`k to the empty vector, `[]`.

`ZTickLabelMode`
  Z-axis tick mark labeling mode.

  `auto` (Default.) MATLAB calculates z-axis tick labels (`ZTickLabels`) that span the `ZData` of the axes' children.
  `manual` MATLAB takes z-axis tick labels from `ZTickLabels`; it does not depend on the `ZData` in the children objects. Setting values for `ZTickLabels` sets this property to `manual`.

`ZTickLabels`
  Z-axis tick mark labels.

  A matrix of strings to use as labels for tick marks along the z-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, and then labels the remaining tick marks by reusing the specified labels. The command

    set(gca,'ZTickLabels',['Old Data';'New Data'])

  labels the first two tick marks on the z-axis `'Old Data'` and `'New Data'` respectively. Each character string must have an equal number of characters because of the way MATLAB stores strings.
  This property does not control the number of tick marks or their locations.

`ZTickMode`
  Z-axis tick mark mode.

  `auto` (Default.) MATLAB calculates z-axis tick mark spacing (`ZTick`) that spans the `ZData` of the axes' children.
  `manual` MATLAB takes z-axis tick spacing from `ZTick`; it does not depend on the `ZData` in the children objects. Setting values for `ZTick` sets this property to `manual`.

## Examples

An important axes property is `Position`. It allows you to define the location of the axes within the figure window. For example,

     h = axes('Position',rect)

creates an axes object at the specified position within the current figure window and returns a handle to it. You specify the location and size of the axes with a rectangle defined by a four element vector,

    rect = [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:

    clf
    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, subplot

(c) Copyright 1994 by The MathWorks, Inc.