1GRDLANDMASK(1) GMT GRDLANDMASK(1)
2
6 grdlandmask - "Create a ""wet-dry"" mask grid from shoreline data base"
7
9 grdlandmask -Gmask_grd_file
10 -Iincrement
11 -Rregion [ -Amin_area[/min_level/max_level][+ag|i|s |S][+r|l][pper‐
12 cent] ] [ -Dresolution[+] ] [ -N ] [ -Nmaskvalues ] [ -V[level] ] [
13 -r ] [ -x[[-]n] ]
14 Note: No space is allowed between the option flag and the associated
16 arguments.
17
19 grdlandmask reads the selected shoreline database and uses that infor‐
20 mation to decide which nodes in the specified grid are over land or
21 over water. The nodes defined by the selected region and lattice spac‐
22 ing will be set according to one of two criteria: (1) land vs water, or
23 (2) the more detailed (hierarchical) ocean vs land vs lake vs island vs
24 pond. The resulting mask may be used in subsequent operations involving
25 grdmath to mask out data from land [or water] areas.
26
28 -Gmask_grd_file]
29 Name of resulting output mask grid file. (See GRID FILE FORMATS
30 below).
31 -Ixinc[unit][+e|n][/yinc[unit][+e|n]]
33 x_inc [and optionally y_inc] is the grid spacing. Optionally,
34 append a suffix modifier. Geographical (degrees) coordinates:
35 Append m to indicate arc minutes or s to indicate arc seconds.
36 If one of the units e, f, k, M, n or u is appended instead, the
37 increment is assumed to be given in meter, foot, km, Mile, nau‐
38 tical mile or US survey foot, respectively, and will be con‐
39 verted to the equivalent degrees longitude at the middle lati‐
40 tude of the region (the conversion depends on PROJ_ELLIPSOID).
41 If y_inc is given but set to 0 it will be reset equal to x_inc;
42 otherwise it will be converted to degrees latitude. All coordi‐
43 nates: If +e is appended then the corresponding max x (east) or
44 y (north) may be slightly adjusted to fit exactly the given
45 increment [by default the increment may be adjusted slightly to
46 fit the given domain]. Finally, instead of giving an increment
47 you may specify the number of nodes desired by appending +n to
48 the supplied integer argument; the increment is then recalcu‐
49 lated from the number of nodes and the domain. The resulting
50 increment value depends on whether you have selected a grid‐
51 line-registered or pixel-registered grid; see App-file-formats
52 for details. Note: if -Rgrdfile is used then the grid spacing
53 has already been initialized; use -I to override the values.
54 -Rwest/east/south/north[/zmin/zmax][+r][+uunit]
56 west, east, south, and north specify the region of interest, and
57 you may specify them in decimal degrees or in
58 [±]dd:mm[:ss.xxx][W|E|S|N] format Append +r if lower left and
59 upper right map coordinates are given instead of w/e/s/n. The
60 two shorthands -Rg and -Rd stand for global domain (0/360 and
61 -180/+180 in longitude respectively, with -90/+90 in latitude).
62 Alternatively for grid creation, give Rcodelon/lat/nx/ny, where
63 code is a 2-character combination of L, C, R (for left, center,
64 or right) and T, M, B for top, middle, or bottom. e.g., BL for
65 lower left. This indicates which point on a rectangular region
66 the lon/lat coordinate refers to, and the grid dimensions nx and
67 ny with grid spacings via -I is used to create the corresponding
68 region. Alternatively, specify the name of an existing grid
69 file and the -R settings (and grid spacing, if applicable) are
70 copied from the grid. Appending +uunit expects projected (Carte‐
71 sian) coordinates compatible with chosen -J and we inversely
72 project to determine actual rectangular geographic region. For
73 perspective view (-p), optionally append /zmin/zmax. In case of
74 perspective view (-p), a z-range (zmin, zmax) can be appended to
75 indicate the third dimension. This needs to be done only when
76 using the -Jz option, not when using only the -p option. In the
77 latter case a perspective view of the plane is plotted, with no
78 third dimension.
79
81 -Amin_area[/min_level/max_level][+ag|i|s|S][+r|l][+ppercent]
82 Features with an area smaller than min_area in km^2 or of hier‐
83 archical level that is lower than min_level or higher than
84 max_level will not be plotted [Default is 0/0/4 (all features)].
85 Level 2 (lakes) contains regular lakes and wide river bodies
86 which we normally include as lakes; append +r to just get
87 river-lakes or +l to just get regular lakes. By default (+ai)
88 we select the ice shelf boundary as the coastline for Antarc‐
89 tica; append +ag to instead select the ice grounding line as
90 coastline. For expert users who wish to print their own Antarc‐
91 tica coastline and islands via psxy you can use +as to skip all
92 GSHHG features below 60S or +aS to instead skip all features
93 north of 60S. Finally, append +ppercent to exclude polygons
94 whose percentage area of the corresponding full-resolution fea‐
95 ture is less than percent. See GSHHG INFORMATION below for more
96 details.
97 -Dresolution[+]
99 Selects the resolution of the data set to use ((f)ull, (h)igh,
100 (i)ntermediate, (l)ow, or (c)rude). The resolution drops off by
101 ~80% between data sets. [Default is l]. Append + to automati‐
102 cally select a lower resolution should the one requested not be
103 available [abort if not found]. Alternatively, choose (a)uto to
104 automatically select the best resolution given the chosen
105 region. Note that because the coastlines differ in details a
106 node in a mask file using one resolution is not guaranteed to
107 remain inside [or outside] when a different resolution is
108 selected.
109 -E Indicate that nodes that fall exactly on a polygon boundary
111 should be considered to be outside the polygon [Default consid‐
112 ers them to be inside].
113 -Nmaskvalues
115 Sets the values that will be assigned to nodes. Values can be
116 any number, including the textstring NaN. Also select -E to let
117 nodes exactly on feature boundaries be considered outside
118 [Default is inside]. Specify this information using 1 of 2 for‐
119 mats:
120 -Nwet/dry.
122 -Nocean/land/lake/island/pond.
124 [Default is 0/1/0/1/0 (i.e., 0/1)].
126 -V[level] (more ...)
128 Select verbosity level [c].
129 -r (more ...)
131 Set pixel node registration [gridline].
132 -x[[-]n] (more ...)
134 Limit number of cores used in multi-threaded algorithms (OpenMP
135 required).
136 -^ or just -
138 Print a short message about the syntax of the command, then
139 exits (NOTE: on Windows just use -).
140 -+ or just +
142 Print an extensive usage (help) message, including the explana‐
143 tion of any module-specific option (but not the GMT common
144 options), then exits.
145 -? or no arguments
147 Print a complete usage (help) message, including the explanation
148 of all options, then exits.
149
151 By default GMT writes out grid as single precision floats in a
152 COARDS-complaint netCDF file format. However, GMT is able to produce
153 grid files in many other commonly used grid file formats and also
154 facilitates so called "packing" of grids, writing out floating point
155 data as 1- or 2-byte integers. To specify the precision, scale and off‐
156 set, the user should add the suffix =ID[+sscale][+ooffset][+ninvalid],
157 where ID is a two-letter identifier of the grid type and precision, and
158 scale and offset are optional scale factor and offset to be applied to
159 all grid values, and invalid is the value used to indicate missing
160 data. See grdconvert and Section grid-file-format of the GMT Technical
161 Reference and Cookbook for more information.
162 When writing a netCDF file, the grid is stored by default with the
164 variable name "z". To specify another variable name varname, append
165 ?varname to the file name. Note that you may need to escape the special
166 meaning of ? in your shell program by putting a backslash in front of
167 it, or by placing the filename and suffix between quotes or double
168 quotes.
169
171 A grid produced by grdlandmask is a categorical dataset. As such, one
172 has to be careful not to interpolate it with standard methods, such as
173 splines. However, if you make a map of this grid using a map projec‐
174 tion the grid will be reprojected to yield a rectangular matrix in the
175 projected coordinates. This interpolation is done using splines by
176 default and thus may yield artifacts in your map. We recommend you use
177 grdimage -nn to instead use a nearest neighbor interpolation for such
178 cases.
179
181 To set all nodes on land to NaN, and nodes over water to 1, using the
182 high resolution data set, do
183 gmt grdlandmask -R-60/-40/-40/-30 -Dh -I5m -N1/NaN -Gland_mask.nc -V
185 To make a 1x1 degree global grid with the hierarchical levels of the
187 nodes based on the low resolution data:
188 gmt grdlandmask -R0/360/-90/90 -Dl -I1 -N0/1/2/3/4 -Glevels.nc -V
190
192 The coastline database is GSHHG (formerly GSHHS) which is compiled from
193 three sources: World Vector Shorelines (WVS), CIA World Data Bank II
194 (WDBII), and Atlas of the Cryosphere (AC, for Antarctica only). Apart
195 from Antarctica, all level-1 polygons (ocean-land boundary) are derived
196 from the more accurate WVS while all higher level polygons (level 2-4,
197 representing land/lake, lake/island-in-lake, and
198 island-in-lake/lake-in-island-in-lake boundaries) are taken from WDBII.
199 The Antarctica coastlines come in two flavors: ice-front or grounding
200 line, selectable via the -A option. Much processing has taken place to
201 convert WVS, WDBII, and AC data into usable form for GMT: assembling
202 closed polygons from line segments, checking for duplicates, and cor‐
203 recting for crossings between polygons. The area of each polygon has
204 been determined so that the user may choose not to draw features
205 smaller than a minimum area (see -A); one may also limit the highest
206 hierarchical level of polygons to be included (4 is the maximum). The 4
207 lower-resolution databases were derived from the full resolution data‐
208 base using the Douglas-Peucker line-simplification algorithm. The clas‐
209 sification of rivers and borders follow that of the WDBII. See the GMT
210 Cookbook and Technical Reference Appendix K for further details.
211
213 gmt, grdmath, grdclip, psmask, psclip, pscoast
214
216 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
2175.4.5 Feb 24, 2019 GRDLANDMASK(1)