Fig.show() - confusion in readthedocs

Just a quick note.
I’ve used GMT for many years but I’m completely new to pygmt.
Just installed today and started playing with it.
The first thing I notice following the readthedocs example:

fig = pygmt.Figure()
fig.basemap(region=[-90, -70, 0, 20], projection=“M8i”, frame=True)
fig.coast(shorelines=True)
fig.show()
is that fig.show() does not open the plot.
I tested a simple example in matplotlib (in same conda env) and fig.show() works as expected.

For pygmt, I had to do:

fig.show(method=‘external’)

and this works to open a pdf. However, the docs are misleading:

https://www.pygmt.org/latest/api/generated/pygmt.Figure.show.html#pygmt.Figure.show

If method='external' , makes PDF preview instead and opens it in the default viewer for your operating system (falls back to the default web browser). Note that the external viewer does not block the current process, so this won’t work in a script.

I’m running this in a script and it works just fine.

Yes, currently Figure.show() only works in Jupyter notebook. To open a preview in the normal python console, you have to use “Figure.show(method=‘external’)”. We already have a working PR (Improve Figure.show for displaying previews in Jupyter notebooks and external viewers by seisman · Pull Request #529 · GenericMappingTools/pygmt · GitHub) to solve the problem, but it’s not finished yet. Hopefully I can find some time finalize that PR in the next few months.

If method='external' , makes PDF preview instead and opens it in the default viewer for your operating system (falls back to the default web browser). Note that the external viewer does not block the current process, so this won’t work in a script.

I agree it’s a little confusing. method='external' works in a script. It can open the preview, but if you’re calling Figure.show(method=‘external’) multiple times, only the last preview will be shown, because “the external viewer does not block the current process”.

Sorry, this is probably not the place to ask this question but I don’t know where else to put it:
Does pygmt only wrap a small portion of the GMT api ?

eg., I wanted to plot a contour map - in GMT I would probably use xyz2grd + grdcontour or grdimage, but I don’t see that any of these routines are wrapped in pygmt (?) I see surface + grdview, but these are to make 2/3d surface contours. Maybe grdview can be used to plot 2D contours on top of a map projection (?)

Thanks!

Not all the core GMT modules are wrapped, but both contour and grdcontour are wrapped, which seems to be what you need. There is the possibility to make a feature request to wrap new modules through GitHub.

xyz2grd is not wrapped yet, and there is a working PR (https://github.com/GenericMappingTools/pygmt/pull/636).