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

seisman · 2025-12-02T06:14:11Z

This PR improves grdview's -Q option in a more Pythonic way by splitting it into multiple parameters:

surftype
dpi
nan_transparent
monochrome
mesh_fill

Preview at https://pygmt-dev--4234.org.readthedocs.build/en/4234/api/generated/pygmt.Figure.grdview.html

Example

import pygmt

grd_relief = pygmt.datasets.load_earth_relief(resolution="15m", region=[-25, -13, 63.2, 66.7])

args = dict(
    region=[-25, -13, 63.2, 66.7], 
    projection="M?", 
    perspective=(-150, 25),
    cmap="SCM/oleron",
    zsize="1.5c",
    plane="+ggray",
    panel=True,
)

fig = pygmt.Figure()
with fig.subplot(nrows=5, ncols=3, subsize=(5, 5), margins=(1, 0.2)):
    for surftype in ("surface", "mesh", "surface+mesh", "image", "waterfall_x", "waterfall_y"):
        fig.grdview(
            grid=grd_relief,
            frame=["xaf", "yaf", f"WSenZ+t{surftype}"],
            surftype=surftype,
            **args,
        )
    for surftype in ("surface", "mesh", "surface+mesh", "image", "waterfall_x", "waterfall_y"):
        fig.grdview(
            grid=grd_relief,
            frame=["xaf", "yaf", f"WSenZ+t{surftype}"],
            surftype=surftype,
            monochrome=True,
            **args,
        )
    for surtype in ("mesh", "waterfall_x", "waterfall_y"):
        fig.grdview(
            grid=grd_relief,
            frame=["xaf", "yaf", f"WSenZ+t{surftype}"],
            surftype=surftype,
            meshfill="red@50",
            **args,
        )
fig.show()

weiji14 · 2025-12-08T20:55:27Z

pygmt/src/grdview.py

+            ),
+            Alias(dpi, name="dpi"),
+            Alias(meshfill, name="meshfill"),
+            Alias(monochrome, name="monochrome", prefix="+m"),


Shouldn't +m be a suffix?

The full syntax is -Qc|i|m[x|y]|s[m][color][+m]. It's a suffix for the -Q option, but for monochrome, it's a prefix. Since monochrome is a boolean, monochrome would be +m, so here it makes no difference if +m is a prefix or a suffix.

Ah right, got it now.

Just a note that after the suffix feature is implemented in #4259, this +m does need to be a prefix, otherwise a list of values will be returned, xref #4259 (comment).

weiji14 · 2025-12-08T21:04:12Z

pygmt/src/grdview.py

+        "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


Can you add a unit test to ensure that backwards compatibility is preserved when a user passes surftype="c", but did not set nan_transparent=True (which is added in this PR). The output grdview plot should still have NaN transparency.

Added in aa9eb73.

This reverts commit 25af727.

Copilot

Pull request overview

This PR refactors PyGMT’s Figure.grdview -Q option into explicit, Pythonic parameters (surftype, dpi, mesh_fill, nan_transparent, monochrome) and updates tests/examples accordingly.

Changes:

Add a dedicated -Q alias builder and expose new grdview parameters to control surface rendering modes.
Expand/refresh grdview tests (including image baselines) to cover the new parameterization and validation behavior.
Update gallery/tutorial examples to use the new long-form surftype values.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
`pygmt/src/grdview.py`	Introduces `_alias_option_Q`, adds new `grdview` parameters, updates docs, and validates parameter combinations.
`pygmt/tests/test_grdview.py`	Adds unit + image tests for new `-Q` parameterization; updates existing tests to new `surftype` values; updates validation tests.
`pygmt/tests/baseline/test_grdview_with_cmap_for_surface_monochrome_plot.png.dvc`	Removes baseline for deleted test.
`pygmt/tests/baseline/test_grdview_with_cmap_for_perspective_surface_plot.png.dvc`	Removes baseline for deleted test.
`pygmt/tests/baseline/test_grdview_with_cmap_for_image_plot.png.dvc`	Removes baseline for deleted test.
`pygmt/tests/baseline/test_grdview_surftype.png.dvc`	Adds baseline for new `surftype` coverage image test.
`pygmt/tests/baseline/test_grdview_monochrome.png.dvc`	Adds baseline for new monochrome image test.
`pygmt/tests/baseline/test_grdview_mesh_pen_and_mesh_fill.png.dvc`	Adds baseline for new mesh pen/fill image test.
`pygmt/tests/baseline/test_grdview_image_dpi.png.dvc`	Adds baseline for new image DPI test.
`examples/tutorials/advanced/draping_on_3d_surface.py`	Updates `surftype` usage to new long-form values.
`examples/tutorials/advanced/3d_perspective_image.py`	Updates `surftype` usage to new long-form values and adjusts inline comments.
`examples/gallery/3d_plots/grdview_surface.py`	Updates example code to use `surftype="surface"`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

