Provided by: gmt_4.5.11-1build1_amd64 bug

NAME

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

SYNOPSIS

       psmask          [xyzfile]         -Ixinc[unit][=|+][/yinc[unit][=|+]]         -Jparameters
       -Rwest/east/south/north[r]    [    -B[p|s]parameters    ]     [     -Ddumpfile     ]     [
       -Eazim/elev[+wlon/lat[/z]][+vx0/y0] ] [ -F ] [ -Gfill ] [ -H[i][nrec] ] [ -K ] [ -N ] [ -O
       ] [ -P ] [ -Ssearch_radius[m|c|k|K] ] [ -T  ]  [  -U[just/dx/dy/][c|label]  ]  [  -V  ]  [
       -X[a|c|r][x-shift[u]]   ]   [  -Y[a|c|r][y-shift[u]]  ]  [  -ccopies  ]   [  -:[i|o]  ]  [
       -bi[s|S|d|D[ncol]|c[var1/...]] ] [ -m[flag] ]

       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
       considered 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 contouring 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. Optionally, append a suffix
              modifier.  Geographical (degrees) coordinates: Append m to indicate arc minutes  or
              c  to indicate arc seconds.  If one of the units e, k, i, or n is appended instead,
              the increment is assumed to be given  in  meter,  km,  miles,  or  nautical  miles,
              respectively,  and  will  be  converted  to the equivalent degrees longitude at the
              middle latitude of the region (the conversion depends on ELLIPSOID).  If /y_inc  is
              given  but set to 0 it will be reset equal to x_inc; otherwise it will be converted
              to degrees latitude.  All coordinates: If = is appended then the corresponding  max
              x  (east)  or y (north) may be slightly adjusted to fit exactly the given increment
              [by default the increment may be  adjusted  slightly  to  fit  the  given  domain].
              Finally, instead of giving an increment you may specify the number of nodes desired
              by appending + to the supplied integer argument; the increment is then recalculated
              from  the number of nodes and the domain.  The resulting increment value depends on
              whether you have selected  a  gridline-registered  or  pixel-registered  grid;  see
              Appendix  B  for details.  Note: if -Rgrdfile is used then grid spacing has already
              been initialized; use -I to override the values.

       -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 setting in
              .gmtdefaults4, but this can be overridden on the command line by appending c, i, or
              m  to  the scale/width value.  When central meridian is optional, default is center
              of longitude range on -R option.  Default standard parallel is  the  equator.   For
              map  height,  max  dimension,  or  min  dimension,  append h, +, or - to the width,
              respectively.
              More details can be found in the psbasemap man pages.

              CYLINDRICAL PROJECTIONS:

              -Jclon0/lat0/scale (Cassini)
              -Jcyl_stere/[lon0/[lat0/]]scale (Cylindrical Stereographic)
              -Jj[lon0/]scale (Miller)
              -Jm[lon0/[lat0/]]scale (Mercator)
              -Jmlon0/lat0/scale (Mercator - Give meridian and standard parallel)
              -Jo[a]lon0/lat0/azimuth/scale (Oblique Mercator - point and azimuth)
              -Jo[b]lon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
              -Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point and pole)
              -Jq[lon0/[lat0/]]scale (Cylindrical Equidistant)
              -Jtlon0/[lat0/]scale (TM - Transverse Mercator)
              -Juzone/scale (UTM - Universal Transverse Mercator)
              -Jy[lon0/[lat0/]]scale (Cylindrical Equal-Area)

              CONIC PROJECTIONS:

              -Jblon0/lat0/lat1/lat2/scale (Albers)
              -Jdlon0/lat0/lat1/lat2/scale (Conic Equidistant)
              -Jllon0/lat0/lat1/lat2/scale (Lambert Conic Conformal)
              -Jpoly/[lon0/[lat0/]]scale ((American) Polyconic)

              AZIMUTHAL PROJECTIONS:

              -Jalon0/lat0[/horizon]/scale (Lambert Azimuthal Equal-Area)
              -Jelon0/lat0[/horizon]/scale (Azimuthal Equidistant)
              -Jflon0/lat0[/horizon]/scale (Gnomonic)
              -Jglon0/lat0[/horizon]/scale (Orthographic)
              -Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale (General Perspective).
              -Jslon0/lat0[/horizon]/scale (General Stereographic)

              MISCELLANEOUS PROJECTIONS:

              -Jh[lon0/]scale (Hammer)
              -Ji[lon0/]scale (Sinusoidal)
              -Jkf[lon0/]scale (Eckert IV)
              -Jk[s][lon0/]scale (Eckert VI)
              -Jn[lon0/]scale (Robinson)
              -Jr[lon0/]scale (Winkel Tripel)
              -Jv[lon0/]scale (Van der Grinten)
              -Jw[lon0/]scale (Mollweide)

              NON-GEOGRAPHICAL PROJECTIONS:

              -Jp[a]scale[/origin][r|z] (Polar coordinates (theta,r))
              -Jxx-scale[d|l|ppow|t|T][/y-scale[d|l|ppow|t|T]] (Linear, log, and power scaling)

       -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 w/e/s/n.  The two shorthands
              -Rg and -Rd stand for global domain (0/360 and -180/+180 in longitude respectively,
              with  -90/+90  in  latitude).   Alternatively, specify the name of an existing grid
              file and the -R settings (and grid spacing, if  applicable)  are  copied  from  the
              grid.   For  calendar  time  coordinates  you  may  either  give  (a) relative time
              (relative to the selected TIME_EPOCH and in the selected  TIME_UNIT;  append  t  to
              -JX|x),  or  (b)  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 exactly as indicated
              (however, input, output and plot formats are customizable; see gmtdefaults).

