# gshhs

Read Global Self-Consistent Hierarchical High-Resolution Geography (GSHHG) data

## Syntax

``S = gshhs(filename)``
``S = gshhs(filename,latlim,lonlim)``
``indexFilename = gshhs(filename,"createindex")``

## Description

example

````S = gshhs(filename)` reads Global Self-Consistent Hierarchical High-Resolution Geography (GSHHG) vector data from a file.```
````S = gshhs(filename,latlim,lonlim)` reads data within the latitude and longitude limits specified by `latlim` and `lonlim`.```

example

````indexFilename = gshhs(filename,"createindex")` creates an index file called `indexFilename` that enables the `gshhs` function to more quickly read subsets of large data sets. Once you create the index file, the `gshhs` function uses it to access data by location.This syntax does not read the GSHHG data. To read the data after creating the index file, use the `gshhs` function again.```

## Examples

collapse all

Extract a file containing coarse GSHHG data from a GNU zipped file. Read the file into the workspace as a geographic data structure array.

```filename = gunzip("gshhs_c.b.gz"); S = gshhs(filename{1});```

Verify that all elements of the structure array represent polygons.

`isequal(S.Geometry,"Polygon")`
```ans = logical 1 ```

Query the number of polygons in the structure array.

`length(S)`
```ans = 1866 ```

Extract the latitude and longitude coordinates of the polygons from the structure array. Then, display the data using lines on a world map.

```lat = [S.Lat]; lon = [S.Lon]; figure worldmap world geoshow(lat,lon,"DisplayType","line")```

Find the polygons corresponding to land areas (`levels == 1`) and lakes (`levels == 2`). Create a map of Europe with the land areas in green and the lakes in blue.

```levels = [S.Level]; land = (levels == 1); lake = (levels == 2); figure worldmap europe geoshow(S(land),"FaceColor","#d2e9b8") geoshow(S(lake),"FaceColor","b")```

Extract a file containing coarse GSHHG data from a GNU zipped file. Create an index for the data.

```filename = gunzip("gshhs_c.b.gz"); indexFilename = gshhs(filename{1},"createindex");```

Read data for a region surrounding Africa into the workspace as a geographic data structure array. The `gshhs` function uses the index to more quickly read the data.

```latlim = [-40 40]; lonlim = [-20 55]; S = gshhs(filename{1},latlim,lonlim);```

Display the data on a world map. To display the lakes and islands within the land areas, sort the structure array in descending order according to the `Level` field.

```[~,ix] = sort([S.Level],"descend"); S = S(ix); figure worldmap(latlim,lonlim) geoshow(S,"FaceColor","#d2e9b8") setm(gca,"FFaceColor","#9dd7ee")```

## Input Arguments

collapse all

Name of the GSHHG file, specified as a character vector or a string scalar.

The filename must have one of these forms:

• `"gshhs_x.b"`

• `"wdb_borders_x.b"`

• `"wdb_rivers_x.b"`

`x` must be `c`, `l`, `i`, `h`, or `f`. These letters correspond to the resolution of the file.

Data Types: `char` | `string`

Latitude limits, specified as an empty vector (`[]`) or a two-element vector in units of degrees.

When you specify `latlim` as an empty vector, the `gshhs` function reads data within the latitude limits `[-90 90]`.

When you specify `latlim` as a two-element vector, the value of `latlim(1)` must be less than the value of `latlim(2)`.

Data Types: `double`

Longitude limits, specified as an empty vector (`[]`) or a two-element vector in units of degrees.

When you specify `lonlim` as an empty vector, the `gshhs` function reads data within the longitude limits `[-180 195]`.

When you specify `lonlim` as a two-element vector, the value of `lonlim(1)` must be less than the value of `lonlim(2)`.

Data Types: `double`

## Output Arguments

collapse all

Geographic data structure, returned as a structure array with these fields:

Field

Description

`Geometry`

Geometric type, returned as `'Line'` or `'Polygon'`.

`BoundingBox`

