rotate3d

Enable rotate mode

Description

You can use rotate mode to explore data by interactively rotating the 3-D view of the axes. Enable or disable rotate mode, and set other basic options, by using the rotate3d function. To further control rotate mode behavior, return and use a rotate3d object.

Most 3-D charts support rotate mode, including 3-D bubble charts, 3-D scatter plots, and surface plots. Charts that support rotate mode typically display the rotate icon in the axes toolbar.

You can also interactively explore data using built-in axes interactions that are enabled by default. For example, you can rotate the view of a 3-D axes by dragging the axes. Built-in interactions do not require you to enable an interaction mode and respond faster than interaction modes. However, you can enable rotate mode to customize the rotation behavior. For more information about built-in interactions, see Control Chart Interactivity.

Creation

Syntax

rotate3d option

rotate3d

rotate3d(fig,option)

rotate3d(ax,option)

r = rotate3d

r = rotate3d(fig)

Description

rotate3d option sets the rotate mode for all axes in the current figure. For example, rotate3d on enables rotate mode and rotate3d off disables rotate mode.

When rotate mode is enabled, rotate the view of the axes using the cursor or the keyboard.

• Cursor — Click and drag the cursor in the axes.

• Keyboard — To increase or decrease the azimuth, press the right arrow (→) or left arrow (←) key. To increase or decrease the elevation, press the up arrow (↑) or down arrow (↓) key.

Some built-in interactions remain enabled by default, regardless of the current interaction mode. To disable built-in rotation interactions that are independent of the rotate mode, use the disableDefaultInteractivity function.

rotate3d toggles the rotate mode. For example, if rotate mode is disabled, then calling rotate3d enables rotate mode.

rotate3d(fig,option) sets the rotate mode for all axes in the specified figure. For example, to enable rotate mode for all axes in the figure fig, use rotate3d(fig,'on').

rotate3d(ax,option) sets the rotate mode for the specified axes. For example, to enable rotate mode for the axes ax, use rotate3d(ax,'on'). Use this syntax with apps created in App Designer and using the uifigure function. (since R2023a)

r = rotate3d creates a rotate3d object for the current figure. This syntax is useful for customizing the rotation mode and style.

r = rotate3d(fig) creates a rotate3d object for the specified figure.

Input Arguments

option — Rotate mode option

'on' | 'off'

Rotate mode option, specified as one of these values:

• 'on' — Enable rotate mode.

• 'off' — Disable rotate mode. Some built-in interactions remain enabled by default, regardless of the current interaction mode. To disable built-in rotation interactions that are independent of the rotate mode, use the disableDefaultInteractivity function.

fig — Target figure

Figure object

Target figure, specified as a Figure object. Specifying a target figure sets the mode for all current or future Axes children.

ax — Target axes

Axes object

Target axes, specified as an Axes object.

Properties

Enable — Rotate mode state

'off' (default) | 'on' | on/off logical value

Rotate mode state, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type OnOffSwitchState.

RotateStyle — Method of rotation

'orbit' (default) | 'box'

Method of rotation, specified as one of these values:

• 'orbit' — Rotate the entire axes.

• 'box' — Rotate a plot-box outline of the axes. 'box' is not supported for figures created using the uifigure function or in MATLAB^® Online™.

Note

In a future release, this property will have no effect. For more information, see Version History.

ActionPreCallback — Function to execute before rotating

[ ] (default) | function handle | cell array | character vector

Function to execute before rotating, specified as one of these values:

• Function handle

• Cell array containing a function handle and additional arguments

• Character vector containing a valid MATLAB command or function, which is evaluated in the base workspace (not recommended)

Use this property to execute code as you start rotating. If you specify this property using a function handle, then MATLAB passes two arguments to the callback function:

• figure — Figure object which you are rotating.

• axesStruct — Structure that contains one field, Axes, the axes object that you are rotating. If you do not use this argument in your callback function, then replace it with the tilde character (~).

For more information about callbacks, see Create Callbacks for Graphics Objects.

ActionPostCallback — Function to execute after rotating

[ ] (default) | function handle | cell array | character vector

Function to execute after rotating, specified as one of these values:

• Function handle

• Cell array containing a function handle and additional arguments

• Character vector containing a valid MATLAB command or function, which is evaluated in the base workspace (not recommended)

Use this property to execute code after you finish rotating. If you specify this property using a function handle, then MATLAB passes two arguments to the callback function:

• figure — Figure object in which you are rotating.

• axesStruct — Structure that contains one field, Axes, the axes object that you are rotating. If you do not use this argument in your callback function, then replace it with the tilde character (~).

For more information about callbacks, see Create Callbacks for Graphics Objects.

ButtonDownFilter — Rotation suppression callback

[ ] (default) | function handle | cell array | character vector

Rotation suppression callback, specified as one of these values:

• Function handle

• Cell array containing a function handle and additional arguments

• Character vector containing a valid MATLAB command or function, which is evaluated in the base workspace (not recommended)

Use this property to suppress rotation under conditions that you define. A numeric or logical output of 1 (true) suppresses rotation, and a numeric or logical output of 0 (false) allows rotation. If you specify this property using a function handle, then MATLAB passes two arguments to the callback function:

