1GSHHG(1) GMT GSHHG(1)
2
6 gshhg - Extract data tables from binary GSHHG or WDBII data files
7
9 gshhg binaryfile.b [ -Amin ] [ -G ] [ -Iid ] [ -L ] [ -Nlevel ] [
10 -Qe|i ] [ -bobinary ] [ -donodata ] [ -oflags ]
11 Note: No space is allowed between the option flag and the associated
13 arguments.
14
16 gshhg reads the binary coastline (GSHHG) or political boundary or river
17 (WDBII) files and writes an ASCII (or binary; see -b) listing to stan‐
18 dard output. It automatically handles byte-swabbing between different
19 architectures. Optionally, only segment header info can be displayed.
20 The header info has the format ID npoints hierarchical-level source
21 area f_area west east south north container ancestor, where hierarchi‐
22 cal levels for coastline polygons go from 1 (shoreline) to 4 (lake
23 inside island inside lake inside land). Source is either W (World Vec‐
24 tor Shoreline) or C (CIA World Data Bank II); lower case is used if a
25 lake is a river-lake. The west east south north is the enclosing rec‐
26 tangle, area is the polygon area in km^2 while f_area is the actual
27 area of the ancestor polygon, container is the ID of the polygon that
28 contains this polygon (-1 if none), and ancestor is the ID of the poly‐
29 gon in the full resolution set that was reduced to yield this polygon
30 (-1 if full resolution since there is no ancestor). For line data the
31 header is simply ID npoints hierarchical-level source west east south
32 north. For more information about the file formats, see TECHNICAL
33 INFORMATION below.
34
36 binaryfile.b
37 GSHHG or WDBII binary data file as distributed with the GSHHG
38 data supplement. Any of the 5 standard resolutions (full, high,
39 intermediate, low, crude) can be used.
40
42 -Amin Only output information for the polygon if its area equals or
43 exceeds min [Default outputs all polygons].
44 -G Write output that can be imported into GNU Octave or Matlab by
46 ending segments with a NaN-record.
47 -Iid Only output information for the polygon that matches id. Use -Ic
49 to get all the continents only [Default outputs all polygons].
50 See below for the id of the largest polygons.
51 -L Only output a listing of polygon or line segment headers
53 [Default outputs headers and data records].
54 -N Only output features whose level matches the given level
56 [Default will output all levels].
57 -Qe|i Control what to do with river-lakes (river sections large enough
59 to be stored as closed polygons). Use -Qe to exclude them and
60 -Qi to exclude everything else instead [Default outputs all
61 polygons].
62 -bo[ncols][type] (more ...)
64 Select native binary output.
65 -donodata (more ...)
67 Replace output columns that equal NaN with nodata.
68 -ocols[,...] (more ...)
70 Select output columns (0 is first column).
71
73 To convert the entire intermediate GSHHG binary data to ASCII files for
74 Octave/Matlab, run
75 gmt gshhg gshhs_i.b --IO_SEGMENT_MARKER=N > gshhs_i.txt
77 To only get a listing of the headers for the river data set at full
79 resolution, try
80 gmt gshhg wdb_rivers_f.b -L > riverlisting.txt
82 To only extract lakes, excluding river-lakes, from the high resolution
84 file, try
85 gmt gshhg gshhs_h.b -Ee -N2 > all_lakes.txt
87
89 None of the polygons have any name information associated with them
90 (i.e., the metadata does not contain this information). However, here
91 are the largest polygons:
92 ┌───┬────────────────────────────┐
94 │ID │ Landmass │
95 ├───┼────────────────────────────┤
96 │0 │ Eurasia │
97 ├───┼────────────────────────────┤
98 │1 │ Africa │
99 ├───┼────────────────────────────┤
100 │2 │ North America │
101 ├───┼────────────────────────────┤
102 │3 │ South America │
103 ├───┼────────────────────────────┤
104 │4 │ Antarctica (AC grounding │
105 │ │ line) │
106 ├───┼────────────────────────────┤
107 │5 │ Antarctica (AC ice line) │
108 ├───┼────────────────────────────┤
109 │6 │ Australia │
110 ├───┼────────────────────────────┤
111 │7 │ Greenland │
112 ├───┼────────────────────────────┤
113 │8 │ New Guinea │
114 ├───┼────────────────────────────┤
115 │9 │ Borneo │
116 ├───┼────────────────────────────┤
117 │10 │ Madagascar │
118 ├───┼────────────────────────────┤
119 │11 │ Baffin Island │
120 ├───┼────────────────────────────┤
121 │12 │ Indonesia │
122 └───┴────────────────────────────┘
123
125 Users who wish to access the GSHHG or WDBII data directly from their
126 custom programs should consult the gshhg.c and gshhg.h source code and
127 familiarize themselves with the data format and how various information
128 flags are packed into a single 4-byte integer. While we do not maintain
129 any Octave/Matlab code to read these files we are aware that both Math‐
130 Works and IDL have made such tools available to their users. However,
131 they tend not to update their code and our file structure has evolved
132 considerably over time, breaking their code. Here, some general techni‐
133 cal comments on the binary data files are given. GSHHG: These files
134 contain completely closed polygons of continents and islands (level 1),
135 lakes (level 2), islands-in-lakes (level 3) and
136 ponds-in-islands-in-lakes (level 4); a particular level can be
137 extracted using the -N option. Continents are identified as the first 6
138 polygons and can be extracted via the -Ic option. The IDs for the con‐
139 tinents are Eurasia (0), Africa (1), North America (2), South America
140 (3), Antarctica (4), and Australia (5). Files are sorted on area from
141 large to small. There are two sub-groups for level 2: Regular lakes
142 and the so-called "river-lakes", the latter being sections of a river
143 that are so wide to warrant a polygon representation. These river-lakes
144 are flagged in the header (also see -Q). All five resolutions are free
145 of self-intersections. Areas of all features have been computed using a
146 Lambert azimuthal equal-area projection centered on the polygon cen‐
147 troids, using WGS-84 as the ellipsoid. GMT use the GSHHG as a starting
148 point but then partition the polygons into pieces using a resolu‐
149 tion-dependent binning system; parts of the world are then rebuilt into
150 closed polygons on the fly as needed. For more information on GSHHG
151 processing, see Wessel and Smith (1996). WDBII. These files contain
152 sets of line segments not necessarily in any particular order. Thus, it
153 is not possible to extract information pertaining to just one river or
154 one country. Furthermore, the 4 lower resolutions derive directly from
155 the full resolution by application of the Douglas-Peucker algorithm
156 (see gshhg_dp), hence self-intersections are increasingly likely as the
157 resolution is degraded. Note that the river-lakes included in GSHHG are
158 also duplicated in the WDBII river files so that each data set can be a
159 stand-alone representation. Users who wish to access both data sets can
160 recognize the river-lakes features by examining the header structure
161 (see the source code for details); they are also the only closed poly‐
162 gons in the WDBII river file. There are many levels (classes) in the
163 river file: River-lakes (0), Permanent major rivers (1), Additional
164 major rivers (2), Additional rivers (3), Minor rivers (4), Intermittent
165 rivers -- major (6), Intermittent rivers -- additional (7), Intermit‐
166 tent rivers -- minor (8), Major canals (10), Canals of lesser impor‐
167 tance (11), and Canals -- irrigation type (12). For the border file
168 there are three levels: National boundaries (1), Internal domestic
169 boundaries (2), and international maritime boundaries (3). Individual
170 levels or classes may be extracted via -N.
171
173 Douglas, D. H., and T. K. Peucker, 1973, Algorithms for the reduction
174 of the number of points required to represent a digitized line of its
175 caricature, Can. Cartogr., 10, 112-122.
176 Gorny, A. J., 1977, World Data Bank II General User GuideRep. PB
178 271869, 10pp, Central Intelligence Agency, Washington, DC.
179 Soluri, E. A., and V. A. Woodson, 1990, World Vector Shoreline, Int.
181 Hydrograph. Rev., LXVII(1), 27-35.
182 Wessel, P., and W. H. F. Smith, 1996, A global, self-consistent, hier‐
184 archical, high-resolution shoreline database, J. Geophys. Res.,
185 101(B4), 8741-8743.
186
188 gmt
189
191 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
1925.4.5 Feb 24, 2019 GSHHG(1)