Bounding box, returned as a 2-by-2 matrix of the form `[minLon minLat; maxLon maxLat]`. The values `minLon` and `minLat` indicate the minimum longitude and latitude, respectively. The values `maxLon` and `maxLat` indicate the maximum longitude and latitude, respectively.

`Lon`

Longitude coordinates, returned as a numeric vector.

`Lat`

Latitude coordinates, returned as a numeric vector.

`South`

Southern latitude boundary, returned as a numeric scalar.

`North`

Northern latitude boundary, returned as a numeric scalar.

`West`

Western longitude boundary, returned as a numeric scalar.

`East`

Eastern longitude boundary, returned as a numeric scalar.

`Area`

Area of the polygon in square kilometers, returned as a numeric scalar.

`Level`

Level in topological hierarchy, returned as an integer in the range [1, 4].

`LevelString`

Level in topological hierarchy, returned as `'land'`, `'lake'`, `'island_in_lake'`, `'pond_in_island_in_lake'`, or `''`.

When you read the WDB rivers and borders data sets, the `LevelString` field is empty.

`NumPoints`

Number of points in the polygon, returned as a nonnegative integer.

`FormatVersion`

Format version of the data file, returned as one of these values:

• A positive integer — Indicates version 3 or later.

• Empty — Indicates version 1 or 2.

`Source`

Data source, returned as one of these values:

• `'WDBII'` — CIA World Data Bank II

• `'WVS'` — World Vector Shorelines

`CrossesGreenwich`

Indicator for the polygon crossing the prime meridian, returned as `1` when the polygon crosses the prime meridian and `0` otherwise

`GSHHS_ID`

Unique polygon ID, returned as a nonnegative integer.

When the value of `FormatVersion` is at least `7` (release 2.0 and later), the structure array contains these additional fields.

Field

Description

`RiverLake`

Indicator for a river-lake, returned as `1` when a polygon is the fat part of a major river and the value of `Level` is `2`, and `0` otherwise.

`AreaFull`

Area of the original full-resolution polygon, returned as a numeric scalar in units of $\frac{1}{10}k{m}^{2}$.

`Container`

ID of the container polygon, returned as a nonnegative integer or `-1`. A value of `-1` indicates that the polygon does not have a container (as in, the value of `Level` is `1`).

`Ancestor`

ID of the ancestor full-resolution polygon, returned as a nonnegative integer or `-1`. A value of `-1` indicates that the polygon does not have an ancestor.

When the value of `FormatVersion` is at least `9` (release 2.2 and later), the structure array contains this additional field.

Field Name

Field Contents

`CrossesDateline`

Indicator for the polygon crossing the dateline, returned as `1` when the polygon crosses the prime meridian and `0` otherwise

Name of the index file, returned as a character vector.

The index file has the same name as the GSHHG data file, but with the extension `i` instead of `b`. The function writes the file in the same folder as `filename`.

collapse all

### Global Self-Consistent Hierarchical High-Resolution Geography

Global Self-Consistent Hierarchical High-Resolution Geography (GSHHG) is a database created by Paul Wessel of the University of Hawaii and Walter H.F. Smith of the National Oceanic and Atmospheric Administration (NOAA) Geosciences Lab. This database includes coastlines, major rivers, and lakes. You can find GSHHG data in various resolutions from the Shoreline / Coastline Resources page on the NOAA website.

GSHHG is formerly known as Global Self-Consistent Hierarchical High-Resolution Shorelines (GSHHS).

## Tips

• Mapping Toolbox™ contains the file `gshhs_c.b` within the GNU zipped file `gshhs_c.b.gz`. The file contains the coarse data set for version 3 (release 1.3).

• When you read data within specified limits, the `gshhs` function does not clip data that is partially within the limits. To clip the data and maintain polygon topology, use the `maptrimp` function and specify the limits as the `Lat` and `Lon` fields contained in `S`.

• The `gshhs` function supports files up to version 15 (releases 1.1 through 2.3.6). The function can also read newer versions, provided they use the same header format as releases 2.0 and 2.1.

## Version History

Introduced before R2006a