Provided by: gmt_4.5.11-1build1_amd64 bug

NAME

       gshhg - Extract ASCII listings from binary GSHHG data files

SYNOPSIS

       gshhg  binaryfile.b  [  -Aarea  ]  [  -G  ] [ -Iid ] [ -L ] [ -M ] [ -Nlevel ] [ -Qe|i ] >
       asciifile.txt

DESCRIPTION

       gshhg 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 segment 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 ancestor 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 polygon (-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 polygons].

       -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 structure 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  America (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 resolutions 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  features  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), Additional 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 international 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, hierarchical, high-
       resolution shoreline database, J. Geophys. Res., 101(B4), 8741-8743.

SEE ALSO

       GMT(1), gshhg_dp(1) gshhgtograss(1)