NAME

     psclip - To set up polygonal clip paths

SYNOPSIS

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

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 with the -C option only.

     xyfiles
          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  is
          needed.  Implicitly sets -O.

     -J    Selects the  map  projection.  Scale  is  inch/degree,
          1:xxxxx. or width in inch (upper case modifier).

          CYLINDRICAL PROJECTIONS:

          -Jclon0/lat0/scale (Cassini)
          -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)
          -Juzone/scale (UTM - Universal Transverse Mercator)
          -Jylon0/lats/scale (Basic Cylindrical Projection)

          AZIMUTHAL PROJECTIONS:

          -Jalon0/lat0/scale (Lambert).
          -Jelon0/lat0/scale (Equidistant).
          -Jglon0/lat0/scale (Orthographic).
          -Jslon0/lat0/scale (General Stereographic)

          CONIC PROJECTIONS:

          -Jblon0/lat0/lat1/lat2/scale (Albers)
          -Jllon0/lat0/lat1/lat2/scale (Lambert)

          MISCELLANEOUS PROJECTIONS:

          -Jhlon0/scale (Hammer)
          -Jilon0/scale (Sinusoidal)
          -Jklon0/scale (Eckert VI)
          -Jnlon0/scale (Robinson)
          -Jrlon0/scale (Winkel Tripel)
          -Jwlon0/scale (Mollweide)

          NON-GEOGRAPHICAL PROJECTIONS:

          -Jpscale (Linear projection for polar (theta,r) coordi-
          nates)
          -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]

     -F    Sets the color used for Frame and annotation. [Default
          is black]

     -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 in  inch
          [Default   is  (-0.75,-0.75)].   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)   inch
          [Default is (1,1) for new plots, (0,0) for overlays].

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

EXAMPLES

     To make an overlay PostScript file that will set up  a  com-
     plex clip area to which subsequent plotting will be confined
     to, try:

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

     To deactivate the clipping, run:

     psclip -C > clip_mask_off.ps

SEE ALSO

     gmt, grdmask, psbasemap, psmask

REFERENCES

     Wessel, P., and W. H. F. Smith, 1995,  The  Generic  Mapping
     Tools  (GMT)  version  3.0  Technical  Reference & Cookbook,
     SOEST/NOAA.
     Wessel, P., and W. H. F. Smith, 1995,  New  Version  of  the
     Generic Mapping Tools Released, EOS Trans. AGU, 76, p. 329.
     Wessel, P., and W. H. F. Smith, 1995,  New  Version  of  the
     Generic           Mapping           Tools          Released,
     http://www.agu.org/eos_elec/95154e.html, Copyright  1995  by
     the American Geophysical Union.
     Wessel, P., and W. H. F. Smith, 1991,  Free  Software  Helps
     Map and Display Data, EOS Trans. AGU, 72, p. 441.