ENH: Add API to manage view state in custom Axes.

[QuLogic]

Custom Axes may require additional information than simply the x/y-limits to describe the view. This API will allow the navigation buttons on the toolbar to function correctly with such Axes (but not necessarily the zoom or pan buttons just yet.)

This PR is simply a quick-to-implement idea; I have not yet applied it anywhere, though the intended usage is in PolarAxes, of course. From discussions on #4699, it seems like something like this might be useful for mplot3d as well.

There's also the question of how to update the view. As we all know by now, setting the x/y-limits does not work if the axes are not Cartesian. But NavigationToolbar2.release_zoom does quite a bit of other stuff before setting the limits and I'm not sure how to reconcile this at the moment.

[efiring]

It would be simpler to put the existing code for ordinary axes here instead of leaving these as NotImplementedError, wouldn't it? I don't see any disadvantage, but I'm probably missing something.

[QuLogic]

Probably; I'm more curious about the API at the moment.

[efiring]

attn: @OceanWolf, @fariza

[fariza]

I proposed something similar #2511 but it was rejected.
At the end, I added the "history" as a tool backend_tools.ToolViewsPositionsin the MEP22 implementation.
I would recommend to modify this tool to hold this information.
NavigationToolbar2 is going to be deprecated soon, I wouldn't invest too much effort to add functionality to it.

[QuLogic]

That was a slightly different proposal, though. I am not suggesting that the Axes store their own history, just that the history tool (wherever it is) asks the Axes what to store instead of assuming the view limits are sufficient.

[fariza]

I see... In that case why not call it get_view and set_view and move the default there instead of rising an exception?

[QuLogic]

get_ and set_ have an existing meaning that I'd like to avoid implying (like set_xlim/get_xlim); the "view" is supposed to be opaque to anything outside the Axes. Taking a cue from Transform, maybe something like freeze_view/unfreeze_view?

[efiring]

I like save/restore better than freeze/unfreeze; it's a better description of what is happening.

[OceanWolf]

What about push and pop? As I see it we basically deal with a view stack of states...

[fariza]

Regarding the names

• save: Means to actually save something, in this case, the method is just returning a specific configuration (limits in the default case), it is not saving anything.
• restore: means that it was this way before and we are putting it back, this is not true, the view can be completely made up
• push and pop: implies that we are moving things inside a stack (this is not the case).
• freeze and unfreeze: Similar to push and pop, it means that the state is stored inside the object. This is not the case.
• get and set: You actually get the current configuration (view limits and stuff) and you actually set the configuration (view limits and stuff). Where you hold the information is another matter, it can be completely made up or in the most common case this information is stored inside the backend_tools.ToolViewsPositions object

If the methods are going to be inside the axes then, it should be possible to call them externally without having to go through the toolbar. In that case, they have to implement the default behavior and their names have to represent what it is actually doing.

[OceanWolf]

@fariza ahh yes, my mistake. we do use a stack, but the stack lies in the tool. So I agree that it looks the best out of the options presented, however I feel it a bit overkill if we generalise this... say in the future we had a state of 100 variables, then we store 100 changes even if we only changed one of them.

Maybe if the tool just stored a dictionary of the changes?

[fariza]

@OceanWolf The variables are stored inside the ToolViewsPositions.view dictionnary, so it should be transparent no matter what we are storing inside.

[QuLogic]

Now updated with get/set and an API for doing zoom-to-rect. It should now be possible for custom Axes to implement the zoom button just like they can implement the pan/zoom button.

[QuLogic]

I'm not really sure why it's necessary to use the frozen view here. Unlike pan/zoom mode, with zoom-to-rect, there's only one time that the view can change (when the button's released), so I wonder if I can just use the existing view limits here?

[fariza]

@tacaswell before merging this, can you confirm that this doesn't have any bad side effects?
I have tested it, and it works fine, but I'm not sure that frozen isn't necessary.

[QuLogic]