pygmt/src/grdview.py

pygmt/tests/test_grdview.py

examples/gallery/3d_plots/grdview_surface.py

pygmt/src/grdview.py

Co-authored-by: Copilot <[email protected]>

…urftype

seisman · 2026-01-26T12:37:14Z

pygmt/tests/test_grdview.py

-@pytest.mark.mpl_image_compare
-def test_grdview_with_cmap_for_image_plot(xrgrid):
-    """
-    Run grdview by passing in a grid and setting a colormap for producing an image plot.
-    """
-    fig = Figure()
-    fig.grdview(grid=xrgrid, cmap="SCM/oleron", surftype="i")
-    return fig


Superseded by test_grdview_surftype

seisman · 2026-01-26T12:37:47Z

pygmt/tests/test_grdview.py

-
-
-@pytest.mark.mpl_image_compare
-def test_grdview_with_cmap_for_surface_monochrome_plot(xrgrid):


Superseded by test_grdview_monochrome

seisman · 2026-01-26T12:38:07Z

pygmt/tests/test_grdview.py

-    return fig
-
-
-@pytest.mark.mpl_image_compare


Superseded by test_grdview_surftype

weiji14 · 2026-01-27T23:59:02Z

pygmt/src/grdview.py

+        - ``"surface"``: surface plot.
+        - ``"surface+mesh"``: surface plot with mesh lines drawn on top of the surface.
+        - ``"image"``: image plot.


I've used surftype="sim" before here. It's been a few years so I can't remember, but maybe check if -Qsim is equal to -Qsm, or if we need to add a surface+image+mesh option 😂

surftype="sim" is identical to surftype="s":

import pygmt grd_relief = pygmt.datasets.load_earth_relief( resolution="15m", region=[-25, -13, 63.2, 66.7] ) args = dict( region=[-25, -13, 63.2, 66.7], projection="M10c", perspective=(-150, 25), cmap="SCM/oleron", frame=True, zsize="1.5c", plane="+ggray", ) fig = pygmt.Figure() fig.grdview(grid=grd_relief, surftype="sim", **args) fig.shift_origin(xshift="w+2c") fig.grdview(grid=grd_relief, surftype="surface", **args) fig.show()

-Qsim is taken as -Qs based on the GMT source code https://github.com/GenericMappingTools/gmt/blob/a091f7542cfded0ab0cc7f7fe1f899790b5eed56/src/grdview.c#L773-L777.

Nice, glad to know we don't need to add more combinations!

weiji14 · 2026-01-28T02:22:46Z

pygmt/src/grdview.py

+        - ``"surface"``: surface plot.
+        - ``"surface+mesh"``: surface plot with mesh lines drawn on top of the surface.
+        - ``"image"``: image plot.


Nice, glad to know we don't need to add more combinations!

weiji14 · 2026-01-28T02:28:21Z

pygmt/src/grdview.py

+    surftype
+        Specify surface type for the grid. Valid values are:
+
+        - ``"mesh"``: mesh plot [Default].


Default is technically None if no argument is passed to surftype. Should we remove the [Default] then, or allow for surftype=True to mean surftype="m"?

I feel surftype=True is not intuitive, mainly because:

surftype=False is meaningless in this context (False usually means "disable")

surftype=True is mapped to -Q but -Q without any arguments is invalid in GMT.

Agree, so let's just remove the [Default] to only allow string literals

Suggested change

- ``"mesh"``: mesh plot [Default].

- ``"mesh"``: mesh plot.

and probably need to update the docs to remove [Default] too at https://docs.generic-mapping-tools.org/6.6/grdview.html#q if -Q by itself is invalid. Unless I'm missing some context?

"Default" actually means -Q is not required, and if not given, -Qm is used.

seisman force-pushed the grdview/surftype branch from ce5fc8f to d3c7bd2 Compare December 2, 2025 06:14

Figure.grdview: Pythonic syntax for surftype parameter

2f32c36

seisman force-pushed the grdview/surftype branch from d3c7bd2 to 2f32c36 Compare December 2, 2025 06:16

seisman mentioned this pull request Dec 2, 2025

Figure.grdview: Create 3-D perspective image or surface mesh from a grid #4208

Closed

26 tasks

Also migrate the meshpen parameter to the new alias system

25af727

seisman added this to PyGMT paper Dec 5, 2025

seisman added this to the 0.18.0 milestone Dec 6, 2025

