gshhs matlab,Read Global Self-Consistent Hierarchical High-Resolution Geography

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 NameField

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

'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 NameField 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.txtat

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

Read Entire Coarse Data Set and Display Levels

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 GSHHG Dataset Using an Index

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.

Introduced before R2006a