## 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] ] [  -M[flag]  ]  [
           -Nout/edge/in  ]  [  -S[radius][k]  ]  [  -V  ]  [ -: ] [ -bi[s][n] ] [
           -f[i|o]colinfo ]

## 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 poly-
           gon 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     xmin, xmax, ymin, and ymax specify the Region of  interest.  For
                  geographic  regions,  these  limits  correspond  to  west, east,
                  south, and north and you may specify them in decimal degrees  or
                  in  [+-]dd:mm[:ss.xxx][W|E|S|N]  format.  Append r if lower left
                  and upper right map coordinates are given instead of  wesn.  The
                  two  shorthands  -Rg  -Rd  stand  for  global  domain  (0/360 or
                  -180/+180 in longitude respectively, with -90/+90 in  latitude).
                  For  calendar time coordinates you may either give relative time
                  (relative  to  the  selected  TIME_EPOCH  and  in  the  selected
                  TIME_UNIT;  append  t  to  -JX|x),  or absolute time of the form
                  [date]T[clock] (append T to -JX|x). At least  one  of  date  and
                  clock must be present; the T is always required. The date string
                  must be of the form [-]yyyy[-mm[-dd]]  (Gregorian  calendar)  or
                  yyyy[-Www[-d]]  (ISO week calendar), while the clock string must
                  be of the form hh:mm:ss[.xxx]. The use of delimiters  and  their
                  type  and  positions must be as indicated (however, input/output
                  and plotting formats are flexible).

## OPTIONS

           -A     If the input data are geographic (as indicated by -fi) 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  .gmtdefaults4 file. If used, GMT
                  default is 1 header record. Use -Hi if only  input  data  should
                  have  header  records  [Default will write out header records if
                  the input data have them].

           -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 and -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].

           -f     Special  formatting  of  input  and output columns (time or geo-
                  graphical data) Specify i(nput) or  o(utput)  [Default  is  both
                  input  and output].  Give one or more columns (or column ranges)
                  separated by commas.  Append T (Absolute calendar time), t (time
                  relative  to  chosen TIME_EPOCH), x (longitude), y (latitude), g
                  (geographic coordinate), or f (floating point) to each column or
                  column range item.

## 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(l), grdlandmask(l), grdmath(l), grdclip(l), psmask(l), psclip(l)

    GMT4.0                            1 Oct 2004                        GRDMASK(l)