Figure.grdview: Add parameters surftype/dpi/mesh_fill/nan_transparent/monochrome to control surface types (#4234)

Author: seisman

examples/gallery/3d_plots/grdview_surface.py

@@ -3,15 +3,14 @@
 ==================
 
 The :meth:`pygmt.Figure.grdview()` method can plot 3-D surfaces with
-``surftype="s"``. Here, we supply the data as an :class:`xarray.DataArray` with
-the coordinate vectors ``x`` and ``y`` defined. Note that the ``perspective``
-parameter here controls the azimuth and elevation angle of the view. We provide
-a list of two arguments to ``frame`` - the first argument specifies the
-:math:`x`- and :math:`y`-axes frame attributes and the second argument,
-prepended with ``"z"``, specifies the :math:`z`-axis frame attributes.
-Specifying the same scale for the ``projection`` and ``zscale`` parameters
-ensures equal axis scaling. The ``shading`` parameter specifies illumination;
-here we choose an azimuth of 45° with ``shading="+a45"``.
+``surftype="surface"``. Here, we supply the data as an :class:`xarray.DataArray` with
+the coordinate vectors ``x`` and ``y`` defined. Note that the ``perspective`` parameter
+here controls the azimuth and elevation angle of the view. We provide a list of two
+arguments to ``frame`` - the first argument specifies the :math:`x`- and :math:`y`-axes
+frame attributes and the second argument, prepended with ``"z"``, specifies the
+:math:`z`-axis frame attributes. Specifying the same scale for the ``projection`` and
+``zscale`` parameters ensures equal axis scaling. The ``shading`` parameter specifies
+illumination; here we choose an azimuth of 45° with ``shading="+a45"``.
 """
 
 # %%
@@ -51,7 +50,7 @@ def ackley(x, y):
     frame=["a5f1g5", "za5f1g5"],
     projection=f"x{SCALE}c",
     zscale=f"{SCALE}c",
-    surftype="s",
+    surftype="surface",
     cmap="SCM/roma",
     perspective=[135, 30],  # Azimuth southeast (135°), at elevation 30°
     shading="+a45",

examples/tutorials/advanced/3d_perspective_image.py

@@ -47,10 +47,8 @@
     frame=["xa", "yaf", "WSnE"],
     projection="M15c",
     zsize="1.5c",
-    # Set the surftype to "surface"
-    surftype="s",
-    # Set the CPT to "geo"
-    cmap="gmt/geo",
+    surftype="surface",
+    cmap="gmt/geo",  # Set the CPT to "geo"
 )
 fig.show()
 
@@ -65,7 +63,7 @@
     frame=["xa", "yaf", "WSnE"],
     projection="M15c",
     zsize="1.5c",
-    surftype="s",
+    surftype="surface",
     cmap="gmt/geo",
     plane=1000,  # Set the plane elevation to 1,000 meters
     facade_fill="gray",  # Color the facade in "gray"
@@ -88,7 +86,7 @@
     frame=["xaf", "yaf", "WSnE"],
     projection="M15c",
     zsize="1.5c",
-    surftype="s",
+    surftype="surface",
     cmap="gmt/geo",
     plane=1000,
     facade_fill="gray",

examples/tutorials/advanced/draping_on_3d_surface.py

@@ -58,7 +58,7 @@
     grid=grd_relief,  # Use elevation grid for z values
     drape_grid=grd_age,  # Use crustal age grid for color-coding
     cmap=True,  # Use colormap created for the crustal age
-    surftype="i",  # Create an image plot
+    surftype="image",  # Create an image plot
     # Use an illumination from the azimuthal directions 0° (north) and 270°
     # (west) with a normalization via a cumulative Laplace distribution for
     # the shading
@@ -122,7 +122,7 @@
     grid=grd_relief,  # Use elevation grid for z values
     drape_grid=drape_grid,  # Drape image grid for the EU flag on top
     cmap=True,  # Use colormap defined for the EU flag
-    surftype="i",  # Create an image plot
+    surftype="image",  # Create an image plot
     # Use an illumination from the azimuthal directions 0° (north) and 270° (west) with
     # a normalization via a cumulative Laplace distribution for the shading
     shading="+a0/270+ne0.6",

pygmt/src/grdview.py

@@ -10,45 +10,132 @@
 from pygmt._typing import PathLike
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session, __gmt_version__
+from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import build_arg_list, deprecate_parameter, fmt_docstring, use_alias
 from pygmt.src.grdinfo import grdinfo
 
 __doctest_skip__ = ["grdview"]
 
 
+def _alias_option_Q(  # noqa: N802
+    surftype=None, dpi=None, mesh_fill=None, monochrome=False, nan_transparent=False
+):
+    """
+    Helper function to build the Alias list for the -Q option.
+
+    Examples
+    --------
+    >>> def parse(**kwargs):
+    ...     return AliasSystem(Q=_alias_option_Q(**kwargs)).get("Q")
+    >>> parse(surftype="surface")
+    's'
+    >>> parse(surftype="mesh")
+    'm'
+    >>> parse(surftype="surface+mesh")
+    'sm'
+    >>> parse(surftype="waterfall_x")
+    'mx'
+    >>> parse(surftype="waterfall_y")
+    'my'
+    >>> parse(surftype="image")
+    'i'
+    >>> parse(surftype="image", nan_transparent=True)
+    'c'
+    >>> parse(surftype="image", dpi=150)
+    'i150'
+    >>> parse(surftype="image", dpi=150, nan_transparent=True)
+    'c150'
+    >>> parse(surftype="mesh", mesh_fill="blue")
+    'mblue'
+    >>> parse(surftype="surface", monochrome=True)
+    's+m'
+    >>> parse(surftype="surface+mesh", monochrome=True)
+    'sm+m'
+
+    >>> # Check for backward compatibility with old raw GMT syntax.
+    >>> for surftype in ["s", "m", "sm", "i", "c", "mx", "my", "mblue", "i150"]:
+    ...     assert parse(surftype=surftype) == surftype
+    """
+    _surftype_mapping = {
+        "surface": "s",
+        "mesh": "m",
+        "surface+mesh": "sm",
+        "image": "c" if nan_transparent is True else "i",
+        "waterfall_x": "mx",
+        "waterfall_y": "my",
+    }
+    # Previously, 'surftype' was aliased to Q.
+    _old_surftype_syntax = surftype is not None and surftype not in _surftype_mapping
+
+    if _old_surftype_syntax and any(
+        v is not None and v is not False
+        for v in (dpi, mesh_fill, monochrome, nan_transparent)
+    ):
+        msg = (
+            "Parameter 'surftype' is given with a raw GMT command string, and conflicts "
+            "with parameters 'dpi', 'mesh_fill', 'monochrome', or 'nan_transparent'."
+        )
+        raise GMTInvalidInput(msg)
+
+    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 mesh_fill is not None and surftype not in {"mesh", "waterfall_x", "waterfall_y"}:
+        msg = (
+            "Parameter 'mesh_fill' can only be used when 'surftype' is 'mesh', "
+            "'waterfall_x', or 'waterfall_y'."
+        )
+        raise GMTInvalidInput(msg)
+
+    return [
+        Alias(
+            surftype,
+            name="surftype",
+            mapping=_surftype_mapping if not _old_surftype_syntax else None,
+        ),
+        Alias(dpi, name="dpi"),
+        Alias(mesh_fill, name="mesh_fill"),
+        Alias(monochrome, name="monochrome", prefix="+m"),
+    ]
+
+
 @fmt_docstring
 # TODO(PyGMT>=0.20.0): Remove the deprecated '*pen' parameters.
 # TODO(PyGMT>=0.20.0): Remove the deprecated 'drapegrid' parameter.
 @deprecate_parameter("contourpen", "contour_pen", "v0.18.0", remove_version="v0.20.0")
 @deprecate_parameter("facadepen", "facade_pen", "v0.18.0", remove_version="v0.20.0")
 @deprecate_parameter("meshpen", "mesh_pen", "v0.18.0", remove_version="v0.20.0")
 @deprecate_parameter("drapegrid", "drape_grid", "v0.18.0", remove_version="v0.20.0")
-@use_alias(
-    C="cmap",
-    G="drape_grid",
-    Q="surftype",
-    I="shading",
-    f="coltypes",
-    n="interpolation",
-)
+@use_alias(C="cmap", G="drape_grid", I="shading", f="coltypes", n="interpolation")
 def grdview(  # noqa: PLR0913
     self,
     grid: PathLike | xr.DataArray,
+    surftype: Literal[
+        "mesh", "surface", "surface+mesh", "image", "waterfall_x", "waterfall_y"
+    ]
+    | None = None,
+    dpi: int | None = None,
+    nan_transparent: bool = False,
+    monochrome: bool = False,
     contour_pen: str | None = None,
+    mesh_fill: str | None = None,
     mesh_pen: str | None = None,
     plane: float | bool = False,
     facade_fill: str | None = None,
     facade_pen: str | None = None,
     projection: str | None = None,
     zscale: float | str | None = None,
     zsize: float | str | None = None,
-    frame: str | Sequence[str] | bool = False,
     region: Sequence[float | str] | str | None = None,
+    frame: str | Sequence[str] | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | Sequence[int] | bool = False,
-    transparency: float | None = None,
     perspective: float | Sequence[float] | str | bool = False,
+    transparency: float | None = None,
     **kwargs,
 ):
     r"""
@@ -69,6 +156,7 @@ def grdview(  # noqa: PLR0913
        - JZ = zsize
        - N = plane, facade_fill
        - R = region
+       - Q = surftype, dpi, mesh_fill, nan_transparent, **+m**: monochrome
        - V = verbose
        - Wc = contour_pen
        - Wf = facade_pen
@@ -80,15 +168,6 @@ def grdview(  # noqa: PLR0913
     Parameters
     ----------
     $grid
-    region : str or list
-        *xmin/xmax/ymin/ymax*\ [**+r**][**+u**\ *unit*].
-        Specify the :doc:`region </tutorials/basics/regions>` of interest. When used
-        with ``perspective``, optionally append */zmin/zmax* to indicate the range to
-        use for the 3-D axes [Default is the region given by the input grid].
-    $projection
-    zscale/zsize
-        Set z-axis scaling or z-axis size.
-    $frame
     cmap : str
         The name of the color palette table to use.
     drape_grid : str or :class:`xarray.DataArray`
@@ -97,24 +176,30 @@ def grdview(  # noqa: PLR0913
         Note that ``zscale`` and ``plane`` always refer to ``grid``. ``drape_grid`` only
         provides the information pertaining to colors, which (if ``drape_grid`` is a
         grid) will be looked-up via the CPT (see ``cmap``).
-    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 surface type for 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`]
+    nan_transparent
+        Make grid nodes with z = NaN transparent, using the color-masking feature in
+        PostScript Level 3. Only applies when ``surftype="image"``.
+    monochrome
+        Force conversion to monochrome image using the (television) YIQ transformation.
     contour_pen
         Draw contour lines on top of surface or mesh (not image). Append pen attributes
         used for the contours.
     mesh_pen
-        Set the pen attributes used for the mesh. You must also select ``surftype`` of
-        **m** or **sm** for meshlines to be drawn.
+        Set the pen attributes used for the mesh. Need to set ``surftype`` to
+        ``"mesh"``, or ``"surface+mesh"`` to draw meshlines.
+    mesh_fill
+        Set the mesh fill in mesh plot or waterfall plots [Default is white].
     plane
         Draw a plane at the specified z-level. If ``True``, defaults to the minimum
         value in the grid. However, if ``region`` was used to set *zmin/zmax* then
@@ -135,6 +220,15 @@ def grdview(  # noqa: PLR0913
         **+m**\ *ambient* to specify azimuth, intensity, and ambient arguments for that
         function, or just give **+d** to select the default arguments [Default is
         ``"+a-45+nt1+m0"``].
+    $projection
+    zscale/zsize
+        Set z-axis scaling or z-axis size.
+    region : str or list
+        *xmin/xmax/ymin/ymax*\ [**+r**][**+u**\ *unit*].
+        Specify the :doc:`region </tutorials/basics/regions>` of interest. When used
+        with ``perspective``, optionally append */zmin/zmax* to indicate the range to
+        use for the 3-D axes [Default is the region given by the input grid].
+    $frame
     $verbose
     $panel
     $coltypes
@@ -167,7 +261,7 @@ def grdview(  # noqa: PLR0913
     ...     # Set the vertical scale (z-axis) to 2 cm
     ...     zsize="2c",
     ...     # Set "surface plot" to color the surface via a CPT
-    ...     surftype="s",
+    ...     surftype="surface",
     ...     # Specify CPT to "geo"
     ...     cmap="gmt/geo",
     ... )
@@ -195,6 +289,13 @@ def grdview(  # noqa: PLR0913
     aliasdict = AliasSystem(
         Jz=Alias(zscale, name="zscale"),
         JZ=Alias(zsize, name="zsize"),
+        Q=_alias_option_Q(
+            surftype=surftype,
+            dpi=dpi,
+            mesh_fill=mesh_fill,
+            monochrome=monochrome,
+            nan_transparent=nan_transparent,
+        ),
         N=[
             Alias(plane, name="plane"),
             Alias(facade_fill, name="facade_fill", prefix="+g"),

pygmt/tests/baseline/test_grdview_image_dpi.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: d384910b17de5a2a842cd2625761c821
+  size: 224724
+  hash: md5
+  path: test_grdview_image_dpi.png

pygmt/tests/baseline/test_grdview_mesh_pen_and_mesh_fill.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: 9158bd6308a9bb59fdcaf56e406954b3
+  size: 55008
+  hash: md5
+  path: test_grdview_mesh_pen_and_mesh_fill.png

pygmt/tests/baseline/test_grdview_monochrome.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: 9fff6fa175e44085570cb61b6bd62f6e
+  size: 104557
+  hash: md5
+  path: test_grdview_monochrome.png

pygmt/tests/baseline/test_grdview_surftype.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: 6a8a38827078400854c972bd24b0d898
+  size: 215417
+  hash: md5
+  path: test_grdview_surftype.png