Add pan and zoom toolbar handling to 3D Axes (Replaces PR#22614) by scottshambaugh · Pull Request #23449 · matplotlib/matplotlib · GitHub

PR Summary

Starting with @greglucas's work in #22614, I got panning and zooming working again with the toolbar buttons. Closes #110 (the oldest open issue!)

Changes in this PR:

Pan and zoom buttons enabled for 3D plots
Panning 3D plots reworked in general. Previously there was a 'scaling factor' in how much the plot moved with mouse movement. This has been updated so that if you are using an orthographic projection, the point directly under the mouse stays directly under the mouse. (This is not possible with a perspective projection)
[bugfix] Panning with a nonzero roll angle was broken, works now.
Made panning button configurable, like the zoom and rotate buttons are
Added in 'x' and 'y' key locking for 3d plot panning and zooming
[bugfix] Fixed mouse zoom jumping if hovering over a separate subplot
Refactor calculating the u, v, w view axes, add these as Axes3D private variables ._view_u, ._view_v, ._view_w
Privatize and add deprecation warnings for Axes3D .eye, .vvec, .sx, .sy, and proj3d.view_transformation()
Tests for panning and zooming

If this is too much packed in a single PR, I can separate it out into the panning and the zooming features.

Zooming behavior:

Edit: All axes now zoom equally.
With right mouse button: All axes are zoomed equally.
With the bounding box and an aspect ratio of 'auto': The scale factors set by the bounding box extents zoom the data axes such that the data is stretched in the u, v plane parallel to the screen but not in the w axis into/out of the screen. In other words, this zooms in 2D, projected onto the 3D data axes. Aspect ratio is set by the aspect of the bounding box. Note that the bounding box scale factors are calculated with respect to the whole canvas rather than the (shrunk) 3D axis limits.
With the bounding box and an aspect ratio of 'equal', 'equalzy', 'equalyz', or 'equalxz': Similar to the above, but the constrained data axes are kept equal, which may induce scaling in the w axis. 'equal' zooms all axes equally.

Please play around with it and see if the behavior is as expected!

Here's my test plot code which you can use:

from mpl_toolkits.mplot3d import Axes3D
import matplotlib.pyplot as plt
import numpy as np
from itertools import product, combinations

fig, ax = plt.subplots(1, 1, subplot_kw={'projection': '3d'})

# Draw rectangular cuboid with side lengths [1, 1, 2]
r = [0, 1]
scale = np.array([1, 1, 2])
for start, end in combinations(np.array(list(product(r, r, r))), 2):
    if np.sum(np.abs(start - end)) == r[1] - r[0]:
        ax.plot3D(*zip(start*scale, end*scale))

ax.view_init(elev=45, azim=45, roll=0)

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

plt.show(block=True)

PR Checklist

Tests and Styling

Has pytest style unit tests (and pytest passes).
Is Flake 8 compliant (install flake8-docstrings and run flake8 --docstring-convention=all).

Documentation

New features are documented, with examples if plot related.
New features have an entry in doc/users/next_whats_new/ (follow instructions in README.rst there).
[n/a] API changes documented in doc/api/next_api_changes/ (follow instructions in README.rst there).
Documentation is sphinx and numpydoc compliant (the docs should build without error).

1) This moves the pan logic that was already in the mouse move handler into the "drag_pan" method to make it available from the toolbar. 2) This expands upon the panning logic to enable a zoom-to-box feature. The zoom-to-box is done relative to the Axes, so it shrinks/expands the box as a fraction of each delta, from lower-left Axes to lower-left zoom-box. Thus, it tries to handle non-centered zooms, which adds more cases to handle versus the current right-click zoom only scaling from the center of the projection.

Talked about this in the dev call today, I got a few things to update but this should merge in after #23409 so zooming can respect fixed aspect ratios if those are set.

OK! Maybe it is better to just deprecate the whole proj3d then? Just thinking that there is a single method deprecated now, while it would be just "as easy" to deprecate the whole submodule? (In terms of writing release notes etc.)

