Figure.colorbar: Plot gray scale or color scale bar

[seisman]

This issue serves as the central place for discussing and tracking the implementation of the colorbar method in PyGMT. The issue will be closed when the initial implementation is complete. Progress is tracked at PyGMT: Wrapping GMT modules.

Documentation

• GMT: https://docs.generic-mapping-tools.org/dev/colorbar.html
• GMT.jl: https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/colorbar
• PyGMT: https://www.pygmt.org/dev/api/generated/pygmt.Figure.colorbar.html

GMT Option Flags and Modifiers

☑️: Implemented; ⬜: To be implemented/discussed; Strikethrough: Won't implement.

• -R: region
• -J: projection
• -B: frame
• -C: cmap
• -D: position/length/width/orientation/reverse/...
• -F: box
• -G: truncate
• -I: shading
• -L
• -M: monochrome Figure.colorbar: Add alias 'monochrome' for option '-M' #4499
• -N: dpi Figure.colorbar: Add alias 'dpi' for the -N option #4501
• -Q: log Figure.colorbar: Migrate the log/scale parameters to the new alias system #4244
• -S
• -U: Use Figure.timestamp instead.
• -V: verbose
• -W: scale Figure.colorbar: Migrate the log/scale parameters to the new alias system #4244
• -X/-Y: Use Figure.shift_origin instead.
• -Z
• -c: panel
• -p: perspective
• -t: transparency
• --PAR=value: Use pygmt.config instead.

Linked Pull Requests

• Initial feature implementation
• Add a tutorial or gallery example

Related Issues and Discussions

Add links to related wrapper discussions, API design threads, or upstream GMT changes here.

[seisman]

For a colorbar, the annotations and labels can be set by either the -B option (can't be used with -L) or the -S option (a simplified version of the -B option).

The -B option is one of the most complicated GMT options, but most -B settings do not affect the colorbar. For example, -BWSEN+tTITLE doesn't work. As far as I can see, the -B syntax that has an effect for a colorbar is

-Bxintervals[+aangle][+llabel][+pprefix][+uunit]
-By+llabel

Here, the x-axis and y-axis represent the long and short dimensions, respectively, so the y-axis only has a label. One common use case is -Bxa10f5+l"Focal Depth" -By+l"km".

The current PyGMT syntax is frame=["xa10f5+lFocal Depth", "y+lkm"]. After the implementation of the Frame/Axis classes (PR #4406), it will be

frame=Frame(xaxis=Axis(annot=10, tick=5, label="Focal Depth"), yaxis=Axis(label="km")

However, it still appears complicated and imperfect. What about splitting it into separate parameters

• xlabel/ylabel (colorbar docs calls them label/unit): labels for x- and y-axis
• annot, tick, grid: intervals for the annotations, ticks and grids
• angle/prefix/unit or annot_angle/annot_prefix/annot_unit(or annot_suffix) for controlling the annotations.

The new syntax would be annot=10, tick=5, xlabel="Focal Depth", ylabel="km". Internally, we need to convert these parameters into the Frame/Axis class and pass it to the frame parameter.

Here is a comparison between different versions:

Version	Example
GMT	-Bxa10+l"Focal Depth" -By+l"km"
PyGMT v0.18.0	frame=["xa10f5+lFocal Depth", "y+lkm"]
After PR #4406	frame=Frame(xaxis=Axis(annot=10, tick=5, label="Focal Depth"), yaxis=Axis(label="km")
The new implemention	annot=10, tick=5, xlabel="Focal Depth", ylabel="km"

As mentioned above, the -S option is a simplified version of the -B option, which can work when the -L option is used. Its syntax is like -S[+aangle][+c|n][+r][+s][+xlabel][+yunit]. It can also set the annotation angle, x-label, and y-label (it's called unit in GMT but I think it's a mistake). So the option can also be split into multiple parameters, e.g., annot_angle, annot_custom, annot_numerical, annot_minmax, no_gridlines, label, unit. We can decide if annot_angle/label/unit should be converted to -B or -S, depending on if -L is used.

[weiji14]

Something to think about: Whether to add an option in Figure.colorbar to plot a circular colorbar based on some examples in #3638. (we can continue discussing in #3638 since this issue is closed).