GSHHG Global Earth Mask

_images/GMT_earthmask.png

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

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:

  1. Oceanic areas beyond the shoreline

  2. Land areas inside the shoreline

  3. Lakes inside the land areas

  4. Islands in lakes in the land areas

  5. 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