Provided by: gmt-manpages_3.4.4-1_all bug

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 projection 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  setting  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 standard 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 origin)
              -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/[slat/]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:

              -Jp[a]scale[/origin] (polar (theta,r) coordinates,  optional  a  for  azimuths  and
              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 arguments

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

       -bo    Selects binary output. Append s for single precision [Default is double].

       -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.). The GMT
              parameters  UNIX_TIME  and  UNIX_TIME_POS  can  affect  the  appearance;  see   the
              gmtdefaults man page for details.

       -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)].  Applies to geographic coordinates only.

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

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(1gmt), grdmask(1gmt), psbasemap(1gmt), psmask(1gmt)

                                            1 Jan 2004                                  PSCLIP(l)