.. index:: ! grdlandmask .. include:: module_core_purpose.rst_ *********** grdlandmask *********** |grdlandmask_purpose| Synopsis -------- .. include:: common_SYN_OPTs.rst_ **gmt grdlandmask** |-G|\ *outgrid* |SYN_OPT-I| |SYN_OPT-R| [ |SYN_OPT-Area| ] [ |-D|\ *resolution*\ [**+f**] ] [ |-E|\ [*bordervalues*] ] [ |-N|\ *maskvalues* ] [ |-V|\ [*level*] ] [ |SYN_OPT-r| ] [ |SYN_OPT-x| ] [ |SYN_OPT--| ] |No-spaces| Description ----------- **grdlandmask** reads the selected shoreline database and uses that information to decide which nodes in the specified grid are over land or over water. The nodes defined by the selected region and lattice spacing will be set according to one of two criteria: (1) land vs water, or (2) the more detailed (hierarchical) ocean vs land vs lake vs island vs pond. The resulting mask may be used in subsequent operations involving :doc:`grdmath` to mask out data from land [or water] areas. Required Arguments ------------------ .. _-G: .. |Add_outgrid| replace:: Give the name of the output mask grid. .. include:: /explain_grd_inout.rst_ :start-after: outgrid-syntax-begins :end-before: outgrid-syntax-ends .. _-I: .. include:: explain_-I.rst_ .. _-R: .. |Add_-Rgeo| unicode:: 0x20 .. just an invisible code .. include:: explain_-Rgeo.rst_ Optional Arguments ------------------ .. _-A: .. |Add_-A| unicode:: 0x20 .. just an invisible code .. include:: explain_-A.rst_ .. _-D: **-D**\ *resolution*\ [**+f**] Selects the resolution of the data set to use ((**f**)ull, (**h**)igh, (**i**)ntermediate, (**l**)ow, or (**c**)rude). The resolution drops off by ~80% between data sets. [Default is **l**]. Append **+f** to automatically select a lower resolution should the one requested not be available [abort if not found]. Alternatively, choose (**a**)uto to automatically select the best resolution given the chosen region. Note that because the coastlines differ in details a node in a mask file using one resolution is not guaranteed to remain inside [or outside] when a different resolution is selected. .. _-E: **-E**\ [*bordervalues*] Nodes that fall exactly on a polygon boundary should be considered to be outside the polygon [Default considers them to be inside]. Alternatively, append either the four values *cborder/lborder/iborder/pborder* or just the single value *bordervalue* (for the case when they should all be the same value). This turns on the line-tracking mode. Now, after setting the mask values specified via |-N| we trace the lines and change the node values for all cells traversed by a line to the corresponding border value. Here, *cborder* is used for cells traversed by the coastline, *lborder* for cells traversed by a lake outline, *iborder* for islands-in-lakes outlines, and *pborder* for ponds-in-islands-in-lakes outlines [Default is no line tracing]. .. _-N: **-N**\ *maskvalues* Sets the values that will be assigned to nodes. Values can be any number, including the textstring NaN. Also select |-E| to let nodes exactly on feature boundaries be considered outside [Default is inside]. Specify this information using 1 of 2 formats: **-N**\ *wet/dry*. **-N**\ *ocean/land/lake/island/pond*. [Default is 0/1/0/1/0 (i.e., 0/1)]. .. |Add_-V| replace:: |Add_-V_links| .. include:: explain_-V.rst_ :start-after: **Syntax** :end-before: **Description** .. |Add_nodereg| unicode:: 0x20 .. just an invisible code .. include:: explain_nodereg.rst_ .. include:: explain_core.rst_ .. include:: explain_help.rst_ Notes ----- A grid produced by grdlandmask is a *categorical* dataset. As such, one has to be careful not to interpolate it with standard methods, such as splines. However, if you make a map of this grid using a map projection the grid will be reprojected to yield a rectangular matrix in the projected coordinates. This interpolation is done using splines by default and thus may yield artifacts in your map. We recommend you use :doc:`grdimage` **-nn** to instead use a nearest neighbor interpolation for such cases. Global Landmask Grids --------------------- Before you make your own masks, be aware that the GMT data server offers global landmask files in multiple grid resolutions. These can be accessed using the remote file names @earth_mask_\ *rr*\ *u*\ [_\ *reg*\ ], where *rr*\ *u* and the optional *reg* indicate the resolution and registration that you desire. See `Global Earth Mask Grids `_ for more information on the availability of resolutions. Examples -------- To set all nodes on land to NaN, and nodes over water to 1, using the high resolution data set, do :: gmt grdlandmask -R-60/-40/-40/-30 -Dh -I5m -N1/NaN -Gland_mask.nc -V To make a 1x1 degree global grid with the hierarchical levels of the nodes based on the low resolution data: :: gmt grdlandmask -R0/360/-90/90 -Dl -I1 -N0/1/2/3/4 -Glevels.nc -V .. include:: explain_gshhg.rst_ See Also -------- :doc:`gmt`, :doc:`grdmath`, :doc:`grdclip`, :doc:`mask`, :doc:`clip`, :doc:`coast`