1GRDMASK(1)                            GMT                           GRDMASK(1)
2
3
4

NAME

6       grdmask - Create mask grid from polygons or point coverage
7

SYNOPSIS

9       grdmask pathfiles  -Gmask_grd_file
10        -Iincrement
11        -Rregion    [     -A[m|p|x|y]    ]    [     -N[z|Z|p|P]values    ]   [
12       -Ssearch_radius[unit] ] [  -V[level] ] [ -bibinary ] [  -dinodata  ]  [
13       -eregexp ] [ -fflags ] [ -ggaps ] [ -hheaders ] [ -iflags ] [ -nflags ]
14       [ -r ] [ -x[[-]n] ] [ -:[i|o] ]
15
16       Note: No space is allowed between the option flag  and  the  associated
17       arguments.
18

DESCRIPTION

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

REQUIRED ARGUMENTS

33       pathfiles
34              The  name  of 1 or more ASCII [or binary, see -bi] files holding
35              the polygon(s) or data points.
36
37       -Gmask_grd_file]
38              Name of resulting output mask grid file. (See GRID FILE  FORMATS
39              below).
40
41       -Ixinc[unit][+e|n][/yinc[unit][+e|n]]
42              x_inc  [and  optionally  y_inc] is the grid spacing. Optionally,
43              append a suffix modifier.  Geographical  (degrees)  coordinates:
44              Append  m  to indicate arc minutes or s to indicate arc seconds.
45              If one of the units e, f, k, M, n or u is appended instead,  the
46              increment  is assumed to be given in meter, foot, km, Mile, nau‐
47              tical mile or US survey foot, respectively,  and  will  be  con‐
48              verted  to  the equivalent degrees longitude at the middle lati‐
49              tude of the region (the conversion depends  on  PROJ_ELLIPSOID).
50              If  y_inc is given but set to 0 it will be reset equal to x_inc;
51              otherwise it will be converted to degrees latitude. All  coordi‐
52              nates:  If +e is appended then the corresponding max x (east) or
53              y (north) may be slightly adjusted  to  fit  exactly  the  given
54              increment  [by default the increment may be adjusted slightly to
55              fit the given domain]. Finally, instead of giving  an  increment
56              you  may  specify the number of nodes desired by appending +n to
57              the supplied integer argument; the increment  is  then  recalcu‐
58              lated  from  the  number  of nodes and the domain. The resulting
59              increment value depends on whether you  have  selected  a  grid‐
60              line-registered  or  pixel-registered grid; see App-file-formats
61              for details. Note: if -Rgrdfile is used then  the  grid  spacing
62              has already been initialized; use -I to override the values.
63
64       -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
65              Specify the region of interest.
66

OPTIONAL ARGUMENTS

68       -A[m|p|x|y]
69              If  the  input data are geographic (as indicated by -f) then the
70              sides in the polygons will be approximated by great circle arcs.
71              When  using  the  -A  sides  will be regarded as straight lines.
72              Alternatively, append m to have sides  first  follow  meridians,
73              then  parallels.  Or  append  p  to first follow parallels, then
74              meridians.  For Cartesian data,  points  are  simply  connected,
75              unless  you  append  x  or y to construct stair-case paths whose
76              first move is along x or y, respectively.
77
78       -N[z|Z|p|P]values
79              Sets the out/edge/in that will be assigned  to  nodes  that  are
80              outside  the polygons, on the edge, or inside. Values can be any
81              number,  including  the  textstring  NaN  [Default  is   0/0/1].
82              Optionally,  use  Nz  to  set  polygon  insides  to  the z-value
83              obtained from the data (either segment header  -Zzval,  -Lheader
84              or  via  -aZ=name);  use -NZ to consider the polygon boundary as
85              part of the inside. Alternatively, use -Np to use a running num‐
86              ber  as polygon ID; optionally append start of the sequence [0].
87              Here, -NP  includes  the  polygon  perimeter  as  inside.  Note:
88              -Nz|Z|p|P  cannot  be used in conjunction with -S; they also all
89              optionally accept /out [0].
90
91       -Ssearch_radius[unit]
92              Set nodes to inside, on edge, or outside depending on their dis‐
93              tance  to  the  nearest data point. Nodes within radius [0] from
94              the nearest data point are considered inside; append a  distance
95              unit  (see  UNITS). If radius is given as z then we instead read
96              individual radii from the 3rd input  column.   Unless  Cartesian
97              data, specify the unit of these radii by appending it after -Sz.
98              If -S is not set then we consider the input data to  define  one
99              or more closed polygon(s) instead.
100
101       -V[level] (more ...)
102              Select verbosity level [c].
103
104       -bi[ncols][t] (more ...)
105              Select native binary input. [Default is 2 input columns].
106
107       -dinodata (more ...)
108              Replace input columns that equal nodata with NaN.
109
110       -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
111              Only accept data records that match the given pattern.
112
113       -f[i|o]colinfo (more ...)
114              Specify data types of input and/or output columns.
115
116       -g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more ...)
117              Determine data gaps and line breaks.
118
119       -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
120              Skip or produce header record(s).
121
122       -icols[+l][+sscale][+ooffset][,...] (more ...)
123              Select input columns and transformations (0 is first column).
124
125       -n[b|c|l|n][+a][+bBC][+tthreshold]
126              Append  +bBC to set any boundary conditions to be used, adding g
127              for geographic, p for periodic, or n for natural boundary condi‐
128              tions.  For the latter two you may append x or y to specify just
129              one direction, otherwise both are  assumed.   [Default  is  geo‐
130              graphic if grid is geographic].
131
132       -r (more ...)
133              Set pixel node registration [gridline].
134
135       -x[[-]n] (more ...)
136              Limit  number of cores used in multi-threaded algorithms (OpenMP
137              required).
138
139       -^ or just -
140              Print a short message about the  syntax  of  the  command,  then
141              exits (NOTE: on Windows just use -).
142
143       -+ or just +
144              Print  an extensive usage (help) message, including the explana‐
145              tion of any module-specific  option  (but  not  the  GMT  common
146              options), then exits.
147
148       -? or no arguments
149              Print a complete usage (help) message, including the explanation
150              of all options, then exits.
151

