1GRDLANDMASK(1) Generic Mapping Tools GRDLANDMASK(1)
2
6 grdlandmask - Create "wet-dry" mask grid file from shoreline data base.
7
9 grdlandmask -Gmask_grd_file] -Ixinc[unit][=|+][/yinc[unit][=|+]]
10 -Rwest/east/south/north[r] [
11 -Amin_area[/min_level/max_level][+r|l][ppercent] ] [ -Dresolution[+] ]
12 [ -F ] [ -Nmaskvalues[o] ] [ -V ]
13
15 grdlandmask reads the selected shoreline database and uses that infor‐
16 mation to decide which nodes in the specified grid are over land or
17 over water. The nodes defined by the selected region and lattice spac‐
18 ing will be set according to one of two criteria: (1) land vs water, or
19 (2) the more detailed (hierarchical) ocean vs land vs lake vs island vs
20 pond. The resulting mask may be used in subsequent operations involv‐
21 ing grdmath to mask out data from land [or water] areas.
22 -G Name of resulting output mask grid file. (See GRID FILE FORMATS
24 below).
25 -I x_inc [and optionally y_inc] is the grid spacing. Optionally,
27 append a suffix modifier. Geographical (degrees) coordinates:
28 Append m to indicate arc minutes or c to indicate arc seconds.
29 If one of the units e, k, i, or n is appended instead, the
30 increment is assumed to be given in meter, km, miles, or nauti‐
31 cal miles, respectively, and will be converted to the equivalent
32 degrees longitude at the middle latitude of the region (the con‐
33 version depends on ELLIPSOID). If /y_inc is given but set to 0
34 it will be reset equal to x_inc; otherwise it will be converted
35 to degrees latitude. All coordinates: If = is appended then the
36 corresponding max x (east) or y (north) may be slightly adjusted
37 to fit exactly the given increment [by default the increment may
38 be adjusted slightly to fit the given domain]. Finally, instead
39 of giving an increment you may specify the number of nodes
40 desired by appending + to the supplied integer argument; the
41 increment is then recalculated from the number of nodes and the
42 domain. The resulting increment value depends on whether you
43 have selected a gridline-registered or pixel-registered grid;
44 see Appendix B for details. Note: if -Rgrdfile is used then
45 grid spacing has already been initialized; use -I to override
46 the values.
47 -R west, east, south, and north specify the Region of interest, and
49 you may specify them in decimal degrees or in
50 [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r if lower left and
51 upper right map coordinates are given instead of w/e/s/n. The
52 two shorthands -Rg and -Rd stand for global domain (0/360 and
53 -180/+180 in longitude respectively, with -90/+90 in latitude).
54 Alternatively, specify the name of an existing grid file and the
55 -R settings (and grid spacing, if applicable) are copied from
56 the grid.
57
59 -A Features with an area smaller than min_area in km^2 or of hier‐
60 archical level that is lower than min_level or higher than
61 max_level will not be plotted [Default is 0/0/4 (all features)].
62 Level 2 (lakes) contains regular lakes and wide river bodies
63 which we normally include as lakes; append +r to just get river-
64 lakes or +l to just get regular lakes (requires GSHHS 2.0.1 or
65 higher). Finally, append +ppercent to exclude polygons whose
66 percentage area of the corresponding full-resolution feature is
67 less than percent (requires GSHHS 2.0 or higher). See GSHHS
68 INFORMATION below for more details.
69 -D Selects the resolution of the data set to use ((f)ull, (h)igh,
71 (i)ntermediate, (l)ow, or (c)rude). The resolution drops off by
72 ~80% between data sets. [Default is l]. Append + to automati‐
73 cally select a lower resolution should the one requested not be
74 available [abort if not found]. Note that because the coast‐
75 lines differ in details a node in a mask file using one resolu‐
76 tion is not guaranteed to remain inside [or outside] when a dif‐
77 ferent resolution is selected.
78 -F Force pixel node registration [Default is gridline registra‐
80 tion]. (Node registrations are defined in GMT Cookbook Appendix
81 B on grid file formats.)
82 -N Sets the values that will be assigned to nodes. Values can be
84 any number, including the textstring NaN. Append o to let nodes
85 exactly on feature boundaries be considered outside [Default is
86 inside]. Specify this information using 1 of 2 formats:
87 -Nwet/dry.
88 -Nocean/land/lake/island/pond.
89 [Default is 0/1/0/1/0 (i.e., 0/1)].
90 -V Selects verbose mode, which will send progress reports to stderr
92 [Default runs "silently"].
93
95 By default GMT writes out grid as single precision floats in a COARDS-
96 complaint netCDF file format. However, GMT is able to produce grid
97 files in many other commonly used grid file formats and also facili‐
98 tates so called "packing" of grids, writing out floating point data as
99 2- or 4-byte integers. To specify the precision, scale and offset, the
100 user should add the suffix =id[/scale/offset[/nan]], where id is a two-
101 letter identifier of the grid type and precision, and scale and offset
102 are optional scale factor and offset to be applied to all grid values,
103 and nan is the value used to indicate missing data. See grdreformat(1)
104 and Section 4.17 of the GMT Technical Reference and Cookbook for more
105 information.
106 When writing a netCDF file, the grid is stored by default with the
108 variable name "z". To specify another variable name varname, append
109 ?varname to the file name. Note that you may need to escape the spe‐
110 cial meaning of ? in your shell program by putting a backslash in front
111 of it, or by placing the filename and suffix between quotes or double
112 quotes.
113
115 To set all nodes on land to NaN, and nodes over water to 1, using the
116 high resolution data set, do
117 grdlandmask -R-60/-40/-40/-30 -Dh -i5m -N1/NaN -Gland_mask.grd -V
119 To make a 1x1 degree global grid with the hierarchical levels of the
121 nodes based on the low resolution data:
122 grdlandmask -R0/360/-90/90 -Dl -I1 -N0/1/2/3/4 -Glevels.grd -V
124
126 The coastline database is GSHHS which is compiled from two sources:
127 World Vector Shorelines (WVS) and CIA World Data Bank II (WDBII). In
128 particular, all level-1 polygons (ocean-land boundary) are derived from
129 the more accurate WVS while all higher level polygons (level 2-4, rep‐
130 resenting land/lake, lake/island-in-lake, and island-in-lake/lake-in-
131 island-in-lake boundaries) are taken from WDBII. Much processing has
132 taken place to convert WVS and WDBII data into usable form for GMT:
133 assembling closed polygons from line segments, checking for duplicates,
134 and correcting for crossings between polygons. The area of each poly‐
135 gon has been determined so that the user may choose not to draw fea‐
136 tures smaller than a minimum area (see -A); one may also limit the
137 highest hierarchical level of polygons to be included (4 is the maxi‐
138 mum). The 4 lower-resolution databases were derived from the full res‐
139 olution database using the Douglas-Peucker line-simplification algo‐
140 rithm. The classification of rivers and borders follow that of the
141 WDBII. See the GMT Cookbook and Technical Reference Appendix K for
142 further details.
143
145 GMT(1), grdmath(1), grdclip(1), psmask(1), psclip(1), pscoast(1)
146GMT 4.5.6 10 Mar 2011 GRDLANDMASK(1)