Add common alias perspective (p) for plotting 3D illustrations (#627)

Used to select a perspective view by setting the
azimuth and elevation angle of the viewpoint.
See https://docs.generic-mapping-tools.org/6.1/gmt.html#perspective-full
and https://docs.generic-mapping-tools.org/6.1/cookbook/options.html#perspective-view-the-p-option

Author: weiji14

pygmt/base_plotting.py

@@ -70,9 +70,10 @@ def _preprocess(self, **kwargs):  # pylint: disable=no-self-use
         U="timestamp",
         X="xshift",
         Y="yshift",
+        p="perspective",
         t="transparency",
     )
-    @kwargs_to_strings(R="sequence")
+    @kwargs_to_strings(R="sequence", p="sequence")
     def coast(self, **kwargs):
         """
         Plot continents, shorelines, rivers, and borders on maps
@@ -132,6 +133,7 @@ def coast(self, **kwargs):
             ``'[level/]pen'``
             Draw shorelines [Default is no shorelines]. Append pen attributes.
         {XY}
+        {p}
         {t}
 
         """
@@ -151,9 +153,10 @@ def coast(self, **kwargs):
         W="scale",
         X="xshift",
         Y="yshift",
+        p="perspective",
         t="transparency",
     )
-    @kwargs_to_strings(R="sequence", G="sequence")
+    @kwargs_to_strings(R="sequence", G="sequence", p="sequence")
     def colorbar(self, **kwargs):
         """
         Plot a gray or color scale-bar on maps.
@@ -214,6 +217,7 @@ def colorbar(self, **kwargs):
             Multiply all z-values in the CPT by the provided scale. By default
             the CPT is used as is.
         {XY}
+        {p}
         {t}
 
         """
@@ -237,9 +241,10 @@ def colorbar(self, **kwargs):
         l="label",
         X="xshift",
         Y="yshift",
+        p="perspective",
         t="transparency",
     )
-    @kwargs_to_strings(R="sequence", L="sequence", A="sequence_plus")
+    @kwargs_to_strings(R="sequence", L="sequence", A="sequence_plus", p="sequence")
     def grdcontour(self, grid, **kwargs):
         """
         Convert grids or images to contours and plot them on maps
@@ -295,6 +300,7 @@ def grdcontour(self, grid, **kwargs):
             to be of the format [*annotcontlabel*][/*contlabel*]. If either
             label contains a slash (/) character then use ``|`` as the
             separator for the two labels instead.
+        {p}
         {t}
         """
         kwargs = self._preprocess(**kwargs)
@@ -320,10 +326,11 @@ def grdcontour(self, grid, **kwargs):
         C="cmap",
         X="xshift",
         Y="yshift",
+        p="perspective",
         t="transparency",
         x="cores",
     )
-    @kwargs_to_strings(R="sequence")
+    @kwargs_to_strings(R="sequence", p="sequence")
     def grdimage(self, grid, **kwargs):
         """
         Project grids or images and plot them on maps.
@@ -339,6 +346,7 @@ def grdimage(self, grid, **kwargs):
         grid : str or xarray.DataArray
             The file name of the input grid or the grid loaded as a DataArray.
         {XY}
+        {p}
         {t}
         {x}
 
@@ -370,10 +378,10 @@ def grdimage(self, grid, **kwargs):
         Wc="contourpen",
         Wm="meshpen",
         Wf="facadepen",
-        p="perspective",
         I="shading",
         X="xshift",
         Y="yshift",
+        p="perspective",
         t="transparency",
     )
     @kwargs_to_strings(R="sequence", p="sequence")
@@ -438,10 +446,6 @@ def grdview(self, grid, **kwargs):
             Sets the pen attributes used for the facade. You must also select
             -N for the facade outline to be drawn.
 
-        perspective : list or str
-            ``'[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0]'``.
-            Select perspective view.
-
         shading : str
             Provide the name of a grid file with intensities in the (-1,+1)
             range, or a constant intensity to apply everywhere (affects the
@@ -452,6 +456,7 @@ def grdview(self, grid, **kwargs):
             ``+d`` to select the default arguments (``+a-45+nt1+m0``).
 
         {XY}
+        {p}
         {t}
 
         """
@@ -495,9 +500,10 @@ def grdview(self, grid, **kwargs):
         U="timestamp",
         X="xshift",
         Y="yshift",
+        p="perspective",
         t="transparency",
     )
-    @kwargs_to_strings(R="sequence", i="sequence_comma")
+    @kwargs_to_strings(R="sequence", i="sequence_comma", p="sequence")
     def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
         """
         Plot lines, polygons, and symbols on maps.
@@ -567,6 +573,7 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
         label : str
             Add a legend entry for the symbol or line being plotted.
 
+        {p}
         {t}
         """
         kwargs = self._preprocess(**kwargs)
