From 2b395fac771b2e1a64b5950747ddbc375924c064 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sun, 7 Dec 2025 20:27:47 +0800 Subject: [PATCH 1/8] Figure.grdview: Rename parameters meshpen->mesh_pen, facadepen->facade_pen, meshpen->mesh_pen (Will be removed in v0.20.0) --- .../advanced/3d_perspective_image.py | 4 +-- pygmt/src/grdview.py | 27 ++++++++++++------- pygmt/tests/test_grdview.py | 6 ++--- 3 files changed, 23 insertions(+), 14 deletions(-) diff --git a/examples/tutorials/advanced/3d_perspective_image.py b/examples/tutorials/advanced/3d_perspective_image.py index c1c3bba36f9..5bef9b37a96 100644 --- a/examples/tutorials/advanced/3d_perspective_image.py +++ b/examples/tutorials/advanced/3d_perspective_image.py @@ -74,7 +74,7 @@ # %% # The ``perspective`` azimuth can be changed to set the direction that is "up" -# in the figure. The ``contourpen`` parameter sets the pen used to draw contour +# in the figure. The ``contour_pen`` parameter sets the pen used to draw contour # lines on the surface. :meth:`pygmt.Figure.colorbar` can be used to add a # color bar to the figure. The ``cmap`` parameter does not need to be passed # again. To keep the color bar's alignment similar to the figure, use ``True`` @@ -92,7 +92,7 @@ cmap="geo", plane="1000+ggrey", # Set the contour pen thickness to "0.1p" - contourpen="0.1p", + contour_pen="0.1p", ) fig.colorbar(perspective=True, frame=["a500", "x+lElevation", "y+lm"]) fig.show() diff --git a/pygmt/src/grdview.py b/pygmt/src/grdview.py index 06b5ef1ab55..90bc13f12b2 100644 --- a/pygmt/src/grdview.py +++ b/pygmt/src/grdview.py @@ -9,20 +9,20 @@ 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, use_alias +from pygmt.helpers import build_arg_list, deprecate_parameter, fmt_docstring, use_alias __doctest_skip__ = ["grdview"] @fmt_docstring +@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") @use_alias( C="cmap", G="drapegrid", N="plane", Q="surftype", - Wc="contourpen", - Wm="meshpen", - Wf="facadepen", I="shading", f="coltypes", n="interpolation", @@ -30,6 +30,9 @@ def grdview( # noqa: PLR0913 self, grid: PathLike | xr.DataArray, + contour_pen: str | None = None, + facade_pen: str | None = None, + mesh_pen: str | None = None, projection: str | None = None, zscale: float | str | None = None, zsize: float | str | None = None, @@ -60,6 +63,9 @@ def grdview( # noqa: PLR0913 - JZ = zsize - R = region - V = verbose + - Wc = contour_pen + - Wf = facade_pen + - Wm = mesh_pen - c = panel - p = perspective - t = transparency @@ -101,15 +107,15 @@ def grdview( # noqa: PLR0913 For any of these choices, you may force a monochrome image by appending the modifier **+m**. - contourpen : str + contour_pen 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 + 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 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). @@ -162,6 +168,9 @@ def grdview( # noqa: PLR0913 aliasdict = AliasSystem( Jz=Alias(zscale, name="zscale"), JZ=Alias(zsize, name="zsize"), + Wc=Alias(contour_pen, name="contour_pen"), + Wf=Alias(facade_pen, name="facade_pen"), + Wm=Alias(mesh_pen, name="mesh_pen"), ).add_common( B=frame, J=projection, diff --git a/pygmt/tests/test_grdview.py b/pygmt/tests/test_grdview.py index 40c40190d21..7b301af97c3 100644 --- a/pygmt/tests/test_grdview.py +++ b/pygmt/tests/test_grdview.py @@ -179,7 +179,7 @@ def test_grdview_surface_plot_styled_with_contourpen(xrgrid): surface plot. """ fig = Figure() - fig.grdview(grid=xrgrid, cmap="relief", surftype="s", contourpen="0.5p,black,dash") + fig.grdview(grid=xrgrid, cmap="relief", surftype="s", contour_pen="0.5p,black,dash") return fig @@ -190,7 +190,7 @@ def test_grdview_surface_mesh_plot_styled_with_meshpen(xrgrid): mesh plot. """ fig = Figure() - fig.grdview(grid=xrgrid, cmap="relief", surftype="sm", meshpen="0.5p,black,dash") + fig.grdview(grid=xrgrid, cmap="relief", surftype="sm", mesh_pen="0.5p,black,dash") return fig @@ -206,7 +206,7 @@ def test_grdview_on_a_plane_styled_with_facadepen(xrgrid): plane=100, perspective=[225, 30], zscale=0.005, - facadepen="0.5p,blue,dash", + facade_pen="0.5p,blue,dash", ) return fig From 06ee20ed315115247b2ac60e15860274e3d343be Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Tue, 2 Dec 2025 15:30:41 +0800 Subject: [PATCH 2/8] Figure.grdview: Improve parameters 'plane'/'facadefill'/'facadepen' to set the plane and facade --- .../advanced/3d_perspective_image.py | 11 +++---- .../advanced/draping_on_3d_surface.py | 4 +-- pygmt/src/grdview.py | 29 ++++++++++++++----- ...st_grdview_facadepen_default_plane.png.dvc | 5 ++++ pygmt/tests/test_grdview.py | 17 ++++++++++- 5 files changed, 51 insertions(+), 15 deletions(-) create mode 100644 pygmt/tests/baseline/test_grdview_facadepen_default_plane.png.dvc diff --git a/examples/tutorials/advanced/3d_perspective_image.py b/examples/tutorials/advanced/3d_perspective_image.py index 5bef9b37a96..c5d2921ef03 100644 --- a/examples/tutorials/advanced/3d_perspective_image.py +++ b/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", # Fill the facade with "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.1p" contour_pen="0.1p", ) diff --git a/examples/tutorials/advanced/draping_on_3d_surface.py b/examples/tutorials/advanced/draping_on_3d_surface.py index eaa85cd367e..95dd464d020 100644 --- a/examples/tutorials/advanced/draping_on_3d_surface.py +++ b/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, ) diff --git a/pygmt/src/grdview.py b/pygmt/src/grdview.py index 90bc13f12b2..f3437e171c7 100644 --- a/pygmt/src/grdview.py +++ b/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,16 @@ 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. + plane + Draw a plane at the specified z-level. If ``True``, default to the minimum value + in the grid. However, if ``region`` was used to set zmin/zmax then that value 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. surftype : str Specify cover type of the grid. Select one of following settings: @@ -165,9 +172,17 @@ def grdview( # noqa: PLR0913 """ self._activate_figure() + # Enable 'plane' if 'facade_fill' or 'facade_pen' is 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"), diff --git a/pygmt/tests/baseline/test_grdview_facadepen_default_plane.png.dvc b/pygmt/tests/baseline/test_grdview_facadepen_default_plane.png.dvc new file mode 100644 index 00000000000..5e56c5a43d7 --- /dev/null +++ b/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 diff --git a/pygmt/tests/test_grdview.py b/pygmt/tests/test_grdview.py index 7b301af97c3..2825ff4a880 100644 --- a/pygmt/tests/test_grdview.py +++ b/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 @@ -211,6 +213,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,dash" + ) + return fig + + @pytest.mark.benchmark @pytest.mark.mpl_image_compare def test_grdview_drapegrid_dataarray(xrgrid): From b6ee6dcf1ce5554e96c1967e84a81e07576b7300 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 10 Dec 2025 10:26:50 +0800 Subject: [PATCH 3/8] Reorder docstrings --- pygmt/src/grdview.py | 23 ++++++++++------------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/pygmt/src/grdview.py b/pygmt/src/grdview.py index f3437e171c7..192659b2f74 100644 --- a/pygmt/src/grdview.py +++ b/pygmt/src/grdview.py @@ -92,16 +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 - Draw a plane at the specified z-level. If ``True``, default to the minimum value - in the grid. However, if ``region`` was used to set zmin/zmax then that value 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. surftype : str Specify cover type of the grid. Select one of following settings: @@ -117,12 +107,19 @@ 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. + plane + Draw a plane at the specified z-level. If ``True``, default to the minimum value + in the grid. However, if ``region`` was used to set zmin/zmax then that value 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 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). From 34e0e3de0521b9b24154d7e2d65953dde64a96a9 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 12 Dec 2025 08:42:42 +0800 Subject: [PATCH 4/8] Update pygmt/src/grdview.py MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com> --- pygmt/src/grdview.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pygmt/src/grdview.py b/pygmt/src/grdview.py index 192659b2f74..eddeb8890b9 100644 --- a/pygmt/src/grdview.py +++ b/pygmt/src/grdview.py @@ -111,8 +111,8 @@ def grdview( # noqa: PLR0913 Set the pen attributes used for the mesh. You must also select ``surftype`` of **m** or **sm** for meshlines to be drawn. plane - Draw a plane at the specified z-level. If ``True``, default to the minimum value - in the grid. However, if ``region`` was used to set zmin/zmax then that value is + 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 From ae930dc298a9ddd44242f161a46a2995961509ee Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 12 Dec 2025 08:43:04 +0800 Subject: [PATCH 5/8] Update examples/tutorials/advanced/3d_perspective_image.py MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com> --- examples/tutorials/advanced/3d_perspective_image.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/tutorials/advanced/3d_perspective_image.py b/examples/tutorials/advanced/3d_perspective_image.py index add6bbe4de9..c380a8bf5b6 100644 --- a/examples/tutorials/advanced/3d_perspective_image.py +++ b/examples/tutorials/advanced/3d_perspective_image.py @@ -68,7 +68,7 @@ surftype="s", cmap="geo", plane=1000, # Set the plane elevation to 1,000 meters - facade_fill="gray", # Fill the facade with "gray" + facade_fill="gray", # Color the facade in "gray" ) fig.show() From 5dd80defff688bd7231c433e38c043613584e2f8 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 12 Dec 2025 08:43:14 +0800 Subject: [PATCH 6/8] Update pygmt/src/grdview.py MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com> --- pygmt/src/grdview.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pygmt/src/grdview.py b/pygmt/src/grdview.py index eddeb8890b9..a13cf7de92e 100644 --- a/pygmt/src/grdview.py +++ b/pygmt/src/grdview.py @@ -120,7 +120,7 @@ def grdview( # noqa: PLR0913 data perimeter. facade_pen Set the pen attributes used for the facade. - shading : str + 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 From f73b0d1837a6fc746687c427c2c48f6d841a86c7 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 12 Dec 2025 10:14:54 +0800 Subject: [PATCH 7/8] Fix styling --- pygmt/src/grdview.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pygmt/src/grdview.py b/pygmt/src/grdview.py index a13cf7de92e..377f1f12502 100644 --- a/pygmt/src/grdview.py +++ b/pygmt/src/grdview.py @@ -111,9 +111,9 @@ def grdview( # noqa: PLR0913 Set the pen attributes used for the mesh. You must also select ``surftype`` of **m** or **sm** for meshlines to be drawn. 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 + 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 From 178dd65c9f3da19627e5ee2424d8fa6efab9fe82 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 12 Dec 2025 17:56:09 +0800 Subject: [PATCH 8/8] Update pygmt/src/grdview.py Co-authored-by: Michael Grund <23025878+michaelgrund@users.noreply.github.com> --- pygmt/src/grdview.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pygmt/src/grdview.py b/pygmt/src/grdview.py index 377f1f12502..f8965880170 100644 --- a/pygmt/src/grdview.py +++ b/pygmt/src/grdview.py @@ -169,7 +169,7 @@ def grdview( # noqa: PLR0913 """ self._activate_figure() - # Enable 'plane' if 'facade_fill' or 'facade_pen' is set + # 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