grdview

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

Synopsis

gmt grdview reliefgrid -Jparameters [ -B[p|s]parameters ] [ -C[cpt]] [ -Gdrapegrid | -Ggrd_r -Ggrd_g -Ggrd_b ] [ -I[intensgrid|intensity|modifiers] ] [ -Jz|Zparameters ] [ -K ] [ -Nlevel[+gfill] ] [ -O ] [ -P ] [ -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] ] [ -Y[a|c|f|r][yshift] ] [ -fflags ] [ -nflags ] [ -pflags ] [ -ttransp ] [ --PAR=value ]

Description

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

reliefgrid: 2-D gridded data set to be imaged (the relief of the surface). (See Grid File Formats).

-Jparameters: Specify the projection. (See full description) (See cookbook summary) (See projections table).

Optional Arguments

-B[p|s]parameters: Set map boundary frame and axes attributes. (See full description) (See cookbook information).

-C[section/]master|cpt|color\(_1\),color\(_2\)[,color\(_3\),…][+h[hinge]][+idz][+u|Uunit][+sfname]

Name of a master CPT, an input CPT file or a comma-separated list of colors from which to build a CPT. If no argument is given then under modern mode we select the current CPT, if it is available. Generally, the input can be many things:

A standard GMT master CPT file, e.g., earth (see Of Colors and Color Legends) and can be either addressed by master or section/master (without any .cpt extension).
File name of already custom-made cpt file (e.g, my_colors.cpt).
Build a linear continuous CPT from color\(_1\),color\(_2\)[,color\(_3\),…] automatically, where z starts at 0 and is incremented by one for each color. In this case, color\(_i\) can be a r/g/b (e.g., 255/100/75), h-s-v triplet (e.g., 180-0.8-1), a c/m/y/k quadruple (e.g., 80/50/40/30), an HTML hexadecimal color (e.g. #aabbcc), or a color name. No spaces between commas are allowed.

A few modifiers pertains to hinges and units:

+h - If given a master CPT with soft hinges then you can enable the hinge at data value hinge [0], whereas for hard-hinge CPTs you can adjust the location of the hinge [0] but not disable it.
+i - Append increment dz to quantize the grid range [Default uses the exact grid range].
+s - Append fname to save the finalized CPT in a disk file. This is useful when the CPT is generated automatically, but if used, must be at the end of the -C option.
+u - For any other master CPT, you may convert their z-values from other distance Units to meter by appending the original unit code.
+U - Likewise, you may convert their z-values from meter to other Units by appending the desired unit code.

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

-I[file|intens|+aazimuth][+d][+mambient][+nargs]

Apply illumination for the input grid. Several methods are available:

Give the file name of a co-registered grid with intensities in the ±1 range.
Give a constant intens to apply everywhere (affects the ambient light).

Alternatively, derive intensities from the main input data grid via a call to grdgradient by appending +aazimuth, +nargs and +mambient for the arguments needed by that module, or just give +d to select the default [+a-45+nt1+m0]. For more specific intensity scenarios run grdgradient separately first. If we should derive intensities from another file than the main grid, specify that file as the file and add suitable modifiers [Default is no illumination]. Note: If the input grid actually is an image then file or constant intens must be provided since derivatives are not available.

-Jz|Zparameters: Set z-axis scaling; same syntax as -Jx.

-N[level][+gfill]: 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. If no level is set then we default to the minimum value in the reliefgrid. However, if -R was used to set zmin/zmax then we use that value if it is less than the grid minimum value.

-Qargs[+m]

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

Specify m for mesh plot [Default], and optionally append color for a different mesh paint [white].
Specify mx or my for waterfall plots (row or column profiles). Specify color as for plain m
Specify s for surface plot, and optionally append m to have mesh lines drawn on top of surface.
Specify i for image plot, and optionally append the effective dots-per-unit resolution for the rasterization [Default is GMT_GRAPHICS_DPU].
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).

Note: If the CPT is categorical then only -Qm is available (but see -T).

-Rxmin/xmax/ymin/ymax[+r][+uunit]: Specify the region of interest. (See full description) (See cookbook information).

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.

-Ssmooth: Smooth the contours before plotting (see grdcontour) [Default is no smoothing].

-T[+o[pen]][+s]: 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 suitable for categorical data where interpolating between values is meaningless and a categorical CPT has been provided via -C. 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][+jjustify][+odx[/dy]][+ttext]: Draw GMT time stamp logo on plot. (See full description) (See cookbook information).

-V[level]: Select verbosity level [w]. (See full description) (See cookbook information).

-Wc|m|fpen

Sets pen for contours, mesh, and facade lines. Choose among these directives:

c: Append the desired contour pen. 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].
f: Append the desired facade pen. 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.
m: Append the desired mesh pen. 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.

-X[a|c|f|r][xshift]: Shift plot origin. (See full description) (See cookbook information).

-Y[a|c|f|r][yshift]: Shift plot origin. (See full description) (See cookbook information).

-f[i|o]colinfo (more …): Specify data types of input and/or output columns.

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

-ttransp[/transp2] (more …): Set transparency level(s) in percent.

-^ or just -: Print a short message about the syntax of the command, then exit (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 exit.
-? or no arguments: Print a complete usage (help) message, including the explanation of all options, then exit.
--PAR=value: Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

Units

For map distance unit, append unit d for arc degree, m for arc minute, and s for arc second, or e for meter [Default unless stated otherwise], f for foot, k for km, M for statute mile, n for nautical mile, and u for US survey foot. By default we compute such distances using a spherical approximation with great circles (-jg) using the authalic radius (see PROJ_MEAN_RADIUS). You can use -jf to perform “Flat Earth” calculations (quicker but less accurate) or -je to perform exact geodesic calculations (slower but more accurate; see PROJ_GEODESIC for method used).

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: If -n is not set and no CPT is given (or a master CPT is given or implied), we automatically set -nc+c.

Classic Mode Arguments

These options are used to manipulate the building of layered GMT PostScript plots in classic mode. They are not available when using GMT modern mode.

-K (more …): Do not finalize the PostScript plot.

-O (more …): Append to existing PostScript plot.

-P (more …): Select “Portrait” plot orientation.

Examples

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.

To make a mesh plot from the file hawaii_grav.nc 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 hawaii_grav.nc -Jl18/24/1.5c -Chawaii.cpt \
            -Jz0.05c -Qm -N-100 -p225/30 -Wc > hawaii_grav_image.ps

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

gmt grdview image.nc -Jx10c -Ccolor.cpt -Qs -p135/30 -Iintens.nc > image3D.ps

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

gmt grdview image.nc -Jx10c -Ccolor.cpt -Qi50 -p135/30 -Iintens.nc > image3D.ps

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

gmt grdview topography.nc -JM6i -Gmagnetics.nc -Cmag_intens.cpt \
            -Qs -p140/30 -Itopo_intens.nc > draped3D.ps

Notes

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.

MacOS Preview Warning

Low-resolution raster-images appearing in PDF or PostScript files may look blurry when viewed with the Preview application under macOS. This happens because Preview decides to resample very coarse (low dpi) images instead of leaving them alone; we do not know of a simple way to turn this feature off. It is most noticeable in color bars for discrete CPTs (we now use -Np as the default setting for such CPTs) and very small grids plotted in either grdimage or grdview -Qi|c. However, if a raster format (such as JPG or PNG) is selected instead then here is no such blurring. Other PDF viewers (e.g., Adobe Acrobat) do not seem similarly affected.