RFC: Pythonic way to set perspective view

[seisman]

GMT’s -p option enables perspective view by setting the azimuth and elevation of the viewpoint. The full documentation is available at:
https://docs.generic-mapping-tools.org/6.6/gmt.html#perspective-full

The GMT command-line syntax is rather complex:

-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0]

At present, we must pass the raw string directly to the perspective parameter in the first plotting command, and then specify perspective=True in subsequent commands. This approach feels un-Pythonic.

One possible improvement is to define an auxiliary class that can be passed to the perspective parameter, for example:

perspective = Perspective(azimuth, elevation, zlevel, ...)

However, a more Pythonic design might be to provide a method—similar to Matplotlib’s [view_init](https://matplotlib.org/stable/api/_as_gen/mpl_toolkits.mplot3d.axes3d.Axes3D.view_init.html)—that allows setting the perspective once and reusing it, like so:

import pygmt

fig = pygmt.Figure()
fig.set_perspective(azimuth=xxx, elevation=xxx, zlevel=xxx)
fig.basemap(region=xxx, projection=xxx, perspective=True)
fig.coast(..., perspective=True)
fig.text(...)  # No perspective parameter needed

With this approach, the perspective parameter can simply take a boolean value—True to apply the perspective settings defined by fig.set_perspective, and False to disable them. This would also simplify the docstring for the perspective parameter.

This is still an early idea, and I’d appreciate any feedback before proceeding with implementation.

[weiji14]

I'm ok with a pygmt.param.Perspective class, but slightly against implementing fig.set_perspective, mostly because unlike fig.set_panel, there's no easy way to translate that to GMT syntax. We would still have to support the old method of passing perspective through e.g. basemap on the first call, and having the new set_perspective method would go against the 'There should be one-- and preferably only one --obvious way to do it'. It is possible to switch to the new syntax only, but then there would be a tricky deprecation cycle.

Implementation-wise, it might require #2388 (make PyGMT stateful), at least having state in the Figure class instance.

Personally, I would encourage a syntax that's more like:

import pygmt

fig = pygmt.Figure()
pp = pygmt.param.Perspective(azimuth=xxx, elevation=xxx, zlevel=xxx)
fig.basemap(region=xxx, projection=xxx, perspective=pp)
fig.coast(..., perspective=pp)  # can also use perspective=True
fig.text(...)  # No perspective parameter needed

this same style of instantiating a param class first, and then using it in the Figure methods can be learned more easily across the different Alias classes (Box/Pattern/Pen/Projection/etc) that are tracked in #4122.

[seisman]

OK. I've implemented a Perspective class in PR #4201. The implementation is simple, and we need to choose suitable parameter names.

-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0]:

• x|y|z: plane
• azim: azimuth
• elev: elevation
• zlevel: zlevel
• +w: center [GMT uses world]
• +v: viewpoint [GMT uses view]

Reference:

• GMT documentation: https://docs.generic-mapping-tools.org/6.6/gmt.html#perspective-full
• GMT long option: https://github.com/GenericMappingTools/gmt/blob/41423e5200fc2d5e83043f6a5df4b18d29e9a165/src/gmt_common_longoptions.h#L151

[seisman]

Currently, the perspective parameter supports the following input forms:

• A single value: azimuth
• A sequence of two values: (azimuth, elevation)
• A sequence of three values: (azimuth, elevation, zlevel)
• True, to reuse the previous perspective setting
• A string (e.g., "x150/30+w30/30") to use the full GMT -p syntax with more controls

Apparently, option 5 is not Pythonic, but it's not commonly used. The Perspective class will supersede it once implemented. Even after implementing Perspective, for backward compatibility, we still need to support the above forms, and more importantly, perspective=30 is simpler than perspective=Perspective(azimuth=30). Therefore, the Perspective class is not a high-priority feature and does not need to be completed before submitting the paper.

PS: I've started PR #4206 to migrate the perspective parameter to the new alias system.