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


       grdlandmask - "Create a ""wet-dry"" mask grid from shoreline data base"


       grdlandmask  -Gmask_grd_file
        -Rregion    [     -Amin_area[/min_level/max_level][+ag|i|s    |S][+r|l][ppercent]   ]   [
       -Dresolution[+] ] [  -N ] [  -Nmaskvalues ] [  -V[level] ] [ -r ] [ -x[[-]n] ]

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


       grdlandmask reads the selected shoreline database and  uses  that  information  to  decide
       which  nodes  in  the specified grid are over land or over water. The nodes defined by the
       selected region and lattice spacing will be set according to one of two criteria: (1) land
       vs water, or (2) the more detailed (hierarchical) ocean vs land vs lake vs island vs pond.
       The resulting mask may be used in subsequent operations involving grdmath to mask out data
       from land [or water] areas.


              Name of resulting output mask grid file. (See GRID FILE FORMATS below).

              x_inc  [and  optionally  y_inc]  is  the  grid spacing. Optionally, append a suffix
              modifier. Geographical (degrees) coordinates: Append m to indicate arc minutes or s
              to  indicate  arc  seconds.  If  one  of  the  units e, f, k, M, n or u is appended
              instead, the increment is assumed to be given in meter, foot,  km,  Mile,  nautical
              mile  or  US  survey  foot,  respectively,  and will be converted to the equivalent
              degrees longitude at the middle latitude of the region (the conversion  depends  on
              PROJ_ELLIPSOID).  If  y_inc  is given but set to 0 it will be reset equal to x_inc;
              otherwise it will be converted to degrees  latitude.  All  coordinates:  If  +e  is
              appended  then the corresponding max x (east) or y (north) may be slightly adjusted
              to fit exactly the given increment  [by  default  the  increment  may  be  adjusted
              slightly  to fit the given domain]. Finally, instead of giving an increment you may
              specify the number of nodes  desired  by  appending  +n  to  the  supplied  integer
              argument;  the  increment  is  then  recalculated  from the number of nodes and the
              domain. The resulting increment value  depends  on  whether  you  have  selected  a
              gridline-registered  or  pixel-registered  grid;  see App-file-formats for details.
              Note: if -Rgrdfile is used then the grid spacing has already been initialized;  use
              -I to override the values.

              west,  east,  south,  and north specify the region of interest, and you may specify
              them in decimal degrees or in [±]dd:mm[][W|E|S|N] format Append +r if  lower
              left  and  upper  right  map  coordinates  are  given  instead  of w/e/s/n. The two
              shorthands -Rg and -Rd stand for global domain (0/360 and  -180/+180  in  longitude
              respectively,  with  -90/+90  in  latitude).  Alternatively for grid creation, give
              Rcodelon/lat/nx/ny, where code is a 2-character combination of L, C, R  (for  left,
              center,  or right) and T, M, B for top, middle, or bottom. e.g., BL for lower left.
              This indicates which point on a rectangular region the  lon/lat  coordinate  refers
              to,  and  the grid dimensions nx and ny with grid spacings via -I is used to create
              the corresponding region.  Alternatively, specify the name of an existing grid file
              and  the  -R  settings  (and grid spacing, if applicable) are copied from the grid.
              Appending +uunit expects projected (Cartesian) coordinates compatible  with  chosen
              -J and we inversely project to determine actual rectangular geographic region.  For
              perspective view (-p), optionally append /zmin/zmax.  In case of  perspective  view
              (-p),  a z-range (zmin, zmax) can be appended to indicate the third dimension. This
              needs to be done only when using the -Jz option, not when using only the -p option.
              In  the  latter  case  a  perspective  view  of the plane is plotted, with no third


              Features with an area smaller than min_area in km^2 or of hierarchical  level  that
              is  lower  than  min_level or higher than max_level will not be plotted [Default is
              0/0/4 (all features)].  Level 2 (lakes)  contains  regular  lakes  and  wide  river
              bodies  which we normally include as lakes; append +r to just get river-lakes or +l
              to just get regular lakes.  By default (+ai) we select the ice  shelf  boundary  as
              the  coastline  for Antarctica; append +ag to instead select the ice grounding line
              as coastline.  For expert users who wish to print their  own  Antarctica  coastline
              and islands via psxy you can use +as to skip all GSHHG features below 60S or +aS to
              instead skip all features north of  60S.   Finally,  append  +ppercent  to  exclude
              polygons whose percentage area of the corresponding full-resolution feature is less
              than percent. See GSHHG INFORMATION below for more details.

              Selects the resolution of the data set  to  use  ((f)ull,  (h)igh,  (i)ntermediate,
              (l)ow, or (c)rude). The resolution drops off by ~80% between data sets. [Default is
              l].  Append + to automatically select a lower resolution should the  one  requested
              not   be   available  [abort  if  not  found].   Alternatively,  choose  (a)uto  to
              automatically select the best  resolution  given  the  chosen  region.   Note  that
              because the coastlines differ in details a node in a mask file using one resolution
              is not guaranteed to remain inside [or outside]  when  a  different  resolution  is

       -E     Indicate that nodes that fall exactly on a polygon boundary should be considered to
              be outside the polygon [Default considers them to be inside].

              Sets the values that will be assigned to nodes. Values can be any number, including
              the  textstring  NaN.  Also select -E to let nodes exactly on feature boundaries be
              considered outside [Default is inside]. Specify  this  information  using  1  of  2



              [Default is 0/1/0/1/0 (i.e., 0/1)].

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

       -r (more ...)
              Set pixel node registration [gridline].

       -x[[-]n] (more ...)
              Limit number of cores used in multi-threaded algorithms (OpenMP required).

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


       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. To specify the precision, scale and offset, the user should
       add the suffix =ID[+sscale][+ooffset][+ninvalid], where ID is a two-letter  identifier  of
       the  grid type and precision, and scale and offset are optional scale factor and offset to
       be applied to all grid values, and invalid is the value used to indicate missing data. See
       grdconvert  and  Section  grid-file-format of the GMT Technical Reference and Cookbook for
       more information.

       When writing a netCDF file, the grid is stored by default with the variable name  "z".  To
       specify another variable name varname, append ?varname to the file name. Note that you may
       need to escape the special meaning of ? in your shell program by putting  a  backslash  in
       front of it, or by placing the filename and suffix between quotes or double quotes.


       A  grid  produced by grdlandmask is a categorical dataset.  As such, one has to be careful
       not to interpolate it with standard methods, such as splines.  However, if you make a  map
       of  this  grid  using a map projection the grid will be reprojected to yield a rectangular
       matrix in the projected coordinates.  This interpolation is done using splines by  default
       and  thus  may  yield artifacts in your map.  We recommend you use grdimage -nn to instead
       use a nearest neighbor interpolation for such cases.


       To set all nodes on land to NaN, and nodes over water to 1, using the high resolution data
       set, do

              gmt grdlandmask -R-60/-40/-40/-30 -Dh -I5m -N1/NaN -V

       To  make  a  1x1 degree global grid with the hierarchical levels of the nodes based on the
       low resolution data:

              gmt grdlandmask -R0/360/-90/90 -Dl -I1 -N0/1/2/3/4 -V


       The coastline database is GSHHG (formerly GSHHS) which is  compiled  from  three  sources:
       World Vector Shorelines (WVS), CIA World Data Bank II (WDBII), and Atlas of the Cryosphere
       (AC, for Antarctica only).   Apart  from  Antarctica,  all  level-1  polygons  (ocean-land
       boundary)  are  derived  from the more accurate WVS while all higher level polygons (level
       2-4,          representing          land/lake,          lake/island-in-lake,           and
       island-in-lake/lake-in-island-in-lake  boundaries)  are  taken from WDBII.  The Antarctica
       coastlines come in two flavors: ice-front or grounding line, selectable via the -A option.
       Much  processing  has  taken place to convert WVS, WDBII, and AC data into usable form for
       GMT:  assembling  closed  polygons  from  line  segments,  checking  for  duplicates,  and
       correcting  for  crossings between polygons.  The area of each polygon has been determined
       so that the user may choose not to draw features smaller than a minimum area (see -A); one
       may  also  limit  the  highest  hierarchical  level  of  polygons to be included (4 is the
       maximum). The 4 lower-resolution databases were derived from the full resolution  database
       using  the Douglas-Peucker line-simplification algorithm. The classification of rivers and
       borders follow that of the WDBII. See the GMT Cookbook and Technical Reference Appendix  K
       for further details.


       gmt, grdmath, grdclip, psmask, psclip, pscoast


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