Add a gallery example showing how to use patterns via the "fill" parameter (or similar parameters)

[yvonnefroehlich]

Description of proposed changes

This PR aims to add a gallery example showing how to use patterns via the fill parameter or similar parameters:

• Add example code
• Add documentation

Preview: https://pygmt-dev--2329.org.readthedocs.build/en/2329/gallery/symbols/patterns.html

References:

• https://docs.generic-mapping-tools.org/6.4/cookbook/features.html#specifying-area-fill-attributes
• https://docs.generic-mapping-tools.org/6.4/cookbook/predefined-patterns.html

Fixes #2323 (partly)

The example is currently placed in the "Symbols and markers" section.

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

[seisman]

I wonder if we should define a class for GMT patterns, e.g.,

class GMTPattern:
    def __init__(self, id, reversed=False, bgcolor="white", fgcolor="black", dpi=1200):
        ...

[yvonnefroehlich]

Additional to the list at the beginning of this example, there is also the possibility to add a pattern via the dcw and frame parameters. The syntax seems to be difficult, as it seems to be something like +g p|P resolution / pattern. The functionality seems to be limited, as it seems that no foreground and background colors could be given (please correct me if I am wrong, so far I did not figure out how to set colors here).

Example code

import pygmt

fig = pygmt.Figure()

with fig.subplot(nrows=1, ncols=2, figsize=("10c", "5c")):

    with fig.set_panel(panel=0):
        fig.basemap(
            region=[-12, 50, 30, 70],
            projection="M?",
            frame="afg",
        )
        fig.coast(
            land="lightbrown",
            water="lightblue",
            shorelines="1/0.5p,black",
            borders="1/0.25p,red",
            dcw="=EU+gp200/8",  # here resolution/pattern 
        )        

    with fig.set_panel(panel=1):
        fig.basemap(
            region=[0, 10, 0, 10],
            projection="X?",
            frame=["afg", "+gp400/8"],  # here resolution/pattern
        )

fig.show()
# fig.savefig(fname="pattern_dcw_frame.png")

Output figure

[seisman]

The syntax seems to be difficult, as it seems to be something like +g p|P resolution / pattern.

This is the old syntax of patterns for GMT 4. The full old syntax is -Gpdpi/pattern[:Bcolor[Fcolor]]. I think the old syntax is still supported in GMT5 and GMT6 (backward compatibility), but it's no longer documented.

The functionality seems to be limited, as it seems that no foreground and background colors could be given.

As I understand it, it's impossible to specify foreground/background colors and dpi using the new syntax in coast -E.

Ping @PaulWessel for comments on this.

[yvonnefroehlich]

I wonder if we should define a class for GMT patterns, e.g.,

class GMTPattern:
    def __init__(self, id, reversed=False, bgcolor="white", fgcolor="black", dpi=1200):
        ...

Maybe we should we open a separate issue for this?
Edit 2023/03/17: Please see issue #2438.

[PaulWessel]

This is surely a case where a fairly recent enhancement (specifying the fill of country via -E in coast), is stuck with a lot of other modifiers (e.g., +r) that elsewhere in -G for fills might mean different things. So here, +g is meant to set -G but we cannot easily do the full list of modifiers, unless we do some coding changes. If we just wanted to follow the pattern specs for -G then I guess we would want to use a 400 dpi red and blue pattern number 8 for Germany with

-EDE+gp8+bred+fblue+r400

but that only gives

coast [ERROR]: Option -E: Unrecognized modifier +bred.
coast [ERROR]: Option -E: Unrecognized modifier +fblue.
-R-10/30/40/60

for the CLI. Of course, the trouble is in the C parsing since it is looking at +r to mean something with rounding of the board coordinates, not dpi of a pattern. Looking at the docs, the +f, +b are otherwise not used by -E for other things, so it may be possible to finesse something but having two different meanings of +r in the same syntax is not good. One option is to declare a bug since the +r|R main modifier prohibits us to pass a general pattern string that contains +r. We could decide that +ddpi is the required modifier and allow +f, +b, and +d if found after +g to be parsed as a pattern. We would then have to do the same to -G main pattern option and backwards introduce +d instead of +r there.

You can let me know if you think this is a good solution or not. I have not looked to see how easy this is to implement (well, doing +d in -G would be simple I think), but extracting the full pattern string given to +g might need some special checking.

[yvonnefroehlich]

Thanks a lot @seisman and @PaulWessel for these fast and detailed comments on this!
I have never used GMT 4, and thus I know little to no about the GMT4 syntax. I apologize for bringing up this discussion. I did not expect this. It was a spontaneous idea to use patterns with the dcw (-E) as well as the frame (-B) parameters, as they both have the +g modifier. While searching for the right syntax, I orientated myself on the GMT example at https://docs.generic-mapping-tools.org/dev/gallery/ex34.html. Maybe/hopefully I can look at these thoughts in more detail on the weekend, but I can not grant for this yet. I apologize for the delay.