From 7f39a7d80723d614ca2315516a3477e5cfe6c11f Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 4 Oct 2024 23:27:05 +0800 Subject: [PATCH] Document the built-in patterns in the Technical Reference section (#3466) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com> Co-authored-by: Michael Grund <23025878+michaelgrund@users.noreply.github.com> --- doc/techref/index.md | 1 + doc/techref/patterns.md | 25 +++++++ examples/gallery/symbols/patterns.py | 101 ++++++++++----------------- 3 files changed, 64 insertions(+), 63 deletions(-) create mode 100644 doc/techref/patterns.md diff --git a/doc/techref/index.md b/doc/techref/index.md index 93dee91fe85..8e0e1f156ce 100644 --- a/doc/techref/index.md +++ b/doc/techref/index.md @@ -10,6 +10,7 @@ visit the {gmt-docs}`GMT Technical Reference `. projections.md fonts.md +patterns.md encodings.md environment_variables ``` diff --git a/doc/techref/patterns.md b/doc/techref/patterns.md new file mode 100644 index 00000000000..17deb045aa3 --- /dev/null +++ b/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) diff --git a/examples/gallery/symbols/patterns.py b/examples/gallery/symbols/patterns.py index 1359fd8f902..a518ac7f034 100644 --- a/examples/gallery/symbols/patterns.py +++ b/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()