UNITS

153       For map distance unit, append unit d for arc degree, m for arc  minute,
154       and s for arc second, or e for meter [Default], f for foot, k for km, M
155       for statute mile, n for nautical mile, and u for  US  survey  foot.  By
156       default  we compute such distances using a spherical approximation with
157       great circles. Prepend - to a distance (or the unit is no  distance  is
158       given) to perform "Flat Earth" calculations (quicker but less accurate)
159       or prepend + to perform exact geodesic calculations  (slower  but  more
160       accurate).
161

GRID FILE FORMATS

163       By  default  GMT  writes  out  grid  as  single  precision  floats in a
164       COARDS-complaint netCDF file format. However, GMT is  able  to  produce
165       grid  files  in  many  other  commonly  used grid file formats and also
166       facilitates so called "packing" of grids, writing  out  floating  point
167       data as 1- or 2-byte integers. To specify the precision, scale and off‐
168       set, the user should add the suffix  =ID[+sscale][+ooffset][+ninvalid],
169       where ID is a two-letter identifier of the grid type and precision, and
170       scale and offset are optional scale factor and offset to be applied  to
171       all  grid  values,  and  invalid  is the value used to indicate missing
172       data. See grdconvert and Section grid-file-format of the GMT  Technical
173       Reference and Cookbook for more information.
174
175       When  writing  a  netCDF  file,  the grid is stored by default with the
176       variable name "z". To specify another  variable  name  varname,  append
177       ?varname to the file name. Note that you may need to escape the special
178       meaning of ? in your shell program by putting a backslash in  front  of
179       it,  or  by  placing  the  filename and suffix between quotes or double
180       quotes.
181

GEOGRAPHICAL AND TIME COORDINATES

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

NOTES

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

SAVE STORAGE SPACE

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

EXAMPLES

212       To set all nodes inside and on the polygons coastline_*.xy  to  0,  and
213       outside points to 1, do
214
215              gmt grdmask coastline_*.xy -R-60/-40/-40/-30 -I5m -N1/0/0 -Gland_mask.nc=nb -V
216
217       To  set  nodes within 50 km of data points to 1 and other nodes to NaN,
218       do
219
220              gmt grdmask data.xyz -R-60/-40/-40/-30 -I5m -NNaN/1/1 -S50k -Gdata_mask.nc=nb -V
221
222       To assign polygon IDs to the gridnodes using the insides of  the  poly‐
223       gons in plates.gmt, based on the attribute POL_ID, do
224
225              gmt grdmask plates.gmt -R-40/40/-40/40 -I2m -Nz -Gplate_IDs.nc=ns -aZ=POL_ID -V
226
227       Same exercise, but instead compute running polygon IDs starting at 100,
228       do
229
230              gmt grdmask plates.gmt -R-40/40/-40/40 -I2m -Np100 -Gplate_IDs.nc=ns -V
231

SEE ALSO

233       gmt, grdlandmask, grdmath, grdclip, psmask, psclip
234
236       2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
237
238
239
240
2415.4.5                            Feb 24, 2019                       GRDMASK(1)
Impressum