Provided by: gmt-common_5.4.5+dfsg-1_all bug

NAME

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

SYNOPSIS

       grdview  relief_file   -Jparameters  [   -B[p|s]parameters  ] [  -C[cpt]] [  -Gdrapefile |
       -Ggrd_r  -Ggrd_g  -Ggrd_b ] [  -I[intensfile|intensity|modifiers] ] [ -Jz|Zparameters ]  [
       -K    ]    [     -Nlevel[+gfill]    ]    [   -O   ]   [   -P   ]   [    -Qargs[+m]   ]   [
       -Rwest/east/south/north[/zmin/zmax][+r] ] [  -Ssmooth ] [  -T[s][o[pen]] ] [  -U[stamp]  ]
       [   -Wc|m|fpen  ]  [   -Xx_offset  ] [  -Yy_offset ] [ -fflags ] [ -nflags ] [ -pflags ] [
       -ttransp ]

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

DESCRIPTION

       grdview reads a 2-D grid file and produces a 3-D  perspective  plot  by  drawing  a  mesh,
       painting  a  colored/grayshaded  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

       relief_file
              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]
              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 [rainbow] to automatically determine a
              continuous CPT from the grid's z-range.  If the dynamic CPT  has  a  default  range
              then that range will be imposed instead.

        -Gdrapefile |  -Ggrd_r  -Ggrd_g  -Ggrd_b
              Drape the image in drapefile on top of the relief provided by relief_file. [Default
              is relief_file]. Note that -Jz  and  -N  always  refers  to  the  relief_file.  The
              drapefile  only  provides  the information pertaining to colors, which is looked-up
              via the CPT (see -C). Alternatively, 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  drapefile  may  be  of  higher
              resolution than the relief_file.

       -I[intensfile|intensity|modifiers]
              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 grd_z via a call to
              grdgradient using the arguments -A-45 and -Nt1 for  that  module.  You  can  append
              +aazimuth  and  **+n*args  to  override  those  values.   If you want more specific
              intensities then run grdgradient separately first.  [Default is no illumination].

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

       -Nlevel[+gfill]
              Draws a plane at this z-level. If  the  optional  color  is  provided  via  the  +g
              modifier,  the  frontal facade between the plane and the data perimeter is colored.
              See -Wf for setting the pen used for the outline.

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

       -P (more ...)
              Select "Portrait" plot orientation.

       -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

              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 relief_file].
       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 relief_file will result in a subset of the grid.

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

       -T[s][o[pen]]
              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[[just]/dx/dy/][c|label] (more ...)
              Draw GMT time stamp logo on plot.

       -V[level] (more ...)
              Select verbosity level [c].

       -Wc|m|fpen

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

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

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

       -X[a|c|f|r][x-shift[u]]

       -Y[a|c|f|r][y-shift[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 PDF 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.

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

EXAMPLES

       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 a illuminated color perspective plot of the gridded data set image.nc, using the
       CPT color.rgb, 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 -Jx10.0c -Ccolor.rgb -Qs -p135/30 -Iintens.nc > image3D.ps

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

              gmt grdview image.nc -Jx10.0c -Ccolor.rgb -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

       Given topo.nc and the Landsat image veggies.ras, first run grd2rgb to get the red,  green,
       and  blue  grids,  and  then drape this image over the topography and shade the result for
       good measure. The commands are

              gmt grd2rgb veggies.ras -Glayer_%c.nc
              gmt grdview topo.nc -JM6i -Qi -p140/30 -Itopo_intens.nc \
                         -Glayer_r.nc -Glayer_g.nc -Glayer_b.nc > image.ps

REMARKS

       For the -Qs option: PostScript provides  no  way  of  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.

SEE ALSO

       gmt,  grd2rgb,  gmtcolors,  grdcontour,  grdimage,  grdsample,  nearneighbor,   psbasemap,
       pscontour, pstext, surface

COPYRIGHT

       2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe