rotate3d

Enable rotate mode

expand all in page

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.

example

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'). (since R2023a)

Before R2025a: Use this syntax with apps created in App Designer or using the uifigure function.

example

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

example

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

Input Arguments

expand all

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.

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

Target axes, specified as an Axes object.

Properties

expand all

Note

If you modify any of these properties of a rotate3d object, then MATLAB® enables legacy exploration modes on the figure. For more information, see enableLegacyExplorationModes.

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.

Method of rotation, specified as 'orbit'. The entire set of axes rotates.

Before R2025a: If you specify 'box', a plot-box outline of the axes rotates. 'box' is not supported for figures created using the uifigure function or in MATLAB Online™.

Note

This property has no effect. For more information, see Version History.

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.

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.

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.

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.

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. For more information, see Legacy Exploration Modes.

Once this property is set to "on", you cannot change it back to "off".

Before R2025a: 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.

Object Functions

Note

If you call any of these object functions for a rotate3d object, then MATLAB enables legacy exploration modes on the figure. For more information, see enableLegacyExplorationModes.

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.

Note

You can achieve the same functionality without entering legacy exploration modes by setting the RotateSupported property of the InteractionOptions object of the axes.

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.

Note

You can achieve the same functionality without entering legacy exploration modes by querying the RotateSupported property of the InteractionOptions object of the axes.

Examples

collapse all

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

surf(peaks)
rotate3d on

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')

Tiled chart layout with rotate mode enabled for the first axes

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

expand all

Alternative Functionality

Axes Toolbar

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

Version History

Introduced before R2006a

expand all

See Also

Functions

Topics