GSHHG(1) Generic Mapping Tools GSHHG(1)NAMEgshhg - Extract ASCII listings from binary GSHHG data files
SYNOPSISgshhg binaryfile.b [ -Aarea ] [ -G ] [ -Iid ] [ -L ] [ -M ] [ -Nlevel ]
[ -Qe|i ] > asciifile.txt
DESCRIPTIONgshhg reads the binary coastline (GSHHS) or political boundary or river
(WDBII) files and extracts an ASCII listing. It automatically handles
byte-swabbing between different architectures. Optionally, only seg‐
ment header info can be displayed. The output header information has
the format ID npoints hierarchical-level source area f_area west east
south north container ancestor, where hierarchical levels for coastline
polygons go from 1 (shoreline) to 4 (lake inside island inside lake
inside land). Source is either W (World Vector Shoreline) or C (CIA
World Data Bank II); lower case is used if a lake is a river-lake (a
portion of a river that is so wide it is better represented by a closed
polygon). The west east south north is the enclosing rectangle, area is
the polygon area in km^2 while f_area is the actual area of the ances‐
tor polygon (at full resolution), container is the ID of the polygon
that contains this polygon (-1 if none), and ancestor is the ID of the
polygon in the full resolution set that was reduced to yield this poly‐
gon (-1 if full resolution since there is no ancestor). For river and
border data the header is simply ID npoints hierarchical-level source
west east south north. For more information about the file formats,
see TECHNICAL INFORMATION below.
binaryfile.b
GSHHS or WDBII binary data file as distributed with the GSHHS
data supplement. Any of the 5 standard resolutions (full, high,
intermediate, low, crude) can be used.
-A Only output polygons whose area equals or exceeds the area value
in km^2 [Default outputs all polygons].
-G Write output that can be imported into GNU Octave or Matlab by
ending each segment with a NaN-record.
-I Only output information for the polygon that matches id. Use
-Ic to get all the continents only [Default outputs all poly‐
gons].
-L Only output a listing of polygon or line segment headers
[Default outputs headers and data records].
-M Start all header records with the GMT multiple segment indicator
'>' [Default uses P for polygons and L for lines].
-N Only output features whose level matches the given level
[Default will output all levels].
-Q Control what to do with river-lakes (river sections large enough
to be stored as closed polygons). Use -Qe to exclude them and
-Qi to exclude everything else instead [Default outputs all
polygons].
EXAMPLES
To convert the entire intermediate GSHHS binary data to ASCII files for
Octave/Mathlab, run
gshhg gshhs_i.b -G > gshhs_i.txt
To only get a listing of the headers for the river data set at full
resolution, try
gshhg wdb_rivers_f.b -L > riverlisting.txt
To only extract lakes, excluding river-lakes, from the high resolution
file, try
gshhg gshhs_h.b -Ee -N2 > all_lakes.txt
TECHNICAL INFORMATION
Users who wish to access the GSHHG (GSHHS and WDBII) data directly from
their custom programs should consult the gshhg.c and gshhg.h source
code and familiarize themselves with the data format and how various
information flags are packed into a single 4-byte integer. While we do
not maintain any Octave/Matlab code to read these files we are aware
that both Mathworks and IDL have made such tools available to their
users. However, they tend not to update their code and our file struc‐
ture has evolved considerably over time, breaking their code. Here,
some general technical comments on the binary data files are given.
GSHHS: These files contain completely closed polygons of continents and
islands (level 1), lakes (level 2), islands-in-lakes (level 3) and
ponds-in-islands-in-lakes (level 4); a particular level can be
extracted using the -N option. Continents are identified as the first
6 polygons and can be extracted via the -Ic option. The IDs for the
continents are Eurasia (0), Africa (1), North America (2), South Amer‐
ica (3), Antarctica (4), and Australia (5). Files are sorted on area
from large to small. There are two sub-groups for level 2: Regular
lakes and the so-called "river-lakes", the latter being sections of a
river that are so wide to warrant a polygon representation. These
river-lakes are flagged in the header (also see -Q). All five resolu‐
tions are free of self-intersections. Areas of all features have been
computed using a Lambert azimuthal equal-area projection centered on
the polygon centroids, using WGS-84 as the ellipsoid. GMT use the
GSHHS as a starting point but then partition the polygons into pieces
using a resolution-dependent binning system; parts of the world are
then rebuilt into closed polygons on the fly as needed. For more
information on GSHHS processing, see Wessel and Smith (1996).
WDBII. These files contain sets of line segments not necessarily in
any particular order. Thus, it is not possible to extract information
pertaining to just one river or one country. Furthermore, the 4 lower
resolutions derive directly from the full resolution by application of
the Douglas-Peucker algorithm (see gshhg_dp), hence self-intersections
are increasingly likely as the resolution is degraded. Note that the
river-lakes included in GSHHS are also duplicated in the WDBII river
files so that each data set can be a stand-alone representation. Users
who wish to access both data sets can recognize the river-lakes fea‐
tures by examining the header structure (see the source code for
details); they are also the only closed polygons in the WDBII river
file. There are many levels (classes) in the river file: River-lakes
(0), Permanent major rivers (1), Additional major rivers (2), Addi‐
tional rivers (3), Minor rivers (4), Intermittent rivers -- major (6),
Intermittent rivers -- additional (7), Intermittent rivers -- minor
(8), Major canals (10), Canals of lesser importance (11), and Canals --
irrigation type (12). For the border file there are three levels:
National boundaries (1), Internal domestic boundaries (2), and interna‐
tional maritime boundaries (3). Individual levels or classes may be
extracted via -N.
REFERENCES
Douglas, D. H., and T. K. Peucker, 1973, Algorithms for the reduction
of the number of points required to represent a digitized line of its
caricature, Can. Cartogr., 10, 112-122.
Gorny, A. J., 1977, World Data Bank II General User GuideRep. PB
271869, 10pp, Central Intelligence Agency, Washington, DC.
Soluri, E. A., and V. A. Woodson, 1990, World Vector Shoreline, Int.
Hydrograph. Rev., LXVII(1), 27-35.
Wessel, P., and W. H. F. Smith, 1996, A global, self-consistent, hier‐
archical, high-resolution shoreline database, J. Geophys. Res.,
101(B4), 8741-8743.
SEE ALSOGMT(1), gshhg_dp(1)gshhgtograss(1)GMT 4.5.14 1 Nov 2015 GSHHG(1)
