Add the Pattern class for specifying bit and hachure patterns to fill symbols and polygons #4020

seisman · 2025-07-27T09:52:09Z

This PR implements the Pattern class, which is a more Pythonic syntax to specify patterns as fill.

The GMT upstream documentation is at https://docs.generic-mapping-tools.org/dev/reference/features.html#specifying-area-fill-attributes.

The GMT CLI syntax is: -GP|ppattern[+bcolor][+fcolor][+rdpi]

The PyGMT parameters are

pattern: pattern
P or p: invert
+b: bgcolor
+f: fgcolor
+r: dpi

Examples:

Pattern(10)
Pattern(10, bgcolor="red", fgcolor="blue", dpi=200, invert=True)

Preview:

Changes in this PR:

Implement the Pattern class
Add Pattern to doc/api/index.rst
Add tests
Update examples that use pattern as fills
Update gallery example examples/gallery/symbols/patterns.py
Remove the unnecessary documentation doc/techref/patterns.md

Closes #2438, closes #2323

seisman · 2025-09-08T15:13:00Z

doc/techref/patterns.md

@@ -1,25 +0,0 @@
-# Bit and Hachure Patterns


This documentation describes the syntax for GMT CLI, which no longer makes sense. with the Pattern class, so this file will be deleted in this PR.

The image for the 90 predefined patterns will be shown at https://pygmt-dev--4020.org.readthedocs.build/en/4020/api/generated/pygmt.params.Pattern.html

Debating on whether to use https://github.com/sphinx-doc/sphinxext-rediraffe to add a redirect for this 🤔

seisman · 2025-09-08T15:26:00Z

pygmt/params/pattern.py

+
+    Parameters
+    ----------
+    id


For this parameter, is id good? Or should we use pattern?

I would use pattern, as it looks like that id is already reserved by Python for something else.

Changed in f627d28.

seisman · 2025-09-08T15:32:03Z

pygmt/params/pattern.py

