Skip to content

Conversation

weiji14
Copy link
Member

@weiji14 weiji14 commented Apr 24, 2021

Description of proposed changes

Start a pygmt.params.Pen convenience class that generates a string which can be passed into GMT's pen (-W) parameter. The Pen class is structured to be under a 'params' folder. Added three basic unit tests to ensure various width/color/style combinations
will be output correctly. Note that this is still a basic implementation, and does not include advanced + modifiers as in https://docs.generic-mapping-tools.org/6.5/plot.html#w.

Preview API docs at https://pygmt-dev--1239.org.readthedocs.build/en/1239/api/generated/pygmt.params.Pen.html

Example code:

import pygmt

# Thick, purple, dashed-dot-dashed border line around some text
pen = pygmt.params.Pen(width="thick", color="purple", style="-.-")
print(pen)
# thick,purple,-.-

fig = pygmt.Figure()
fig.text(x=1, y=1, region=[0, 2, 0, 2], pen=pen, text=pen)
fig.savefig("text_pen.png")
fig.show()

produces:

text_pen

References:

Fixes #1173, part of #1082

Reminders

  • Run make format and make check to make sure the code follows the style guide.
  • Add tests for new features or tests that would have caught the bug that you're fixing.
  • Add new public functions/methods/classes to doc/api/index.rst.
  • Write detailed docstrings for all functions/methods.
  • If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

  • /format: automatically format and lint the code
  • /test-gmt-dev: run full tests on the latest GMT development version

weiji14 added 3 commits April 25, 2021 00:10
Start a `pygmt.param.Pen` convenience class that
generates a string which can be passed into GMT's
pen (-W) parameter. The Pen class is structured to be
under a 'param' folder. Added three basic unit tests
to ensure various width/color/style combinations
will be output correctly.
Placing the API docs for param.Pen under a new
'Parameters' subsection. 'Specifying pen attributes'
documentation is copied from GMT cookbook, with
examples modified to use the PyGMT syntax.
@weiji14
Copy link
Member Author

weiji14 commented Jul 17, 2021

/format

@weiji14 weiji14 modified the milestones: 0.5.0, 0.6.0 Sep 30, 2021
@weiji14 weiji14 modified the milestones: 0.6.0, 0.7.0 Mar 1, 2022
@weiji14 weiji14 modified the milestones: 0.7.0, 0.9.0 Jun 15, 2022
@weiji14 weiji14 removed this from the 0.9.0 milestone Mar 6, 2023
@weiji14 weiji14 changed the title RFC Initial pygmt.param.Pen class for specifying pen attributes Add a Pen class for specifying pen attributes Sep 16, 2025
@weiji14
Copy link
Member Author

weiji14 commented Sep 16, 2025

Reviving this after almost four and a half years! Have refactored things slightly to build on top of #3995.

Now deciding how to handle slightly various pen/-W implementations across different GMT modules:

plus some others too, but too lazy to list them. Thoughts?

@seisman
Copy link
Member

seisman commented Sep 16, 2025

I feel that a pen like 2p,red,- is already very simple, so a Pen class is not necessary for this case. Of course, for more complicated pen and line attributes (https://docs.generic-mapping-tools.org/6.5/reference/features.html#specifying-line-attributes), a Pen class is necessary, and we should implement these modifiers.

As for the module-specific prefix/suffix/modifiers, I think we should leave them to the wrapper instead. For example,

  • coast's -Wlevel/pen may accept a dict like shorelines={1: "2p", 2: "1p,blue,-"}.
  • grdcontour's -W<type> can be implemented into multiple parameters like pen/pen_annot/pen_regular or let pen accept a dict like pen={"annot": "1p,blue", "regular": "2p,red"}.

Comment on lines +47 to +68
color : str
The *color* can be specified in five different ways:

- Gray. Specify a *gray* shade in the range 0-255 (linearly going
from black [0] to white [255]).

- RGB. Specify *r*/*g*/*b*, each ranging from 0-255. Here 0/0/0 is
black, 255/255/255 is white, 255/0/0 is red, etc. Alternatively,
you can give RGB in hexadecimal using the *#rrggbb* format.

- HSV. Specify *hue*-*saturation*-*value*, with the former in the
0-360 degree range while the latter two take on the range 0-1 [17]_.

- CMYK. Specify *cyan*/*magenta*/*yellow*/*black*, each ranging
from 0-100%.

- Name. Specify one of 663 valid color names. See
:gmt-docs:`gmtcolors` for a list of all valid names. A very small
yet versatile subset consists of the 29 choices *white*, *black*, and
[light\|\ dark]{*red, orange, yellow, green, cyan, blue, magenta,
gray\|\ grey, brown*\ }. The color names are case-insensitive, so
mixed upper and lower case can be used (like *DarkGreen*).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The description for color can also be applied to parameters like fill. I guess we can move these paragraphs to a separate page under "Technical Reference" section.

"""
assert str(Pen(width=1)) == "1,,"
assert str(Pen(color="yellow")) == ",yellow,"
assert str(Pen(style="-.-")) == ",,-.-"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want ,,-.- or just -.-?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feature Brand new feature
Projects
Status: In Progress
Development

Successfully merging this pull request may close these issues.

Add individual parameters for pen settings
3 participants