Wrap colorbar

Initial commit for wrapping the colorbar function raised first at #109 but also #231, to be implemented under base_plotting.py alongside the other mapping related stuff. Original GMT `colorbar` documentation can be found at https://docs.generic-mapping-tools.org/latest/colorbar.html.

Storing sample test cases under test_colorbar.py. Current implementation has an alias for position (D) which is arguably the most important one. and the one we've focused writing the tests for. Also wrapped around common aliases region (R), projection (J), frame (B) and cmap (C).

Author: weiji14

doc/api/index.rst

@@ -24,6 +24,7 @@ Plotting data and laying out the map:
 
     Figure.basemap
     Figure.coast
+    Figure.colorbar
     Figure.plot
     Figure.contour
     Figure.grdcontour

pygmt/base_plotting.py

@@ -125,6 +125,49 @@ def coast(self, **kwargs):
         with Session() as lib:
             lib.call_module("coast", build_arg_string(kwargs))
 
+    @fmt_docstring
+    @use_alias(R="region", J="projection", B="frame", C="cmap", D="position")
+    @kwargs_to_strings()
+    def colorbar(self, **kwargs):
+        """
+        Plot a gray or color scale-bar on maps.
+
+        Both horizontal and vertical scales are supported. For CPTs with gradational
+        colors (i.e., the lower and upper boundary of an interval have different colors)
+        we will interpolate to give a continuous scale. Variations in intensity due to
+        shading/illumination may be displayed by setting the option -I. Colors may be
+        spaced according to a linear scale, all be equal size, or by providing a file
+        with individual tile widths.
+
+        Full option list at :gmt-docs:`colorbar.html`
+
+        Parameters
+        ----------
+        position (D) : str
+            ``[g|j|J|n|x]refpoint[+wlength[/width]][+e[b|f][length]][+h|v][+jjustify]
+            [+m[a|c|l|u]][+n[txt]][+odx[/dy]]``.
+            Defines the reference point on the map for the color scale using one of four
+            coordinate systems:
+            (1) Use -Dg for map (user) coordinates,
+            (2) use -Dj or -DJ for setting refpoint via a 2-char justification code that
+            refers to the (invisible) map domain rectangle,
+            (3) use -Dn for normalized (0-1) coordinates, or
+            (4) use -Dx for plot coordinates (inches, cm, etc.).\
+            All but -Dx requires both -R and -J to be specified.
+            Append +w followed by the length and width of the color bar.
+            If width is not specified then it is set to 4% of the given length.
+            Give a negative length to reverse the scale bar.
+            Append +h to get a horizontal scale [Default is vertical (+v)].
+            By default, the anchor point on the scale is assumed to be the bottom left
+            corner (BL), but this can be changed by appending +j followed by a 2-char
+            justification code justify.
+
+        {aliases}
+        """
+        kwargs = self._preprocess(**kwargs)
+        with Session() as lib:
+            lib.call_module("colorbar", build_arg_string(kwargs))
+
     @fmt_docstring
     @use_alias(
         A="annotation",

pygmt/tests/baseline/test_colorbar_positioned_using_justification_code.png

@@ -0,0 +1,59 @@
+"""
+Tests colorbar
+"""
+import pytest
+
+from .. import Figure
+
+
+@pytest.mark.mpl_image_compare
+def test_colorbar_using_paper_coordinates():
+    """
+    Create colorbar positioned at 0cm,0cm with length 1cm and width 0.5cm.
+    """
+    fig = Figure()
+    fig.colorbar(cmap="rainbow", position="x0c/0c+w1c/0.5c")
+    return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_colorbar_using_paper_coordinates_horizontal():
+    """
+    Create colorbar positioned at 0cm,0cm with length 2cm oriented horizontally.
+    """
+    fig = Figure()
+    fig.colorbar(cmap="rainbow", position="x0c/0c+w2c+h")
+    return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_colorbar_positioned_using_map_coordinates():
+    """
+    Create colorbar positioned at latitude,longitude 3,6 with length 2cm.
+    """
+    fig = Figure()
+    fig.basemap(region=[2, 4, 6, 8], projection="t0/2c", frame=True)
+    fig.colorbar(cmap="rainbow", position="g3/6+w2c")
+    return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_colorbar_positioned_using_justification_code():
+    """
+    Create colorbar positioned at Top Center inside the map frame with length 2cm.
+    """
+    fig = Figure()
+    fig.basemap(region=[2, 4, 6, 8], projection="t0/2c", frame=True)
+    fig.colorbar(cmap="rainbow", position="jTC+w2c")
+    return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_colorbar_positioned_using_normalized_coords():
+    """
+    Create colorbar positioned at normalized coordinates 0.75,0.25 with length 2cm.
+    """
+    fig = Figure()
+    fig.basemap(region=[2, 4, 6, 8], projection="t0/2c", frame=True)
+    fig.colorbar(cmap="rainbow", position="n0.75/0.25+w2c")
+    return fig