pyrocko.dataset.gshhg

Interface to the GSHHG (coastlines, rivers and borders) database.

The Global Self-consistent Hierarchical High-resolution Geography Database (GSHHG) is a collection of polygons representing land, lakes, rivers and political borders.

If the database is not already available, it will be downloaded automatically on first use.

For more information about GSHHG, see http://www.soest.hawaii.edu/pwessel/gshhg/.

Citation

If you use this dataset, please cite

Wessel, P., and W. H. F. Smith, A Global Self-consistent, Hierarchical, High-resolution Shoreline Database, J. Geophys. Res., 101, #B4, pp. 8741-8743, 1996.

Functions

bounding_boxes_overlap(wesn1, wesn2)	Check whether two bounding boxes intersect.
is_valid_bounding_box(wesn)	Check if a given bounding box meets the GSHHG conventions.
is_valid_polygon(points)	Check if polygon points meet the GSHHG conventions.
point_in_bounding_box(point, wesn[, tolerance])	Check whether point is contained in a given bounding box.
points_in_bounding_box(points, wesn[, tolerance])	Check which points are contained in a given bounding box.

Classes

GSHHG(gshhg_file)	GSHHG database access.
Polygon(gshhg_file, offset, *attr)	Representation of a GSHHG polygon.

is_valid_bounding_box(wesn)

Check if a given bounding box meets the GSHHG conventions.

Parameters:

wesn – bounding box as (west, east, south, north) in [deg]

is_valid_polygon(points)

Check if polygon points meet the GSHHG conventions.

Parameters:

points – Array of (lat, lon) pairs, shape (N, 2).

points_in_bounding_box(points, wesn, tolerance=0.1)

Check which points are contained in a given bounding box.

Parameters:

• points – Array of (lat lon) pairs, shape (N, 2) [deg].

• wesn – Region tuple (west, east, south, north) [deg]

• tolerance – increase the size of the test bounding box by tolerance [deg] on every side (Some GSHHG polygons have a too tight bounding box).

Returns:

Bool array of shape (N,).

point_in_bounding_box(point, wesn, tolerance=0.1)

Check whether point is contained in a given bounding box.

Parameters:

• points – Array of (lat lon) pairs, shape (N, 2) [deg].

• wesn – Region tuple (west, east, south, north) [deg]

• tolerance – increase the size of the test bounding box by tolerance [deg] on every side (Some GSHHG polygons have a too tight bounding box).

Return type:

bool

bounding_boxes_overlap(wesn1, wesn2)

Check whether two bounding boxes intersect.

Parameters:

• wesn1 (tuple of 4 float) – Region tuple (west, east, south, north) [deg]

• wesn2 (tuple of 4 float) – Region tuple (west, east, south, north) [deg]

Return type:

bool

class Polygon(gshhg_file, offset, *attr)

Bases: object

Representation of a GSHHG polygon.

property points

Points of the polygon.

Array of (lat, lon) pairs, shape (N, 2).

Return type:

numpy.ndarray

is_land()

Check if the polygon is land.

Return type:

bool

is_lake()

Check if the polygon is a lake.

Return type:

bool

is_island_in_lake()

Check if the polygon is an island in a lake.

Return type:

bool

is_pond_in_island_in_lake()

Check if the polygon is pond on an island in a lake.

Return type:

bool

is_antarctic_icefront()

Check if the polygon is antarctic icefront.

Return type:

bool

is_antarctic_grounding_line()

Check if the polygon is antarctic grounding line.

Return type:

bool

contains_point(point)

Check if point lies in polygon.

Parameters:

point (tuple) – (lat, lon) [deg]

Return type:

bool

See pyrocko.orthodrome.contains_points().

contains_points(points)

Check if points lie in polygon.

Parameters:

points (numpy.ndarray) – Array of (lat lon) pairs, shape (N, 2) [deg].

See pyrocko.orthodrome.contains_points().

Returns:

Bool array of shape (N,)

class GSHHG(gshhg_file)

Bases: object

GSHHG database access.

This class provides methods to select relevant polygons (land, lakes, etc.) for given locations or regions. It also provides robust high-level functions to test if the Earth is dry or wet at given coordinates.

get_polygons_at(lat, lon)

Get all polygons whose bounding boxes contain point.

Parameters:

• lat (float) – Latitude in [deg]

• lon (float) – Longitude in [deg]

Returns:

List of Polygon

Return type:

list

get_polygons_within(west, east, south, north)

Get all polygons whose bounding boxes intersect with a bounding box.

Parameters:

• west (float) – Western boundary in decimal degree

• east (float) – Eastern boundary in decimal degree

• north (float) – Northern boundary in decimal degree

• south (float) – Southern boundary in decimal degree

Returns:

List of Polygon

Return type:

list

is_point_on_land(lat, lon)

Check whether a point is on land.

Lakes are considered not land.

Parameters:

• lat (float) – Latitude in [deg]

• lon (float) – Longitude in [deg]

Return type:

bool

get_land_mask(points)

Check whether given points are on land.

Lakes are considered not land.

Parameters:

points (numpy.ndarray) – Array of (lat, lon) pairs, shape (N, 2).

Returns:

Boolean land mask

Return type:

numpy.ndarray of shape (N,)

classmethod full()

Return the full-resolution GSHHG database.

classmethod high()

Return the high-resolution GSHHG database.

classmethod intermediate()

Return the intermediate-resolution GSHHG database.

classmethod low()

Return the low-resolution GSHHG database.

classmethod crude()

Return the crude-resolution GSHHG database.