manpagez: man pages & more
man gshhg(1)
Home | html | info | man
gshhg(1)                              GMT                             gshhg(1)




NAME

       gshhg - Extract data tables from binary GSHHG or WDBII data files


SYNOPSIS

       gshhg  binaryfile.b [  -Amin ] [  -G ] [  -Iid ] [  -L ] [  -Nlevel ] [
       -Qe|i ] [ -bobinary ] [ -donodata ] [ -oflags ]

       Note: No space is allowed between the option flag  and  the  associated
       arguments.


DESCRIPTION

       gshhg reads the binary coastline (GSHHG) or political boundary or river
       (WDBII) files and writes an ASCII (or binary; see -b) listing to  stan-
       dard  output.  It automatically handles byte-swabbing between different
       architectures. Optionally, only segment header info can  be  displayed.
       The  header  info  has  the format ID npoints hierarchical-level source
       area f_area west east south north container ancestor, where  hierarchi-
       cal  levels  for  coastline  polygons  go from 1 (shoreline) to 4 (lake
       inside island inside lake inside land).  Source is either W (World Vec-
       tor  Shoreline)  or C (CIA World Data Bank II); lower case is used if a
       lake is a river-lake. The west east south north is the  enclosing  rec-
       tangle,  area  is  the  polygon area in km^2 while f_area is the actual
       area of the ancestor polygon, container is the ID of the  polygon  that
       contains this polygon (-1 if none), and ancestor is the ID of the poly-
       gon in the full resolution set that was reduced to yield  this  polygon
       (-1  if  full resolution since there is no ancestor). For line 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.


REQUIRED ARGUMENTS

       binaryfile.b
              GSHHG or WDBII binary data file as distributed  with  the  GSHHG
              data  supplement. Any of the 5 standard resolutions (full, high,
              intermediate, low, crude) can be used.


OPTIONAL ARGUMENTS

       -Amin  Only output information for the polygon if its  area  equals  or
              exceeds min [Default outputs all polygons].

       -G     Write  output  that can be imported into GNU Octave or Matlab by
              ending segments with a NaN-record.

       -Iid   Only output information for the polygon that matches id. Use -Ic
              to  get  all the continents only [Default outputs all polygons].
              See below for the id of the largest polygons.

       -L     Only output  a  listing  of  polygon  or  line  segment  headers
              [Default outputs headers and data records].

       -N     Only  output  features  whose  level  matches  the  given  level
              [Default will output all levels].

       -Qe|i  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].

       -bo[ncols][type] (more a|)
              Select native binary output.

       -donodata (more a|)
              Replace output columns that equal NaN with nodata.

       -ocols[,a|] (more a|)
              Select output columns (0 is first column).


EXAMPLES

       To convert the entire intermediate GSHHG binary data to ASCII files for
       Octave/Matlab, run

              gmt gshhg gshhs_i.b --IO_SEGMENT_MARKER=N > gshhs_i.txt

       To only get a listing of the headers for the river  data  set  at  full
       resolution, try

              gmt gshhg wdb_rivers_f.b -L > riverlisting.txt

       To  only extract lakes, excluding river-lakes, from the high resolution
       file, try

              gmt gshhg gshhs_h.b -Ee -N2 > all_lakes.txt


SPECIFIC POLYGONS

       None of the polygons have any name  information  associated  with  them
       (i.e.,  the metadata does not contain this information).  However, here
       are the largest polygons:

                          +---+----------------------------+
                          |ID | Landmass                   |
                          +---+----------------------------+
                          |0  | Eurasia                    |
                          +---+----------------------------+
                          |1  | Africa                     |
                          +---+----------------------------+
                          |2  | North America              |
                          +---+----------------------------+
                          |3  | South America              |
                          +---+----------------------------+
                          |4  | Antarctica  (AC  grounding |
                          |   | line)                      |
                          +---+----------------------------+
                          |5  | Antarctica (AC ice line)   |
                          +---+----------------------------+
                          |6  | Australia                  |
                          +---+----------------------------+
                          |7  | Greenland                  |
                          +---+----------------------------+
                          |8  | New Guinea                 |
                          +---+----------------------------+
                          |9  | Borneo                     |
                          +---+----------------------------+
                          |10 | Madagascar                 |
                          +---+----------------------------+
                          |11 | Baffin Island              |
                          +---+----------------------------+
                          |12 | Indonesia                  |
                          +---+----------------------------+


TECHNICAL INFORMATION

       Users  who  wish  to access the GSHHG or 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 Math-
       Works 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 techni-
       cal  comments  on  the binary data files are given.  GSHHG: 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  con-
       tinents  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 ariver-lakesa, 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  cen-
       troids,  using WGS-84 as the ellipsoid. GMT use the GSHHG as a starting
       point but then partition the  polygons  into  pieces  using  a  resolu-
       tion-dependent binning system; parts of the world are then rebuilt into
       closed polygons on the fly as needed. For  more  information  on  GSHHG
       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 GSHHG 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 poly-
       gons 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  a major (6), Intermittent rivers a additional (7), Intermittent
       rivers a minor (8), Major canals  (10),  Canals  of  lesser  importance
       (11),  and Canals a 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,  hier-
       archical,   high-resolution   shoreline  database,  J.  Geophys.  Res.,
       101(B4), 8741-8743.


SEE ALSO

       gmt(1)


COPYRIGHT

       2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe



5.4.2                            Jun 24, 2017                         gshhg(1)

gmt5 5.4.2 - Generated Thu Jun 29 13:42:14 CDT 2017
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.