GenericMappingTools / GenericMappingTools/gmt
Discussion: Improve -B for GMT 6 via long-format options
- Dominant language
- C
- Stars
- 979
- Forks
- 414
- Avg merge
- 17h 26m
- Merged PRs (30d)
- 54
Description
The complicated **-B** option has been with us since GMT 1. In GMT 5 we broke it up into several **-B** options that set different aspects of basemap specifications. However, it remains a very busy and unclear option. Let us see what needs to be set when a basemap is required in GMT:
**1. The Canvas/Frame**
- Which axes to plot and how (via combination of codes WESNwesnlrbtZzu) [Default is MAP_FRAME_AXES]
- Optionally paint canvas with uniform color (via **+g**_fill_) [No fill]
- Optionally add plot title (via **+t**"my title") [no title]
- Optionally suppress all frames and annotations (via **+n**)
- For geographically oblique gridlines from another pole (via **+o**_lon/lat_) [North pole; Rare usage]
- For 3-D plots, we may wish to outline the 3-D box and see x-z, y-z gridlines, if selected (via **+b**) [no box]
**2. Axes**
Each of the axes we selected have many sub-settings. Furthermore, there are potentially two separate annotation/tick/gridline systems per axis: **p** - primary (Default, closest to axis) and **s** - secondary (farther from axis). Each system has many settings:
- annotation interval (a)
- tick interval (f)
- gridline interval (g)
- annotation prefix prepended to annotations (**+p**)
- annotation unit appended to annotations (**+u**)
- Axis label (**+l|L**)
- Secondary axis label (**+s|S**) if different
**3. Intervals**
- Intervals (e.g., annotation, tick, gridline) have settings too. By default they are placed at integer multiples of the given interval, but this placement can be phase-shifted by adding +|-_phase_ [0].
- Intervals take units and these may scale the interval but may also imply how numbers might be formatted (mostly applies to time axes).
- Some intervals can be given as multiples or fractions of pi which means the pi symbol (and factors/fractions) are used in the annotations.
- For log10 axis the intervals can be 1,2,3 or even negative; codes **p** and **l** imply different formatting.
- For power axis code **p** implies different formatting.
- For custom annotations a **c** is given instead of a,f,g (the file will have these settings).
**Draft proposal for discussion:**
Introduce additional long-format --option=* options to clarify how to give basemap specifics. They do not replace **-B** but can be used instead of **-B**. Like the other long-format options (#230) they will be available to both classic and modern mode.
1. Canvas/frame:
- **--frame**=|none[**+fill**=_fill_][**+pole**=_lon/lat_]
- Break out separate **--title**=_title_
2. Axis: (below, _int_ can be none, auto, a numerical value with optional appended unit character, or name of file with custom annotations, tickmarks, and gridspacings)
The first set apply to the primary (or only) axes system:
- **--annotations**=_int_[**+phase**=_phase_][**+prefix**=_txt_][**+unit**=_unit_]
- **--ticks**=_int_[**+unit**=_unit_][**+phase**=_phase_]
- **--gridlines**=_int_[**+unit**=_unit_][**+phase**=_phase_] Default is none
The second set apply to the secondary axes system:
- **--secondary-annotations**=_int_[**+phase**=_phase_][**+prefix**=_txt_][**+unit**=_unit_]
- **--secondary-ticks**=_int_[**+unit**=_unit_][**+phase**=_phase_]
- **--secondary-gridlines**=_int_[**+unit**=_unit_][**+phase**=_phase_] Default is none
There is only one label per axis but the E, N, U axes could have an "other" label:
- **--xlabel**=_xlabel_
- **--ylabel**=_ylabel_
- **--zlabel**=_zlabel_
- **--other-xlabel**=_xlabel_
- **--other-ylabel**=_ylabel_
- **--other-zlabel**=_zlabel_
The labels are given their own long option per axis to avoid difficulties in parsing free-form text separated by slashes (which could be part of the text); this is also why **--title** is a separate option.
The defaults are the same as before but needs a trigger **--frame**=default (like **-Baf** is needed today):
**--frame**=
**--annotations**=auto
**--ticks**=auto
**--gridlines**=none
There is some duplications here: **--frame**=none is the same as **--annotations**=none **--ticks**=none
A few simple examples:
```
-Baf
-BWSne+gred -Baf
-Bx30f10g5 -By2f1
-B+glightgray+t"My plot" -Bxaf+l"X-axis" -Byaf+l"Y-axis"
```
would become
```
--frame=default
--frame=WSen+fill=red
--annotations=30/2 --ticks=10/1 --gridlines=5/none
--frame=default+fill=lightgray --xlabel="X-axis" --ylabel="Y-axis" --title="My plot"
```
Pre-parsing of these long-format options in gmt_init_module will result in a series of corresponding short **-B** options that the standard GMT parser can handle.
Note that external interfaces may break these down further (e.g., 'x-annotations', [1 3 15 19]) but can then concatenate these separate axis settings to the required --annotations=argument format.
Please give feedback on the chosen long-options and suggest improvements. The goal is to converge on the right set of long-format options and house the parsing of these in the C API and thus relieve the external interfaces from doing tedious parsing when preparing calls to GMT via GMT_Call_Module.
Contributor guide
Assessment
This issue has not been assessed yet.