OPTIONS

       No space between the option flag and the associated arguments.

       -B     Sets map boundary annotation and tickmark intervals; see the psbasemap man page for
              all the details.

       -C     Mark  end  of  existing  clip  path.  No input file is needed.  Implicitly sets -O.
              However,  you  must  supply  -Xa  and  -Ya  settings  if  you  are  using  absolute
              positioning.

       -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).  Append  +n<n_pts>
              to  limit  the  number  of  points in files to a minimum of n_pts.  That is, do not
              write individual polygon files if they do not have at least n_pts vertices.  Often,
              when  one  uses the -D option it is not wished to output any ps code to stdout.  In
              such cases redirect the output to > /dev/null on  *nix  systems  or  to  >  nul  on
              Windows.

       -E     Sets  the  viewpoint's  azimuth and elevation (for perspective view) [180/90].  For
              frames used for animation, you may want to append + to fix the center of your  data
              domain  (or  specify a particular world coordinate point with +wlon0/lat[/z]) which
              will project to the center of your page size (or specify  the  coordinates  of  the
              projected view point with +vx0/y0).

       -F     Force   pixel   node   registration  [Default  is  gridline  registration].   (Node
              registrations are defined in GMT Cookbook Appendix B on grid file formats.)

       -G     Paint the clip polygons (or tiles) with a selected fill [Default is no fill].  (See
              SPECIFYING FILL below).

       -H     Input  file(s) has header record(s).  If used, the default number of header records
              is N_HEADER_RECS.  Use -Hi if only input data should have header  records  [Default
              will  write  out header records if the input data have them]. Blank lines and lines
              starting with # are always skipped.  Not used with binary data.

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

       -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 [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  m  to  indicate minutes or c to indicate seconds.  Append k to
              indicate km (implies -R and -I are in degrees, and we will use a  fast  flat  Earth
              approximation  to  calculate  distance).   For  more  accuracy,  use uppercase K if
              distances should be calculated along geodesics.  However, if the current  ELLIPSOID
              is spherical then great circle calculations are used.

       -T     Plot tiles instead of clip polygons.  Use -G to set tile color or pattern.

       -U     Draw  Unix  System time stamp on plot.  By adding just/dx/dy/, the user may specify
              the justification of the stamp and where the stamp should fall on the page relative
              to  lower  left  corner of the plot.  For example, BL/0/0 will align the lower left
              corner of the time stamp with the lower  left  corner  of  the  plot.   Optionally,
              append  a  label,  or  c (which will plot the command string.).  The GMT parameters
              UNIX_TIME, UNIX_TIME_POS, and UNIX_TIME_FORMAT can affect the appearance;  see  the
              gmtdefaults man page for details.  The time string will be in the locale set by the
              environment variable TZ (generally local time).

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

       -X -Y  Shift  plot  origin  relative  to  the  current  origin  by  (x-shift,y-shift)  and
              optionally append the length unit (c, i, m, p).  You can prepend  a  to  shift  the
              origin  back  to  the  original position after plotting, or prepend  r [Default] to
              reset the current origin to the new location.  If -O is used then the  default  (x-
              shift,y-shift)   is   (0,0),   otherwise  it  is  (r1i,  r1i)  or  (r2.5c,  r2.5c).
              Alternatively, give c to align the center coordinate (x or y) of the plot with  the
              center of the page based on current page size.

       -:     Toggles  between (longitude,latitude) and (latitude,longitude) input and/or output.
              [Default is (longitude,latitude)].  Append i to select input only or  o  to  select
              output only.  [Default affects both].

       -bi    Selects  binary  input.   Append  s  for  single precision [Default is d (double)].
              Uppercase S or D will force byte-swapping.  Optionally, append ncol, the number  of
              columns  in your binary input file if it exceeds the columns needed by the program.
              Or append c if the input  file  is  netCDF.  Optionally,  append  var1/var2/...  to
              specify the variables to be read.  [Default is 2 input columns].

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

       -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  and -b must set the number of output columns explicitly.  By
              default the -m setting applies to both input and output.  Use -mi and -mo  to  give
              separate settings to input and output.

   SPECIFYING FILL
       fill   The  attribute  fill specifies the solid shade or solid color (see SPECIFYING COLOR
              below) or the pattern  used  for  filling  polygons.   Patterns  are  specified  as
              pdpi/pattern,  where pattern gives the number of the built-in pattern (1-90) or the
              name of a Sun 1-, 8-, or 24-bit raster file. The dpi sets  the  resolution  of  the
              image.   For   1-bit  rasters:  use  Pdpi/pattern  for  inverse  video,  or  append
              :Fcolor[B[color]] to specify fore-  and  background  colors  (use  color  =  -  for
              transparency).   See  GMT Cookbook & Technical Reference Appendix E for information
              on individual patterns.

   SPECIFYING COLOR
       color  The color of lines, areas and patterns can be specified by a valid color name; by a
              gray  shade  (in  the  range  0-255); by a decimal color code (r/g/b, each in range
              0-255; h-s-v, ranges 0-360, 0-1, 0-1; or c/m/y/k, each  in  range  0-1);  or  by  a
              hexadecimal  color  code (#rrggbb, as used in HTML).  See the gmtcolors manpage for
              more information and a full list of color names.

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

       psmask africa_grav.xyg -R 20/40/20/40 -I 5m -JM 10i -O -K > mask.ps

       The same example but this time we use white tiling:

       psmask africa_grav.xyg -R 20/40/20/40 -I 5m -JM 10i -T -O -K -G white > mask.ps

SEE ALSO

       GMT(1), gmtcolors(5), grdmask(1), surface(1), psbasemap(1), psclip(1)