Here's my test script for whoever reviews this. You can copy in the text annotations from this example if you want to try that out - they work fine.

from mpl_toolkits.mplot3d import axes3d
import matplotlib.pyplot as plt
import matplotlib.animation as animation

fig = plt.figure()
ax = fig.add_subplot(projection='3d')

# Grab some test data.
X, Y, Z = axes3d.get_test_data(0.05)

# Plot a basic wireframe.
ax.plot_wireframe(X, Y, Z, rstride=10, cstride=10)

ax.set_xlabel('x')
ax.set_ylabel('y')
ax.set_zlabel('z')

vertical_axis = 'z'
elev, azim, roll = 30, 0, 0
ax.view_init(elev, azim, roll, vertical_axis=vertical_axis)

'''
def update_view(num):
    elev = num
    azim = num
    roll = num
    ax.view_init(elev, azim, roll, vertical_axis=vertical_axis)

anim = animation.FuncAnimation(fig, update_view, interval=25, save_count=360)
anim.save("roll.mp4")
#'''

plt.show(block=True)

Note that I believe the inversion at about 6.5 seconds into the second video is due to the issue addressed by PR #10762

I updated this to fix issue #10241 as well, since PR #10762 looks abandoned and this fix couples into the roll angle as well. Per the discussion in that PR, I only normalized the angles when generating the projection matrix, not when storing them. The second animation looks a lot better now.

Thanks for the contribution! The animations look really great!

can you please comment how this PR behaves wrt. to my two remarks in #14453 (comment)?

Sure thing!

1. In short, azimuth then elevation rotations are first applied, and then roll.
   In long, the elevation and azimuth first define a location for the "eye" looking at the scene. The primary view is then formed by looking from the eye down the vector towards the center of the viewing volume "R". This vector "v" is given an orthogonal vector "u" that aligns with the vertical_axis, and a vector orthogonal to both "w". u and w define the "up" and "right" directions for the viewport. The current code stops there. What I do is then simply rotate u and w in the viewing plane clockwise by the roll angle so that the end result is only a rotation of the viewport. You can dig into this in the lib/mpl_toolkits/mplot3d/proj3d.py:view_transformation() function.
2. Rotation using the mouse on an interactive plot still only controls elevation and azimuth, meaning that this feature is only really relevant to users who want to create more complex camera angles programmatically. You won't be able to control roll by clicking and dragging.

@jklymak
That's a good optimization, I can add it in this evening!

So the problem here is that elevation and azimuth already break with standard axis rotations. As matlab (ref 1, ref 2) and matplotlib currently define them, azimuth corresponds to a standard right-handed "yaw" rotation about z, but elevation corresponds to a left-handed "pitch" rotation about y (i.e. elevation = -pitch). This really breaks with all other normally used conventions which only use right-handed rotations. And matlab doesn't use a roll angle with the elev/azim convention.

In that second reference, mathworks does talk about another camera module they have which uses roll/pitch/yaw as the camera frames. They cite "IEEE. Standard for Distributed Interactive Simulation – Application Protocols. IEEE P1278.1/D16 Rev 18, May 2012." as the source for that. But those are all right-hand rotations, and to change to match with that would break the current implementation.

So we have to keep elevation and azimuth as-is for backwards compatibility. But we're a bit in the dark as to prior art for how to define the roll angle. To be clear it should definitely go last in the rotation order here, but whether it's a left-hand or right-hand rotation is up to us. I currently have it defined as a left-hand rotation as shown here (first image below). Searching around I found a slide deck that shows that OpenGL uses a right-hand rotation as shown here (second image below), but note that with how the XYZ axes are defined in the picture with the plane, their rotations are all left-handed, which makes me really question this source. Note also that in both of these sources, 1) their elevation and azimuth rotations are both flipped in handedness from our/matlab convention, and 2) the axes that are being rotated about also conflict. So we can't straight up adopt OpenGL's approach.

Both those sources also call this angle something different - "tilt". Using this or "twist" might help disambiguate it if a more complex camera with roll/pitch/yaw ever gets added.

The image I've found with the clearest example is this one, though it's not really sourced to anything. The roll/"twist" rotation here is right-handed as viewed from the origin.

Is anyone's head hurting yet? :) To make a simple summary, we're pretty locked in but still have to decide which way the purple arrow is pointing in the bottom image. I'm leaning now towards what's in the bottom image but calling it "tilt" instead of "roll". If anyone has a good canonical source or prior art on this I'm all ears. And this should probably get a documentation image that's clear on the sign conventions.

Another summary:
Standard rotation matrices about each of the XYZ axes are applied like so: R(+X)(roll) * R(+Y)(pitch) * R(+Z)(yaw)
We have to choose between: R(+X)(tilt) * R(-Y)(elevation) * R(+Z)(azimuth) or R(-X)(tilt) * R(-Y)(elevation) * R(+Z)(azimuth). I would recommend the former.

@scottshambaugh yes, Euler angles always hurt the head!

a) agree that we can't break our current meaning of elev and azimuth.
b) agree that it looks like "roll" going last is pretty typical

Angles are somewhat funny because are they what happens if I turn the camera in the positive direction or are they what happens to the scene when I turn in the positive direction?

Matplotlib seems consistent to me in choosing camera movement. i.e. azimuth=10 moves the camera 10 degrees right-handedly around the z axis. elevation=10 moves the camera up 10 degrees from the original x-y plane. This is exactly the same as your last diagram.

If you agree that these two angles mean where the camera goes, then I think the "roll" or "twist" should be right handed movement of the camera, again, just as your diagram shows i.e. roll=10 will spin the camera 10 degrees counter-clockwise. However, again, that means the scene will spin 10 degrees clockwise.

It would be great to include a diagram like the above in the docs so this is crystal clear for folks. It would probably be better made in something that has light shading. If the one above is open source, it would be fine.

None of this is made simpler by the choice of azimuth=0 as looking from the positive x-axis side!

If we add this, I would suggest two diagrams:

Ok, I opened up issue #21508 for creating that diagram for the docs. Could use a hand with that, creating those kinds of images isn't my strong suit.

I renamed the angle to "tilt" to disambiguate from roll/pitch/yaw, and added that speedup optimization for the default tilt=0. The rotation directions were kept as originally, meaning that the last image there correctly shows the movement of the camera (ie positive tilt means the camera rotates counterclockwise, world rotates clockwise). That means the coordinate transformation of the world axes are the second option: R(-X)(tilt) * R(-Y)(elevation) * R(+Z)(azimuth)

Ok, switched it back to roll and flipped the handedness to match with pyvista. #21508 is updated as well. Ready to rock and roll.

I'm not sure how to fix the PR Cleanliness failing check.

I think thats fine. PR cleanliness is failing because you have probably added and removed the same images in different commits. Rebase your commits to a single commit (or a couple if they make sense to you) and force-push back to GitHub and the PR should pass....

@jklymak Does that address everything you were worried about?

Ooops sorry. I'll try and look tomorrow. Thanks for the ping.

As a documentation idea: It would be cool to have an explanation of the degrees of freedom as animation:

1. Start with a certain view.
2. Move +/- azimuth and while doing so, show a title/label "azimuth"
3. Move +/- elevation and while doing so, show a title/label "elevation"
4. Move +/- roll and while doing so, show a title/label "elevation"

@scottshambaugh since you make these awesome animations, would you be interested in doing this as a follow-up PR?

Sure, that’s not hard to do. Make sense to put it in the gallery?

Yes, please put it in 3d plotting.

Bump

Looks great. Did you want to squash the two commits, us to do it, or leave them as-is?

I don't have a preference, go ahead and do whatever the general convention is.

OK, Squashed and merged.... Thanks a lot for working on this!

Thanks for making it an easy process!