Implement the Perspective class for specifying viewpoint

doc/api/index.rst

@@ -217,6 +217,7 @@ Class-style Parameters
     Box
     Frame
     Pattern
+    Perspective
     Position
 
 Enums

pygmt/helpers/decorators.py

@@ -274,24 +274,13 @@
             Set pen attributes for lines or the outline of symbols.""",
     "perspective": r"""
         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 plot frame) are drawn.
-              Only applied when used together with ``zsize`` or ``zscale``. [Default is
-              at the bottom of the z-axis].
-
+            Select perspective view and set the viewpoint.
+            Pass a :class:`pygmt.params.Perspective` object to control the viewpoint.
             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.""",
+            from the previous plotting method. It also accepts following shortcuts: a
+            single value *azimuth*, a sequence of two values (*azimuth*, *elevation*),
+            or a sequence of three values (*azimuth*, *elevation*, *level*). Refer to
+            :class:`pygmt.params.Perspective` for meaning of the parameters.""",
     "projection": r"""
         projection
             *projcode*\[*projparams*/]\ *width*\|\ *scale*.

pygmt/params/__init__.py

@@ -5,4 +5,5 @@
 from pygmt.params.box import Box
 from pygmt.params.frame import Axis, Frame
 from pygmt.params.pattern import Pattern
+from pygmt.params.perspective import Perspective
 from pygmt.params.position import Position

pygmt/params/perspective.py

@@ -0,0 +1,110 @@
+"""
+The Perspective class for setting perspective view.
+"""
+
+import dataclasses
+from collections.abc import Sequence
+from typing import Literal
+
+from pygmt.alias import Alias
+from pygmt.exceptions import GMTValueError
+from pygmt.params.base import BaseParam
+
+__doctest_skip__ = ["Perspective"]
+
+
+@dataclasses.dataclass(repr=False)
+class Perspective(BaseParam):
+    """
+    Class for setting perspective view.
+
+    Examples
+    --------
+    >>> import pygmt
+    >>> from pygmt.params import Axis, Frame, Perspective
+    >>> fig = pygmt.Figure()
+    >>> fig.basemap(
+    ...     region=[0, 10, 0, 10, 0, 20],
+    ...     projection="X3c",
+    ...     zsize="3c",
+    ...     frame=Frame(axes="WSenZ", title="Perspective View", axis=Axis(grid=True)),
+    ...     perspective=Perspective(azimuth=135, elevation=40, level=10),
+    ... )
+    >>> fig.show()
+    """
+
+    #: Azimuth angle of the viewpoint in degrees. Default is 180.0, i.e., looking from
+    #: south to north.
+    azimuth: float | None = None
+
+    #: Elevation angle of the viewpoint in degrees above the horizon. Default is 90.0,
+    #: i.e., looking straight down at nadir.
+    elevation: float | None = None
+
+    #: The level at which all 2-D elements, (e.g., the plot frame), are drawn. Only
+    #: valid when used together with parameters ``zsize`` or ``zscale``. Default is at
+    #: the bottom of the selected axis.
+    level: float | None = None
+
+    #: Set which constant-coordinate plane is used as the plotting plane. Use ``"x"``,
+    #: ``"y"``, or ``"z"`` for the x-plane, y-plane, or horizontal z-plane,
+    #: respectively [Default is ``"z"``].
+    plane: Literal["x", "y", "z"] | None = None
+
+    #: Reference point for the perspective view. By default, the view rotates about the
+    #: plotting origin. Use ``refpoint`` and ``cstype`` to rotate about a different
+    #: point instead. The format of ``refpoint`` depends on the value of ``cstype``:
+    #:
+    #: - ``cstype="mapcoords"``: (*longitude*, *latitude*) or
+    #:   (*longitude*, *latitude*, *z*)
+    #: - ``cstype="plotcoords"``: (*x*, *y*)
+    refpoint: Sequence[float | str] | None = None
+
+    #: Coordinate system type of ``refpoint``. Valid values are:
+    #:
+    #: - ``"mapcoords"``: Map/data coordinates
+    #: - ``"plotcoords"``: Plot coordinates
+    #:
+    #: Defaults to ``"mapcoords"``.
+    cstype: Literal["mapcoords", "plotcoords"] = "mapcoords"
+
+    def _validate(self):
+        """
+        Post-initialization processing to validate parameters.
+        """
+        # azimuth is required, so it must be set to the default if not specified.
+        if self.azimuth is None:
+            self.azimuth = 180.0  # Default azimuth is 180.0
+
+        # Set default elevation if level is set but elevation is not.
+        if self.level is not None and self.elevation is None:
+            self.elevation = 90.0  # Default elevation is 90.0
+
+        if self.plane is not None and self.plane not in {"x", "y", "z"}:
+            raise GMTValueError(
+                self.plane, description="plane", choices={"x", "y", "z"}
+            )
+
+        if self.cstype not in {"mapcoords", "plotcoords"}:
+            raise GMTValueError(
+                self.cstype, description="cstype", choices={"mapcoords", "plotcoords"}
+            )
+
+    @property
+    def _aliases(self):
+        """
+        Aliases for the parameters.
+        """
+        return [
+            Alias(self.plane, name="plane"),
+            Alias(self.azimuth, name="azimuth"),
+            Alias(self.elevation, name="elevation", prefix="/"),
+            Alias(self.level, name="level", prefix="/"),
+            Alias(
+                self.refpoint,
+                name="refpoint",
+                sep="/",
+                prefix={"mapcoords": "+w", "plotcoords": "+v"}[self.cstype],
+                size={"mapcoords": {2, 3}, "plotcoords": 2}[self.cstype],
+            ),
+        ]

pygmt/src/basemap.py

@@ -9,7 +9,7 @@
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.helpers import build_arg_list, fmt_docstring, is_given
-from pygmt.params import Axis, Box, Frame
+from pygmt.params import Axis, Box, Frame, Perspective
 
 
 @fmt_docstring
@@ -28,7 +28,7 @@ def basemap(
     box: Box | str | bool = False,
     panel: int | Sequence[int] | bool = False,
     coltypes: str | None = None,
-    perspective: float | Sequence[float] | str | bool = False,
+    perspective: Perspective | float | Sequence[float] | bool = False,
     transparency: float | None = None,
     **kwargs,
 ):

pygmt/src/coast.py

@@ -15,7 +15,7 @@
     is_nonstr_iter,
     use_alias,
 )
-from pygmt.params import Axis, Box, Frame
+from pygmt.params import Axis, Box, Frame, Perspective
 
 __doctest_skip__ = ["coast"]
 
@@ -90,7 +90,7 @@ def coast(
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | Sequence[int] | bool = False,
-    perspective: float | Sequence[float] | str | bool = False,
+    perspective: Perspective | float | Sequence[float] | bool = False,
     transparency: float | None = None,
     **kwargs,
 ):

pygmt/src/colorbar.py

@@ -11,7 +11,7 @@
 from pygmt.exceptions import GMTValueError
 from pygmt.helpers import build_arg_list, fmt_docstring, is_given, use_alias
 from pygmt.helpers.utils import is_nonstr_iter
-from pygmt.params import Axis, Box, Frame, Position
+from pygmt.params import Axis, Box, Frame, Perspective, Position
 from pygmt.src._common import _parse_position
 
 __doctest_skip__ = ["colorbar"]
@@ -278,7 +278,7 @@ def colorbar(
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | Sequence[int] | bool = False,
-    perspective: float | Sequence[float] | str | bool = False,
+    perspective: Perspective | float | Sequence[float] | bool = False,
     transparency: float | None = None,
     **kwargs,
 ):

pygmt/src/contour.py

@@ -14,7 +14,7 @@
     is_nonstr_iter,
     use_alias,
 )
-from pygmt.params import Axis, Frame
+from pygmt.params import Axis, Frame, Perspective
 
 
 @fmt_docstring
@@ -45,7 +45,7 @@ def contour(
     | bool = False,
     panel: int | Sequence[int] | bool = False,
     incols: int | str | Sequence[int | str] | None = None,
-    perspective: float | Sequence[float] | str | bool = False,
+    perspective: Perspective | float | Sequence[float] | bool = False,
     transparency: float | None = None,
     coltypes: str | None = None,
     **kwargs,

pygmt/src/directional_rose.py

@@ -9,7 +9,7 @@
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.helpers import build_arg_list, fmt_docstring
-from pygmt.params import Box, Position
+from pygmt.params import Box, Perspective, Position
 from pygmt.src._common import _parse_position
 
 __doctest_skip__ = ["directional_rose"]
@@ -26,7 +26,7 @@ def directional_rose(
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | Sequence[int] | bool = False,
-    perspective: float | Sequence[float] | str | bool = False,
+    perspective: Perspective | float | Sequence[float] | bool = False,
     transparency: float | None = None,
 ):
     """