+        [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


reversed, inversed, inverted (or invert), which one is better?

GMT and GMT.jl use the word invert for image's -I option.

https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/image/

https://github.com/GenericMappingTools/gmt/blob/3f87eb0da19e76260cd5582e3256891dfe6a0ae2/src/longopt/psimage_inc.h#L40

I think I like invert. For me, it describes better that the fore- and background colors of the pattern are flipped, and it is shorter than inverted.

Changed in 28be123.

examples/gallery/symbols/patterns.py

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

yvonnefroehlich · 2025-09-09T12:48:58Z

examples/gallery/symbols/patterns.py

-# By default, the pattern is plotted in black and white with a resolution of 300 dpi.
+# By default, a pattern is plotted in black and white with a resolution of 1200 dpi.


Did the default change from 300 dpi to 1200 dpi? Or was 300 dpi wrong / a typo?

The upstream documentation says 1200, but the source code says 300. Actually it's a typo in the upstream documentation. See PR GenericMappingTools/gmt#8789 for details.

Fixed in e9eca8e.

weiji14 · 2025-09-24T22:15:46Z

examples/tutorials/advanced/cartesian_histograms.py

+    # Fill bars with GMT pattern 8, with white background and black foreground.
+    fill=Pattern(8, bgcolor="white", fgcolor="black"),


At L149 above, could you add an intersphinx link to :class:`pygmt.params.Pattern` ? Then we can properly close #2323.

You meant L179, right? Done in 5774b35.

weiji14

Looks great overall, approving with some very minor comments.

weiji14 · 2025-09-25T21:41:44Z

doc/techref/patterns.md

@@ -1,25 +0,0 @@
-# Bit and Hachure Patterns


Debating on whether to use https://github.com/sphinx-doc/sphinxext-rediraffe to add a redirect for this 🤔

weiji14 · 2025-09-25T21:44:40Z

pygmt/params/pattern.py

+          images using image raster files.
+    dpi
+        Resolution of the pattern in dots per inch (DPI) [Default is 300].
+    bgcolor/fgcolor


Type hints for these not showing in the docs. Does it matter?

I tried to make it work but was not successful.

weiji14 · 2025-09-25T21:53:53Z

examples/tutorials/advanced/focal_mechanisms.py

+    compressionfill=Pattern(8),
+    extensionfill=Pattern(31),


Just want to flag that we need to remember to update the type-hints for various *fill parameters to include pygmt.params.Pattern later.

seisman force-pushed the AliasSystem/params/base branch from 311c83f to 926a690 Compare July 29, 2025 04:39

seisman force-pushed the feature/pattern branch from 19c1e1f to 5816270 Compare July 29, 2025 04:40

seisman force-pushed the feature/pattern branch from 5816270 to 89020a2 Compare September 7, 2025 15:01

seisman added the feature Brand new feature label Sep 7, 2025

seisman force-pushed the feature/pattern branch from 89020a2 to 1571b19 Compare September 7, 2025 15:31

Base automatically changed from AliasSystem/params/base to main September 8, 2025 03:39

seisman added 5 commits September 8, 2025 18:20

Implement the Pattern class for specifying pattern as fills

1fd9d4a

Add tests for the Pattern class

30d6b92

Use the Pattern class in examples

db82469

Improve the gallery example for patterns

3031c59

Remove unnecessary content from the techref for patterns

ed1ba89

seisman force-pushed the feature/pattern branch from 1571b19 to ed1ba89 Compare September 8, 2025 10:20

seisman added 2 commits September 8, 2025 18:36

Improve docstrings

57e9c4e

Remove the doc/techref/patterns.md doc

3ba2006

seisman changed the title ~~WIP: Add the Pattern class~~ Add the Pattern class for specifying bit and hachure patterns to fill symbols and polygons Sep 8, 2025

seisman added 6 commits September 8, 2025 18:51

Fix a typo in URL

5dfa0d2

Smaller image size

0ca48c6

Fix a typo in examples/gallery/symbols/patterns.py

43bf9ff

Use the figure directive

2a18366

Polish examples/gallery/symbols/patterns.py

5cda812

Fix the text for each pattern

dcbcaa8

seisman added this to the 0.17.0 milestone Sep 8, 2025

seisman added 2 commits September 8, 2025 23:15

Fix the image width to show the pattern string

ff3419c

Validate that fgcolor and fgcolor cannot both be empty

1b17ab0

seisman commented Sep 8, 2025

View reviewed changes

Fix styling

994c3be

seisman marked this pull request as ready for review September 8, 2025 15:32

seisman added the needs review This PR has higher priority and needs review. label Sep 8, 2025

seisman requested a review from Copilot September 9, 2025 02:39

seisman added 4 commits September 9, 2025 17:09

Rename id to pattern

f627d28

Rename reversed to invert

28be123

One more fix for reverse->invert

a8af0e7

Merge branch 'main' into feature/pattern

56bbf3c

yvonnefroehlich reviewed Sep 9, 2025

View reviewed changes

examples/gallery/symbols/patterns.py Outdated Show resolved Hide resolved

Fix a typo

74da7a8

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

yvonnefroehlich reviewed Sep 9, 2025

View reviewed changes

seisman added 3 commits September 9, 2025 21:17

DOC: Fix the default resolution from 1200 to 300 for patterns

e9eca8e

Polish docstrings

43036c5

Merge branch 'main' into feature/pattern

4431649

seisman requested a review from a team September 10, 2025 12:16

seisman added 3 commits September 13, 2025 22:50

Merge branch 'main' into feature/pattern

1b453a9

Merge branch 'main' into feature/pattern

938b5fb

Merge branch 'main' into feature/pattern

b2b1250

seisman mentioned this pull request Sep 18, 2025

Release PyGMT v0.17.0 #4100

Closed

43 tasks

seisman added 4 commits September 18, 2025 21:47

Merge branch 'main' into feature/pattern

6dfff08

Merge branch 'main' into feature/pattern

e715fdb

Merge branch 'main' into feature/pattern

806c912

Merge branch 'main' into feature/pattern

61dedd2

seisman mentioned this pull request Sep 24, 2025

Gallery example for histogram/plot showing bit and hachure patterns #2323

Closed

weiji14 reviewed Sep 24, 2025

View reviewed changes

seisman added 2 commits September 25, 2025 07:44

Add intersphinx link to Pattern

5774b35

Merge branch 'main' into feature/pattern

8131163

weiji14 approved these changes Sep 25, 2025

View reviewed changes

weiji14 mentioned this pull request Sep 25, 2025

Tracking issue for AliasSystem migration and param class additions #4122

Open

seisman merged commit bd1dd63 into main Sep 26, 2025
22 of 24 checks passed

seisman deleted the feature/pattern branch September 26, 2025 01:05

seisman removed the needs review This PR has higher priority and needs review. label Sep 26, 2025

seisman added a commit that referenced this pull request Sep 26, 2025

Add PR #4020 [skip ci]

3ce82da

weiji14 mentioned this pull request Oct 1, 2025

pygmt.params.Pattern: Set default pattern value to 1 plus extra validation checks #4134

Merged

6 tasks

		# By default, the pattern is plotted in black and white with a resolution of 300 dpi.
		# By default, a pattern is plotted in black and white with a resolution of 1200 dpi.

		# Fill bars with GMT pattern 8, with white background and black foreground.
		fill=Pattern(8, bgcolor="white", fgcolor="black"),

Uh oh!

Add the Pattern class for specifying bit and hachure patterns to fill symbols and polygons #4020

Add the Pattern class for specifying bit and hachure patterns to fill symbols and polygons #4020

Uh oh!

Conversation

seisman commented Jul 27, 2025 • edited by weiji14 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seisman Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weiji14 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

seisman commented Jul 27, 2025 •

edited by weiji14

Loading

seisman Sep 9, 2025 •

edited

Loading