GSHHG Earth Mask

Many users need ocean/land mask grids to isolate features that should only be set over the ocean or on land. While you can prevent such areas from being plotted via the clipping in coast, you may still want to perform calculations on gridded data and apply masks via grdmath. Such mask grids can be computed via grdlandmask but they can take a long time to compute for large regions, the full GSHHG resolution, and small grid spacings. For these reasons we offer precalculated mask grids via the remote server mechanism.

Usage

You access a global mask grid by specifying the special name

@earth_mask[_rru[_reg]]

The following codes for rru and the optional reg are supported (dimensions are listed for pixel-registered grids; gridline-registered grids increment dimensions by one):

GSHHG Earth Mask

Code	Dimensions	Reg	Size	Description
01d	360 x 180	g,p	20 KB	1 arc degree global mask (skip features < 12364 km^2)
30m	720 x 360	g,p	24 KB	30 arc minute global mask (skip features < 3091 km^2)
20m	1080 x 540	g,p	30 KB	20 arc minute global mask (skip features < 1374 km^2)
15m	1440 x 720	g,p	35 KB	15 arc minute global mask (skip features < 773 km^2)
10m	2160 x 1080	g,p	57 KB	10 arc minute global mask (skip features < 343 km^2)
06m	3600 x 1800	g,p	106 KB	6 arc minute global mask (skip features < 124 km^2)
05m	4320 x 2160	g,p	117 KB	5 arc minute global mask (skip features < 86 km^2)
04m	5400 x 2700	g,p	149 KB	4 arc minute global mask (skip features < 55 km^2)
03m	7200 x 3600	g,p	209 KB	3 arc minute global mask (skip features < 31 km^2)
02m	10800 x 5400	g,p	393 KB	2 arc minute global mask (skip features < 14 km^2)
01m	21600 x 10800	g,p	998 KB	1 arc minute global mask (skip features < 3 km^2)
30s	43200 x 21600	g,p	2.6 MB	30 arc second global mask (skip features < 1 km^2)
15s	86400 x 43200	g,p	7.5 MB	15 arc second global mask (all features)

See GMT remote dataset usage for when resolution codes are optional or required. All of these data will, when downloaded, be placed in your ~/.gmt/server directory, with the Earth mask files being placed in an earth/earth_mask sub-directory.

Technical Information

Given that GSHHG contains 5 levels (ocean, land, lake, island-in-lake, pond-in-island-in-lake) corresponding to levels 0-4, the mask grids were computed to reflect those 5 levels. Thus, the node values in the mask grids are all in the 0-4 range and have these meanings:

0. Oceanic areas beyond the shoreline

1. Land areas inside the shoreline

2. Lakes inside the land areas

3. Islands in lakes in the land areas

4. Smaller lakes in islands that are found within lakes inside the land area

This means that if you only want a mask for the ocean or one for wet versus dry, you will need to run a simple grdmath command to adjust the mask for your use. We give some common examples here. To create a gridline-registered mask that is 0 in the ocean and 1 everywhere else (even in lakes, etc.), try:

gmt grdmath @earth_mask_01m_g 0 GT = ocean_land.grd

To make a pixel-registered mask that has NaNs on land and 1 in the oceans, use:

gmt grdmath @earth_mask_01m_p 0 LE 0 NAN = land_NaN.grd

Finally, to make a pixel-registered mask that is 1 for lakes and NaN elsewhere, try:

gmt grdmath @earth_mask_01m 2 EQ 0 NAN = lakes_and_NaN.grd