.. index:: ! grdlandmask

***********
grdlandmask
***********

.. only:: not man

    grdlandmask - Create a "wet-dry" mask grid from shoreline data base

Synopsis
--------

.. include:: common_SYN_OPTs.rst_

**grdlandmask** |-G|\ *mask_grd_file*
|SYN_OPT-I|
|SYN_OPT-R|
[ |-A|\ *min\_area*\ [/*min\_level*/*max\_level*][\ **+ag**\ \|\ **i**\ \|\ **s** \|\ **S**][\ **+r**\ \|\ **l**][\ **p**\ *percent*] ]
[ |-D|\ *resolution*\ [**+**] ]
[ |-N| ]
[ |-N|\ *maskvalues* ]
[ |-V|\ [*level*] ] [ **-r** ]
[ |SYN_OPT-x| ]

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

**-G**\ *mask_grd_file*]
    Name of resulting output mask grid file. (See GRID FILE FORMATS below). 

.. _-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*\ [**+**]
    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 **+** 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**
    Indicate that nodes that fall exactly on a polygon boundary should be
    considered to be outside the polygon [Default considers them to be inside].

.. _-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)]. 

.. _-V:

.. |Add_-V| unicode:: 0x20 .. just an invisible code
.. include:: explain_-V.rst_

.. |Add_nodereg| unicode:: 0x20 .. just an invisible code
.. include:: explain_nodereg.rst_

.. include:: explain_core.rst_

.. include:: explain_help.rst_

.. include:: explain_grd_output.rst_

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_gshhs.rst_

See Also
--------

:doc:`gmt`, :doc:`grdmath`,
:doc:`grdclip`, :doc:`psmask`,
:doc:`psclip`, :doc:`pscoast`
