AliasSystem: Migrate the 'perspective' parameter to the new alias system (#4206)

Co-authored-by: Yvonne Fröhlich <[email protected]>
Co-authored-by: Wei Ji <[email protected]>

Author: 3 people

pygmt/alias.py

@@ -335,6 +335,8 @@ def add_common(self, **kwargs):
                         name="registration",
                         mapping={"gridline": "g", "pixel": "p"},
                     )
+                case "p":
+                    alias = Alias(value, name="perspective", sep="/", size={2, 3})
                 case "t":
                     alias = Alias(value, name="transparency")
                 case "x":

pygmt/helpers/decorators.py

@@ -262,12 +262,25 @@
         pen : str
             Set pen attributes for lines or the outline of symbols.""",
     "perspective": r"""
-        perspective : list or str
-            [**x**\|\ **y**\|\ **z**]\ *azim*\[/*elev*\[/*zlevel*]]\
-            [**+w**\ *lon0*/*lat0*\[/*z0*]][**+v**\ *x0*/*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`.""",
+        perspective
+            Select perspective view and set the azimuth and elevation of the viewpoint.
+
+            Accepts a single value or a sequence of two or three values: *azimuth*,
+            (*azimuth*, *elevation*), or (*azimuth*, *elevation*, *zlevel*).
+
+            - *azimuth*: Azimuth angle of the viewpoint in degrees [Default is 180,
+              i.e., looking from south to north].
+            - *elevation*: Elevation angle of the viewpoint above the horizon [Default
+              is 90, i.e., looking straight down at nadir].
+            - *zlevel*: Z-level at which 2-D elements (e.g., the map frame) are drawn.
+              Only applied when used together with ``zsize`` or ``zscale``. [Default is
+              at the bottom of the z-axis].
+
+            Alternatively, set ``perspective=True`` to reuse the perspective setting
+            from the previous plotting method, or pass a string following the full
+            GMT syntax for finer control (e.g., adding ``+w`` or ``+v`` modifiers to
+            select an axis location other than the plot origin). See
+            :gmt-docs:`gmt.html#perspective-full` for details.""",
     "projection": r"""
         projection
             *projcode*\[*projparams*/]\ *width*\|\ *scale*.

pygmt/src/basemap.py

@@ -7,7 +7,7 @@
 
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
-from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
+from pygmt.helpers import build_arg_list, fmt_docstring, use_alias
 
 
 @fmt_docstring
@@ -17,9 +17,7 @@
     Td="rose",
     Tm="compass",
     f="coltypes",
-    p="perspective",
 )
-@kwargs_to_strings(p="sequence")
 def basemap(
     self,
     projection: str | None = None,
@@ -31,6 +29,7 @@ def basemap(
     | bool = False,
     panel: int | Sequence[int] | bool = False,
     transparency: float | None = None,
+    perspective: float | Sequence[float] | str | bool = False,
     **kwargs,
 ):
     r"""
@@ -54,6 +53,7 @@ def basemap(
        - R = region
        - V = verbose
        - c = panel
+       - p = perspective
        - t = transparency
 
     Parameters
@@ -109,6 +109,7 @@ def basemap(
         R=region,
         V=verbose,
         c=panel,
+        p=perspective,
         t=transparency,
     )
     aliasdict.merge(kwargs)

pygmt/src/coast.py

@@ -12,7 +12,6 @@
     args_in_kwargs,
     build_arg_list,
     fmt_docstring,
-    kwargs_to_strings,
     use_alias,
 )
 from pygmt.params import Box
@@ -31,9 +30,7 @@
     N="borders",
     S="water",
     W="shorelines",
-    p="perspective",
 )
-@kwargs_to_strings(p="sequence")
 def coast(
     self,
     resolution: Literal[
@@ -47,6 +44,7 @@ def coast(
     | bool = False,
     panel: int | Sequence[int] | bool = False,
     transparency: float | None = None,
+    perspective: float | Sequence[float] | str | bool = False,
     **kwargs,
 ):
     r"""
@@ -76,6 +74,7 @@ def coast(
        - R = region
        - V = verbose
        - c = panel
+       - p = perspective
        - t = transparency
 
     Parameters
@@ -229,6 +228,7 @@ def coast(
         R=region,
         V=verbose,
         c=panel,
+        p=perspective,
         t=transparency,
     )
     aliasdict.merge(kwargs)

pygmt/src/colorbar.py

@@ -15,16 +15,9 @@
 
 @fmt_docstring
 @use_alias(
-    C="cmap",
-    D="position",
-    G="truncate",
-    L="equalsize",
-    Q="log",
-    W="scale",
-    Z="zfile",
-    p="perspective",
+    C="cmap", D="position", G="truncate", L="equalsize", Q="log", W="scale", Z="zfile"
 )
-@kwargs_to_strings(G="sequence", I="sequence", p="sequence")
+@kwargs_to_strings(G="sequence", I="sequence")
 def colorbar(
     self,
     shading: float | Sequence[float] | bool = False,
@@ -36,6 +29,7 @@ def colorbar(
     | bool = False,
     panel: int | Sequence[int] | bool = False,
     transparency: float | None = None,
+    perspective: float | Sequence[float] | str | bool = False,
     **kwargs,
 ):
     r"""
@@ -70,6 +64,7 @@ def colorbar(
        - R = region
        - V = verbose
        - c = panel
+       - p = perspective
        - t = transparency
 
     Parameters
@@ -173,6 +168,7 @@ def colorbar(
         R=region,
         V=verbose,
         c=panel,
+        p=perspective,
         t=transparency,
     )
     aliasdict.merge(kwargs)

pygmt/src/contour.py

@@ -32,9 +32,8 @@
     h="header",
     i="incols",
     l="label",
-    p="perspective",
 )
-@kwargs_to_strings(i="sequence_comma", p="sequence")
+@kwargs_to_strings(i="sequence_comma")
 def contour(  # noqa: PLR0913
     self,
     data: PathLike | TableLike | None = None,
@@ -49,6 +48,7 @@ def contour(  # noqa: PLR0913
     | bool = False,
     panel: int | Sequence[int] | bool = False,
     transparency: float | None = None,
+    perspective: float | Sequence[float] | str | bool = False,
     **kwargs,
 ):
     r"""
@@ -68,6 +68,7 @@ def contour(  # noqa: PLR0913
        - R = region
        - V = verbose
        - c = panel
+       - p = perspective
        - t = transparency
 
     Parameters
@@ -171,6 +172,7 @@ def contour(  # noqa: PLR0913
         R=region,
         V=verbose,
         c=panel,
+        p=perspective,
         t=transparency,
     )
     aliasdict.merge(kwargs)

pygmt/src/grdcontour.py

@@ -33,9 +33,8 @@
     W="pen",
     l="label",
     f="coltypes",
-    p="perspective",
 )
-@kwargs_to_strings(L="sequence", p="sequence")
+@kwargs_to_strings(L="sequence")
 def grdcontour(
     self,
     grid: PathLike | xr.DataArray,
@@ -46,6 +45,7 @@ def grdcontour(
     | bool = False,
     panel: int | Sequence[int] | bool = False,
     transparency: float | None = None,
+    perspective: float | Sequence[float] | str | bool = False,
     **kwargs,
 ):
     r"""
@@ -61,6 +61,7 @@ def grdcontour(
        - R = region
        - V = verbose
        - c = panel
+       - p = perspective
        - t = transparency
 
     Parameters
@@ -172,6 +173,7 @@ def grdcontour(
         R=region,
         V=verbose,
         c=panel,
+        p=perspective,
         t=transparency,
     )
     aliasdict.merge(kwargs)

pygmt/src/grdimage.py

@@ -9,7 +9,7 @@
 from pygmt._typing import PathLike
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
-from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
+from pygmt.helpers import build_arg_list, fmt_docstring, use_alias
 
 __doctest_skip__ = ["grdimage"]
 
@@ -24,9 +24,7 @@
     Q="nan_transparent",
     n="interpolation",
     f="coltypes",
-    p="perspective",
 )
-@kwargs_to_strings(p="sequence")
 def grdimage(  # noqa: PLR0913
     self,
     grid: PathLike | xr.DataArray,
@@ -39,6 +37,7 @@ def grdimage(  # noqa: PLR0913
     | bool = False,
     panel: int | Sequence[int] | bool = False,
     transparency: float | None = None,
+    perspective: float | Sequence[float] | str | bool = False,
     cores: int | bool = False,
     **kwargs,
 ):
@@ -83,6 +82,7 @@ def grdimage(  # noqa: PLR0913
        - R = region
        - V = verbose
        - c = panel
+       - p = perspective
        - t = transparency
        - x = cores
 
@@ -187,6 +187,7 @@ def grdimage(  # noqa: PLR0913
         R=region,
         V=verbose,
         c=panel,
+        p=perspective,
         t=transparency,
         x=cores,
     )

pygmt/src/grdview.py

@@ -9,7 +9,7 @@
 from pygmt._typing import PathLike
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
-from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
+from pygmt.helpers import build_arg_list, fmt_docstring, use_alias
 
 __doctest_skip__ = ["grdview"]
 
@@ -26,10 +26,8 @@
     I="shading",
     f="coltypes",
     n="interpolation",
-    p="perspective",
 )
-@kwargs_to_strings(p="sequence")
-def grdview(
+def grdview(  # noqa: PLR0913
     self,
     grid: PathLike | xr.DataArray,
     projection: str | None = None,
@@ -41,6 +39,7 @@ def grdview(
     | bool = False,
     panel: int | Sequence[int] | bool = False,
     transparency: float | None = None,
+    perspective: float | Sequence[float] | str | bool = False,
     **kwargs,
 ):
     r"""
@@ -62,6 +61,7 @@ def grdview(
        - R = region
        - V = verbose
        - c = panel
+       - p = perspective
        - t = transparency
 
     Parameters
@@ -168,6 +168,7 @@ def grdview(
         R=region,
         V=verbose,
         c=panel,
+        p=perspective,
         t=transparency,
     )
     aliasdict.merge(kwargs)

pygmt/src/histogram.py

@@ -32,10 +32,9 @@
     h="header",
     i="incols",
     l="label",
-    p="perspective",
     w="wrap",
 )
-@kwargs_to_strings(T="sequence", i="sequence_comma", p="sequence")
+@kwargs_to_strings(T="sequence", i="sequence_comma")
 def histogram(
     self,
     data: PathLike | TableLike,
@@ -46,6 +45,7 @@ def histogram(
     | bool = False,
     panel: int | Sequence[int] | bool = False,
     transparency: float | None = None,
+    perspective: float | Sequence[float] | str | bool = False,
     **kwargs,
 ):
     r"""
@@ -59,6 +59,7 @@ def histogram(
        - R = region
        - V = verbose
        - c = panel
+       - p = perspective
        - t = transparency
 
     Parameters
@@ -156,6 +157,7 @@ def histogram(
         R=region,
         V=verbose,
         c=panel,
+        p=perspective,
         t=transparency,
     )
     aliasdict.merge(kwargs)