@@ -619,9 +626,10 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
         C="levels",
         X="xshift",
         Y="yshift",
+        p="perspective",
         t="transparency",
     )
-    @kwargs_to_strings(R="sequence", i="sequence_comma")
+    @kwargs_to_strings(R="sequence", i="sequence_comma", p="sequence")
     def contour(self, x=None, y=None, z=None, data=None, **kwargs):
         """
         Contour table data by direct triangulation.
@@ -678,6 +686,7 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs):
             label contains a slash (/) character then use ``|`` as the
             separator for the two labels instead.
         {XY}
+        {p}
         {t}
 
         """
@@ -711,9 +720,10 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs):
         U="timestamp",
         X="xshift",
         Y="yshift",
+        p="perspective",
         t="transparency",
     )
-    @kwargs_to_strings(R="sequence")
+    @kwargs_to_strings(R="sequence", p="sequence")
     def basemap(self, **kwargs):
         """
         Produce a basemap for the figure.
@@ -746,6 +756,7 @@ def basemap(self, **kwargs):
             reference and anchor points
         {U}
         {XY}
+        {p}
         {t}
 
         """
@@ -764,9 +775,10 @@ def basemap(self, **kwargs):
         F="box",
         X="xshift",
         Y="yshift",
+        p="perspective",
         t="transparency",
     )
-    @kwargs_to_strings(R="sequence")
+    @kwargs_to_strings(R="sequence", p="sequence")
     def logo(self, **kwargs):
         """
         Place the GMT graphics logo on a map.
@@ -792,6 +804,7 @@ def logo(self, **kwargs):
             GMT logo.
         {U}
         {XY}
+        {p}
         {t}
 
         """
@@ -810,9 +823,10 @@ def logo(self, **kwargs):
         M="monochrome",
         X="xshift",
         Y="yshift",
+        p="perspective",
         t="transparency",
     )
-    @kwargs_to_strings(R="sequence")
+    @kwargs_to_strings(R="sequence", p="sequence")
     def image(self, imagefile, **kwargs):
         """
         Place images or EPS files on maps.
@@ -846,6 +860,7 @@ def image(self, imagefile, **kwargs):
             Convert color image to monochrome grayshades using the (television)
             YIQ-transformation.
         {XY}
+        {p}
         {t}
         """
         kwargs = self._preprocess(**kwargs)
@@ -861,9 +876,10 @@ def image(self, imagefile, **kwargs):
         F="box",
         X="xshift",
         Y="yshift",
+        p="perspective",
         t="transparency",
     )
-    @kwargs_to_strings(R="sequence")
+    @kwargs_to_strings(R="sequence", p="sequence")
     def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwargs):
         """
         Plot legends on maps.
@@ -898,6 +914,7 @@ def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwarg
             default, uses '+gwhite+p1p' which draws a box around the legend
             using a 1 point black pen and adds a white background.
         {XY}
+        {p}
         {t}
         """
         kwargs = self._preprocess(**kwargs)
@@ -929,6 +946,7 @@ def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwarg
         W="pen",
         X="xshift",
         Y="yshift",
+        p="perspective",
         t="transparency",
     )
     @kwargs_to_strings(
@@ -937,6 +955,7 @@ def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwarg
         angle="sequence_comma",
         font="sequence_comma",
         justify="sequence_comma",
+        p="sequence",
     )
     def text(
         self,
@@ -1036,6 +1055,7 @@ def text(
             (see *clearance*) [Default is width = default, color = black,
             style = solid].
         {XY}
+        {p}
         {t}
         """
         kwargs = self._preprocess(**kwargs)
@@ -1093,9 +1113,10 @@ def text(
         C="offset",
         X="xshift",
         Y="yshift",
+        p="perspective",
         t="transparency",
     )
-    @kwargs_to_strings(R="sequence")
+    @kwargs_to_strings(R="sequence", p="sequence")
     def meca(
         self,
         spec,
@@ -1191,6 +1212,7 @@ def meca(
         {R}
         {B}
         {XY}
+        {p}
         {t}
         """
 

pygmt/helpers/decorators.py

@@ -86,6 +86,13 @@
             - 'c' for bicubic [Default]
             - 'l' for bilinear
             - 'n' for nearest-neighbor""",
+    "p": """\
+        perspective : list or str
+            ``'[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0]'``.
+            Select perspective view and set the azimuth and elevation angle of
+            the viewpoint. Default is [180, 90]. Full documentation is at
+            :gmt-docs:`gmt.html#perspective-full`.
+        """,
     "registration": """\
         registration : str
             ``[g|p]``