NAME

       psclip - Initialize or terminate polygonal clip paths

SYNOPSIS

       psclip  [  table  ]  parameters  [n]  west/east/south/north[/zmin/zmax][r] [ [m|p|x|y] ] [
       [p|s]parameters ] z|Zparameters ] [  ] [  ] [  ] [  ] [  ] [  [just/dx/dy/][c|label]  ]  [
       [level]  ]  [  x_offset  ]  [  y_offset  ]  [ -bi<binary> ] [ -ccopies ] [ -di<nodata> ] [
       -f<flags> ] [ -g<gaps> ] [ -h<headers> ] [ -i<flags> ] [ -p<flags>  ]  [  -t<transp>  ]  [
       -:[i|o] ]

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

DESCRIPTION

       psclip  reads  (x,y)  file(s) [or standard input] and draws polygons that are activated as
       clipping paths. Several files may be read to create complex paths  consisting  of  several
       non-connecting  segments.  Only marks that are subsequently drawn inside the clipping path
       will be shown. To determine what is inside or outside the clipping path, psclip  uses  the
       even-odd  rule.  When  a  ray  drawn  from any point, regardless of direction, crosses the
       clipping path segments an odd number of times, the point is inside the clipping  path.  If
       the number is even, the point is outside. The -N option, reverses the sense of what is the
       inside and outside of the paths by plotting a clipping path along the map boundary.  After
       subsequent  plotting,  which  will  be  clipped  against  these paths, the clipping may be
       deactivated by running psclip a second time with the -C option only.

REQUIRED ARGUMENTS

       -C[|n] Mark end of existing clip path(s). No input file will be processed.  No  projection
              information  is  needed  unless  -B has been selected as well. With no arguments we
              terminate all active clipping paths.  Experts may restrict the termination to  just
              n  of the active clipping path by passing that as the argument.  Remember to supply
              -X and -Y settings if you have moved since the clip started.

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

       -A[m|p|x|y]
              By default, geographic line segments are connected as great circle arcs. To connect
              them as straight lines, use the -A flag. Alternatively, add m to connect  the  line
              by  first  following  a meridian, then a parallel. Or append p to start following a
              parallel, then a meridian. (This can be practical to connect lines along parallels,
              for example).  For Cartesian data, points are simply connected, unless you append x
              or y to construct stair-case paths whose first move is along x or y, respectively.

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

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

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

       -N     Invert the sense of what is inside and outside. For example, when  using  a  single
              path,  this  means that only points outside that path will be shown. Cannot be used
              together with -B.

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

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

       -T     Rather than read any input files, simply turn  on  clipping  for  the  current  map
              region.  Basically,  -T  is  a  convenient  way to run psclip with the arguments -N
              /dev/null (or, under Windows, -N NUL). Cannot be used together with -B.

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

       -f[i|o]colinfo (more ...)
              Specify data types of input and/or output columns.

       -g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more ...)
              Determine data gaps and line breaks.

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

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

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

EXAMPLES

       To  make  an  overlay  PostScript  file  that  will  set  up  a complex clip area to which
       subsequent plotting will be confined, run:

              gmt psclip my_region.xy -R0/40/0/40 -Jm0.3i -O -K > clip_mask_on.ps

       To deactivate the clipping in an existing plotfile, run:

              gmt psclip -C -O >> complex_plot.ps

SEE ALSO

       gmt, grdmask, psbasemap, psmask

COPYRIGHT

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