# gshhs

Read Global Self-Consistent Hierarchical High-Resolution Geography

## Syntax

```S = gshhs(filename) S = gshhs(filename, latlim, lonlim) indexfilename = gshhs(filename, 'createindex') ```

## Description

`S = gshhs(filename)` reads GSHHG (formerly GSHHS) vector data for the entire world from `filename`. GSHHG files must have names of the form `gshhs_``x``.b`, `wdb_borders_``x``.b`, or `wdb_rivers_``x``.b`, where `x` is one of the letters `c`, `l`, `i`, `h` or `f`, corresponding to increasing resolution (and file size). The result returned in `S` is a polygon or line geographic data structure array (a geostruct, with `'Lat'` and `'Lon'` coordinate fields).

`S = gshhs(filename, latlim, lonlim)` reads a subset of the vector data from `filename`. The limits of the desired data are specified as two-element vectors of latitude, `latlim`, and longitude, `lonlim`, in degrees. The elements of `latlim` and `lonlim` must be in ascending order. Longitude limits range from ```[-180 195]```. If `latlim` is empty, the latitude limits are `[-90 90]`. If `lonlim` is empty, the longitude limits are `[-180 195]`.

`indexfilename = gshhs(filename, 'createindex')` creates an index file for faster data access when requesting a subset of a larger dataset. The index file has the same name as the GSHHG data file, but with the extension `'i'`, instead of `'b'` and is written in the same folder as `filename`. The name of the index file is returned, but no coastline data are read. A call using this option should be followed by an additional call to `gshhs` to import actual data. On that and subsequent calls, `gshhs` detects the presence of the index file and uses it to access records by location much faster than it would without an index.

## Output Structure

The output structure `S` contains the following fields. All latitude and longitude values are in degrees.

Field Name

Field Contents

`'Geometry'`

`'Line'` or `'Polygon'`

`'BoundingBox'`

`[minLon minLat; maxLon maxLat]`

`'Lon'`

Coordinate vector

`'Lat'`

Coordinate vector

`'South'`

Southern latitude boundary

`'North'`

Northern latitude boundary

`'West'`

Western longitude boundary

`'East'`

Eastern longitude boundary

`'Area'`

Area of polygon in square kilometers

`'Level'`

Scalar value ranging from 1 to 4, indicates level in topological hierarchy

`'LevelString'`

`'land'`, `'lake'`, `'island_in_lake'`, `'pond_in_island_in_lake'`, or `''`

`'NumPoints'`

Number of points in the polygon

`'FormatVersion'`

Format version of data file. Positive integer for versions 3 and later; empty for versions 1 and 2.

`'Source'`

Source of data: `'WDBII'` or `'WVS'`

`'CrossesGreenwich'`

Scalar flag: `true` if the polygon crosses the prime meridian; `false` otherwise

`'GSHHS_ID'`

Unique polygon scalar id number, starting at 0

For releases 2.0 and higher (`FormatVersion` 7 and higher), the following additional fields are included in the output structure:

Field Name

Field Contents

`'RiverLake'`

Scalar flag: `true` if the polygon is the fat part of a major river and the `Level` value is set to 2; `false` otherwise.

`'AreaFull'`

Area of original full-resolution polygon in units $\frac{1}{10}k{m}^{2}$.

`'Container'`

ID of container polygon that encloses this polygon. Set to -1 to indicate none.

`'Ancestor'`

ID of ancestor polygon in the full resolution set that was the source of this polygon. Set to -1 to indicate none.

For Release 2.2 and higher (`FormatVersion` 9 and higher) the following additional field is included in the output structure:

Field Name

Field Contents

`'CrossesDateline'`

Scalar flag: `true` if the polygon crosses the dateline; `false` otherwise.

## Background

The Global Self-Consistent Hierarchical High-Resolution Geography (formerly the Global Self-Consistent Hierarchical High-Resolution Shoreline) was created by Paul Wessel of the University of Hawaii and Walter H.F. Smith of the NOAA Geosciences Lab. At the full resolution, the data requires 85 MB uncompressed, but lower resolution versions are also provided. This database includes coastlines, major rivers, and lakes. The GSHHG data in various resolutions is available over the Internet from the National Oceanic and Atmospheric Administration, National Geophysical Data Center website.

Version 3 (Release 1.3) of the `gshhs_c.b` (coarse) data set ships with the toolbox in the `matlabroot/examples/map/data` folder. For details, type

`type gshhs_c.txt`
at the MATLAB® command prompt. The `gshhs` function has been qualified on GSHHG releases 1.1 through 2.3.6 (version 15). It should also be able to read newer versions, if they adhere to the same header format as releases 2.0 and 2.1.

## Examples

collapse all

Read the entire coarse data set. You can use similar code to read intermediate, full resolution, or high resolution GSHHG data sets.

```filename = gunzip('gshhs_c.b.gz', tempdir); shorelines = gshhs(filename{1}); delete(filename{1})```

Display data as a coastline.

```figure worldmap world geoshow([shorelines.Lat],[shorelines.Lon])```

Display each level using a different color.

```levels = [shorelines.Level]; land = (levels == 1); lake = (levels == 2); island = (levels == 3); figure worldmap world geoshow(shorelines(land), 'FaceColor',[0 1 0]) geoshow(shorelines(lake), 'FaceColor',[0 0 1]) geoshow(shorelines(island),'FaceColor',[1 1 0])```

Read the entire coarse data set, creating an index. You can use similar code to read intermediate, full-resolution, or high resolution GSHHG data sets.

```filename = gunzip('gshhs_c.b.gz', tempdir); indexname = gshhs(filename{1}, 'createindex');```

Display Africa as a green polygon. Note that `gshhs` detects and uses the index file automatically.

```figure worldmap Africa```

```projection = gcm; latlim = projection.maplatlimit; lonlim = projection.maplonlimit; africa = gshhs(filename{1}, latlim, lonlim); delete(filename{1}) delete(indexname)```

Sort by descending level to keep smaller level 2 and level 3 features on top.

```[~,ix] = sort([africa.Level],'descend'); africa = africa(ix); geoshow(africa, 'FaceColor', 'green') setm(gca, 'FFaceColor', 'cyan')```

## Tips

• If you are extracting data within specified geographic limits and using data other than coarse resolution, consider creating an index file first. Also, to speed rendering when mapping very large amounts of data, you might want to plot the data as `NaN`-clipped lines rather than as patches.

• When you specify latitude-longitude limits, polygons that completely fall outside those limits are excluded, but no trimming of features that partially traverse the region is performed. If you want to eliminate data outside of a rectangular region of interest, you can use `maptrimp` with the `Lat` and `Lon` fields of the geostruct returned by `gshhs` to clip the data to your region and still maintain polygon topology.

• You can read the WDB rivers and borders datasets but the `LevelString` field will be empty. The `Level` values vary from feature to feature but the interpretations of these values are not documented as part of the GSHHG distribution and are therefore not converted to character vectors.