How to define the view angle#

The position of the viewport "camera" in a 3D plot is defined by three angles:elevation,azimuth, androll. From the resulting position, it alwayspoints towards the center of the plot box volume. The angle direction is acommon convention, and is shared withPyVista andMATLAB.Note that a positive roll angle rotates theviewing plane clockwise, so the 3d axes will appear to rotatecounter-clockwise.

Rotating the plot using the mouse will control azimuth, elevation,as well as roll, and all three angles can be set programmatically:

importmatplotlib.pyplotaspltax=plt.figure().add_subplot(projection='3d')ax.view_init(elev=30,azim=45,roll=15)

Primary view planes#

To look directly at the primary view planes, the required elevation, azimuth,and roll angles are shown in the diagram of an "unfolded" plot below. These arefurther documented in themplot3d.axes3d.Axes3D.view_init API.

(Sourcecode,2x.png,png)

Rotation with mouse#

3D plots can be reoriented by dragging the mouse.There are various ways to accomplish this; the style of mouse rotationcan be specified by settingrcParams["axes3d.mouserotationstyle"] (default:'arcball'), seeCustomizing Matplotlib with style sheets and rcParams.

Prior to v3.10, the 2D mouse position corresponded directlyto azimuth and elevation; this is also how it is done inMATLAB.To keep it this way, setmouserotationstyle:azel.This approach works fine for spherical coordinate plots, where thez axis is special;however, it leads to a kind of 'gimbal lock' when looking down thez axis:the plot reacts differently to mouse movement, dependent on the particularorientation at hand. Also, 'roll' cannot be controlled.

As an alternative, there are various mouse rotation styles where the mousemanipulates a virtual 'trackball'. In its simplest form (mouserotationstyle:trackball),the trackball rotates around an in-plane axis perpendicular to the mouse motion(it is as if there is a plate laying on the trackball; the plate itself is fixedin orientation, but you can drag the plate with the mouse, thus rotating the ball).This is more natural to work with than theazel style; however,the plot cannot be easily rotated around the viewing direction - one has tomove the mouse in circles with a handedness opposite to the desired rotation,counterintuitively.

A different variety of trackball rotates along the shortest arc on the virtualsphere (mouserotationstyle:sphere). Rotating around the viewing directionis straightforward with it: grab the ball near its edge instead of near the center.

Ken Shoemake's ARCBALL[Shoemake1992] is also available (mouserotationstyle:Shoemake);it resembles thesphere style, but is free of hysteresis,i.e., returning mouse to the original positionreturns the figure to its original orientation; the rotation is independentof the details of the path the mouse took, which could be desirable.However, Shoemake's arcball rotates at twice the angular rate of themouse movement (it is quite noticeable, especially when adjusting roll),and it lacks an obvious mechanical equivalent; arguably, the path-independentrotation is not natural (however convenient), it could take some getting used to.So it is a trade-off.

Henriksen et al.[Henriksen2002] provide an overview. In summary:

The way it was prior to v3.10; this is also MATLAB's style

Mouse controls roll too (not only azimuth and elevation)

Figure reacts the same way to mouse movements, regardless of orientation (no difference between 'poles' and 'equator')

Returning mouse to original position returns figure to original orientation (rotation is independent of the details of the path the mouse took)

The style has a corresponding natural implementation as a mechanical device

While it is possible to control roll with thetrackball style, this is not immediately obvious (it requires moving the mouse in large circles) and a bit counterintuitive (the resulting roll is in the opposite direction)

You can try out one of the various mouse rotation styles using:

importmatplotlibasmplmpl.rcParams['axes3d.mouserotationstyle']='trackball'# 'azel', 'trackball', 'sphere', or 'arcball'importnumpyasnpimportmatplotlib.pyplotaspltfrommatplotlibimportcmax=plt.figure().add_subplot(projection='3d')X=np.arange(-5,5,0.25)Y=np.arange(-5,5,0.25)X,Y=np.meshgrid(X,Y)R=np.sqrt(X**2+Y**2)Z=np.sin(R)surf=ax.plot_surface(X,Y,Z,cmap=cm.coolwarm,linewidth=0,antialiased=False)plt.show()

Alternatively, create a filematplotlibrc, with contents:

axes3d.mouserotationstyle:trackball

(or any of the other styles, instead oftrackball), and then run any ofthe3D plotting examples.

The size of the virtual trackball, sphere, or arcball can be adjustedby settingrcParams["axes3d.trackballsize"] (default:0.667). This specifies how muchmouse motion is needed to obtain a given rotation angle (when near the center),and it controls where the edge of the sphere or arcball is (how far fromthe center, hence how close to the plot edge).The size is specified in units of the Axes bounding box,i.e., to make the arcball span the whole bounding box, set it to 1.A size of about 2/3 appears to work reasonably well; this is the default.

Both arcballs (mouserotationstyle:sphere andmouserotationstyle:arcball) have a noticeable edge; the edge can be madeless abrupt by specifying a border width,rcParams["axes3d.trackballborder"] (default:0.2).This works somewhat like Gavin Bell's arcball, which wasoriginally written for OpenGL[Bell1988], and is used in Blender and Meshlab.Bell's arcball extends the arcball's spherical control surface with a hyperbola;the two are smoothly joined. However, the hyperbola extends all the way beyondthe edge of the plot. In the mplot3d sphere and arcball style, the border extendsto a radiustrackballsize/2+trackballborder.Beyond the border, the style works like the original: it controls roll only.A border width of about 0.2 appears to work well; this is the default.To obtain the original Shoemake's arcball with a sharp border,set the border width to 0.For an extended border similar to Bell's arcball, where the transition fromthe arcball to the border occurs at 45°, set the border width to\(\sqrt 2 \approx 1.414\).The border is a circular arc, wrapped around the arcball sphere cylindrically(like a doughnut), joined smoothly to the sphere, much like Bell's hyperbola.