seisman added the enhancement Improving an existing feature label Dec 6, 2025

seisman mentioned this pull request Dec 7, 2025

Tracking the status of the examples included in the paper GenericMappingTools/pygmt-paper-figures#14

Open

19 tasks

weiji14 reviewed Dec 8, 2025

View reviewed changes

seisman mentioned this pull request Dec 9, 2025

Figure.grdview: Deprecate parameters contourpen/facadepen/meshpen to contour_pen/facade_pen/mesh_pen (Will be removed in v0.20.0) #4260

Merged

seisman added 6 commits December 9, 2025 22:24

Merge branch 'main' into grdview/surftype

6be6476

Revert "Also migrate the meshpen parameter to the new alias system"

af37916

This reverts commit 25af727.

Improve docstrings and add more checks

fcf69e6

Update existing tests

19cd544

Update existing gallery examples

831d5c2

Add more tests

16051a0

seisman force-pushed the grdview/surftype branch from 69c28ef to 16051a0 Compare December 9, 2025 15:19

seisman added 11 commits December 9, 2025 23:20

Update examples/gallery/3d_plots/grdview_surface.py

af8da8f

Fix a typo

e1b7740

Do not check invalid surftype

40beb74

Merge branch 'main' into grdview/surftype

0bd3efd

Update docstrings for mesh_pen

aedfd1c

Merge branch 'main' into grdview/surftype

74882f0

Add one test for surftype

d2accb9

Add one more test for dpi

ec9d3ec

Add one more test for mesh_pen/mesh_fill

f1ea73f

Fix test_grdview_mesh_pen_and_mesh_fill

b8f7ffa

Remove duplicated tests

073d3b6

seisman removed this from the 0.18.0 milestone Dec 25, 2025

Add tests for backward compatibility

aa9eb73

seisman changed the title ~~Figure.grdview: Pythonic syntax for surftype parameter~~ Figure.grdview: Add parameters surftype/dpi/mesh_fill/nan_transparent/monochrome to control surfure types Jan 11, 2026

Merge branch 'main' into grdview/surftype

05682df

weiji14 mentioned this pull request Jan 22, 2026

AliasSystem: Support adding a suffix to a value and simplify Figure.wiggle #4259

Open

seisman added 2 commits January 23, 2026 19:51

Merge branch 'main' into grdview/surftype

4fc7e37

Improve the checking of conflicting parameters

6d83cb6

seisman marked this pull request as ready for review January 23, 2026 12:31

seisman added the needs review This PR has higher priority and needs review. label Jan 23, 2026

Merge branch 'main' into grdview/surftype

13b00ee

seisman requested a review from Copilot January 26, 2026 04:08

Copilot started reviewing on behalf of seisman January 26, 2026 04:12 View session

Copilot AI reviewed Jan 26, 2026

View reviewed changes

seisman and others added 7 commits January 26, 2026 12:21

Fix a typo [skip ci]

a9ba352

Co-authored-by: Copilot <[email protected]>

Improve docstrings for gallery example

0114016

Fix a typo

ee0c403

Fix a typo

fd5353d

Remove trailing whitespaces

ccd0cf0

Move parameter check to the _alias_option_Q function

7cb3da6

Merge remote-tracking branch 'origin/grdview/surftype' into grdview/s…

27ddac0

…urftype

seisman mentioned this pull request Jan 26, 2026

Figure 3: Use long-form argument for the surftype parameter GenericMappingTools/pygmt-paper-figures#29

Draft

seisman added 2 commits January 26, 2026 19:28

Update baseline image

824b694

Merge branch 'main' into grdview/surftype

25072e5

seisman commented Jan 26, 2026

View reviewed changes

seisman added final review call This PR requires final review and approval from a second reviewer and removed needs review This PR has higher priority and needs review. labels Jan 26, 2026

seisman requested a review from a team January 27, 2026 03:44

weiji14 reviewed Jan 27, 2026

View reviewed changes

Merge branch 'main' into grdview/surftype

050b7e6

weiji14 reviewed Jan 28, 2026

View reviewed changes

Move tests as doctests

727a938



		@pytest.mark.mpl_image_compare
		def test_grdview_with_cmap_for_surface_monochrome_plot(xrgrid):

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

Are you sure you want to change the base?

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

Conversation

seisman commented Dec 2, 2025 • edited by weiji14 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weiji14 Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weiji14 Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seisman Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weiji14 Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

seisman commented Dec 2, 2025 •

edited by weiji14

Loading

weiji14 Jan 22, 2026 •

edited

Loading

weiji14 Jan 27, 2026 •

edited

Loading

seisman Jan 28, 2026 •

edited

Loading

weiji14 Jan 28, 2026 •

edited

Loading