Main Content

gshhs

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

Description

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 110km2.

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.

More About

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