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


gmt grdview reliefgrid -Jparameters [ -B[p|s]parameters ] [ -C[cpt]] [ -Gdrapegrid | -Ggrd_r -Ggrd_g -Ggrd_b ] [ -I[intensgrid|intensity|modifiers] ] [ -Jz|Zparameters ] [ -Nlevel[+gfill] ] [ -Qargs[+m] ] [ -Rwest/east/south/north[/zmin/zmax][+r][+uunit] ] [ -Ssmooth ] [ -T[+o[pen]][+s] ] [ -U[stamp] ] [ -Wc|m|fpen ] [ -X[a|c|f|r][xshift[u]] ] [ -Y[a|c|f|r][yshift[u]] ] [ -fflags ] [ -nflags ] [ -pflags ] [ -ttransp ] [ --PAR=value ]

Note: No space is allowed between the option flag and the associated arguments.


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

Required Arguments

2-D gridded data set to be imaged (the relief of the surface). (See GRID FILE FORMAT below.)
-Jparameters (more …)
Select map projection.
-Jz|Zparameters (more …)
Set z-axis scaling; same syntax as -Jx.

Optional Arguments

-B[p|s]parameters (more …)
Set map boundary frame and axes attributes.
-C[cpt |master[+izinc] |color1,color2[,color3,…]]
The name of the CPT. Must be present if you want (1) mesh plot with contours (-Qm), or (2) shaded/colored perspective image (-Qs or -Qi). For -Qs: You can specify that you want to skip a z-slice by setting the red r/g/b component to -; to use a pattern give red = P|ppattern[+bcolor][+fcolor][+rdpi]. Alternatively, supply the name of a GMT color master dynamic CPT [turbo, but geo for @earth_relief and srtm for @srtm_relief data] to automatically determine a continuous CPT from the grid’s z-range; you may round up/down the z-range by adding +izinc. If no argument is given to -C then under modern mode we select the current CPT.
-Gdrapegrid | -Ggrd_r -Ggrd_g -Ggrd_b
Drape the image in drapegrid on top of the relief provided by reliefgrid. [Default determines colors from reliefgrid]. Note that -Jz and -N always refers to the reliefgrid. The drapegrid only provides the information pertaining to colors, which (if drapegrid is a grid) will be looked-up via the CPT (see -C). Instead, you may give three grid files via separate -G options in the specified order. These files must contain the red, green, and blue colors directly (in 0-255 range) and no CPT is needed. The drapegrid may be of a different resolution than the reliefgrid. Finally, drapegrid may be an image to be draped over the surface, in which case the -C option is not required.
Gives the name of a grid file with intensities in the (-1,+1) range, or a constant intensity to apply everywhere; this simply affects the ambient light. If just + is given then we derive an intensity grid from the input data grid reliefgrid via a call to grdgradient using the arguments -A-45 and -Nt1 for that module. You can append +aazimuth and +nargs to override those values. If you want more specific intensities then run grdgradient separately first. [Default is no illumination].
Draws 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. See -Wf for setting the pen used for the outline.

Select one of following settings. For any of these choices, you may force a monochrome image by appending the modifier +m. Colors are then converted to shades of gray using the (monochrome television) YIQ transformation

  1. Specify m for mesh plot [Default], and optionally append color for a different mesh paint [white].
  2. Specify mx or my for waterfall plots (row or column profiles). Specify color as for plain m
  3. Specify s for surface plot, and optionally append m to have mesh lines drawn on top of surface.
  4. Specify i for image plot, and optionally append the effective dpi resolution for the rasterization [100].
  5. Specify c. Same as -Qi but will make nodes with z = NaN transparent, using the colormasking feature in PostScript Level 3 (the PS device must support PS Level 3). .
-Rxmin/xmax/ymin/ymax[+r][+uunit] (more …)
Specify the region of interest.

For perspective view -p, optionally append /zmin/zmax. (more …) This option may be used to indicate the range used for the 3-D axes [Default is region given by the reliefgrid]. You may ask for a larger w/e/s/n region to have more room between the image and the axes. A smaller region than specified in the reliefgrid will result in a subset of the grid.

