xenial (1) psmask.1gmt.gz

Provided by: gmt-common_5.2.1+dfsg-3build1_all bug

NAME

       psmask - Use data tables to clip or mask map areas with no coverage

SYNOPSIS

       psmask  [  table  ]  increment  parameters  region  [ [p|s]parameters ] [ dumpfile ] [ [l|r] ] [ fill ] [
       z|Zparameters ] [  ] [ [+|-]nodegrid ] [  ]  [   ]  [   ]  [  cut  ]  [  search_radius[unit]  ]  [   ]  [
       [just/dx/dy/][c|label] ] [ [level] ] [ x_offset ] [ y_offset ] [ -bi<binary> ] [ -ccopies ] [ -di<nodata>
       ] [ -h<headers> ] [ -i<flags> ] [ -p<flags> ] [ -r ] [ -t<transp> ] [ -:[i|o] ]

       psmask -C [ -K ] [ -O ]

       Note: No space is allowed between the option flag and the associated arguments.

DESCRIPTION

       psmask reads a (x,y,z) file [or standard input] and uses this information to find out  which  grid  cells
       are  reliable.  Only grid cells which have one or more data points are considered reliable. As an option,
       you may specify a radius of influence. Then, all grid cells 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.

REQUIRED

       -Ixinc[unit][=|+][/yinc[unit][=|+]]
              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 s to indicate arc seconds.
              If one of the units e, f, k, M, n or u is appended instead, the increment is assumed to  be  given
              in  meter, foot, km, Mile, nautical mile or US survey foot, respectively, and will be converted to
              the equivalent degrees longitude at the middle latitude of the region (the conversion  depends  on
              PROJ_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 App-file-formats for details. Note: if -Rgrdfile is used then the  grid
              spacing has already been initialized; use -I to override the values.

       -Jparameters (more ...)
              Select map projection.

       -R[unit]xmin/xmax/ymin/ymax[r] (more ...)
              Specify the region of interest.

       For perspective view p, optionally append /zmin/zmax. (more ...)

OPTIONAL ARGUMENTS

       table  One  or  more  ASCII (or binary, see -bi[ncols][type]) data table file(s) holding a number of data
              columns. If no tables are given then we read from standard input.

       -B[p|s]parameters (more ...)
              Set map boundary intervals.

       -C     Mark end of existing clip path. No input file is needed. Implicitly sets -O. Also supply -X and -Y
              settings if you have moved since the clip started.

       -Ddumpfile
              Dump  the  (x,y)  coordinates  of  each clipping polygon to one or more output files (or stdout if
              template is not given). No plotting will take place. If template contains the  C-format  specifier
              %d (including modifications like %05d) then polygons will be written to different files; otherwise
              all polygons are written to the specified file (template). The files are ASCII unless -bo is used.
              See -Q to exclude small polygons from consideration.

       -F[l|r]
              Force  clip contours (polygons) to be oriented so that data points are to the left (-Fl [Default])
              or right (-Fr) as we move along the perimeter [Default is arbitrary orientation]. Requires -D.

       -Gfill Paint the clip polygons (or tiles) with a selected fill [Default is no fill].

       -Jz|Zparameters (more ...)
              Set z-axis scaling; same syntax as -Jx.

       -K (more ...)
              Do not finalize the PostScript plot.

       -L[+|-]nodegrid
              Save the internal grid with ones (data constraint) and zeros (no data) to the named  nodegrid  [no
              grid  saved].   Use L+ to convert the no data flags to NaNs before writing the grid, while L- will
              instead convert the data flags to NaNs.

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

       -O (more ...)
              Append to existing PostScript plot.

       -P (more ...)
              Select "Portrait" plot orientation.

       -Q     Do not dump polygons with less than cut number of points [Dumps all polygons]. Only applicable  if
              -D has been specified.

       -Ssearch_radius[unit]
              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  the
              distance unit (see UNITS).

       -T     Plot tiles instead of clip polygons. Use -G to set tile color or pattern. Cannot be used with -D.

       -U[just/dx/dy/][c|label] (more ...)
              Draw GMT time stamp logo on plot.

       -V[level] (more ...)
              Select verbosity level [c].

       -X[a|c|f|r][x-shift[u]]

       -Y[a|c|f|r][y-shift[u]] (more ...)
              Shift plot origin.

       -bi[ncols][t] (more ...)
              Select native binary input. [Default is 2 input columns].

       -ccopies (more ...)
              Specify number of plot copies [Default is 1].

       -dinodata (more ...)
              Replace input columns that equal nodata with NaN.

       -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
              Skip or produce header record(s). Not used with binary data.

       -icols[l][sscale][ooffset][,...] (more ...)
              Select input columns (0 is first column).

       -p[x|y|z]azim/elev[/zlevel][+wlon0/lat0[/z0]][+vx0/y0] (more ...)
              Select perspective view.

       -r (more ...)
              Set pixel node registration [gridline].

       -t[transp] (more ...)
              Set PDF transparency level in percent.

       -:[i|o] (more ...)
              Swap 1st and 2nd column on input and/or output.

       -^ or just -
              Print a short message about the syntax of the command, then exits (NOTE: on Windows use just -).

       -+ or just +
              Print  an  extensive usage (help) message, including the explanation of any module-specific option
              (but not the GMT common options), then exits.

       -? or no arguments
              Print a complete usage (help) message, including the explanation of options, then exits.

       --version
              Print GMT version and exit.

       --show-datadir
              Print full path to GMT share directory and exit.

UNITS

       For map distance unit, append unit d for arc degree, m for arc minute, and s for arc  second,  or  e  for
       meter [Default], f for foot, k for km, M for statute mile, n for nautical mile, and u for US survey foot.
       By default we compute such distances using a spherical approximation with great circles. Prepend -  to  a
       distance  (or  the  unit  is no distance is given) to perform "Flat Earth" calculations (quicker but less
       accurate) or prepend + to perform exact geodesic calculations (slower but more accurate).

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:

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

       We do it again, but this time we wish to save the clipping polygons to file all_pols.txt:

              gmt psmask africa_grav.xyg -R20/40/20/40 -I5m -Dall_pols.txt

       A repeat of the first example but this time we use white tiling:

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

SEE ALSO

       gmt, gmtcolors, grdmask, surface, psbasemap, psclip

       2015, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe