Add documentation for Axes3d.view_init() angles #29114
Conversation
- Clarify the relation between the view_init() angles and the rotation of the scene, and add recommendation to use keyword arguments - Change axes.view_init() arguments to keywords if the arguments are numbers - Label angles as elev, azim, or roll as appropriate, when it is not evident already - Avoid unnecessary argument repetition (elev=elev, azim=azim, roll=roll) - Stick with the original order: elev, azim, roll, in view_init() keyword arguments
| A roll angle of 0, 90, 180, or 270 degrees will rotate these views | ||
| while keeping the axes horizontal or vertical. | ||
|
|
||
| The *azim*, *elev*, *roll* angles correspond to rotations of the scene |
There was a problem hiding this comment.
A textual description is quite hard to follow. I suggest to instead link to https://matplotlib.org/devdocs/api/toolkits/mplot3d/view_angles.html#how-to-define-the-view-angle. And maybe move the quarternions there as well (in a note?).
| vertical_axis=vertical_axis, | ||
| share=True, | ||
| ) | ||
| self.view_init(elev, azim, roll, vertical_axis=vertical_axis, |
There was a problem hiding this comment.
Not that I care too much, but why are we going back here to positional arguments?
There was a problem hiding this comment.
For consistency, with:
axes3d.py: line 142: self.view_init(self.initial_elev, self.initial_azim, self.initial_roll)
test_axes3d.py: line 180: ax.view_init(elev, azim, roll)
test_axes3d.py: line 1873: ax2.view_init(elev, azim, roll, share=True)
test_axes3d.py: line 1877: ax.view_init(elev, azim, roll)
rotate_axes3d_sgskip.py: line 47: ax.view_init(elev, azim, roll)
(And come to think of it, we could change axes3d.py, line 1372 too - consider it done.)
Since we are not going to change the order of the angles, there is no reason to use keyword arguments in these cases, it would just lead to duplication: elev=elev, azim=azim, roll=roll, for no benefit whatsoever, the intent is already clear without the keywords.
| Unfortunately, this order does not match the order in which rotations are | ||
| applied, and it differs from the order used in other programs (``azim, elev``) | ||
| and in `matplotlib.colors.LightSource`. However, it cannot be | ||
| changed, since that would compromise backward compatibility. |
There was a problem hiding this comment.
I don't think this paragraph is needed, IMO it creates more confusion than it relieves.
| with the original scene). | ||
|
|
||
| If you would like to make the connection with quaternions (because | ||
| `Euler angles are horrible |
There was a problem hiding this comment.
This is an excellent reference, but I think the tone should be more neural. E.g. "See X for a discussion on why quaternions are a more natural way to represent orientations"
There was a problem hiding this comment.
It is being changed.
There was a problem hiding this comment.
It is being changed.
What do you mean by this? I don’t see any changes here. Did you forget to push?
There was a problem hiding this comment.
Oh I'm sorry, it is less than clear, I meant to say: I'm changing it and I'll push a commit once I've tried to address the other issues raised too. (It may take a little while.)
PR summary
This is an alternative for PR #28395, it adds documentation to clarify the relation between the Axes3d.view_init() angles and the rotation of the scene, and add recommendation to use keyword arguments; but unlike #28395, it leaves the original order (elev, azim, roll) unaffected. It closes Issue #28353.
PR checklist