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

NAME

       grdmask - Create mask grid from polygons or point coverage

SYNOPSIS

       grdmask pathfiles  -Gmask_grd_file
        -Iincrement
        -Rregion  [  -A[m|p|x|y] ] [  -N[z|Z|p|P]values ] [  -Ssearch_radius[unit] ] [  -V[level]
       ] [ -bibinary ] [ -dinodata ] [ -eregexp ] [ -fflags ] [ -ggaps ] [ -hheaders ] [  -iflags
       ] [ -nflags ] [ -r ] [ -x[[-]n] ] [ -:[i|o] ]

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

DESCRIPTION

       grdmask  can  operate  in two different modes. 1. It reads one or more pathfiles that each
       define a closed polygon. The nodes defined by the specified  region  and  lattice  spacing
       will  be  set  equal  to  one  of  three  possible values depending on whether the node is
       outside, on the polygon perimeter, or inside the polygon. The resulting mask may  be  used
       in  subsequent  operations involving grdmath to mask out data from polygonal areas. 2. The
       pathfiles simply represent data point locations and the mask  is  set  to  the  inside  or
       outside  value  depending  on whether a node is within a maximum distance from the nearest
       data point. If the distance specified is zero then only the nodes nearest each data  point
       are considered "inside".

REQUIRED ARGUMENTS

       pathfiles
              The  name  of  1 or more ASCII [or binary, see -bi] files holding the polygon(s) or
              data points.

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

       -Ixinc[unit][+e|n][/yinc[unit][+e|n]]
              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.

       -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
              Specify the region of interest.

OPTIONAL ARGUMENTS

       -A[m|p|x|y]
              If the input data are geographic (as  indicated  by  -f)  then  the  sides  in  the
              polygons  will  be approximated by great circle arcs.  When using the -A sides will
              be regarded as straight lines.  Alternatively, append m to have sides first  follow
              meridians,  then  parallels. Or append p to first follow parallels, then meridians.
              For Cartesian data, points are simply connected,  unless  you  append  x  or  y  to
              construct stair-case paths whose first move is along x or y, respectively.

       -N[z|Z|p|P]values
              Sets  the out/edge/in that will be assigned to nodes that are outside the polygons,
              on the edge, or inside. Values can be any  number,  including  the  textstring  NaN
              [Default  is  0/0/1].   Optionally,  use  Nz  to set polygon insides to the z-value
              obtained from the data (either segment header -Zzval, -Lheader  or  via  -aZ=name);
              use  -NZ to consider the polygon boundary as part of the inside. Alternatively, use
              -Np to use a running number as polygon ID; optionally append start of the  sequence
              [0].  Here, -NP includes the polygon perimeter as inside. Note: -Nz|Z|p|P cannot be
              used in conjunction with -S; they also all optionally accept /out [0].

       -Ssearch_radius[unit]
              Set nodes to inside, on edge, or outside depending on their distance to the nearest
              data  point.  Nodes  within  radius  [0] from the nearest data point are considered
              inside; append a distance unit (see UNITS). If radius is given as z then we instead
              read  individual  radii  from the 3rd input column.  Unless Cartesian data, specify
              the unit of these radii by appending it after -Sz.   If  -S  is  not  set  then  we
              consider the input data to define one or more closed polygon(s) instead.

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

       -bi[ncols][t] (more ...)
              Select native binary input. [Default is 2 input columns].

       -dinodata (more ...)
              Replace input columns that equal nodata with NaN.

       -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
              Only accept data records that match the given pattern.

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

       -g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more ...)
              Determine data gaps and line breaks.

       -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
              Skip or produce header record(s).

       -icols[+l][+sscale][+ooffset][,...] (more ...)
              Select input columns and transformations (0 is first column).

       -n[b|c|l|n][+a][+bBC][+tthreshold]
              Append  +bBC  to set any boundary conditions to be used, adding g for geographic, p
              for periodic, or n for natural boundary conditions. For  the  latter  two  you  may
              append  x or y to specify just one direction, otherwise both are assumed.  [Default
              is geographic if grid is geographic].

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

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], 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. Prepend - to a distance (or the unit is no  distance  is
       given)  to  perform  "Flat Earth" calculations (quicker but less accurate) or prepend + to
       perform exact geodesic calculations (slower but more accurate).

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

GEOGRAPHICAL AND TIME COORDINATES

       When  the  output  grid  type  is  netCDF,  the  coordinates  will be labeled "longitude",
       "latitude", or "time" based on the attributes of the input data or grid (if any) or on the
       -f  or  -R  options.  For  example,  both  -f0x  -f1t and -R90w/90e/0t/3t will result in a
       longitude/time grid. When the x, y, or z coordinate is time, it will be stored in the grid
       as relative time since epoch as specified by TIME_UNIT and TIME_EPOCH in the gmt.conf file
       or on the command line. In addition, the unit attribute of the time variable will indicate
       both this unit and epoch.

NOTES

       A  grid  produced by grdmask 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.

SAVE STORAGE SPACE

       Since most uses of grdmask revolves around creating  mask  grids  that  hold  just  a  few
       integer  values  (and  perhaps  NaN),  we  choose  to  write them to disk as byte grids by
       appending the suffix =nb to the desired grid filename.  Some situations may store integers
       that  exceed  the  range available in a byte and for those we specify a short integer grid
       with =ns.  For larger integers you may consider =ni, otherwise use the default float  grid
       format.

EXAMPLES

       To  set all nodes inside and on the polygons coastline_*.xy to 0, and outside points to 1,
       do

              gmt grdmask coastline_*.xy -R-60/-40/-40/-30 -I5m -N1/0/0 -Gland_mask.nc=nb -V

       To set nodes within 50 km of data points to 1 and other nodes to NaN, do

              gmt grdmask data.xyz -R-60/-40/-40/-30 -I5m -NNaN/1/1 -S50k -Gdata_mask.nc=nb -V

       To assign polygon IDs to the gridnodes using the insides of the  polygons  in  plates.gmt,
       based on the attribute POL_ID, do

              gmt grdmask plates.gmt -R-40/40/-40/40 -I2m -Nz -Gplate_IDs.nc=ns -aZ=POL_ID -V

       Same exercise, but instead compute running polygon IDs starting at 100, do

              gmt grdmask plates.gmt -R-40/40/-40/40 -I2m -Np100 -Gplate_IDs.nc=ns -V

SEE ALSO

       gmt, grdlandmask, grdmath, grdclip, psmask, psclip

COPYRIGHT

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