Provided by: gmt_4.5.11-1build1_amd64 bug

NAME

       psclip - To set up polygonal clip paths

SYNOPSIS

       psclip xyfiles -Jparameters -Rwest/east/south/north[r] [ -B[p|s]parameters ] [ -Eazim/elev
       ] [ -K ] [ -N ] [ -O ] [ -P ] [ -T ] [ -U[just/dx/dy/][c|label] ] [ -V  ]  [  -X[a|c|r][x-
       shift[u]]   ]  [  -Y[a|c|r][y-shift[u]]  ]  [  -Zzlevel  ]  [  -ccopies]  [  -:[i|o]  ]  [
       -bi[s|S|d|D[ncol]|c[var1/...]] ] [ -fcolinfo ] [ -m[flag] ]

       psclip -C [ -K ] [ -O ]

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.

       xyfiles
              ASCII [or binary, see -b] file(s) with (x,y) values for clip polygons.  If no files
              are given, the standard input is read.

       -C     Mark end of existing clip path.   No  input  file  or  projection  information  are
              needed.   However,  you  must supply -Xa and -Ya settings if you are using absolute
              positioning.

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

       -E     Sets the viewpoint's azimuth and elevation [180/90].

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

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

       -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     Selects Overlay plot mode [Default initializes a new plot system].

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

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

       -Z     For 3-D projections: Sets the z-level of the polygons [Default is the bottom of the
              z-axis].

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

       -f     Special formatting of input and/or output  columns  (time  or  geographical  data).
              Specify  i  or  o  to  make  this apply only to input or output [Default applies to
              both].  Give one or more columns (or column ranges) separated by commas.  Append  T
              (absolute calendar time), t (relative time in chosen TIME_UNIT since TIME_EPOCH), x
              (longitude), y (latitude), or f (floating point) to each  column  or  column  range
              item.  Shorthand -f[i|o]g means -f[i|o]0x,1y (geographic coordinates).

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

EXAMPLES

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

       psclip my_region.xy -R 0/40/0/40 -Jm 0.3i -O -K > clip_mask_on.ps

       To deactivate the clipping in an existing plotfile, run:

       psclip -C -O >> complex_plot.ps

BUGS

       psclip cannot handle polygons that contain the south or north pole.   For  such  polygons,
       you  should split them into two and make each explicitly contain the polar point.  The two
       clip polygons will combine to give the desired effect.

SEE ALSO

       GMT(1), grdmask(1), psbasemap(1), psmask(1)