Figure.grdview: Pythonic syntax for surftype parameter

pygmt/src/grdview.py

@@ -9,6 +9,7 @@
 from pygmt._typing import PathLike
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
+from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import build_arg_list, fmt_docstring, use_alias
 
 __doctest_skip__ = ["grdview"]
@@ -19,9 +20,7 @@
     C="cmap",
     G="drapegrid",
     N="plane",
-    Q="surftype",
     Wc="contourpen",
-    Wm="meshpen",
     Wf="facadepen",
     I="shading",
     f="coltypes",
@@ -30,6 +29,15 @@
 def grdview(  # noqa: PLR0913
     self,
     grid: PathLike | xr.DataArray,
+    surftype: Literal[
+        "mesh", "surface", "surface+mesh", "image", "waterfallx", "waterfally"
+    ]
+    | None = None,
+    dpi: int | None = None,
+    meshfill: float | None = None,
+    meshpen: str | None = None,
+    monochrome: bool = False,
+    nan_transparent: bool = False,
     projection: str | None = None,
     zscale: float | str | None = None,
     zsize: float | str | None = None,
@@ -59,7 +67,9 @@ def grdview(  # noqa: PLR0913
        - Jz = zscale
        - JZ = zsize
        - R = region
+       - Q = surftype
        - V = verbose
+       - Wm = meshpen
        - c = panel
        - p = perspective
        - t = transparency
@@ -89,24 +99,29 @@ def grdview(  # noqa: PLR0913
         Draw a plane at this z-level. If the optional color is provided via the **+g**
         modifier, and the projection is not oblique, the frontal facade between the
         plane and the data perimeter is colored.
-    surftype : str
-        Specify cover type of the grid. Select one of following settings:
-
-        - **m**: mesh plot [Default].
-        - **mx** or **my**: waterfall plots (row or column profiles).
-        - **s**: surface plot, and optionally append **m** to have mesh lines drawn on
-          top of the surface.
-        - **i**: image plot.
-        - **c**: Same as **i** but will make nodes with z = NaN transparent.
-
-        For any of these choices, you may force a monochrome image by appending the
-        modifier **+m**.
+    surftype
+        Specify cover type of the grid. Valid values are:
+
+        - ``"mesh"``: mesh plot [Default].
+        - ``"surface``: surface plot.
+        - ``"surface+mesh"``: surface plot with mesh lines drawn on top of the surface.
+        - ``"image"``: image plot.
+        - ``"waterfall_x"``/``"waterfall_y"``: waterfall plots (row or column profiles).
+    dpi
+        Effective dots-per-unit resolution for the rasterization for image plots (i.e.,
+        ``surftype="image"``) [Default is :gmt-term:`GMT_GRAPHICS_DPU`]
+    meshfill
+        Set the mesh fill [Default is white] for mesh or waterfall plots.
+    meshpen
+        Set the pen attributes for the mesh lines, for mesh, or waterfall plots.
+    monochrome
+        Force conversion to monochrome image using the (television) YIQ transformation.
+    nan_transparent
+        Make grid nodes with z = NaN transparent, using the color-masking feature in
+        PostScript Level 3. Only applies when ``surftype="image"``.
     contourpen : str
         Draw contour lines on top of surface or mesh (not image). Append pen attributes
         used for the contours.
-    meshpen : str
-        Set the pen attributes used for the mesh. You must also select ``surftype`` of
-        **m** or **sm** for meshlines to be drawn.
     facadepen :str
         Set the pen attributes used for the facade. You must also select ``plane`` for
         the facade outline to be drawn.
@@ -159,9 +174,45 @@ def grdview(  # noqa: PLR0913
     """
     self._activate_figure()
 
+    if dpi is not None and surftype != "image":
+        msg = "Parameter 'dpi' can only be used when 'surftype' is 'image'."
+        raise GMTInvalidInput(msg)
+    if nan_transparent and surftype != "image":
+        msg = "Parameter 'nan_transparent' can only be used when 'surftype' is 'image'."
+        raise GMTInvalidInput(msg)
+    if meshfill is not None and surftype not in {"mesh", "waterfallx", "waterfally"}:
+        msg = (
+            "Parameter 'meshfill' can only be used when 'surftype' is "
+            "'mesh', 'waterfallx', or 'waterfally'."
+        )
+        raise GMTInvalidInput(msg)
+
+    _surtype_mapping = {
+        "surface": "s",
+        "mesh": "m",
+        "surface+mesh": "sm",
+        "image": "c" if nan_transparent is True else "i",
+        "waterfallx": "mx",
+        "waterfally": "my",
+    }
+
+    # surftype was aliased to Q previously.
+    _old_surftype_syntax = surftype not in _surtype_mapping and surftype is not None
+
     aliasdict = AliasSystem(
         Jz=Alias(zscale, name="zscale"),
         JZ=Alias(zsize, name="zsize"),
+        Q=[
+            Alias(
+                surftype,
+                name="surftype",
+                mapping=_surtype_mapping if not _old_surftype_syntax else None,
+            ),
+            Alias(dpi, name="dpi"),
+            Alias(meshfill, name="meshfill"),
+            Alias(monochrome, name="monochrome", prefix="+m"),
+        ],
+        Wm=Alias(meshpen, name="meshpen"),
     ).add_common(
         B=frame,
         J=projection,