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

[seisman]

This issue serves as the central place for discussing and tracking the implementation of the grdview method in PyGMT. The issue will be closed when the initial implementation is complete. Progress is tracked at PyGMT: Wrapping GMT modules.

Documentation

• GMT: https://docs.generic-mapping-tools.org/dev/grdview.html
• GMT.jl: https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/grdview
• PyGMT: https://www.pygmt.org/dev/api/generated/pygmt.Figure.grdview.html

GMT Option Flags and Modifieres

☑️: Implemented; ⬜: To be implemented/discussed; Strikethrough: Won't implement.

• ingrid: grid
• -R: region
• -J: projection
• -Jz: zscale/zsize
• -B: frame
• -C: cmap Figure.grdview: Migrate cmap alias to the new alias system #4443
• -G: drape_grid Figure.grdview: Migrate the 'drapegrid' parameter to the new alias system #4442
• -I
• -N: plane/facade_fill Figure.grdview: Improve parameters plane/facade_fill/facade_pen to set the plane and facade #4235 @seisman
• -Q: surftype/dpi/meshfill/nan_transparent/monochrome Figure.grdview: Add parameters surftype/dpi/mesh_fill/nan_transparent/monochrome to control surface types #4234 @seisman
• -S: smooth Figure.grdview: Add alias "smooth" for the -S option #4444
• -T Figure.grdview, Figure.grdimage: Add alias "no_interpolation" for "-T" #3355
• -U: Use Figure.timestamp instead.
• -V: verbose
• -W:
  • -Wc: contour_pen
  • -Wf: facade_pen Figure.grdview: Improve parameters plane/facade_fill/facade_pen to set the plane and facade #4235 @seisman
  • -Wm: mesh_pen Figure.grdview: Add parameters surftype/dpi/mesh_fill/nan_transparent/monochrome to control surface types #4234
• -X/-Y: Use Figure.shift_origin instead.
• -f
• -b
• -p
• -t
• --PAR=value: Use pygmt.config instead.

Linked Pull Requests

• Initial feature implementation Wrap grdview #330 @weiji14
• Add a tutorial or gallery example

Related Issues and Discussions

Add links to related wrapper discussions, API design threads, or upstream GMT changes here.

[seisman]

-Q option is one of the commonly used options in grdview. Its full syntax is -Qc|i|m[x|y]|s[m][color][+m], with full documentation at https://docs.generic-mapping-tools.org/6.6/grdview.html#q.

It will be used in the Figure 3 of the PyGMT paper, so we need to make it Pythonic. Below is an example showing the possible use cases of this option:

import pygmt

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

fig = pygmt.Figure()
with fig.subplot(nrows=4, ncols=3, subsize=(5, 5), margins=(1, 0.2)):
    for surftype in ("c", "i", "i50", "m", "mx", "my", "mlightblue", "mxgreen", "mylightred", "s", "sm", "s+m"):
        fig.grdview(
            region=[-25, -13, 63.2, 66.7], 
            projection="M?", 
            frame=["xaf", "yaf", f"WSenZ+t{surftype}"],
            perspective=(-150, 25),
            grid=grd_relief,
            cmap="SCM/oleron",
            surftype=surftype,
            zsize="1.5c",
            plane="+ggray",
            panel=True,
        )
fig.show()

The output image is:

So, what is the Pythonic way to specify this option?

1. The parameter surftype can be used to control the plot type. Its possible values are:
   • "surface": mapped to "s", i.e., surface plot
   • "mesh": mapped to "m", i.e., mesh plot
   • "surface_mesh"/"surface+mesh": mapped to "sm", surface plot with mesh lines on top
   • "waterfallx"/waterfall_x: mapped to "mx", waterfall plot in x direction
   • "waterfally"/waterfall_y: mapped to "my", waterfall plot in y direction
   • "image": mapped to "i", i.e., image plot
2. More parameters are needed to cover more complicated cases:
   • Parameter nan_transparent: surftype="c" is similar to "i" for an image plot, with transparent NaN nodes. So, surftype="image", nan_transparent=True is mapped to "c". The parameter name nan_transparent is the same as grdimage's -Q option.
   • Parameter dpi: Set the dpi for image plot "i" or "c". The parameter name is the same as grdimage's -E option
   • meshfill/meshcolor: Set the color (patterns are allowed, so fill makes more sense) for mesh and waterfall plots.
   • Parameter monochrome: For the modifier +m. The name is the same as grdimage's -M option

Also see the GMT.jl documentation for reference.

Any comments?