NAME

     psmask - To clip or mask areas of no data on a map


SYNOPSIS

     psmask    [xyzfile]     -Idx[m|c][/dy[m|c]]     -Jparameters
     -Rwest/east/south/north[r]  [  -Btickinfo ] [ -Ddumpfile ] [
     -Eazimuth/elevation ] [ -F ] [ -Gfill ] [ -H[nrec] ] [ -K  ]
     [  -M[flag]  ] [ -N ] [ -O ] [ -P ] [ -Sradius[k] ] [ -T ] [
     -U[/dx/dy/][label] ] [ -V ] [ -Xx-shift ] [  -Yy-shift  ]  [
     -ccopies ]  [ -: ] [ -bi[s][n] ]

     psmask -C [ -K ] [ -O ]


DESCRIPTION

     psmask reads a (x,y,z) file [or  standard  input]  and  uses
     this  information to find out which grid cells are reliable.
     Only gridcells which have one or more data points  are  con-
     sidered reliable.  As an option, you may specify a radius of
     influence. Then, all gridcells that are within radius  of  a
     data  point are considered reliable.  Furthermore, an option
     is provided to reverse the sense of the test.  Having  found
     the  reliable/not  reliable points, psmask will either paint
     tiles to mask these nodes (with the -T) switch, or use  con-
     touring  to create polygons that will clip out regions of no
     interest.  When clipping  is  initiated,  it  will  stay  in
     effect until turned off by a second call to psmask using the
     -C option.

     xyzfile
          File with (x,y,z) values (e.g., that was  used  to  run
          surface).  If no file is given, standard input is read.
          For binary files, see -b.

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

     -J   Selects  the  map  projection.  Scale  is  UNIT/degree,
          1:xxxxx,  or width in UNIT (upper case modifier).  UNIT
          is cm, inch, or m, depending on the  MEASURE_UNIT  set-
          ting in .gmtdefaults, but this can be overridden on the
          command line by  appending  the  c,  i,  or  m  to  the
          scale/width value.

          CYLINDRICAL PROJECTIONS:

          -Jclon0/lat0/scale (Cassini)
          -Jjlon0/scale (Miller)
          -Jmscale (Mercator - Greenwich and Equator as origin)
          -Jmlon0/lat0/scale (Mercator - Give meridian and  stan-
          dard parallel)
          -Joalon0/lat0/azimuth/scale (Oblique Mercator  -  point
          and azimuth)
          -Joblon0/lat0/lon1/lat1/scale (Oblique Mercator  -  two
          points)
          -Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point
          and pole)
          -Jqlon0/scale   (Equidistant   Cylindrical   Projection
          (Plate Carree))
          -Jtlon0/scale (TM - Transverse Mercator,  with  Equator
          as y = 0)
          -Jtlon0/lat0/scale (TM - Transverse Mercator, set  ori-
          gin)
          -Juzone/scale (UTM - Universal Transverse Mercator)
          -Jylon0/lats/scale (Basic Cylindrical Projection)

          AZIMUTHAL PROJECTIONS:

          -Jalon0/lat0/scale (Lambert).
          -Jelon0/lat0/scale (Equidistant).
          -Jflon0/lat0/horizon/scale (Gnomonic).
          -Jglon0/lat0/scale (Orthographic).
          -Jslon0/lat0/scale (General Stereographic)

          CONIC PROJECTIONS:

          -Jblon0/lat0/lat1/lat2/scale (Albers)
          -Jdlon0/lat0/lat1/lat2/scale (Equidistant)
          -Jllon0/lat0/lat1/lat2/scale (Lambert)

          MISCELLANEOUS PROJECTIONS:

          -Jhlon0/scale (Hammer)
          -Jilon0/scale (Sinusoidal)
          -Jk[f|s]lon0/scale (Eckert IV (f) and VI (s))
          -Jnlon0/scale (Robinson)
          -Jrlon0/scale (Winkel Tripel)
          -Jvlon0/scale (Van der Grinten)
          -Jwlon0/scale (Mollweide)

          NON-GEOGRAPHICAL PROJECTIONS:

          -Jpscale[/origin] (polar (theta,r) coordinates, option-
          ally offset theta [0])
          -Jxx-scale[l|ppow][/y-scale[l|ppow]] (Linear, log,  and
          power scaling)
          More details can be found in the psbasemap manpages.

     -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

     No space between the option flag and  the  associated  argu-
     ments


     -B   Sets map boundary tickmark intervals. See psbasemap for
          details.

     -C   Mark end of existing  clip  path.   No  input  file  is
          needed.  Implicitly sets -O.

     -D   Dumps out the  resulting  clipping  polygons  to  disk.
          Ignored if -T is set.  If no dumpprefix is given we use
          mask (Files will be called mask_*.d).

     -E   Sets the viewpoint's azimuth and elevation for perspec-
          tive plots [180/90]

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

     -G   Paint the clip polygons [or tiles] with  selected  fill
          [Default  is  no  fill].   Specify the shade (0-255) or
          color (r/g/b, each in 0-255).

     -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.   Not
          used with binary data.

     -K   More PostScript code will be  appended  later  [Default
          terminates the plot system].

     -M   Multiple segment file(s).  Segments are separated by  a
          special  record.   For  ASCII files the first character
          must be flag [Default is '>'].  For  binary  files  all
          fields must be NaN.

     -N   Invert the sense of the test, i.e. clip  regions  where
          there is data coverage.

     -O   Selects Overlay plot mode [Default  initializes  a  new
          plot system].

     -P   Selects  Portrait  plotting  mode   [GMT   Default   is
          Landscape, see gmtdefaults to change this].

     -S   Sets radius of influence. Grid nodes within radius of a
          data  point  are  considered  reliable.  [Default is 0,
          which means that only grid cells with data in them  are
          reliable].   Append  k  to  indicated km, also implying
          that -R -I are in degrees.

     -T   Plot tiles instead of clip polygons  (Only  works  with
          -Jx, -Jj, -Jm, -Jq, and -Jy).

     -U   Draw Unix System time stamp on plot.  User may  specify
          where the lower left corner of the stamp should fall on
          the  page  relative  to  lower  left  corner  of  plot.
          Optionally,  append  a label, or c (which will plot the
          command string.)

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

     -X -Y
          Shift origin of plot by (x-shift,y-shift).   Prepend  a
          for  absolute  coordinates;  the default (r) will reset
          plot origin.

     -:   Toggles      between      (longitude,latitude)      and
          (latitude,longitude)    input/output.     [Default   is
          (longitude,latitude)].

     -c   Specifies the number of plot copies. [Default is 1]

     -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 make an overlay PostScript file that will  mask  out  the
     regions  of  a  contour  map  where there is no control data
     using clip polygons, try:

     psmask africa_grav.xyg -R20/40/20/40 -I5m  -JM10i  -O  -K  >
     mask.ps

     The same example but this time we use tiling:

     psmask africa_grav.xyg -R20/40/20/40 -I5m -JM10i -T -O -K  >
     mask.ps


SEE ALSO

     gmt(l), grdmask(l), surface(l), psbasemap(l), psclip(l)