NAME

       grdmask - Create mask grdfiles from xy paths.

SYNOPSIS

       grdmask pathfiles -Gmask_grd_file] -Ixinc[m|c][/yinc[m|c]] -Rwest/east/south/north[r] [ -A
       ] [ -F ] [ -H[nrec] ] [ -L ] [ -M[flag] ] [ -Nout/edge/in ] [ -S[radius][k] ] [ -V ] [  -:
       ] [ -bi[s][n] ]

DESCRIPTION

       grdmask  can  operate  in  2  different  modes. 1. It reads one or more xy-files that each
       define a closed polygon.  The nodes defined by the specified region  and  lattice  spacing
       will  be  set  equal  to  one  of  three  possible values depending on whether the node is
       outside, on the polygon perimeter, or inside the polygon. The resulting mask  grdfile  may
       be  used in subsequent operations involving grdmath to mask out data from polygonal areas.
       2. The xy-files simply represent data point locations and the mask is set to the inside or
       outside  value  depending  on whether a node is within a maximum distance from the nearest
       data point.  If the distance specified is zero then only the nodes nearest each data point
       are considered "inside".

       pathfiles
              The  name  of  1  or more ASCII [or binary, see -b] files holding the polygon(s) or
              data points.

       -G     Name of resulting output mask grd file.

       -I     x_inc [and optionally y_inc] is the grid spacing. Append m to indicate minutes or c
              to indicate seconds.

       -R     west,  east, south, and north specify the Region of interest. To specify boundaries
              in degrees and minutes [and seconds], use the dd:mm[:ss] format. Append r if  lower
              left and upper right map coordinates are given instead of wesn.

OPTIONS

       -A     If  the  input  data  are  geographic  (as  indicated  by -L) then the sides in the
              polygons will be approximated by great circle arcs. This can be  turned  off  using
              the -A switch.

       -F     Force pixel registration. [Default is grid registration].

       -H     Input  file(s)  has  Header  record(s).  Number of header records can be changed by
              editing your .gmtdefaults file. If used, GMT default is 1 header record.

       -L     Indicates that the x column contains longitudes, which may differ from the  regions
              in -R by [multiples of] 360 degrees [Default assumes no periodicity].

       -M     Multiple  segment file. Segments are separated by a record whose first character is
              flag.  [Default is '>'].

       -N     Sets the values that will be assigned to nodes that are outside  the  polygons,  on
              the  edge,  or  inside.  Values  can  be  any  number, including the textstring NaN
              [Default is 0/0/1].

       -S     Set nodes depending on their distance from the nearest  data  point.  Nodes  within
              radius  [0] from a data point are considered inside. Append k to indicate map units
              (e.g., -R -I in degrees and radius in km).

       -V     Selects verbose mode, which will send progress  reports  to  stderr  [Default  runs
              "silently"].

       -bi    Selects  binary input. Append s for single precision [Default is double].  Append n
              for the number of columns in the binary file(s).  [Default is 2 input columns].

EXAMPLES

       To set all nodes inside and on the polygons coastline_*.xy to 0, and outside points to  1,
       do

       grdmask coastline_*.xy -R-60/-40/-40/-30 -I5m -N1/0/0 -Gland_mask.grd -V

       To set nodes within 50 km of data points to 1 and other nodes to NaN, do

       grdmask data.xyz -R-60/-40/-40/-30 -I5m -NNaN/1/1 -S50k -Gdata_mask.grd -V

SEE ALSO

       gmt(1gmt), grdlandmask(1gmt), grdmath(1gmt), grdclip(1gmt), psmask(1gmt), psclip(1gmt)

                                            1 Jan 2004                                 GRDMASK(l)