rotate3d - Enable rotate mode - MATLAB (original) (raw)

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 therotate3d 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

Description

rotate3d [option](#mw%5F44606056-8b3f-405b-b951-f9df3bbfaf96) 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](#mw%5Fd0ac1d0d-190e-442c-8a70-1d1717026c9c),[option](#mw%5F44606056-8b3f-405b-b951-f9df3bbfaf96)) sets the rotate mode for all axes in the specified figure. For example, to enable rotate mode for all axes in the figure fig, userotate3d(fig,'on').

rotate3d([ax](#mw%5F02e38633-6ce8-4bb8-8ed4-1d988924c541),[option](#mw%5F44606056-8b3f-405b-b951-f9df3bbfaf96)) sets the rotate mode for the specified axes. For example, to enable rotate mode for the axesax, 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](#mw%5Fd0ac1d0d-190e-442c-8a70-1d1717026c9c)) creates arotate3d 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, seeenableLegacyExplorationModes.

Rotate mode state, specified as 'on' or 'off', or as numeric or logical 1 (true) or0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent tofalse. 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 therotate3d object. If you did not specify a figure, thenFigureHandle is the figure that was current when you created therotate3d object.

Legacy mode, specified as "on" or "off", or as numeric or logical 1 (true) or0 (false). A value of "on" is equivalent to true, and "off" is equivalent tofalse. 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 torotate3d objects for figures created using theuifigure 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, seeenableLegacyExplorationModes.

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.

Examples

collapse all

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

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

When enabled, rotate mode provides continuous rotation of axes and the objects it contains through mouse movement. This behavior differs from thecamorbit function in that while rotate mode modifies theView 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.

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

expand all

Set the rotate mode for axes by specifying the axes as the first input ofrotate3d. When setting the rotate mode for axes, the function does not return a rotate3d object. Previously, you could set the rotate mode for axes only in apps created in App Designer or using the uifigure function.

The RotateStyle property of a rotate3d object has no effect. Plot-box outline rotation is no longer supported, and rotation is about the entire axes regardless of the value of the property. This behavior change was announced in R2023b and took effect in R2025a.

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

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.