Gallery plots for each projection

[leouieda]

Description of the desired feature

The user documentation contains a gallery of projections available. The plots showcase the projection so it's easy to choose which one you want (by clicking an image instead of having to google the name). We need to fill out this gallery with all projections listed in https://www.generic-mapping-tools.org/gmt/latest/proj_codes_GMT.html

To make a gallery plot, place a script that generates the figure in examples/projections and sphinx-gallery will take care of the rest. The file must have a specific format (see the other examples). Ideally, each projection should show a case in which it's ideal (e.g. not using Mercator for high latitudes).

Any help with this is greatly appreciated! We can build this out slowly, one example at a time.

[DefUs3r]

Sir, I would like to take up this issue. I am a beginner and I have no idea of the codebase and a very slight idea of what this library does. I would like to make my first commit here. Can you help me out?

[seisman]

There is a chapter "GMT Map Projections" in the GMT cookbook. We can copy the examples.

[leouieda]

Thanks, @seisman. I was wondering where that was. I want to try this out here and hopefully copy some of it over to the GMT docs later on.

[leouieda]

:wave: Hi @DefUs3r, thanks for offering to help! Please have a look at our Contributing Guide. You will need at least a bit of mapping knowledge, though, since the goal is to write example scripts.

[phloose]

I have a background in geoinformatics and i am slightly familiar with projections so i would like to give this a try. The commands used would be ideally the ones from the GMT Map Projections page @seisman mentioned? I also found the grouping of the projection parameters on this page into cylindrical, conic, azimutal, miscellaneus and non-geographic projections very good to make it easier for the user to select what he needs. Maybe a short description, what the primary purpose of a certain projection is, would be helpful too, especially for new, unexperienced users.

I am already playing around with the examples and if i find it suitable will file a pull request if you don't mind?!

[leouieda]

Hi @xibalba01 we don't mind PRs at all :slightly_smiling_face: I agree that having a small description of when the projection should be used would be very helpful! I like the idea of grouping the examples as well.

[phloose]

I have problems building the docs under windows:

Running make all or make html yields in:

