Skip to content

Add documentation for Axes3d.view_init() angles #29114

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add documentation for Axes3d.view_init() angles #29114

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion galleries/examples/mplot3d/2dcollections3d.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@

# Customize the view angle so it's easier to see that the scatter points lie
# on the plane y=0
ax.view_init(elev=20., azim=-35, roll=0)
ax.view_init(elev=20, azim=-35, roll=0)

plt.show()

Expand Down
2 changes: 1 addition & 1 deletion galleries/examples/mplot3d/box3d.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@
)

# Set zoom and angle view
ax.view_init(40, -30, 0)
ax.view_init(elev=40, azim=-30, roll=0)
ax.set_box_aspect(None, zoom=0.9)

# Colorbar
Expand Down
48 changes: 38 additions & 10 deletions lib/mpl_toolkits/mplot3d/axes3d.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1095,13 +1095,12 @@ def clabel(self, *args, **kwargs):
def view_init(self, elev=None, azim=None, roll=None, vertical_axis="z",
share=False):
"""
Set the elevation and azimuth of the Axes in degrees (not radians).
Set the elevation, azimuth, and roll of the Axes, in degrees (not radians).

This can be used to rotate the Axes programmatically.

To look normal to the primary planes, the following elevation and
azimuth angles can be used. A roll angle of 0, 90, 180, or 270 deg
will rotate these views while keeping the axes at right angles.
azimuth angles can be used:

========== ==== ====
view plane elev azim
Expand All @@ -1114,6 +1113,40 @@ def view_init(self, elev=None, azim=None, roll=None, vertical_axis="z",
-YZ 0 180
========== ==== ====

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
Copy link
Member

@timhoffm timhoffm Nov 10, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?).

observed by a stationary camera, as follows (assuming a default vertical
axis of 'z'). First, a left-handed rotation about the z axis is applied
(*azim*), then a right-handed rotation about the (camera) y axis (*elev*),
then a right-handed rotation about the (camera) x axis (*roll*). Here,
the z, y, and x axis are fixed axes (not the axes that rotate together
with the original scene).

If you would like to make the connection with quaternions (because
`Euler angles are horrible
Copy link
Contributor

@scottshambaugh scottshambaugh Nov 10, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is being changed.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is being changed.

What do you mean by this? I don’t see any changes here. Did you forget to push?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

<https://github.com/moble/quaternion/wiki/Euler-angles-are-horrible>`_):
the *azim*, *elev*, *roll* angles relate to the (intrinsic) rotation of
the plot via:

*q* = exp(+roll **x̂** / 2) exp(+elev **ŷ** / 2) exp(−azim **ẑ** / 2)

(with angles given in radians instead of degrees). That is, the angles
are a kind of `Tait-Bryan angles
<https://en.wikipedia.org/wiki/Euler_angles#Tait%E2%80%93Bryan_angles>`_:
−z, +y', +x", rather than classic `Euler angles
<https://en.wikipedia.org/wiki/Euler_angles>`_.

To avoid confusion, provide the view angles as keyword
arguments: ``.view_init(elev=30, azim=-60, roll=0, ...)``.
This specific order is consistent with the order of positional arguments.
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this paragraph is needed, IMO it creates more confusion than it relieves.



Parameters
----------
elev : float, default: None
Expand Down Expand Up @@ -1606,13 +1639,8 @@ def _on_move(self, event):

# update view
vertical_axis = self._axis_names[self._vertical_axis]
self.view_init(
elev=elev,
azim=azim,
roll=roll,
vertical_axis=vertical_axis,
share=True,
)
self.view_init(elev, azim, roll, vertical_axis=vertical_axis,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not that I care too much, but why are we going back here to positional arguments?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

share=True)
self.stale = True

# Pan
Expand Down
2 changes: 1 addition & 1 deletion lib/mpl_toolkits/mplot3d/tests/test_art3d.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ def test_scatter_3d_projection_conservation():
fig = plt.figure()
ax = fig.add_subplot(projection='3d')
# fix axes3d projection
ax.roll = 0
ax.elev = 0
ax.azim = -45
ax.roll = 0
ax.stale = True

x = [0, 1, 2, 3, 4]
Expand Down
12 changes: 6 additions & 6 deletions lib/mpl_toolkits/mplot3d/tests/test_axes3d.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ def test_bar3d_shaded():
)
for ax, (elev, azim, roll) in zip(axs, views):
ax.bar3d(x2d, y2d, x2d * 0, 1, 1, z, shade=True)
ax.view_init(elev=elev, azim=azim, roll=roll)
ax.view_init(elev, azim, roll)
fig.canvas.draw()


Expand Down Expand Up @@ -708,7 +708,7 @@ def test_surface3d_masked():
norm = mcolors.Normalize(vmax=z.max(), vmin=z.min())
colors = mpl.colormaps["plasma"](norm(z))
ax.plot_surface(x, y, z, facecolors=colors)
ax.view_init(30, -80, 0)
ax.view_init(elev=30, azim=-80, roll=0)


@check_figures_equal(extensions=["png"])
Expand Down Expand Up @@ -748,7 +748,7 @@ def test_surface3d_masked_strides():
z = np.ma.masked_less(x * y, 2)

ax.plot_surface(x, y, z, rstride=4, cstride=4)
ax.view_init(60, -45, 0)
ax.view_init(elev=60, azim=-45, roll=0)


@mpl3d_image_comparison(['text3d.png'], remove_text=False, style='mpl20')
Expand Down Expand Up @@ -1160,7 +1160,7 @@ def test_axes3d_cla():
def test_axes3d_rotated():
fig = plt.figure()
ax = fig.add_subplot(1, 1, 1, projection='3d')
ax.view_init(90, 45, 0) # look down, rotated. Should be square
ax.view_init(elev=90, azim=45, roll=0) # look down, rotated. Should be square


def test_plotsurface_1d_raises():
Expand Down Expand Up @@ -1870,11 +1870,11 @@ def test_shared_view(fig_test, fig_ref):
ax2 = fig_test.add_subplot(132, projection="3d", shareview=ax1)
ax3 = fig_test.add_subplot(133, projection="3d")
ax3.shareview(ax1)
ax2.view_init(elev=elev, azim=azim, roll=roll, share=True)
ax2.view_init(elev, azim, roll, share=True)

for subplot_num in (131, 132, 133):
ax = fig_ref.add_subplot(subplot_num, projection="3d")
ax.view_init(elev=elev, azim=azim, roll=roll)
ax.view_init(elev, azim, roll)


def test_shared_axes_retick():
Expand Down
Loading