rotate3d

Rotate 3-D view using mouse

Syntax

rotate3d on rotate3d off rotate3d rotate3d(figure_handle,...) rotate3d(axes_handle,...) h = rotate3d(figure_handle)

Description

rotate3d on turns on rotate mode and enables rotation on all axes within the current figure.

rotate3d off turns off rotate mode and disables interactive axes rotation in the current figure. Starting in R2018b, some rotate interactions are enabled by default, regardless of the rotate mode. If you want to disable these default interactions, then use the disableDefaultInteractivity function.

rotate3d toggles interactive axes rotation in the current figure.

rotate3d(figure_handle,...) enables rotation within the specified figure instead of the current figure.

rotate3d(axes_handle,...) turns on rotate mode only in the specified axes.

h = rotate3d(figure_handle) returns a rotate3d mode object for figure figure_handle for you to customize the mode's behavior.

Using Rotate Mode Objects

You access the following properties of rotate mode objects.

FigureHandle <handle> — The associated figure handle, a read-only property that cannot be set
Enable 'on'|'off' — Specifies whether this figure mode is currently enabled on the figure
RotateStyle 'orbit'|'box' — Sets the method of rotation
'orbit' rotates the entire axes; 'box' rotates a plot-box outline of the axes.
UseLegacyExplorationModes 'off' (default) | 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 matlab.lang.OnOffSwitchState.
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'. This property only applies to rotate3d objects for figures created using the uifigure function or in MATLAB^® Online™.

Rotate3D Mode Callbacks

You can program the following callbacks for rotate3d mode operations.

ButtonDownFilter <function_handle> — Function to intercept ButtonDown events

The application can inhibit the rotate operation under circumstances the programmer defines, depending on what the callback returns. The input function handle should reference a function with two implicit arguments (similar to handle callbacks):

function [res] = myfunction(obj,event_obj)
% obj          handle to the object that has been clicked on
% event_obj    handle to event data object (empty in this release)
% res [output] logical flag to determine whether the rotate
%              operation should take place or the 'ButtonDownFcn'
%              property of the object should take precedence

ActionPreCallback <function_handle> — Function to execute before rotating
Set this callback to listen to when a rotate operation will start. The input function handle should reference a function with two implicit arguments (similar to graphics object callbacks):
```
function myfunction(obj,event_obj)
% obj         handle to the figure that has been clicked on
% event_obj   object containing struct of event data
```
The event data has the following field:

Axes
The handle of the axes that is being panned
ActionPostCallback <function_handle> — Function to execute after rotating
Set this callback to listen to when a rotate operation has finished. The input function handle should reference a function with two implicit arguments (similar to graphics object callbacks):
```
function myfunction(obj,event_obj)
% obj         handle to the figure that has been clicked on
% event_obj   object containing struct of event data (same as the
%             event data of the 'ActionPreCallback' callback)
```

Rotate3D Mode Utility Functions

The following functions in pan mode query and set certain of its properties.

flags = isAllowAxesRotate(h,axes) — Function querying permission to rotate axes
Calling the function isAllowAxesRotate on the rotate3d object, h, with a vector of axes handles, axes, as input will return a logical array of the same dimension as the axes handle vector which indicate whether a rotate operation is permitted on the axes objects.
setAllowAxesRotate(h,axes,flag) — Function to set permission to pan axes
Calling the function setAllowAxesRotate on the rotate3d object, h, with a vector of axes handles, axes, and a logical scalar, flag, will either allow or disallow a rotate operation on the axes objects.

Examples

Example 1

Rotate the plot using the mouse:

surf(peaks);
rotate3d on;

Example 2

Rotate the plot using the "Plot Box" rotate style:

surf(peaks);
h = rotate3d;
h.RotateStyle = 'box';
h.Enable = 'on';

Example 3

Create two axes as subplots and then prevent one from rotating:

ax1 = subplot(1,2,1);
surf(peaks);
h = rotate3d;
h.Enable = 'on';
ax2 = subplot(1,2,2);
surf(membrane);
setAllowAxesRotate(h,ax2,false); % disable rotating for second plot

Example 4

Create a buttonDown callback for rotate mode objects to trigger. Copy the following code to a new file, execute it, and observe 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
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

Example 5

Create callbacks for pre- and post-buttonDown events for rotate3D mode objects to trigger. Copy the following code to a new file, execute it, and observe rotation behavior:

function demo_mbd2
% Listen to rotate events
surf(peaks);
h = rotate3d;
h.ActionPreCallback = @myprecallback;
h.ActionPostCallback = @mypostcallback;
h.Enable = 'on';

function myprecallback(obj,evd)
disp('A rotation is about to occur.');

function mypostcallback(obj,evd)
newView = round(evd.Axes.View);
msgbox(sprintf('The new view is [%d %d].',newView));

Tips

When enabled, rotate3d provides continuous rotation of axes and the objects it contains through mouse movement. A numeric readout appears in the lower left corner of the figure during rotation, showing the current azimuth and elevation of the axes. Releasing the mouse button removes the animated box and the readout. This differs from the camorbit function in that while the rotate3d tool 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.

You can also enable 3-D rotation from the figure Tools menu or the figure toolbar.

You can create a rotate3d mode object once and use it to customize the behavior of different axes, as example 3 illustrates. 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 (when panning, zooming, etc.), you will receive a warning if you attempt to change any of the figure's 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 some keep track of which interactive mode is active, if any, before attempting to do this.

When you assign different 3-D rotation behaviors to different subplot axes via a mode object and then link them using the linkaxes function, the behavior of the axes you manipulate with the mouse will carry over to the linked axes, regardless of the behavior you previously set for the other axes.

Alternatives

Use the Rotate3D tool on the toolbar to enable and disable rotate3D mode on a plot, or select Rotate 3D from the figure's Tools menu.

Documentation