DOC: Add gallery example for using EPSG codes

[yvonnefroehlich]

Description of proposed changes

This PR aims to add a gallery example showing the usage of EPSG codes with the projection parameter.
At the moment the example is listed in the gallery under "Maps and map elements"; Edit "Projections".

Fixes #2004

Preview: https://pygmt-dev--3973.org.readthedocs.build/en/3973/gallery/maps/epsg_codes.html

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 wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
• If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash command is:

• /format: automatically format and lint the code

[yvonnefroehlich]

Recently building the Docs for windows started failing with:

embedding documentation hyperlinks for projections... [ 97%] polar.html
embedding documentation hyperlinks for projections... [100%] sg_execution_times.html

build succeeded.

The HTML pages are in _build\html.
make: *** [Makefile:35: html] Error 2816
make: Leaving directory 'D:/a/pygmt/pygmt/doc'
Error: Process completed with exit code 2.

[seisman]

Recently building the Docs for windows started failing with:

embedding documentation hyperlinks for projections... [ 97%] polar.html
embedding documentation hyperlinks for projections... [100%] sg_execution_times.html

build succeeded.

The HTML pages are in _build\html.
make: *** [Makefile:35: html] Error 2816
make: Leaving directory 'D:/a/pygmt/pygmt/doc'
Error: Process completed with exit code 2.

Yes, looking at the CI build history at https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_docs.yml?query=branch%3Amain, it started to fail since #3932

[seisman]

What about mentioning EPSG codes on the following two pages: https://pygmt-dev--3973.org.readthedocs.build/en/3973/projections/index.html and https://pygmt-dev--3973.org.readthedocs.build/en/3973/techref/projections.html

[yvonnefroehlich]

/format

[yvonnefroehlich]

/format

[yvonnefroehlich]

What about mentioning EPSG codes on the following two pages: https://pygmt-dev--3973.org.readthedocs.build/en/3973/projections/index.html and https://pygmt-dev--3973.org.readthedocs.build/en/3973/techref/projections.html

Now I moved the EPSG example to the end of the projection gallery, and mention using EPSG codes a the beginning of both projection files.

[yvonnefroehlich]

I prefer to keep this PR unmerged until we figure out which EPSG codes GMT supports.

Agree, this should be clear to the users. No worries, we can move this PR to a later release. Probably we also have to update the upstream GMt docs first.

[seisman]

https://github.com/GenericMappingTools/gmt/blob/6272b11fd8de71d190ece4809153bfed58be923e/src/gmt_plot.c#L8024

Above is the GMT function that deals with EPSG codes. As I understand it, it relies on GDAL to convert EPSG codes to a proj string, then GMT converts the proj string into a projection that GMT can support (e.g., -JM10c). So, only a few EPSG codes are supported.

In other words, do people use EPSG codes very often? Do we need to document this feature?

[yvonnefroehlich]

https://github.com/GenericMappingTools/gmt/blob/6272b11fd8de71d190ece4809153bfed58be923e/src/gmt_plot.c#L8024

Above is the GMT function that deals with EPSG codes. As I understand it, it relies on GDAL to convert EPSG codes to a proj string, then GMT converts the proj string into a projection that GMT can support (e.g., -JM10c). So, only a few EPSG codes are supported.

In other words, do people use EPSG codes very often? Do we need to document this feature?

I personally never used EPSG codes until now. This is actually why I started working on this gallery example - to learn more about these codes 🙂. What is the experience of the others @GenericMappingTools/pygmt-maintainers? How widely EPSG codes are used?

Hm. As only a subset of EPSG codes is actually supported, it can be a bit misleading (and disappointing) for users seeing the gallery example and then realizing that the code they need for their own work is not supported...

[michaelgrund]

https://github.com/GenericMappingTools/gmt/blob/6272b11fd8de71d190ece4809153bfed58be923e/src/gmt_plot.c#L8024
Above is the GMT function that deals with EPSG codes. As I understand it, it relies on GDAL to convert EPSG codes to a proj string, then GMT converts the proj string into a projection that GMT can support (e.g., -JM10c). So, only a few EPSG codes are supported.
In other words, do people use EPSG codes very often? Do we need to document this feature?

I personally never used EPSG codes until now. This is actually why I started working on this gallery example - to learn more about these codes 🙂. What is the experience of the others @GenericMappingTools/pygmt-maintainers? How widely EPSG codes are used?

Hm. As only a subset of EPSG codes is actually supported, it can be a bit misleading (and disappointing) for users seeing the gallery example and then realizing that the code they need for their own work is not supported...

I used EPSG codes heavily in business projects which focused on specific regions e.g. in Germany. This means EPSG codes can be very region-dependent and therefore they are partly only "valid" for a defined sub-region of a single country (e.g. see here for Germany and neighboring states).

---

---

They are often used in standard GIS analysis on a regional scale by authorities and state departments.

So we definitely should mention that PyGMT/GMT does not support all available EPSG codes, especially since we support map tiles which make it easy to visualize geographical content e.g. on small scales like cities etc.

[seisman]

@yvonnefroehlich I guess this PR is ready for review.

[yvonnefroehlich]

https://github.com/GenericMappingTools/gmt/blob/6272b11fd8de71d190ece4809153bfed58be923e/src/gmt_plot.c#L8024
Above is the GMT function that deals with EPSG codes. As I understand it, it relies on GDAL to convert EPSG codes to a proj string, then GMT converts the proj string into a projection that GMT can support (e.g., -JM10c). So, only a few EPSG codes are supported.
In other words, do people use EPSG codes very often? Do we need to document this feature?

I personally never used EPSG codes until now. This is actually why I started working on this gallery example - to learn more about these codes 🙂. What is the experience of the others @GenericMappingTools/pygmt-maintainers? How widely EPSG codes are used?
Hm. As only a subset of EPSG codes is actually supported, it can be a bit misleading (and disappointing) for users seeing the gallery example and then realizing that the code they need for their own work is not supported...

I used EPSG codes heavily in business projects which focused on specific regions e.g. in Germany. This means EPSG codes can be very region-dependent and therefore they are partly only "valid" for a defined sub-region of a single country (e.g. see here for Germany and neighboring states).

They are often used in standard GIS analysis on a regional scale by authorities and state departments.

So we definitely should mention that PyGMT/GMT does not support all available EPSG codes, especially since we support map tiles which make it easy to visualize geographical content e.g. on small scales like cities etc.

Thanks @michaelgrund for this information!
OK, this explains why there are so many of these EPSG codes; this website is already mentioned in the example. So far I could not figure out explicitly which codes are supported by GMT and which are not. Exemplarily, I try the ones listed for Germany, and some work and some do not. Good point with the aspect regarding map tiles. So, I think we can have these EPSG codes as a normal gallery example and mention there that not all codes are supported.

[yvonnefroehlich]

@yvonnefroehlich I guess this PR is ready for review.

Yes 🙂. Converted it back to a normal gallery example. Currently the EPSG codes are not mentioned anymore on the projection table and Technical Reference page.