Add the Pattern class for filling symbols/areas with GMT patterns

Author: seisman

examples/tutorials/advanced/cartesian_histograms.py

@@ -18,6 +18,7 @@
 # Import the required packages
 import numpy as np
 import pygmt
+from pygmt.params import Pattern
 
 # %%
 # Generate random data from a normal distribution:
@@ -204,10 +205,8 @@
     frame=["wSnE", "xaf10", "ya5f1+lCumulative counts"],
     data=data01,
     series=10,
-    # Use pattern ("p") number 8 as fill for the bars
-    # Set the background ("+b") to white [Default]
-    # Set the foreground ("+f") to black [Default]
-    fill="p8+bwhite+fblack",
+    # Fill bars with GMT pattern 8, with white background and black foreground.
+    fill=Pattern(8, bgcolor="white", fgcolor="black"),
     pen="1p,darkgray,solid",
     histtype=0,
     # Show cumulative counts

examples/tutorials/advanced/focal_mechanisms.py

@@ -18,6 +18,7 @@
 # %%
 import pandas as pd
 import pygmt
+from pygmt.params import Pattern
 
 # Set up arguments for basemap
 region = [-5, 5, -5, 5]
@@ -122,8 +123,8 @@
     longitude=2,
     latitude=0,
     depth=0,
-    compressionfill="p8",
-    extensionfill="p31",
+    compressionfill=Pattern(8),
+    extensionfill=Pattern(31),
     outline=True,
 )
 

pygmt/params/__init__.py

@@ -3,3 +3,4 @@
 """
 
 from pygmt.params.box import Box
+from pygmt.params.pattern import Pattern

pygmt/params/pattern.py

@@ -0,0 +1,88 @@
+"""
+The Pattern class for specifying GMT filling patterns.
+"""
+
+import dataclasses
+
+from pygmt.alias import Alias
+from pygmt.exceptions import GMTValueError
+from pygmt.params.base import BaseParam
+
+__doctest_skip__ = ["Pattern"]
+
+
+@dataclasses.dataclass(repr=False)
+class Pattern(BaseParam):
+    """
+    Class for GMT filling patterns.
+
+    Parameters
+    ----------
+    id
+        The pattern identifier. It can be in two forms:
+
+        - An integer in the range 1-90, corresponding to one of
+          :doc:`the 90 predefined 64x64 bit-patterns </techref/patterns>` provided with
+          GMT.
+        - The name of a 1-, 8-, or 24-bit image raster file, to create customized,
+          repeating images using image raster files.
+    dpi
+        Resolution of the pattern in dots per inch (DPI) [Default is 1200].
+    bgcolor/fgcolor
+        The background/foreground color for predefined bit-patterns or 1-bit images.
+        [Default is white for background and black for foreground]. Setting either to
+        an empty string will yield a transparent background/foreground where only the
+        foreground or background pixels will be painted.
+    reversed
+        If True, the pattern will be bit-reversed, i.e., white and black areas will be
+        interchanged (only applies to 1-bit images or predefined bit-image patterns).
+
+    Examples
+    --------
+    Draw a global map with land areas filled with pattern 15 in a light red background
+    and 300 dpi resolution:
+
+    >>> import pygmt
+    >>> from pygmt.params import Pattern
+    >>> fig = pygmt.Figure()
+    >>> fig.coast(
+    ...     region="g",
+    ...     projection="H10c",
+    ...     frame=True,
+    ...     land=Pattern(15, bgcolor="lightred", dpi=300),
+    ...     shorelines=True,
+    ... )
+    >>> fig.show()
+    """
+
+    id: int | str
+    dpi: int | None = None
+    bgcolor: str | None = None
+    fgcolor: str | None = None
+    reversed: bool = False
+
+    def _validate(self):
+        """
+        Validate the parameters.
+        """
+        if isinstance(self.id, int) and not (1 <= self.id <= 90):
+            raise GMTValueError(
+                self.id,
+                description="pattern id",
+                reason=(
+                    "Pattern id must be an integer in the range 1-90 "
+                    "or the name of a 1-, 8-, or 24-bit image raster file."
+                ),
+            )
+
+    @property
+    def _aliases(self):
+        """
+        Aliases for the Pattern class.
+        """
+        return [
+            Alias(self.id, name="id", prefix="P" if self.reversed else "p"),
+            Alias(self.bgcolor, name="bgcolor", prefix="+b"),
+            Alias(self.fgcolor, name="fgcolor", prefix="+f"),
+            Alias(self.dpi, name="dpi", prefix="+r"),
+        ]

pygmt/tests/test_params_pattern.py

@@ -0,0 +1,43 @@
+"""
+Test the Pattern class.
+"""
+
+import pytest
+from pygmt.exceptions import GMTValueError
+from pygmt.params import Pattern
+
+
+def test_pattern():
+    """
+    Test the Pattern class.
+    """
+    assert str(Pattern(1)) == "p1"
+    assert str(Pattern(id=1)) == "p1"
+
+    assert str(Pattern("pattern.png")) == "ppattern.png"
+
+    assert str(Pattern(10, bgcolor="red")) == "p10+bred"
+    assert str(Pattern(20, fgcolor="blue")) == "p20+fblue"
+    assert str(Pattern(30, bgcolor="red", fgcolor="blue")) == "p30+bred+fblue"
+    assert str(Pattern(30, fgcolor="blue", bgcolor="")) == "p30+b+fblue"
+    assert str(Pattern(30, fgcolor="", bgcolor="red")) == "p30+bred+f"
+
+    assert str(Pattern(40, dpi=300)) == "p40+r300"
+
+    assert str(Pattern(50, reversed=True)) == "P50"
+
+    pattern = Pattern(90, reversed=True, bgcolor="red", fgcolor="blue", dpi=300)
+    assert str(pattern) == "P90+bred+fblue+r300"
+
+    pattern = Pattern("pattern.png", bgcolor="red", fgcolor="blue", dpi=300)
+    assert str(pattern) == "ppattern.png+bred+fblue+r300"
+
+
+def test_pattern_invalid_id():
+    """
+    Test that an invalid pattern id raises a GMTValueError.
+    """
+    with pytest.raises(GMTValueError):
+        _ = str(Pattern(91))
+    with pytest.raises(GMTValueError):
+        _ = str(Pattern(0))