pygmt/src/fill_between.py

@@ -10,7 +10,7 @@
 from pygmt.clib import Session
 from pygmt.exceptions import GMTValueError
 from pygmt.helpers import build_arg_list, fmt_docstring
-from pygmt.params import Axis, Frame
+from pygmt.params import Axis, Frame, Perspective
 
 __doctest_skip__ = ["fill_between"]
 
@@ -36,7 +36,7 @@ def fill_between(
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | Sequence[int] | bool = False,
-    perspective: float | Sequence[float] | str | bool = False,
+    perspective: Perspective | float | Sequence[float] | bool = False,
     transparency: float | None = None,
 ):
     """

pygmt/src/grdcontour.py

@@ -16,7 +16,7 @@
     kwargs_to_strings,
     use_alias,
 )
-from pygmt.params import Axis, Frame
+from pygmt.params import Axis, Frame, Perspective
 
 __doctest_skip__ = ["grdcontour"]
 
@@ -42,7 +42,7 @@ def grdcontour(
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | Sequence[int] | bool = False,
-    perspective: float | Sequence[float] | str | bool = False,
+    perspective: Perspective | float | Sequence[float] | bool = False,
     transparency: float | None = None,
     coltypes: str | None = None,
     **kwargs,

pygmt/src/grdimage.py

@@ -10,7 +10,7 @@
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.helpers import build_arg_list, fmt_docstring, use_alias
-from pygmt.params import Axis, Frame
+from pygmt.params import Axis, Frame, Perspective
 
 __doctest_skip__ = ["grdimage"]
 
@@ -36,7 +36,7 @@ def grdimage(
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | Sequence[int] | bool = False,
-    perspective: float | Sequence[float] | str | bool = False,
+    perspective: Perspective | float | Sequence[float] | bool = False,
     transparency: float | None = None,
     cores: int | bool = False,
     coltypes: str | None = None,

pygmt/src/grdview.py

@@ -17,7 +17,7 @@
     is_given,
     use_alias,
 )
-from pygmt.params import Axis, Frame
+from pygmt.params import Axis, Frame, Perspective
 from pygmt.src.grdinfo import grdinfo
 
 __doctest_skip__ = ["grdview"]
@@ -141,7 +141,7 @@ def grdview(
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | Sequence[int] | bool = False,
-    perspective: float | Sequence[float] | str | bool = False,
+    perspective: Perspective | float | Sequence[float] | bool = False,
     transparency: float | None = None,
     coltypes: str | None = None,
     **kwargs,

pygmt/src/histogram.py

@@ -15,7 +15,7 @@
     kwargs_to_strings,
     use_alias,
 )
-from pygmt.params import Axis, Frame
+from pygmt.params import Axis, Frame, Perspective
 
 
 @fmt_docstring
@@ -52,7 +52,7 @@ def histogram(
     | bool = False,
     panel: int | Sequence[int] | bool = False,
     incols: int | str | Sequence[int | str] | None = None,
-    perspective: float | Sequence[float] | str | bool = False,
+    perspective: Perspective | float | Sequence[float] | bool = False,
     transparency: float | None = None,
     **kwargs,
 ):

pygmt/src/hlines.py

@@ -6,6 +6,7 @@
 
 import numpy as np
 from pygmt.exceptions import GMTValueError
+from pygmt.params import Perspective
 
 __doctest_skip__ = ["hlines"]
 
@@ -18,7 +19,7 @@ def hlines(
     pen: str | None = None,
     label: str | None = None,
     no_clip: bool = False,
-    perspective: str | bool | None = None,
+    perspective: Perspective | float | Sequence[float] | bool | None = None,
 ):
     """
     Plot one or multiple horizontal line(s).

