Document the built-in patterns in the Technical Reference section (#3466

)

Co-authored-by: Yvonne Fröhlich <[email protected]>
Co-authored-by: Michael Grund <[email protected]>

doc/techref/index.md

@@ -10,6 +10,7 @@ visit the {gmt-docs}`GMT Technical Reference <reference.html>`.
 
 projections.md
 fonts.md
+patterns.md
 encodings.md
 environment_variables
 ```

doc/techref/patterns.md

@@ -0,0 +1,25 @@
+# Bit and hachure patterns
+
+PyGMT supports a variety of bit and hachure patterns that can be used to fill polygons.
+
+These patterns can be defined using the following syntax:
+
+**P**|**p**_pattern_[**+b**_color_][**+f**_color_][**+r**_dpi_]
+
+*pattern* can either be a number in the range 1-90 or the name of a 1-, 8-, or 24-bit
+image raster file. The former will result in one of the 90 predefined 64x64 bit-patterns
+provided by GMT (see the figure below). The latter allows the user to create customized,
+repeating images using image raster files.
+
+By specifying upper case **P** instead of **p** the image will be bit-reversed, i.e.,
+white and black areas will be interchanged (only applies to 1-bit images or predefined
+bit-image patterns). For these patterns and other 1-bit images one may specify
+alternative **b**ackground and **f**oreground colors (by appending **+b**_color_ and/or
+**+f**_color_) that will replace the default white and black pixels, respectively.
+Excluding *color* from a fore- or background specification yields a transparent image
+where only the back- or foreground pixels will be painted. The **+r**_dpi_ modifier sets
+the resolution in dpi.
+
+The image below shows the 90 predefined bit patterns that can be used in PyGMT.
+
+![](https://docs.generic-mapping-tools.org/6.5/_images/GMT_App_E.png)

examples/gallery/symbols/patterns.py

@@ -1,67 +1,44 @@
-r"""
+"""
 Bit and hachure patterns
 ========================
 
-PyGMT allows using bit or hachure patterns via the ``fill`` parameter
-or similar parameters:
+In addition to colors, PyGMT also allows using bit and hachure patterns to fill
+symbols, polygons, and other areas, via the ``fill`` parameter or similar parameters.
+
+Example method parameters that support bit and hachure patterns include:
 
-- :meth:`pygmt.Figure.coast`: Land and water masses via ``land`` and
-  ``water``, respectively
+- :meth:`pygmt.Figure.coast`: Land and water masses via ``land`` and ``water``
 - :meth:`pygmt.Figure.histogram`: Histogram bars via ``fill``
-- :meth:`pygmt.Figure.meca`: Focal mechanisms via ``compressionfill``
-  and ``extensionfill``
+- :meth:`pygmt.Figure.meca`: Focal mechanisms via ``compressionfill`` and
+  ``extensionfill``
 - :meth:`pygmt.Figure.plot`: Symbols and polygons via ``fill``
 - :meth:`pygmt.Figure.rose`: Histogram sectors via ``fill``
 - :meth:`pygmt.Figure.solar`: Day-light terminators via ``fill``
 - :meth:`pygmt.Figure.ternary`: Symbols via ``fill``
-- :meth:`pygmt.Figure.velo`: Uncertainty wedges and velocity error
-  ellipses via ``uncertaintyfill``
-- :meth:`pygmt.Figure.wiggle`: Anomalies via ``fillpositive``
-  and ``fillnegative``
-
-The required argument has the following form:
+- :meth:`pygmt.Figure.velo`: Uncertainty wedges and velocity error ellipses via
+  ``uncertaintyfill``
+- :meth:`pygmt.Figure.wiggle`: Anomalies via ``fillpositive`` and ``fillnegative``
 
-**P**\|\ **p**\ *pattern*\ [**+b**\ *color*][**+f**\ *color*][**+r**\ *dpi*]
-
-*pattern* can either be a number in the range 1-90 or the name of a
-1-, 8-, or 24-bit image raster file. The former will result in one of the 90
-predefined 64 x 64 bit-patterns provided by GMT; an overview can by found at
-:gmt-docs:`reference/predefined-patterns.html`.
-The latter allows the user to create customized, repeating images using image
-raster files.
-By specifying upper case **P** instead of **p** the image will be
-bit-reversed, i.e., white and black areas will be interchanged (only applies
-to 1-bit images or predefined bit-image patterns).
-For these patterns and other 1-bit images one may specify alternative
-**b**\ ackground and **f**\ oreground colors (by appending **+b**\ *color*
-and/or **+f**\ *color*) that will replace the default white and black pixels,
-respectively. Excluding *color* from a fore- or background specification yields
-a transparent image where only the back- or foreground pixels will be painted.
-The **+r**\ *dpi* modifier sets the resolution in dpi.
+GMT provides 90 predefined patterns that can be used in PyGMT. The patterns are numbered
+from 1 to 90, and can be colored and inverted. The resolution of the pattern
+can be changed, and the background and foreground colors can be set. For a complete list
+of available patterns and the full syntax to specify a pattern, refer to the
+:doc:`/techref/patterns`.
 """
 
 # %%
 import pygmt
 
-y = 11
-
-fig = pygmt.Figure()
-fig.basemap(
-    region=[0, 10, 0, 12],
-    projection="X10c",
-    frame="rlbt+glightgray+tBit and Hachure Patterns",
-)
-
-# To use a pattern as fill append "p" and the number of the desired
-# pattern. By default, the pattern is plotted in black and white
-# with a resolution of 300 dpi
-for pattern in [
+# A list of patterns that will be demonstrated.
+# To use a pattern as fill append "p" and the number of the desired pattern.
+# By default, the pattern is plotted in black and white with a resolution of 300 dpi.
+patterns = [
     # Plot a hachted pattern via pattern number 8
     "p8",
     # Plot a dotted pattern via pattern number 19
     "p19",
-    # Set the background color ("+b") to "red3"
-    # and the foreground color ("+f") to "lightgray"
+    # Set the background color ("+b") to "red3" and the foreground color ("+f") to
+    # "lightgray"
     "p19+bred3+flightbrown",
     # Invert the pattern by using a capitalized "P"
     "P19+bred3+flightbrown",
@@ -70,23 +47,21 @@
     # Make the background transparent by not giving a color after "+b";
     # works analogous for the foreground
     "p19+b+flightbrown+r100",
-]:
-    # Plot a square with the pattern as fill
-    fig.plot(
-        x=2,
-        y=y,
-        style="s2c",  # square with a width of 2 centimeters
-        pen="1p,black",  # 1 point thick, black outline
-        fill=pattern,
-    )
-    # Add a description of the pattern
-    fig.text(
-        x=4,
-        y=y,
-        text=pattern,
-        font="Courier-Bold",
-        justify="ML",  # justification of the text is Middle Left
-    )
-    y -= 2
+]
 
+fig = pygmt.Figure()
+fig.basemap(
+    region=[0, 10, 0, 12],
+    projection="X10c",
+    frame="rlbt+glightgray+tBit and Hachure Patterns",
+)
+
+y = 11
+for pattern in patterns:
+    # Plot a square with the pattern as fill.
+    # The square has a size of 2 centimeters with a 1 point thick, black outline.
+    fig.plot(x=2, y=y, style="s2c", pen="1p,black", fill=pattern)
+    # Add a description of the pattern.
+    fig.text(x=4, y=y, text=pattern, font="Courier-Bold", justify="ML")
+    y -= 2
 fig.show()