pygmt.Figure.grdview

Figure.grdview(grid, projection=None, region=None, verbose=False, panel=False, transparency=None, **kwargs)

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

Reads a 2-D grid file and produces a 3-D perspective plot by drawing a mesh, painting a colored/gray-shaded surface made up of polygons, or by scanline conversion of these polygons to a raster image. Options include draping a data set on top of a surface, plotting of contours on top of the surface, and apply artificial illumination based on intensities provided in a separate grid file.

Full GMT docs at https://docs.generic-mapping-tools.org/6.6/grdview.html.

Aliases:

B = frame C = cmap G = drapegrid I = shading JZ = zsize Jz = zscale N = plane

Q = surftype Wc = contourpen Wf = facadepen Wm = meshpen f = coltypes n = interpolation

p = perspective J = projection R = region V = verbose c = panel t = transparency

Parameters:

• grid (str | PathLike | DataArray) –

  Name of the input grid file or the grid loaded as a xarray.DataArray object.

  For reading a specific grid file format or applying basic data operations, see https://docs.generic-mapping-tools.org/6.6/gmt.html#grd-inout-full for the available modifiers.

• region (str or list) – xmin/xmax/ymin/ymax[+r][+uunit]. Specify the region 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 (str | None, default: None) – projcode[projparams/]width|scale. Select map projection.

• zscale/zsize (float or str) – Set z-axis scaling or z-axis size.

• frame (bool, str, or list) – Set map boundary frame and axes attributes.

• cmap (str) – The name of the color palette table to use.

• drapegrid (str or xarray.DataArray) – The file name or a xarray.DataArray of the image grid to be draped on top of the relief provided by grid [Default determines colors from grid] 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[+gfill]. 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:

  • 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.

• contourpen (str) – 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) – Set the pen attributes used for the facade. You must also select plane for the facade outline 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). Alternatively, derive an intensity grid from the main input data grid by using pygmt.grdgradient first; append +aazimuth, +nargs, and +mambient 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”].

• verbose (bool or str) – Select verbosity level [Full usage].

• panel (int | tuple[int, int] | bool, default: False) –

  Select a specific subplot panel. Only allowed when used in Figure.subplot mode.

  • True to advance to the next panel in the selected order.

  • index to specify the index of the desired panel.

  • (row, col) to specify the row and column of the desired panel.

  The panel order is determined by the Figure.subplot method. row, col and index all start at 0.

• coltypes (str) – [i|o]colinfo. Specify data types of input and/or output columns (time or geographical data). Full documentation is at https://docs.generic-mapping-tools.org/6.6/gmt.html#f-full.

• interpolation (str) –

  [b|c|l|n][+a][+bBC][+c][+tthreshold]. Select interpolation mode for grids. You can select the type of spline used:

  • b for B-spline

  • c for bicubic [Default]

  • l for bilinear

  • n for nearest-neighbor

• perspective (list or str) – [x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0]. Select perspective view and set the azimuth and elevation angle of the viewpoint [Default is [180, 90]]. Full documentation is at https://docs.generic-mapping-tools.org/6.6/gmt.html#perspective-full.

• transparency (float) – Set transparency level, in [0-100] percent range [Default is 0, i.e., opaque]. Only visible when PDF or raster format output is selected. Only the PNG format selection adds a transparency layer in the image (for further processing).

Example

>>> import pygmt
>>> # Load the 30 arc-minutes grid with "gridline" registration in a given region
>>> grid = pygmt.datasets.load_earth_relief(
...     resolution="30m",
...     region=[-92.5, -82.5, -3, 7],
...     registration="gridline",
... )
>>> # Create a new figure instance with pygmt.Figure()
>>> fig = pygmt.Figure()
>>> # Create the contour plot
>>> fig.grdview(
...     # Pass in the grid downloaded above
...     grid=grid,
...     # Set the perspective to an azimuth of 130° and an elevation of 30°
...     perspective=[130, 30],
...     # Add a frame to the x- and y-axes
...     # Specify annotations on the south and east borders of the plot
...     frame=["xa", "ya", "wSnE"],
...     # Set the projection of the 2-D map to Mercator with a 10 cm width
...     projection="M10c",
...     # Set the vertical scale (z-axis) to 2 cm
...     zsize="2c",
...     # Set "surface plot" to color the surface via a CPT
...     surftype="s",
...     # Specify CPT to "geo"
...     cmap="geo",
... )
>>> # Show the plot
>>> fig.show()

Examples using pygmt.Figure.grdview

Plotting a surface

Plotting a surface

Creating a 3-D perspective image

Creating a 3-D perspective image

Draping a dataset on top of a topographic surface

Draping a dataset on top of a topographic surface