Frame/Axis classes for frame settings to wrap GMT's -B option

[seisman]

Summary

This issue tracks the implementation of Frame and Axis classes in PyGMT as a structured wrapper around GMT’s -B option. The goal is to provide a Pythonic API for frame settings while preserving compatibility with existing frame usage.

Documentation

• GMT -B: https://docs.generic-mapping-tools.org/dev/gmt.html#b-full
• PyGMT Frame: https://www.pygmt.org/dev/api/generated/pygmt.params.Frame.html
• PyGMT Axis: https://www.pygmt.org/dev/api/generated/pygmt.params.Axis.html

Motivation

GMT’s -B syntax is powerful but hard to read and discover in Python code. For example:

frame=["WStr+tTitle", "xa2f1g2+lxlabel", "ya5f1g5+lylabel"]

A structured API would improve readability, discoverability, validation, testing, and documentation. We decide to implement two classes, Frame and Axis, to control the frame and axis settings. An example usage is like below:

from pygmt.params import Axis, Frame

frame = Frame(
    axes="WStr",
    title="Title",
    xaxis=Axis(annot=2, tick=1, grid=2, label="xlabel"),
    yaxis=Axis(annot=5, tick=1, grid=5, label="ylabel"),
)

Checklist

Axis

The GMT CLI syntax is

-B[p|s][x|y|z]intervals[+aangle|n|p][+e[l|u]][+f][+l|Llabel][+pprefix][+s|Sseclabel][+uunit]

in which intervals is in the form of [a|f|g][stride][phase][unit].

• a: annot, set annotation interval Add the Frame/Axis class for setting frame and axes #4406
• f: tick, set tick interval Add the Frame/Axis class for setting frame and axes #4406
• g: grid, set gridline interval Add the Frame/Axis class for setting frame and axes #4406
• +p: prefix, set annotation prefix text Add the Frame/Axis class for setting frame and axes #4406
• +u: unit, append annotation unit text Add the Frame/Axis class for setting frame and axes #4406
• +a: angle, set annotation angle Add the Frame/Axis class for setting frame and axes #4406
  • +aangle Add the Frame/Axis class for setting frame and axes #4406
  • +an|p
• +e params.Axis: Add parameter "end_skip" to skip annotations at ends of axis #4593
• +f
• +l: label, set axis label text Add the Frame/Axis class for setting frame and axes #4406
• +L: hlabel set horizontal label for y-axis params.Axis: Add parameters hlabel/alt_label/alt_hlabel for more controls of axis labels #4589
• +s: alt_label: set alternative label for upper or right axis params.Axis: Add parameters hlabel/alt_label/alt_hlabel for more controls of axis labels #4589
• +S: alt_label: set horizontal label for right axis params.Axis: Add parameters hlabel/alt_label/alt_hlabel for more controls of axis labels #4589
• -B0
• -B00
• -B000

In GMT, there are primary and secondary x-, y-, and z-axis.

• axis: apply the same primary axis settings to x/y axes Add the Frame/Axis class for setting frame and axes #4406
• axis2: apply the same secondary axis settings to x/y axes params.Frame: Support for setting up secondary axis for both x- and y-axis #4583
• xaxis/xaxis2/yaxis/yaxis2/zaxis/zaxis2: configure the primary/secondary x/y/z-axis separately Add the Frame/Axis class for setting frame and axes #4406

Frame

The GMT CLI syntax is:

-B[axes][+b][+gfill][+i[val]][+n][+olon/lat][+ssubtitle][+ttitle][+w[pen]][+xfill][+yfill][+zfill]

• axes: Combinations of WESNZwesnzlrbtu to specify the axes to draw. Add the Frame/Axis class for setting frame and axes #4406
• +b: box params.Frame: Add parameters for 3-D plots #4594
• +g: fill, set the frame interior fill params.Frame: Add parameters 'fill' for filling the base map #4520
• +i
• +o
• +s: subtitle plot subtitle params.Frame: Add subtitle support #4591
• +t: title, set the frame title Add the Frame/Axis class for setting frame and axes #4406
• +w: wall_pen params.Frame: Add parameters for 3-D plots #4594
• +x: yzfill params.Frame: Add parameters for 3-D plots #4594
• +y: xzfill params.Frame: Add parameters for 3-D plots #4594
• +z: xyfill params.Frame: Add parameters for 3-D plots #4594

Other use cases

• frame=True: keep the simple shortcut for automatic annotations
• frame="none": mapped to -B+n Pythonic implemention of the frame="+n" setting #4403

Related PRs

• Add the Frame/Axis class for setting frame and axes #4406
• params.Frame: Allow setting 'axis' and 'zaxis' simultaneously #4498
• params.Frame: Support for setting up secondary axis for both x- and y-axis #4583
• WIP: Add the Axis and Frame classes for the frame parameter #4016
• Implement the frame='none' syntax for no frames #4404

Related issues

• Better way to configure axis (instead of B/frame) #249
• Pythonic implemention of the frame="+n" setting #4403