Documentation

pbaspect

Control relative lengths of each axis

Syntax

  • pbaspect auto
  • pbaspect manual

Description

example

pbaspect(ratio) sets the plot box aspect ratio for the current axes. The plot box aspect ratio is the relative length of the x-axis, y-axis, and z-axis. Specify ratio as a three-element vector of positive values that represent the ratio of the x-axis, y-axis, and z-axis lengths. For example, [3 1 1] specifies that the length of the x-axis is equal to three times the length of the y-axis and z-axis. For equal axis lengths in all directions, use [1 1 1].

pbaspect auto lets the axes choose the appropriate plot box aspect ratio and sets the associated mode to automatic. The mode must be automatic to enable the stretch-to-fill feature of the axes.

pbaspect manual uses the ratio stored in the PlotBoxAspectRatio property of the axes object and sets the associated mode to manual. When the mode is manual, it disables the stretch-to-fill feature of the axes. Specifying a value for the plot box aspect ratio sets the mode to manual.

example

pb = pbaspect returns the plot box aspect ratio for the current axes.

example

m = pbaspect('mode') returns the current mode, which is either 'auto' or 'manual'. By default, the mode is automatic unless you specify the plot box aspect ratio or set the mode to manual.

example

pbaspect(ax,___) uses the axes specified by ax instead of the current axes. Specify an axes object with any of the input argument combinations in the previous syntaxes. Use single quotes around input arguments that are character strings, for example pbaspect(ax,'auto') and pbaspect(ax,'manual').

Examples

collapse all

Use Equal Axis Lengths

Create a simple line plot. Make the x-axis, y-axis, and z-axis (not shown) equal lengths.

x = linspace(0,10);
y = sin(x);
plot(x,y)
pbaspect([1 1 1])

Use Different Axis Lengths

Plot a surface and make the x-axis twice as long as the y-axis and z-axis.

[x,y] = meshgrid(-2:.2:2);
z = x.*exp(-x.^2 - y.^2);
surf(x,y,z)
pbaspect([2 1 1])

When you specify the plot box aspect ratio, the associated mode changes to manual. Query the current plot box aspect ratio mode.

m = pbaspect('mode')
m =

manual

Query Plot Box Aspect Ratio

Create a surface plot.

[x,y] = meshgrid(-2:.2:2);
z = x.*exp(-x.^2 - y.^2);
surf(x,y,z)

Query the plot box aspect ratio. The values indicate the ratio of the x-axis length to y-axis length to z-axis length.

pb = pbaspect
pb =

    1.0000    0.9419    0.8518

Set Plot Box Aspect Ratio for Specific Axes

Create a figure with two subplots and return the axes objects from the subplot function. Set the plot box aspect ratio for lower subplot by specifying ax2 as the first input argument to the pbaspect function.

ax1 = subplot(2,1,1);
surf(peaks)

ax2 = subplot(2,1,2);
plot(peaks)
pbaspect(ax2,[2 1 1])

Input Arguments

collapse all

ratio — Plot box aspect ratiothree-element vector

Plot box aspect ratio, specified as a three-element vector of positive values. For example, pbaspect([3 2 1]) specifies that the ratio of the x-axis length to y-axis length to z-axis length is 3 to 2 to 1. Thus, the x-axis is the longest and the z-axis is the shortest.

Specifying the ratio sets the PlotBoxAspectRatio property for the axes object to the specified value. The PlotBoxAspectRatio property interacts with the DataAspectAspectRatio, XLim, YLim, and ZLim properties to control the length and scale of the x-axis, y-axis, and z-axis.

Specifying the ratio sets the PlotBoxAspectRatioMode property to 'manual' and disables the Stretch-to-fill behavior of the axes.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

ax — Axes objectaxes object

Axes object. If you do not specify an axes object, then pbaspect uses the current axes (gca).

Output Arguments

collapse all

pb — Current plot box aspect ratio valuesthree-element vector

Current plot box aspect ratio, returned as a three-element vector of values representing the ratio of the x-axis, y-axis, and z-axis lengths.

Querying the plot box aspect ratio values returns the PlotBoxAspectRatio property value for the axes object.

m — Current plot box aspect ratio mode'auto' | 'manual'

Current plot box aspect ratio mode, returned as either 'auto' or 'manual'. When the mode is automatic, the axes determines the appropriate plot box aspect ratio value. If you specify a value, then the mode changes to manual.

Querying the plot box aspect ratio mode returns the PlotBoxAspectRatioMode property value for the axes object.

More About

expand all

Stretch-to-fill

When the stretch-to-fill feature is enabled, MATLAB® stretches the axes to fill the available space. Some distortion can occur. Thus, the axes might not exactly match the data aspect ratio, plot box aspect ratio, and camera-view angle values stored in its DataAspectRatio, PlotBoxAspectRatio, and CameraViewAngle properties. When stretch-to-fill is disabled, MATLAB makes the axes as large as possible within the available space and strictly adheres to the property values so that there is no distortion. The last two elements of the Position property of the axes object determine the available space.

The stretch-to-fill feature is enabled when the DataAspectRatioMode, PlotBoxAspectRatioMode, and CameraViewAngleMode properties of the axes object are all set to 'auto'. If one or more modes are manual, the feature is disabled. Thus, if you specify the data aspect ratio, plot box aspect ratio, or camera-view angle, then the stretch-to-fill feature is disabled.

For example, this figure shows the same plot with and without the stretch-to-fill feature enabled. The dotted line shows the available space as defined by the Position property. In both versions, the data aspect ratio, plot box aspect ratio, and camera-view angle values are the same. However, in the left plot, the stretching introduces some distortion.

Stretch-to-fill enabled (some distortion)Stretch-to-fill disabled (no distortion)

See Also

| | | |

Introduced before R2006a

Was this topic helpful?