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

[seisman]

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:

• https://pygmt-dev--4020.org.readthedocs.build/en/4020/api/generated/pygmt.params.Pattern.html
• https://pygmt-dev--4020.org.readthedocs.build/en/4020/gallery/symbols/patterns.html
• https://pygmt-dev--4020.org.readthedocs.build/en/4020/tutorials/advanced/focal_mechanisms.html
• https://pygmt-dev--4020.org.readthedocs.build/en/4020/tutorials/basics/polygons.html
• https://pygmt-dev--4020.org.readthedocs.build/en/4020/gallery/symbols/patterns.html

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.

[seisman]

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

[seisman]

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

[yvonnefroehlich]

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

[seisman]

Changed in f627d28.

[seisman]

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

[yvonnefroehlich]

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.

[seisman]

Changed in 28be123.

[Copilot]

Pull Request Overview

This PR introduces the Pattern class, providing a Pythonic interface for specifying bit and hachure patterns to fill symbols and polygons in PyGMT, replacing the previous string-based pattern syntax.

• Implements a new Pattern dataclass with validation for pattern IDs, colors, and resolution
• Updates examples and documentation to use the new class instead of string patterns
• Removes outdated technical reference documentation about pattern strings

Reviewed Changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pygmt/params/pattern.py	Core Pattern class implementation with validation and GMT string generation
pygmt/tests/test_params_pattern.py	Comprehensive test suite for Pattern class functionality
pygmt/params/init.py	Exports Pattern class from params module
examples/tutorials/basics/polygons.py	Updates documentation reference from patterns to Pattern class
examples/tutorials/advanced/focal_mechanisms.py	Replaces string patterns with Pattern class instances
examples/tutorials/advanced/cartesian_histograms.py	Updates histogram fill to use Pattern class
examples/gallery/symbols/patterns.py	Major refactor demonstrating Pattern class usage
doc/techref/patterns.md	Removes outdated pattern string documentation
doc/techref/index.md	Removes reference to deleted patterns.md
doc/api/index.rst	Adds Pattern to API documentation

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[yvonnefroehlich]

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

[seisman]

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.