Add gallery example to show usage of tile maps

[michaelgrund]

Description of proposed changes

So far we don't promote the usage of tilemaps. Here's a gallery example to show its application using two different sources.

Preview: https://pygmt-dev--2585.org.readthedocs.build/en/2585/gallery/maps/tilemaps.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.
• Use underscores (not hyphens) in names of Python files and directories.

Slash Commands

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

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[michaelgrund]

/format

[michaelgrund]

/format

[michaelgrund]

/format

[weiji14]

Nice one, thanks @michaelgrund for adding this example! Just one comment for now.

[seisman]

Nice example! Do you think switching the order of the two examples makes more sense? I.e., the first example uses the tile providers available from contextily and the second is a more advanced example for people who wants to use custom tile servers that contextily doesn't provide (source="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png" as an example although contextily supports OpenStreetMap).

[michaelgrund]

Nice example! Do you think switching the order of the two examples makes more sense? I.e., the first example uses the tile providers available from contextily and the second is a more advanced example for people who wants to use custom tile servers that contextily doesn't provide (source="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png" as an example although contextily supports OpenStreetMap).

Not sure, since contextily needs to be loaded additionally as a separate library, compared to the "direct" link to the custom tile servers. What do others think?

[yvonnefroehlich]

Nice example! Do you think switching the order of the two examples makes more sense? I.e., the first example uses the tile providers available from contextily and the second is a more advanced example for people who wants to use custom tile servers that contextily doesn't provide (source="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png" as an example although contextily supports OpenStreetMap).

Not sure, since contextily needs to be loaded additionally as a separate library, compared to the "direct" link to the custom tile servers. What do others think?

I have no clear answer here, and I feel I am fine with both orders. Here are some thoughts or ideas, which are maybe helpful regarding a decision:
Considering that contextily needs to be loaded additionally and that the Stamen.Watercolor option is a more special visualization than OpenStreetMap, the current Figure order makes sense to me. However, by default (i.e., the source parameter is not specified), the xyzservices.TileProvider object xyzservices.providers.Stamen.Terrain is used. So, maybe expand the example and start without specifying source. Then introduce source based on using not the default Stamen.Terrain web tiles, but the Stamen.Watercolor option from contextily. Create a second figure to show that also a web tile provider in the form of a URL can be used and introduce the zoom parameter.

Code example: (comments need definitly some improvement)

import contextily
import pygmt

fig = pygmt.Figure()

# Default xyzservices.providers.Stamen.Terrain
fig.tilemap(
    region=[-157.84, -157.8, 21.255, 21.285],
    projection="M12c",
    frame="af+e",
)

fig.shift_origin(xshift="13c")

fig.tilemap(
    region=[-157.84, -157.8, 21.255, 21.285],
    projection="M12c",
    # Instead of Stamen.Terrain web tiles use the Stamen.Watercolor option
    # from contextily
    source=contextily.providers.Stamen.Watercolor,
    frame=["wSne", "af+e"],
)

fig.show()

###############################################################################
# Instead of a web tile provider in the form of a xyzservices.TileProvider
# object use one in the form of a URL

fig = pygmt.Figure()

fig.tilemap(
    region=[-157.84, -157.8, 21.255, 21.285],
    projection="M12c",
    # Set level of details (0-22)
    # Higher levels mean a zoom level closer to the Earth's
    # surface with more tiles covering a smaller
    # geographic area and thus more details and vice versa
    # Please note, not all zoom levels are always available
    zoom=14,
    # Use tiles from OpenStreetMap tile server
    source="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
    frame="afg+e",
)

fig.show()

Output figures:

[seisman]

maybe expand the example and start without specifying source. Then introduce source based on using not the default Stamen.Terrain web tiles, but the Stamen.Watercolor option from contextily. Create a second figure to show that also a web tile provider in the form of a URL can be used and introduce the zoom parameter.

Good idea!

[weiji14]

maybe expand the example and start without specifying source. Then introduce source based on using not the default Stamen.Terrain web tiles, but the Stamen.Watercolor option from contextily. Create a second figure to show that also a web tile provider in the form of a URL can be used and introduce the zoom parameter.

Good idea!

This is starting to sound like a tutorial instead of a gallery example 😅 Let's maybe keep to just 2 maps at a maximum instead of 3 for this gallery example. We can still show one using Stamen, and another figure using OpenStreetmap's tile server.

Note that the latter OpenStreetMap example is actually the same as using contextily.OpenStreetMap.Mapnik, but it's still good to show how people can use a tile server url like https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png. Also, either way, contextily will have to be used with or without import contextily, so the order doesn't matter too much.

[seisman]

This is starting to sound like a tutorial instead of a gallery example

Why not extend it as a tutorial?

[michaelgrund]

This is starting to sound like a tutorial instead of a gallery example

Why not extend it as a tutorial?

I think we should have both, gallery example and tutorial.

[seisman]

OK. Approving this PR.

[yvonnefroehlich]

I am fine with having both gallery example and tutorial, as suggested by @michaelgrund. In this case, I feel @weiji14 is right, and the gallery example should be short. For the tutorial, I suggest considering also the lonlat parameter.

[weiji14]

Yep, let's open up a separate PR for a longer tutorial.

[yvonnefroehlich]

Yep, let's open up a separate PR for a longer tutorial.

@michaelgrund do you also plan to add this tutorial, or @weiji14 do you want to work on this?