(pygmt) C:\Users\mo3kLo4r\Documents\Code\OpenSource\pygmt\doc>make all
ECHO ist ausgeschaltet (OFF).
"Building API docs."
ECHO ist ausgeschaltet (OFF).
sphinx-autogen -i -t _templates -o api/generated api/*.rst
[autosummary] generating autosummary for: api/*.rst
[autosummary] writing to api/generated
Traceback (most recent call last):
  File "C:\Users\mo3kLo4r\Miniconda3\envs\pygmt\Scripts\sphinx-autogen-script.py", line 10, in <module>
    sys.exit(main())
  File "C:\Users\mo3kLo4r\Miniconda3\envs\pygmt\lib\site-packages\sphinx\ext\autosummary\generate.py", line 421, in main
    app=app)
  File "C:\Users\mo3kLo4r\Miniconda3\envs\pygmt\lib\site-packages\sphinx\ext\autosummary\generate.py", line 137, in generate_autosummary_docs
    items = find_autosummary_in_files(sources)
  File "C:\Users\mo3kLo4r\Miniconda3\envs\pygmt\lib\site-packages\sphinx\ext\autosummary\generate.py", line 253, in find_autosummary_in_files
    errors='ignore') as f:
  File "C:\Users\mo3kLo4r\Miniconda3\envs\pygmt\lib\codecs.py", line 898, in open
    file = builtins.open(filename, mode, buffering)
OSError: [Errno 22] Invalid argument: 'api/*.rst'
make: *** [api] Fehler 1

A short workaround was to not use api/*.rst and instead use index.rst explicitly from the api/ folder, but then i get another error when trying to build the html pages:

(pygmt) C:\Users\mo3kLo4r\Documents\Code\OpenSource\pygmt\doc>make html
ECHO ist ausgeschaltet (OFF).
"Building API docs."
ECHO ist ausgeschaltet (OFF).
sphinx-autogen -i -t _templates -o api/generated api/index.rst
[autosummary] generating autosummary for: api/index.rst
[autosummary] writing to api/generated
ECHO ist ausgeschaltet (OFF).
"Building HTML files."
ECHO ist ausgeschaltet (OFF).
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.8.5
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://docs.scipy.org/doc/numpy/objects.inv...
loading intersphinx inventory from http://pandas.pydata.org/pandas-docs/stable/objects.inv...
intersphinx inventory has moved: http://pandas.pydata.org/pandas-docs/stable/objects.inv -> https://pandas.pydata.org/pandas-docs/stable/objects.inv
loading intersphinx inventory from http://xarray.pydata.org/en/stable/objects.inv...
generating gallery...
Der Befehl "gswin64c" ist entweder falsch geschrieben oder
konnte nicht gefunden werden.
WARNING: C:\Users\mo3kLo4r\Documents\Code\OpenSource\pygmt\examples\gallery\coast\borders.py failed to execute correctly: Traceback (most recent call last):
  File "C:\Users\mo3kLo4r\Miniconda3\envs\pygmt\lib\site-packages\sphinx_gallery\gen_rst.py", line 480, in _memory_usage
    out = func()
  File "C:\Users\mo3kLo4r\Miniconda3\envs\pygmt\lib\site-packages\sphinx_gallery\gen_rst.py", line 465, in __call__
    exec(self.code, self.globals)
  File "C:\Users\mo3kLo4r\Documents\Code\OpenSource\pygmt\examples\gallery\coast\borders.py", line 25, in <module>
    fig.show()
  File "c:\users\mo3klo4r\documents\code\opensource\pygmt\pygmt\figure.py", line 272, in show
    fmt="png", dpi=dpi, anti_alias=True, as_bytes=True, transparent=True
  File "c:\users\mo3klo4r\documents\code\opensource\pygmt\pygmt\figure.py", line 342, in _preview
    self.savefig(fname, dpi=dpi, **kwargs)
  File "c:\users\mo3klo4r\documents\code\opensource\pygmt\pygmt\figure.py", line 225, in savefig
    self.psconvert(prefix=prefix, fmt=fmt, crop=crop, **kwargs)
  File "c:\users\mo3klo4r\documents\code\opensource\pygmt\pygmt\helpers\decorators.py", line 187, in new_module
    return module_func(*args, **kwargs)
  File "c:\users\mo3klo4r\documents\code\opensource\pygmt\pygmt\helpers\decorators.py", line 282, in new_module
    return module_func(*args, **kwargs)
  File "c:\users\mo3klo4r\documents\code\opensource\pygmt\pygmt\figure.py", line 165, in psconvert
    lib.call_module("psconvert", build_arg_string(kwargs))
  File "c:\users\mo3klo4r\documents\code\opensource\pygmt\pygmt\clib\session.py", line 490, in call_module
    module, status, self._error_message
pygmt.exceptions.GMTCLibError: Module 'psconvert' failed with status code 78:
psconvert [ERROR]: Error opening HKLM key
psconvert [ERROR]: Failed to parse response to GhostScript version query [n = -1 0 0].

psconvert [ERROR]: Error opening HKLM key
Der Befehl "gswin64c" ist entweder falsch geschrieben oder
konnte nicht gefunden werden.
psconvert [ERROR]: Failed to parse response to GhostScript version query [n = -1 0 0].

Exception occurred:
  File "c:\users\mo3klo4r\documents\code\opensource\pygmt\pygmt\clib\session.py", line 490, in call_module
    module, status, self._error_message
pygmt.exceptions.GMTCLibError: Module 'psconvert' failed with status code 78:
psconvert [ERROR]: Error opening HKLM key
psconvert [ERROR]: Failed to parse response to GhostScript version query [n = -1 0 0].
The full traceback has been saved in C:\Users\mo3kLo4r\AppData\Local\Temp\sphinx-err-_hpy72rb.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [html] Fehler 2

Somehow psconvert can't find ghostscript even though its installed... Strange, since normal plotting within a jupyter notebook works. In the beginning i didnt had ghostscript installed so no plot worked and i got the same error. Any ideas?

Under linux building the docs works, although initially i had problems with ghostscript. psconvert produced postscript files with decimal values that used a comma instead of a period. I could fix it by setting LC_NUMERIC to en_US.UTF-8 (i have a german system...)

EDIT

Ok obviously if ghostscript on windows is NOT installed via conda pygmt/gmt doesnt find its executable...

[phloose]

I split the projections folder into the main groups by creating subfolders with their own README.txt like it is described in the sphinx-gallery-docs. Now it appears like i was thinking it makes the most sense.

Do you think it would make sense to write a small general introduction for every type of projection?

[willschlitzer]

I'll work on this.

[willschlitzer]

Should the different projections have a particular and standardized color scheme? The GMT docs don't seem to follow any standard color scheme, but all of the PyGMT projection examples have gray land and white water.

[seisman]

I don't think we have any standardized color scheme here. I actually prefer the maps in the GMT docs.

[willschlitzer]

I prefer them as well. My thought is to copy the GMT example projection maps when able, as I think they are all good maps and there's no need to reinvent the wheel. I just want to make sure there isn't a plan in place already for standardized example projection maps.

[willschlitzer]

I think it would be a good idea to have the home page of the projection gallery have some sort of table that lists the different projection codes. Even when the gallery is fleshed out, it won't be immediately clear to someone looking at PyGMT code what the given projection is, and this will keep them from having to click on all of the gallery examples to find out. I looked through the PyGMT docs to see if there are any examples of a table but couldn't find one; any ideas on how to implement this?

[willschlitzer]

Are we missing any examples for gallery plots?

[seisman]

@willschlitzer Thanks again for your recent contributions! I think this issue is close to finishing.

I think it would be better to also add logarithmic projection and power projection.

[seisman]

I think it would be a good idea to have the home page of the projection gallery have some sort of table that lists the different projection codes. Even when the gallery is fleshed out, it won't be immediately clear to someone looking at PyGMT code what the given projection is, and this will keep them from having to click on all of the gallery examples to find out. I looked through the PyGMT docs to see if there are any examples of a table but couldn't find one; any ideas on how to implement this?

@willschlitzer Sounds a good idea. Could you open a new issue for this so that we can better discuss it?

[phloose]

Before you close this issue i would like to add that it would be nice to have some explanatory text about each projection like in the GMT cookbook . I proposed and started this with #318 and would think that this is very useful for people new to GMT and mapping, because projections are not easy to grasp for everyone.

[willschlitzer]

Would we be able to copy the text directly from the GMT cookbook on the reasoning behind using different projections? I don't want to plagiarize, but I would also hope to avoid reinventing the wheel if possible.

[seisman]

I don't want to plagiarize, but I would also hope to avoid reinventing the wheel if possible.

PyGMT and GMT belong to the same organization, so don't worry about plagiarization. We can just copy and paste from the cookbook, and even improve it if someone has more knowledge more about projections.

Again, it would be good if @willschlitzer can open a new issue for your comment https://github.com/GenericMappingTools/pygmt/issues/292#issuecomment-742367645, and @phloose for your comment https://github.com/GenericMappingTools/pygmt/issues/292#issuecomment-747743344, as I don't want to make the discussions too long in this issue.