NAME

     psclip - To set up polygonal clip paths


SYNOPSIS

     psclip  xyfiles  -Jparameters  -Rwest/east/south/north[r]  [
     -Btickinfo ] [ -Eaz/el ] [ -K ] [ -N ] [ -M[flag] ] [ -O ] [
     -P ] [ -U[/dx/dy/][label] ] [ -V ] [ -Xx-shift ] [ -Yy-shift
     ] [ -Zzlevel ] [ -ccopies ] [ -: ] [ -bi[s][n] ]

     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.   As  an option (-N), the
     user may choose to reverse the sense of what is  the  inside
     and  outside of the paths.  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  pro-
          jection information are needed.

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

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

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

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

     -M   Multiple segment file.  Segments  are  separated  by  a
          record  whose  first  character is <flag>.  [Default is
          '>'].

     -N   Invert the sense of what is inside and  outside,  i.e.,
          use the outside of the polygons for clipping.

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

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

     -Z   For 3-D projections:  Sets the z-level of the  polygons
          [0].

     -:   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  set  up  a
     complex  clip area to which subsequent plotting will be con-
     fined to, try:

     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:

     psclip -C -O >> complex_plot.ps


SEE ALSO

     gmt(l), grdmask(l), psbasemap(l), psmask(l)