Syntax

Description

rotate3d on enables mouse-base rotation on all axes within the current figure.

rotate3d off disables interactive axes rotation in the current figure.

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,...) enables rotation 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.

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

Alternatives

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

See Also

camorbit | pan | rotate | view | zoom