• axes — The axes object that you are rotating.

• eventData — Empty argument. Replace it with the tilde character (~) in the function definition to indicate that this argument is not used.

If you specify this property using a function handle, then you must assign the function output to a variable.

For more information about callbacks, see Create Callbacks for Graphics Objects.

FigureHandle — Figure object

Figure object

This property is read-only.

Figure object that you specified when creating the rotate3d object. If you did not specify a figure, then FigureHandle is the figure that was current when you created the rotate3d object.

UseLegacyExplorationModes — Legacy mode

'off' (default) | 'on' | on/off logical value

Legacy mode, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type OnOffSwitchState.

This property applies only to rotate3d objects for figures created using the uifigure function or in MATLAB Online. Setting this property to 'on' changes the behavior of interaction modes in UI figures so they match the behavior of modes in traditional figures. For more information, see enableLegacyExplorationModes.

Once this property is set to 'on', it cannot be changed back to 'off'.

Object Functions

Use the rotate3d object functions to customize the rotation behavior of axes objects within a figure. For all of these functions, the axes and rotate mode objects must be associated with the same figure.

setAllowAxesRotate

The setAllowAxesRotate function sets permission to rotate axes. Calling setAllowAxesRotate(r,axes,tf) on the rotate3d object r, with a vector of axes objects axes and a logical scalar tf as inputs, allows or disallows a rotate operation on the axes objects. Enabling rotate mode for axes using setAllowAxesRotate does not enable rotate mode for the figure. To do this, set the Enable property of the rotate3d object.

isAllowAxesRotate

The isAllowAxesRotate function queries permission to rotate axes. Calling tf = isAllowAxesRotate(r,axes) on the rotate3d object r, with a vector of axes objects axes as an input, returns a logical array tf with the same size as axes. tf indicates whether a rotate operation is permitted on the axes objects. Returning the rotate mode of axes using isAllowAxesRotate does not return the rotate mode for the figure. To do this, access the Enable property of the rotate3d object.

Examples

Enable Rotate Mode

Create a 3-D plot and enable rotate mode. Then, interactively rotate the axes.

surf(peaks)
rotate3d on

Specify Axes for Rotation

Create two axes in a tiled chart layout, and enable rotate mode for only the first axes.

tiledlayout(1,2);
ax1 = nexttile;
surf(peaks)

ax2 = nexttile;
contour(peaks);

rotate3d(ax1,'on')

Create Button Down Callback

Create a button down callback for rotate mode objects to trigger. Copy the following code to a new file, execute it, and observe the rotation behavior.

function demo_mbd
    % Allow a line to have its own 'ButtonDownFcn' callback
    hLine = plot(rand(1,10),'ButtonDownFcn','disp(''This executes'')');
    hLine.Tag = 'DoNotIgnore';
    h = rotate3d;
    h.ButtonDownFilter = @mycallback;
    h.Enable = 'on';
    % mouse-click on the line
end

function [flag] = mycallback(obj,event_obj)
    % If the tag of the object is 'DoNotIgnore', then return true
    objTag = obj.Tag;
    if strcmpi(objTag,'DoNotIgnore')
       flag = true;
    else
       flag = false;
    end
end

More About

Rotating View Versus Camera Position

When enabled, rotate mode provides continuous rotation of axes and the objects it contains through mouse movement. This behavior differs from the camorbit function in that while rotate mode modifies the View property of the axes, the camorbit function fixes the aspect ratio and modifies the CameraTarget, CameraPosition and CameraUpVector properties of the axes. See Axes Properties for more information.

Changing Callback Functions

You can create a rotate3d object and use it to customize the behavior of different axes. You can also change its callback functions on the fly.

Note

Do not change figure callbacks within an interactive mode. While a mode is active (such as when rotate mode is enabled), you will receive a warning if you attempt to change any of the figure's keyboard callbacks or window callbacks, and the operation will not succeed. The one exception to this rule is the figure WindowButtonMotionFcn callback, which can be changed from within a mode. Therefore, if you are creating a UI that updates a figure's callbacks, the UI should keep track of and check which interactive mode is active, if any, before attempting to change a callback.

When you assign different rotation behaviors to different axes in a figure by using mode objects and then link them using the linkaxes function, the behavior of the axes you manipulate with the mouse carries over to the linked axes, regardless of the behavior you previously set for the other axes.

Alternative Functionality

Axes Toolbar

For some charts, enable rotate mode by clicking the rotate icon in the axes toolbar.

Version History

Introduced before R2006a

R2023b: The RotateStyle property will have no effect

RotateStyle property of a rotate3d object will have no effect in a future release. Plot-box outline rotation will no longer be supported, and rotation will be about the entire axes regardless of the value of the property.

R2023a: Set rotate mode for specified axes in apps

For apps created in App Designer and using the uifigure function, set the rotate mode for axes by specifying the axes as the first input of rotate3d. When setting the rotate mode for axes, the function does not return a rotate3d object.

R2018b: Explore data with 3-D rotation enabled by default

Interactively explore your data using built-in axes interactions that are enabled by default. For example, you can click and drag to rotate the axes (3-D view) without enabling rotate mode. For more information, see Control Chart Interactivity.

Previously, no axes interactions were enabled by default.