pygmt/src/image.py

@@ -9,7 +9,7 @@
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.helpers import build_arg_list, fmt_docstring, use_alias
-from pygmt.params import Axis, Box, Frame, Position
+from pygmt.params import Axis, Box, Frame, Perspective, Position
 from pygmt.src._common import _parse_position
 
 
@@ -32,7 +32,7 @@ def image(
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | Sequence[int] | bool = False,
-    perspective: float | Sequence[float] | str | bool = False,
+    perspective: Perspective | float | Sequence[float] | bool = False,
     transparency: float | None = None,
     **kwargs,
 ):

pygmt/src/legend.py

@@ -11,7 +11,7 @@
 from pygmt.clib import Session
 from pygmt.exceptions import GMTTypeError
 from pygmt.helpers import build_arg_list, data_kind, fmt_docstring, is_nonstr_iter
-from pygmt.params import Axis, Box, Frame, Position
+from pygmt.params import Axis, Box, Frame, Perspective, Position
 from pygmt.src._common import _parse_position
 
 
@@ -31,7 +31,7 @@ def legend(
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | Sequence[int] | bool = False,
-    perspective: float | Sequence[float] | str | bool = False,
+    perspective: Perspective | float | Sequence[float] | bool = False,
     transparency: float | None = None,
     **kwargs,
 ):