gshhs - Read Global Self-Consistent Hierarchical High-Resolution Shoreline

Syntax

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

Description

S = gshhs(filename) reads GSHHS version 1.3 and earlier vector data for the entire world from filename. GSHHS files have names of the form gshhs_X.b, where X is one of the letters c, l, i, h and f, corresponding to increasing resolution (and file size). The result returned in S is a polygon geographic data structure array (geostruct).

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 GSHHS data file, but with the extension 'i', instead of 'b' and is written in the same directory 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 geostruct output structure S contains the following fields; all latitude and longitude values are in degrees:

Field Name	Field Contents
`Geometry`	`'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'` or `'lake'`, or `'island_in_lake'`, or `'pond_in_island_in_lake'` or `'other'`
`NumPoints`	Number of points in the polygon
`FormatVersion`	Format version of data: empty if unspecified
`Source`	Source of data: `'WDBII'` or `'WVS'`
`CrossGreenwich`	Scalar flag: true if the polygon crosses the prime meridian, false otherwise
`GSHHS_ID`	Unique polygon scalar id number, starting at 0

Remarks

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.

Note that 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.

Background

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 GSHHS data in various resolutions is available over the Internet from the National Oceanic and Atmospheric Administration, National Geophysical Data Center Web site.

Version 1.3 of the gshhs_c.b (coarse) data set ships with the toolbox in the toolbox/map/mapdemos directory. For details, type

type gshhs_c.txt

at the MATLAB command prompt.

Examples

Example 1

Read the entire coarse data set (located on the MATLAB path in matlabroot/toolbox/map/mapdemos) and display as a coastline:

filename = gunzip('gshhs_c.b.gz', tempdir);
world = gshhs(filename{1});
delete(filename{1})
figure
worldmap world
geoshow([world.Lat], [world.Lon])

After creating an index file, read and display Africa as a green polygon; note that gshhs detects and uses the index file automatically:

filename = gunzip('gshhs_c.b.gz', tempdir);
indexname = gshhs(filename{1}, 'createindex');
figure
worldmap Africa
projection = gcm;
latlim = projection.maplatlimit;
lonlim = projection.maplonlimit;
africa = gshhs(filename{1}, latlim, lonlim);
delete(filename{1})
delete(indexname)
geoshow(africa, 'FaceColor', 'green')
setm(gca, 'FFaceColor', 'cyan')

Note The following examples use publicly available GSHHS data files that do not ship with the Mapping Toolbox software. For details on locating GSHHS data for download over the Internet, see the following documentation at the MathWorks Web site: http://www.mathworks.com/support/tech-notes/2100/2101.html.

Example 2

Read all of the lowest resolution database:

s = gshhs('gshhs_c.b')

Example 3

Read the intermediate resolution database for South America:

s = gshhs('gshhs_i.b',[-60 -15],[-90 -30])

Example 4

Read the full-resolution file for East and West Falkland Islands (Islas Malvinas):

s = gshhs('gshhs_f.b',[-55 -50],[-65 -55])

Example 5

Create the index file for the high-resolution database:

gshhs('gshhs_h.b','createindex')