That deprecation may naturally be better off in a different PR though. (Sorry, could have thought of that earlier, but didn't realize that proj3d was not really user material.)

Btw, do you know what happens if I squash-merge the commits? Will it still contain both you and @greglucas as authors? (That doesn't happen on Gitlab I've noticed...)

I've found some libraries that use proj3d though, e.g.,

Most seem to use proj_transform though, so maybe it is enough to keep that?

Which may mean that there is no big deal if one method is deprecated here and some others in another PR.

Thinking a bit more about it I suggest the following for now:

Rewrite the deprecation note to (only) consider the privatized attributes instead.
Deprecate suitable parts of proj3d in another PR (which of course you do not have to write). I think those needs another discussion.

Sounds good to me, I undeprecated view_transformation for now, rewrote the API change note, and opened #24098 to track that work forward.

I don't believe that a squash merge would preserve that... I can rebase to just squash all mine if that make sense but might be a few days till I can get back to my personal computer for the CLI.

Subject to wording in deprecation notice and uncertainty how to deal with the multiple commits, especially the merge commits.

" The only time we are really strict about it is ... to remove upstream merges."

Not sure if it holds here or if the size of this PR means that we can ignore it.

Co-authored-by: Oscar Gustafsson <oscar.gustafsson@gmail.com>

…to pan-zoom-3d

Cool, docs are building with that notice now.

I'm not following the squash discussion. Is this only about crediting multiple people in the squash commit? That is done by Co-authored-by lines. Important: This needs two empty lines before. When you squash via the GitHub UI you can edit the commit message. AFAIR the co-author lines are in there by default.

Thanks @timhoffm for the clarification/reminder! You are correct that they are there by default, but not two empty in front of it (I added those though, to be on the safe side).

(Context: I did something similar in GitLab and there it wasn't added by default so I had to do a force push on the main branch. DId want to avoid that there...)

…plotlib#23449) * ENH: Add pan and zoom toolbar handling to 3D Axes 1) This moves the pan logic that was already in the mouse move handler into the "drag_pan" method to make it available from the toolbar. 2) This expands upon the panning logic to enable a zoom-to-box feature. The zoom-to-box is done relative to the Axes, so it shrinks/expands the box as a fraction of each delta, from lower-left Axes to lower-left zoom-box. Thus, it tries to handle non-centered zooms, which adds more cases to handle versus the current right-click zoom only scaling from the center of the projection. * Rewrite zooming with bounding box * Rewrite 3d panning to work with a roll angle * Whats new for zoom and pan buttons * Make pan button configurable * Do not jump when zooming and mouse goes over other subplot * Rework zooming for 3d plots * Handle x/y lock when zooming and panning * Update tests * Docstrings * Dont assume a scale_z * Limit zoom box * Test zoom pan key modifiers * Save some calculation by saving view axes * Deprecation warnings for Axes3D.eye, .vvec * Remove Axes3D._prepare_view_from_bbox for now * Comments and docstrings * Switch from uvn to uvw * Save aspect to axes * Constrain zooming with mouse when one of the equal aspect ratios is set * Cleanup * Cleanup * Consolidate finding equal aspect axis indices * linting * More intuitive scaling * Box zoom keeps existing aspect ratios * Linting * Code review comments * Revert parameters for view_transformation * Fix new 3d pan/zoom view going on view stack twice * Better clipping * Test 3d toolbar navigation * Privatize helper functions * Deprecations * Code review changes * Deprecation note * Undeprecate proj3d.view_transformation * Undeprecate proj3d.view_transformation * Update doc/api/next_api_changes/deprecations/23449-SS.rst Co-authored-by: Greg Lucas <greg.m.lucas@gmail.com> Co-authored-by: Scott Shambaugh <scottshambaugh@users.noreply.github.com> Co-authored-by: Oscar Gustafsson <oscar.gustafsson@gmail.com>

greglucas and others added 10 commits July 19, 2022 13:40

Rewrite zooming with bounding box

9fd9c66

Rewrite 3d panning to work with a roll angle

4b1d8cf

Whats new for zoom and pan buttons

a6e4651

Make pan button configurable

d7a3d6c

Do not jump when zooming and mouse goes over other subplot

acbec0c

Rework zooming for 3d plots

bb95903

Handle x/y lock when zooming and panning

88d616f

Update tests

5833512

Docstrings

b6fe8b0

scottshambaugh commented Jul 19, 2022

View reviewed changes

Comment thread lib/mpl_toolkits/mplot3d/axes3d.py

Dont assume a scale_z

8a1e166

scottshambaugh marked this pull request as ready for review July 19, 2022 23:34

scottshambaugh added 2 commits July 19, 2022 18:31

Limit zoom box

8f434d6

Test zoom pan key modifiers

da4fccc

scottshambaugh force-pushed the pan-zoom-3d branch from 0ea88d2 to da4fccc Compare July 20, 2022 02:09

Save some calculation by saving view axes

695fd50

oscargus added topic: mplot3d topic: widgets/UI labels Jul 20, 2022

scottshambaugh added 2 commits July 21, 2022 16:39

Deprecation warnings for Axes3D.eye, .vvec

86f4f64

Remove Axes3D._prepare_view_from_bbox for now

47f7000

scottshambaugh mentioned this pull request Jul 22, 2022

[Doc]: Create diagram to show rotation directions for 3D plots #21508

Closed

scottshambaugh force-pushed the pan-zoom-3d branch from 026802a to 353d8b8 Compare July 22, 2022 04:26

Comments and docstrings

1eb74b6

scottshambaugh force-pushed the pan-zoom-3d branch from 353d8b8 to 1eb74b6 Compare July 22, 2022 04:34

scottshambaugh commented Jul 22, 2022

View reviewed changes

Comment thread lib/mpl_toolkits/mplot3d/proj3d.py

Switch from uvn to uvw

4a6020b

scottshambaugh marked this pull request as draft July 28, 2022 23:07

greglucas mentioned this pull request Jul 29, 2022

ENH: Add pan and zoom toolbar handling to 3D Axes #22614

Closed

3 of 4 tasks

oscargus reviewed Oct 5, 2022

View reviewed changes

Comment thread doc/api/next_api_changes/deprecations/23449-SS.rst Outdated

scottshambaugh mentioned this pull request Oct 5, 2022

[MNT]: Document and deprecate proj3d #24098

Open

scottshambaugh force-pushed the pan-zoom-3d branch from 0b58a03 to 7ef2f41 Compare October 6, 2022 01:07

Undeprecate proj3d.view_transformation

a045f36

scottshambaugh force-pushed the pan-zoom-3d branch from 7ef2f41 to a045f36 Compare October 6, 2022 01:13

Undeprecate proj3d.view_transformation

e759fba

oscargus reviewed Oct 6, 2022

View reviewed changes

Comment thread doc/api/next_api_changes/deprecations/23449-SS.rst Outdated

oscargus approved these changes Oct 6, 2022

View reviewed changes

Update doc/api/next_api_changes/deprecations/23449-SS.rst

ae8f6a1

Co-authored-by: Oscar Gustafsson <oscar.gustafsson@gmail.com>

scottshambaugh force-pushed the pan-zoom-3d branch 3 times, most recently from 56ca03a to ad52d28 Compare October 8, 2022 22:49

Merge branch 'pan-zoom-3d' of github.com:scottshambaugh/matplotlib in…

28fae53

…to pan-zoom-3d

scottshambaugh force-pushed the pan-zoom-3d branch from ad52d28 to 28fae53 Compare October 8, 2022 23:45

oscargus merged commit 4896ec1 into matplotlib:main Oct 10, 2022

oscargus mentioned this pull request Jan 14, 2023

Deprecate unused/undocumented functions in proj3d #24985

Merged

6 tasks

scottshambaugh mentioned this pull request Nov 23, 2025

[ENH]: Adding Zoom Option in Interactive 3D plot #30772

Open

Add pan and zoom toolbar handling to 3D Axes (Replaces PR#22614) by scottshambaugh · Pull Request #23449 · matplotlib/matplotlib · GitHub

Repository navigation

Add pan and zoom toolbar handling to 3D Axes (Replaces PR#22614) - #23449

Add pan and zoom toolbar handling to 3D Axes (Replaces PR#22614)#23449oscargus merged 47 commits intomatplotlib:mainmatplotlib/matplotlib:mainfrom scottshambaugh:pan-zoom-3dscottshambaugh/matplotlib:pan-zoom-3dCopy head branch name to clipboard

Conversation

scottshambaugh commented Jul 19, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

PR Checklist

Uh oh!

Uh oh!

Uh oh!

scottshambaugh commented Jul 28, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oscargus commented Oct 5, 2022

Uh oh!

oscargus commented Oct 5, 2022

Uh oh!

Uh oh!

oscargus commented Oct 5, 2022

Uh oh!

scottshambaugh commented Oct 5, 2022

Uh oh!

scottshambaugh commented Oct 5, 2022

Uh oh!

Uh oh!

oscargus left a comment

Choose a reason for hiding this comment

Uh oh!

scottshambaugh commented Oct 9, 2022

Uh oh!

timhoffm commented Oct 9, 2022

Uh oh!

oscargus commented Oct 10, 2022

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Add pan and zoom toolbar handling to 3D Axes (Replaces PR#22614)#23449
oscargus merged 47 commits into
matplotlib:mainfrom
scottshambaugh:pan-zoom-3d

scottshambaugh commented Jul 19, 2022 •
edited
Loading

scottshambaugh commented Jul 28, 2022 •
edited
Loading