Smooth the contours before plotting (see grdcontour) [Default is no smoothing].
Plot image without any interpolation. This involves converting each node-centered bin into a polygon which is then painted separately. Append +s to skip nodes with z = NaN. This option is useful for categorical data where interpolating between values is meaningless. Optionally, append +o to draw the tile outlines, and specify a custom pen if the default pen is not to your liking. As this option produces a flat surface it cannot be combined with -JZ or -Jz.
-U[label][+c][+jjust][+odx/dy] (more …)
Draw GMT time stamp logo on plot.
-V[level] (more …)
Select verbosity level [c].


Draw contour lines on top of surface or mesh (not image). Append pen attributes used for the contours. [Default: width = 0.75p, color = black, style = solid].
Sets the pen attributes used for the mesh. [Default: width = 0.25p, color = black, style = solid]. You must also select -Qm or -Qsm for meshlines to be drawn.
Sets the pen attributes used for the facade. [Default: width = 0.25p, color = black, style = solid]. You must also select -N for the facade outline to be drawn.


-Y[a|c|f|r][yshift[u]] (more …)
Shift plot origin.
-n[b|c|l|n][+a][+bBC][+c][+tthreshold] (more …)
Select interpolation mode for grids.
-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more …)
Select perspective view.
-t[transp] (more …)
Set transparency level in percent.
-^ or just -
Print a short message about the syntax of the command, then exits (NOTE: on Windows just use -).
-+ or just +
Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exits.
-? or no arguments
Print a complete usage (help) message, including the explanation of all options, then exits.
Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

Grid File Formats

By default GMT writes out grid as single precision floats in a COARDS-complaint netCDF file format. However, GMT is able to produce grid files in many other commonly used grid file formats and also facilitates so called “packing” of grids, writing out floating point data as 1- or 2-byte integers. (more …)

Consequences of grid resampling

Except for Cartesian cases, we need to resample your geographic grid onto an equidistant projected grid. In doing so various algorithms come into play that projects data from one lattice to another while avoiding anti-aliasing, leading to possible distortions. One expected effect of resampling with splines is the tendency for the new resampled grid to slightly exceed the global min/max limits of the original grid. If this is coupled with tight CPT limits you may find that some map areas may show up with fore- or background color due to the resampling. In that case you have two options: (1) Modify your CPT to fit the resampled extrema (reported with -V) or (2) Impose clipping of resampled values so they do not exceed the input min/max values (add +c to your -n option).


Note: Below are some examples of valid syntax for this module. The examples that use remote files (file names starting with @) can be cut and pasted into your terminal for testing. Other commands requiring input files are just dummy examples of the types of uses that are common but cannot be run verbatim as written.

Note: Since many GMT plot examples are very short (i.e., one module call between the gmt begin and gmt end commands), we will often present them using the quick modern mode GMT Modern Mode One-line Commands syntax, which simplifies such short scripts.

To make a mesh plot from the file and drawing the contours given in the CPT hawaii.cpt on a Lambert map at 1.5 cm/degree along the standard parallels 18 and 24, with vertical scale 20 mgal/cm, and looking at the surface from SW at 30 degree elevation, run

gmt grdview -Jl18/24/1.5c -Chawaii.cpt -Jz0.05c -Qm -N-100 -p225/30 -Wc -pdf hawaii_grav_image

To create a illuminated color perspective plot of the gridded data set, using the CPT color.cpt, with linear scaling at 10 cm/x-unit and tickmarks every 5 units, with intensities provided by the file, and looking from the SE, use

gmt grdview -Jx10c -Ccolor.cpt -Qs -p135/30 -pdf image3D

To make the same plot using the rastering option with dpi = 50, use

gmt grdview -Jx10c -Ccolor.cpt -Qi50 -p135/30 -pdf image3D

To create a color perspective plot of the gridded data set, using the CPT mag_intens.cpt, draped over the relief given by the file, with Mercator map width of 6 inch and tickmarks every 1 degree, with intensities provided by the file, and looking from the SE, run

gmt grdview -JM6i -Cmag_intens.cpt -Qs -p140/30 -pdf draped3D


For the -Qs option: The PostScript language has no mechanism for smoothly varying colors within a polygon, so colors can only vary from polygon to polygon. To obtain smooth images this way you may resample the grid file(s) using grdsample or use a finer grid size when running gridding programs like surface or nearneighbor. Unfortunately, this produces huge PostScript files. The alternative is to use the -Qi option, which computes bilinear or bicubic continuous color variations within polygons by using scanline conversion to image the polygons.