Skip to content

Add the Frame/Axis class for setting frame and axes [Part 1]#4406

Merged
seisman merged 23 commits intomainfrom
class/frame-part1
Mar 9, 2026
Merged

Add the Frame/Axis class for setting frame and axes [Part 1]#4406
seisman merged 23 commits intomainfrom
class/frame-part1

Conversation

@seisman
Copy link
Member

@seisman seisman commented Feb 10, 2026

This PR implements the Frame/Axis class for setting frame and axes attributes. It's a subset of PR #4016 because the -B option is complicated, and it will take a long time to finish #4016, which again will delay the paper submission.

Currently, only a small subset of the -B option is implemented in this PR, but it should already cover most use cases.

Here is a comparison table between the GMT CLI and the PyGMT versions:

GMT PyGMT
-B frame=True
-BWSEN frame=Frame("WSEN") or frame=Frame(axes="WSEN")
-BWSEN+tMY TITLE frame=Frame("WSEN", title="MY TITLE")
-Ba frame=Axis(annnot=True)
-Bafg frame=Axis(annot=True, tick=True, grid=True)
-Ba30f15g5 frame=Axis(annot=30, tick=15, grid=5)
-Ba30f15g5+lLABEL frame=Axis(annot=30, tick=15, grid=5, label="LABEL")
-BWSEN+tTITLE -Bxa30f15g5+lXlabel -Bya4f2g1+lYlabel frame=Frame("WSEN", title="TITLE", xaxis=Axis(annot=30, tick=15, grid=5, label="Ylabel"), yaxis=Axis(annot=4, tick=4, grid=1, label="Ylabel"))

This PR doens't break backward-compatibility, so frame="WSEN", frame="afg", frame="a30f15g5", frame=["WSEN+tTITLE", "xafg", "yafg"] are still supported.

Preview:

@seisman seisman added enhancement Improving an existing feature feature Brand new feature and removed enhancement Improving an existing feature labels Feb 10, 2026
@seisman seisman added this to the 0.19.0 milestone Feb 10, 2026
@seisman seisman added the needs review This PR has higher priority and needs review. label Feb 10, 2026
@seisman seisman requested a review from a team February 25, 2026 05:06
@seisman seisman removed the needs review This PR has higher priority and needs review. label Mar 6, 2026
@seisman seisman added the final review call This PR requires final review and approval from a second reviewer label Mar 6, 2026
>>> fig.basemap(
... region=[0, 10, 0, 20],
... projection="X10c/10c",
... frame=Axis(annot=4, tick=2, grid=1),
Copy link
Member

Choose a reason for hiding this comment

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

The "long" version would be
frame=Frame(axis=Axis(annot=4, tick=2, grid=1))
?

Copy link
Member Author

Choose a reason for hiding this comment

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

yes

Copy link
Member

@weiji14 weiji14 left a comment

Choose a reason for hiding this comment

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

Nice and focused start, just some comments for now.

Alias(self.annot, name="annot", prefix="a"),
Alias(self.tick, name="tick", prefix="f"),
Alias(self.grid, name="grid", prefix="g"),
Alias(self.label, name="label", prefix="+l"),
Copy link
Member

Choose a reason for hiding this comment

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

How to alias +L "forces a horizontal label for y-axes, which is useful for very short labels" (https://docs.generic-mapping-tools.org/6.6/gmt.html#axes-settings) later?

Copy link
Member Author

Choose a reason for hiding this comment

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

I plan to alias it to hlabel. See #4016 for the proposed full aliases.

seisman and others added 2 commits March 7, 2026 13:24
Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>
@seisman
Copy link
Member Author

seisman commented Mar 8, 2026

@GenericMappingTools/pygmt-maintainers I plan to merge this PR tomorrow, so please give this PR a final review.


Examples
--------
To specify the same attributes for all axes, with intervals of 4 for annotations,
Copy link
Member

Choose a reason for hiding this comment

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

Wondering, if all four sides (WSEN) or only the west/left and south/bottom sides (WSrt) have annotations and ticks.

Copy link
Member Author

Choose a reason for hiding this comment

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

Axis controls annotation/tick/gridline settings for x- and y-axes, while WSEN/WSrt further controls if a specific axis need annotation/tick/grdiline. I've rephrase the docstring and hopefully can make it clear.

seisman and others added 2 commits March 9, 2026 10:14
Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>
@seisman seisman removed final review call This PR requires final review and approval from a second reviewer high-priority labels Mar 9, 2026
@seisman seisman merged commit 5e1ed53 into main Mar 9, 2026
19 of 22 checks passed
@seisman seisman deleted the class/frame-part1 branch March 9, 2026 02:30
@github-project-automation github-project-automation bot moved this from In Progress to Done in Pythonic GMT arguments Mar 9, 2026
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: Done

Development

Successfully merging this pull request may close these issues.

3 participants