Wrap plot3d

[weiji14]

Wrapping the plot3d function! Original GMT plot3d function can be found at https://docs.generic-mapping-tools.org/latest/plot3d.html. Current implementation is mostly copy-modify-pasted from plot, including the tests. Also added extra aliases to the basemap function to make it 3D capable.

Live documentation preview of plot3d API is at https://pygmt-git-mapping-plot3d.gmt.vercel.app/api/generated/pygmt.Figure.plot3d.html. Gallery example is at https://pygmt-git-mapping-plot3d.gmt.vercel.app/gallery/plot/scatter3d.html

Description of proposed changes

This is the gallery example of a 3D plot with the Iris flower dataset, inspired by the example at https://scikit-learn.org/stable/auto_examples/cluster/plot_cluster_iris.html 😄

Here's another example with a bit of a geographic curve:

fig = Figure()
fig.plot3d(
    x=data[:, 0],
    y=data[:, 1],
    z=data[:, 2],
    zscale=5,
    perspective=[225, 30],
    region=[10, 70, -5, 10, 0, 1],
    projection="R270/4i",
    style="s1c",
    color="green",
    frame=["ag", "zag"],
)
fig.savefig("example_plot3d.png")
fig.show()

produces:

Alternatively, we could follow GMT.jl's example at https://www.generic-mapping-tools.org/GMT.jl/latest/plot/ and just have one plot function, which would handle 3D plotting if the z dimension is provided. Thoughts?

Fixes #467

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If adding new functionality, add an example to docstrings or tutorials.

[seisman]

A little off-topic, but should we sort all the methods alphabetically?

[weiji14]

Maybe just for the Figure.* methods, but that's for a separate PR.

[seisman]

Yes.

[seisman]

I feel that we should use spacing=[1, 2, 0.5] here, but unfortunately, it's unimplemented in pygmt.info().

[weiji14]

Yeah, forgot to handle that in #575. Should handle that (list inputs) when we complete the documentation for info.

[seisman]

This makecpt command produces a discrete CPT (see the figure below). It doesn't make sense for the categorical data here.
.

Instead, we should use makecpt -F+c, which produces categorical CPT.

But the colorbar annotations don't make sense to me. Perhaps another GMT bug.

Note: the gridlines are not shown in GMT 6.1.1. It's a new future in GMT master (see GenericMappingTools/gmt#3993), but the gridlines in XZ and YZ planes may also have bugs. Will report to GMT later.

[seisman]

Already reported to upstream GenericMappingTools/gmt#4387 and GenericMappingTools/gmt#4388.

[weiji14]

Instead, we should use makecpt -F+c, which produces categorical CPT.
But the colorbar annotations don't make sense to me. Perhaps another GMT bug.

Ah yes, forgot about -F+c! Actually, the Iris species categories are nominal (discrete) rather than ordinal (i.e. ranked 1st, 2nd, 3rd), so a legend would make more sense here than a colorbar. Another thought I had was to label each species using text plotted in 3D, but we haven't implemented that 'feature' yet.

So for now, I think we can just use -F+c here and ignore the colorbar, though we should add another categorical gallery example to close #244? I'd like to avoid adding a legend since it requires a for-loop to make the labels (and this complicates the example).

The wall frames look good though, too bad we need to wait for GMT 6.2.0! But good that we found two bugs to report to upstream GMT 😆

[weiji14]

Actually, makecpt -F is not aliased yet. Do we want to do that here or in a separate PR?

Edit: Opened up #676 to complete documentation of makecpt.

[weiji14]

Alright, with #676 merged, I've updated the code to use pygmt.makecpt(..., color_model="+c", ...)

pygmt/examples/gallery/plot/scatter3d.py

Line 34 in 40f7120

pygmt.makecpt(cmap="cubhelix", color_model="+c", series=(0, 3, 1))

In the future when we bump the minimum GMT version to 6.2.0 which would include the new feature at GenericMappingTools/gmt#4390, we can do the following:

pygmt.makecpt(cmap="cubhelix", color_model="+cSetosa,Versicolor,Virginica", series=(0, 3, 1))
fig.plot3d(...)
fig.colorbar()
fig.show()

which would produce a nice colorbar ;)

[seisman]

What about adding a title here?

[weiji14]

The title looks like it is placed too high without the gridlines at the back, doesn't look very nice:

[seisman]

Agree

[weiji14]

Thanks for the thorough review @seisman!