PS, is there an automated way of testing this sort of thing? I just ran examples/api/two_scales.py.

[fariza]

Unfortunately there is no way to automatically test.
With the upcoming MEP27 it will be easier to create a virtual backend and emulate user input. For the time being, just try it as much as you can.

[QuLogic]

If that's the case, I'm not sure why Travis failed, as it seems a bit unrelated.

[jenshnielsen]

The failure is unrelated. I restarted travis

[fariza]

this view variable is not defined

[fariza]

@QuLogic Did you try it with PolarAxes as you mentionned in the description? I am curious to know if works as expected, or something else needs to be moved to Axes.
If possible, try it with both toolmanager and ToolbarNavigation2

[QuLogic]

I've been working on it here. It's a bit hacky and some things are buggy, but the API here seems to work well enough.

[fariza]

👍

[fariza]

@OceanWolf @tacaswell what do you guys think?

[tacaswell]

Sorry, I have my hands full else where and have not been paying attention to this thread at all.

[efiring]

Attn: @mdboom, @pelson: this is important, and I think it deals with
areas in which you are particularly knowledgeable.

On 8/1/15, Thomas A Caswell notifications@github.com wrote:

Sorry, I have my hands full else where and have not been paying attention to
this thread at all.

---

Reply to this email directly or view it on GitHub:
#4795 (comment)

[pelson]

Attn: @mdboom, @pelson: this is important, and I think it deals with areas in which you are particularly knowledgeable.

Thanks @efiring. The proposal makes a lot of sense - 👍 on the axes being able to control what and how the "view" is preserved. My only concerns are about:

• how much logic went into set_view_bbox - I don't feel like that is something I'd like to repeat in a subclass, and yet I also don't know whether all of that method is useful to non-cartesian axes.
• the names set_view and get_view. These sound like something that a user could see, and misuse accidentally - I'm not averse to having a private API for this behaviour (ax._get_axes_view / ax._set_axes_view would be fine IMO).

Otherwise, awesome contribution @QuLogic, thanks!

[fariza]

@pelson I actually prefer the public methods, they allow to easily switch views programatically.

[pelson]

they allow to easily switch views programatically

Completely. But imagine you were coming to mpl for the first time: there are already way to many public methods. This functionality is superb, and I know it will be well used by cartopy for one, but it isn't in the list of the first 30 methods on an Axes I'd show to a new user...

Alternatively, @shoyer and I talked about the concept of method namespaces such that you could do something like axes.gui.set_view() / axes.gui.get_view(). It seems that Pandas has an implementation of this already (and I have a hacked together proof of concept which I did before knowing about the pandas version.

[tacaswell]

@pelson Long term I would like to pull all of the plotting methods off of the Axes objects which will help address the issue of information overload. We can then use module-level name spacing to group related functions.

I really need to write up a long document of my thoughts on large-scale API changes.

[fariza]

@pelson Ok, I agree we have tooooooo many public methods in one place.
Sorry @QuLogic please change the names to private ones _set_view and _get_view

[QuLogic]

how much logic went into set_view_bbox - I don't feel like that is something I'd like to repeat in a subclass, and yet I also don't know whether all of that method is useful to non-cartesian axes.

Think of it this way: there were two copies in the two toolbars, and now there's only one copy in the axes, so I've reduced code redundancy!

[QuLogic]

I seem to always get this PS backend failure...

[fariza]

Is anybody against this?

[pelson]

@QuLogic - thanks for this awesome change 👍.
Would you mind submitting another PR to add an entry to the whats new? Thx

[QuLogic]

I'm pretty sure this is in the rc for 1.5, though it's tagged as 2.1.

[jenshnielsen]

@QuLogic Yes if you click a commit you can see which tags it's in. Both of these are in 1.5 rc1

[QuLogic]

Oh yes, I know; I just like to keep my milestones straight.

[OceanWolf]

Sorry for those just messaged, hit reply to wrong email, just delete.