Figure.grdview: Improve parameters plane/facade_fill/facade_pen to set the plane and facade (#4235)

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>
Co-authored-by: Michael Grund <23025878+michaelgrund@users.noreply.github.com>

Author: 3 people

examples/tutorials/advanced/3d_perspective_image.py

@@ -55,8 +55,8 @@
 fig.show()
 
 # %%
-# The ``plane`` parameter sets the elevation and color of a plane that provides
-# a fill below the surface relief.
+# The ``plane`` parameter sets the elevation and color of a plane that provides a fill
+# below the surface relief.
 
 fig = pygmt.Figure()
 fig.grdview(
@@ -67,8 +67,8 @@
     zsize="1.5c",
     surftype="s",
     cmap="geo",
-    # Set the plane elevation to 1,000 meters and make the fill "gray"
-    plane="1000+ggray",
+    plane=1000,  # Set the plane elevation to 1,000 meters
+    facade_fill="gray",  # Color the facade in "gray"
 )
 fig.show()
 
@@ -90,7 +90,8 @@
     zsize="1.5c",
     surftype="s",
     cmap="geo",
-    plane="1000+ggrey",
+    plane=1000,
+    facade_fill="gray",
     # Set the contour pen thickness to 0.1 points
     contour_pen="0.1p",
 )

examples/tutorials/advanced/draping_on_3d_surface.py

@@ -65,7 +65,7 @@
     shading="+a0/270+ne0.6",
     perspective=[157.5, 30],  # Azimuth and elevation for the 3-D plot
     zsize="1.5c",
-    plane="+gdarkgray",
+    facade_fill="darkgray",
     frame=True,
 )
 
@@ -128,7 +128,7 @@
     shading="+a0/270+ne0.6",
     perspective=[157.5, 30],  # Define azimuth, elevation for the 3-D plot
     zsize="1c",
-    plane="+gdarkgray",
+    facade_fill="darkgray",
     frame=True,
 )
 

pygmt/src/grdview.py

@@ -21,7 +21,6 @@
 @use_alias(
     C="cmap",
     G="drapegrid",
-    N="plane",
     Q="surftype",
     I="shading",
     f="coltypes",
@@ -31,8 +30,10 @@ def grdview(  # noqa: PLR0913
     self,
     grid: PathLike | xr.DataArray,
     contour_pen: str | None = None,
-    facade_pen: 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,
@@ -61,6 +62,7 @@ def grdview(  # noqa: PLR0913
        - J = projection
        - Jz = zscale
        - JZ = zsize
+       - N = plane, facade_fill
        - R = region
        - V = verbose
        - Wc = contour_pen
@@ -90,11 +92,6 @@ def grdview(  # noqa: PLR0913
         Note that ``zscale`` and ``plane`` always refer to ``grid``. ``drapegrid`` only
         provides the information pertaining to colors, which (if ``drapegrid`` is a
         grid) will be looked-up via the CPT (see ``cmap``).
-    plane : float or str
-        *level*\ [**+g**\ *fill*].
-        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:
 
@@ -110,13 +107,20 @@ def grdview(  # noqa: PLR0913
     contour_pen
         Draw contour lines on top of surface or mesh (not image). Append pen attributes
         used for the contours.
-    facade_pen
-        Set the pen attributes used for the facade. You must also select ``plane`` for
-        the facade outline to be drawn.
     mesh_pen
         Set the pen attributes used for the mesh. You must also select ``surftype`` of
         **m** or **sm** for meshlines to be drawn.
-    shading : str
+    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
+        *zmin* is used if it is less than the grid minimum value. Use ``facade_pen`` and
+        ``facade_fill`` to control the appearance of the plane.
+    facade_fill
+        Fill for the frontal facade between the plane specified by ``plane`` and the
+        data perimeter.
+    facade_pen
+        Set the pen attributes used for the facade.
+    shading : str or float
         Provide the name of a grid file with intensities in the (-1,+1) range, or a
         constant intensity to apply everywhere (affects the ambient light).
         Alternatively, derive an intensity grid from the main input data grid by using
@@ -165,9 +169,17 @@ def grdview(  # noqa: PLR0913
     """
     self._activate_figure()
 
+    # Enable 'plane' if 'facade_fill' or 'facade_pen' are set
+    if plane is False and (facade_fill is not None or facade_pen is not None):
+        plane = True
+
     aliasdict = AliasSystem(
         Jz=Alias(zscale, name="zscale"),
         JZ=Alias(zsize, name="zsize"),
+        N=[
+            Alias(plane, name="plane"),
+            Alias(facade_fill, name="facade_fill", prefix="+g"),
+        ],
         Wc=Alias(contour_pen, name="contour_pen"),
         Wf=Alias(facade_pen, name="facade_pen"),
         Wm=Alias(mesh_pen, name="mesh_pen"),

pygmt/tests/baseline/test_grdview_facadepen_default_plane.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: cfff4879fbe7ab03d8a304b2622b9782
+  size: 26208
+  hash: md5
+  path: test_grdview_facadepen_default_plane.png

pygmt/tests/test_grdview.py

@@ -150,7 +150,9 @@ def test_grdview_on_a_plane_with_colored_frontal_facade(xrgrid):
     is colored gray, while setting a 3-D perspective viewpoint.
     """
     fig = Figure()
-    fig.grdview(grid=xrgrid, plane="100+ggray", perspective=[225, 30], zscale=0.005)
+    fig.grdview(
+        grid=xrgrid, plane=100, facade_fill="gray", perspective=[225, 30], zscale=0.005
+    )
     return fig
 
 
@@ -213,6 +215,19 @@ def test_grdview_on_a_plane_styled_with_facadepen(xrgrid):
     return fig
 
 
+@pytest.mark.mpl_image_compare
+def test_grdview_facadepen_default_plane(xrgrid):
+    """
+    Run grdview by passing in a grid and plotting it on the default z-plane with styled
+    lines for the frontal facade.
+    """
+    fig = Figure()
+    fig.grdview(
+        grid=xrgrid, perspective=[225, 30], zscale=0.005, facade_pen="0.5p,blue,dashed"
+    )
+    return fig
+
+
 @pytest.mark.benchmark
 @pytest.mark.mpl_image_compare
 def test_grdview_drapegrid_dataarray(xrgrid):