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

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.

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

Read and Display GSHHG Data

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")

Read GSHHG Data Using Index

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

filename — Name of GSHHG file

character vector | string scalar

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

latlim — Latitude limits

[] | two-element vector

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

lonlim — Longitude limits

[] | two-element vector

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

S — Geographic data structure

structure array

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

indexFilename — Name of index file

character vector

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

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