GenericMappingTools / GenericMappingTools/gmt

Discussion: Improve -B for GMT 6 via long-format options

Open
#254 5 comments 0 reactions 0 assignees View on GitHub
discussion
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.