Provided by: gmt-common_5.4.5+dfsg-1_all bug

NAME

       psxy - Plot lines, polygons, and symbols on maps

SYNOPSIS

       psxy [ table ]  -Jparameters
        -Rwest/east/south/north[/zmin/zmax][+r]  [  -A[m|p|x|y] ] [  -B[p|s]parameters ] [  -Ccpt
       ] [  -Ddx/dy ] [  -E[x|y|X|Y][+a][+cl|f][+n][+wcap][+ppen] ] [   -F[c|n|r][refpoint]  ]  [
       -Gfill  ]  [  -Iintens ] [  -K ] [  -L[+b|d|D][+xl|r|x0][+yl|r|y0][+ppen] ] [  -N[c|r] ] [
       -O ] [  -P  ]  [   -S[symbol][size[u]  ]  [   -T  ]  [   -U[stamp]  ]  [   -V[level]  ]  [
       -W[pen][attr]  ] [  -Xx_offset ] [  -Yy_offset ] [ -aflags ] [ -bibinary ] [ -dinodata ] [
       -eregexp ] [ -fflags ] [ -ggaps ] [ -hheaders ] [ -iflags ] [ -pflags ]  [  -ttransp  ]  [
       -:[i|o] ]

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

DESCRIPTION

       psxy  reads  (x,y) pairs from files [or standard input] and generates PostScript code that
       will plot lines, polygons, or symbols at those locations on a map. If a symbol is selected
       and  no  symbol size given, then psxy will interpret the third column of the input data as
       symbol size. Symbols whose size is <= 0 are skipped. If no symbols are specified then  the
       symbol code (see -S below) must be present as last column in the input. If -S is not used,
       a line connecting the data points will be drawn instead. To explicitly close polygons, use
       -L.  Select  a  fill with -G. If -G is set, -W will control whether the polygon outline is
       drawn or not. If a symbol is selected, -G  and  -W  determines  the  fill  and  outline/no
       outline, respectively. The PostScript code is written to standard output.

REQUIRED ARGUMENTS

       -Jparameters (more ...)
              Select map projection.

       -Rxmin/xmax/ymin/ymax[+r][+uunit] (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.
              Use -T to ignore all input files, including standard input (see below).

       -A[m|p|x|y]
              By  default,  geographic line segments are drawn as great circle arcs. To draw them
              as straight lines, use the -A flag.  Alternatively, add m to draw 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  draw  a  line  along  parallels,  for
              example).   For Cartesian data, points are simply connected, unless you append x or
              y to draw stair-case curves that whose first move is along x or y, respectively.

       -B[p|s]parameters (more ...)
              Set map boundary frame and axes attributes.

       -Ccpt  Give a CPT or specify -Ccolor1,color2[,color3,...]  to build  a  linear  continuous
              CPT from those colors automatically.  In this case colorn can be a r/g/b triplet, a
              color name, or an HTML hexadecimal color (e.g. #aabbcc ).  If -S is set, let symbol
              fill  color be determined by the z-value in the third column. Additional fields are
              shifted over by one column (optional size would  be  4th  rather  than  3rd  field,
              etc.).  If  -S is not set, then psxy expects the user to supply a multisegment file
              where each segment header contains a -Zval string. The val will control  the  color
              of the line or polygon (if -L is set) via the CPT.

       -Ddx/dy
              Offset  the plot symbol or line locations by the given amounts dx/dy [Default is no
              offset]. If dy is not given it is set equal to dx.

       -E[x|y|X|Y][+a][+cl|f][+n][+wcap][+ppen]
              Draw symmetrical error bars. Append x and/or y to indicate which bars you  want  to
              draw (Default is both x and y). The x and/or y errors must be stored in the columns
              after the (x,y) pair [or (x,y,z) triplet]. If +a is  appended  then  we  will  draw
              asymmetrical error bars; these requires two rather than one extra data column, with
              the low and high value.  If upper case X and/or Y are used  we  will  instead  draw
              "box-and-whisker"  (or  "stem-and-leaf")  symbols.  The x (or y) coordinate is then
              taken as the median value, and four  more  columns  are  expected  to  contain  the
              minimum  (0%  quantile),  the 25% quantile, the 75% quantile, and the maximum (100%
              quantile) values. The 25-75% box may be filled by using -G. If +n is  appended  the
              we  draw  a  notched  "box-and-whisker"  symbol  where the notch width reflects the
              uncertainty in the median. This symbol requires a 5th extra data column to  contain
              the  number of points in the distribution.  The +w modifier sets the cap width that
              indicates the length of the end-cap on the error  bars  [7p].  Pen  attributes  for
              error  bars  may also be set via +ppen.  [Defaults: width = default, color = black,
              style = solid]. When -C is used we can control how the look-up color is applied  to
              our  symbol.   Append +cf to use it to fill the symbol, while +cl will just set the
              error pen color and turn off symbol fill.  Giving +c will set both color items.

       -F[c|n|r][a|f|s|r|refpoint]
              Alter the way points are connected (by specifying a scheme) and  data  are  grouped
              (by  specifying  a  method).   Append one of three line connection schemes: c: Draw
              continuous line segments for each group [Default].  r: Draw line  segments  from  a
              reference  point  reset  for each group.  n: Draw networks of line segments between
              all points in each group.  Optionally, append the one of four segmentation  methods
              to  define the group: a: Ignore all segment headers, i.e., let all points belong to
              a single group, and set group reference point to the very first point of the  first
              file.   f:  Consider  all data in each file to be a single separate group and reset
              the group reference point to the first point of each group.  s: Segment headers are
              honored so each segment is a group; the group reference point is reset to the first
              point of each incoming segment [Default].  r: Same as s, but  the  group  reference
              point  is  reset  after  each  record  to  the  previous point (this method is only
              available with the -Fr scheme).  Instead of the codes a|f|s|r you  may  append  the
              coordinates  of a refpoint which will serve as a fixed external reference point for
              all groups.

       -Gfill Select color or pattern for filling of symbols or polygons [Default  is  no  fill].
              Note that psxy will search for -G and -W strings in all the segment headers and let
              any values thus found over-ride the command line settings.

       -Iintens
              Use the supplied intens value (nominally in the -1 to + 1 range)  to  modulate  the
              fill color by simulating illumination [none].

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

       -L[+b|d|D][+xl|r|x0][+yl|r|y0][+ppen]
              Force  closed  polygons.  Alternatively, append modifiers to build a polygon from a
              line segment.  Append +d to build symmetrical envelope around y(x) using deviations
              dy(x)  given  in  extra  column 3.  Append +D to build asymmetrical envelope around
              y(x) using deviations dy1(x) and dy2(x) from extra columns 3-4.  Append +b to build
              asymmetrical  envelope  around y(x) using bounds yl(x) and yh(x) from extra columns
              3-4.  Append +xl|r|x0 to connect first and last point to anchor  points  at  either
              xmin,  xmax,  or  x0,  or append +yb|t|y0 to connect first and last point to anchor
              points at either ymin, ymax, or y0.  Polygon may be  painted  (-G)  and  optionally
              outlined by adding +ppen [no outline].

       -N[c|r]
              Do  NOT  clip  symbols  that  fall  outside  map border [Default plots points whose
              coordinates are strictly inside the map border only]. The option does not apply  to
              lines  and  polygons  which  are  always  clipped  to  the map region. For periodic
              (360-longitude) maps we must plot all symbols twice in case they are clipped by the
              repeating  boundary.  The -N will turn off clipping and not plot repeating symbols.
              Use -Nr to turn off clipping but retain the plotting of such repeating symbols,  or
              use -Nc to retain clipping but turn off plotting of repeating symbols.

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

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

       -S[symbol][size[u]]
              Plot  symbols  (including  vectors, pie slices, fronts, decorated or quoted lines).
              If present, size is symbol size in the unit set in gmt.conf (unless c, i, or  p  is
              appended).  If  the  symbol  code (see below) is not given it will be read from the
              last column in the input data; this cannot  be  used  in  conjunction  with  binary
              input.   Optionally, append c, i, or p to indicate that the size information in the
              input  data  is  in  units  of  cm,  inch,  or  point,  respectively  [Default   is
              PROJ_LENGTH_UNIT]. Note: if you provide both size and symbol via the input file you
              must use PROJ_LENGTH_UNIT to indicate the unit used for the symbol size  or  append
              the  units  to  the  sizes in the file.  If symbol sizes are expected via the third
              data column then you may convert those values to suitable symbol sizes via  the  -i
              mechanism.

              The  uppercase  symbols  A,  C, D, G, H, I, N, S, T are normalized to have the same
              area as a circle with diameter size, while the size of the corresponding  lowercase
              symbols refers to the diameter of a circumscribed circle.

              You can change symbols by adding the required -S option to any of your multisegment
              headers.

              Choose between these symbol codes:

              -S-    x-dash (-). size is the length of a short horizontal (x-dir) line segment.

              -S+    plus (+). size is diameter of circumscribing circle.

              -Sa    star. size is diameter of circumscribing circle.

              -Sb[size[c|i|p|u]][b[base]]
                     Vertical bar extending from base to y. size is bar width.  Append u if  size
                     is  in  x-units  [Default is plot-distance units].  By default, base = ymin.
                     Append b[base] to change this value. If base is not appended then we read it
                     from the last input data column.

              -SB[size[c|i|p|u]][b[base]]
                     Horizontal  bar  extending  from  base to x. size is bar width.  Append u if
                     size is in y-units [Default is plot-distance units].   By  default,  base  =
                     xmin.  Append  b[base] to change this value. If base is not appended then we
                     read it from the last input data column.

              -Sc    circle. size is diameter of circle.

              -Sd    diamond. size is diameter of circumscribing circle.

              -Se    ellipse.  Direction  (in   degrees   counter-clockwise   from   horizontal),
                     major_axis, and minor_axis must be found in columns 3, 4, and 5.

              -SE    Same  as  -Se,  except  azimuth  (in  degrees east of north) should be given
                     instead of direction. The azimuth will be mapped into an angle based on  the
                     chosen  map  projection (-Se leaves the directions unchanged.)  Furthermore,
                     the axes lengths must be given  in  geographical  instead  of  plot-distance
                     units.  An  exception  occurs for a linear projection in which we assume the
                     ellipse axes are given in the same units as  -R.   For  degenerate  ellipses
                     (circles)  with just the diameter given, use -SE-.  The diameter is excepted
                     to be given in column 3.  Alternatively, append the desired diameter to -SE-
                     and  this fixed diameter is used instead.  For allowable geographical units,
                     see UNITS.

              -Sfgap[/size][+l|+r][+b+c+f+s+t][+ooffset][+p[pen]].
                     Draw a front. Supply distance gap between symbols and symbol size. If gap is
                     negative,  it  is  interpreted to mean the number of symbols along the front
                     instead. If size is missing it is set to 30% of the gap, except when gap  is
                     negative  and size is thus required.  Append +l or +r to plot symbols on the
                     left or right side of the front  [Default  is  centered].  Append  +type  to
                     specify  which  symbol  to  plot:  box,  circle,  fault,  slip, or triangle.
                     [Default is fault]. Slip means  left-lateral  or  right-lateral  strike-slip
                     arrows  (centered  is not an option). The +s modifier optionally accepts the
                     angle used to draw the vector  [20].   Alternatively,  use  +S  which  draws
                     arcuate  arrow  heads.   Append +ooffset to offset the first symbol from the
                     beginning of the front by that amount [0]. The chosen symbol is  drawn  with
                     the  same pen as set for the line (i.e., via -W).  The use an alternate pen,
                     append +ppen.  To skip the outline, just  use  +p.   Note:  By  placing  -Sf
                     options  in  the  segment  header  you  can  change  the  front  types  on a
                     segment-by-segment basis.

              -Sg    octagon. size is diameter of circumscribing circle.

              -Sh    hexagon. size is diameter of circumscribing circle.

              -Si    inverted triangle. size is diameter of circumscribing circle.

              -Sj    Rotated rectangle. Direction (in degrees counter-clockwise from horizontal),
                     x-dimension, and y-dimension must be found in columns 3, 4, and 5.

              -SJ    Same  as  -Sj,  except  azimuth  (in  degrees east of north) should be given
                     instead of direction. The azimuth will be mapped into an angle based on  the
                     chosen  map  projection  (-Sj leaves the directions unchanged.) Furthermore,
                     the dimensions must be given in geographical instead of plot-distance units.
                     For a degenerate rectangle (square) with one dimension given, use -SJ-.  The
                     dimension is excepted to be given in column 3.   Alternatively,  append  the
                     dimension  diameter  to  -SJ-  and this fixed dimension is used instead.  An
                     exception occurs for a linear projection in which we assume  the  dimensions
                     are  given  in  the same units as -R.  For allowable geographical units, see
                     UNITS.

              -Sk    kustom symbol. Append name/size, and we will  look  for  a  definition  file
                     called  name.def  in  (1)  the  current directory or (2) in ~/.gmt or (3) in
                     $GMT_SHAREDIR/custom. The symbol as defined in that file is of size  1.0  by
                     default;  the  appended  size  will  scale symbol accordingly. Users may add
                     their own custom *.def files; see CUSTOM SYMBOLS below.

              -Sl    letter or text string (less than 256  characters).  Give  size,  and  append
                     +tstring  after  the  size.  Note  that  the  size  is  only approximate; no
                     individual scaling is done for  different  characters.  Remember  to  escape
                     special  characters  like  *.  Optionally, you may append +ffont to select a
                     particular font [Default is  FONT_ANNOT_PRIMARY]  and  +jjustify  to  change
                     justification [CM].

              -Sm    math  angle arc, optionally with one or two arrow heads [Default is no arrow
                     heads]. The size is the length of the vector head. Arc width is set  by  -W.
                     The  radius  of  the  arc  and  its  start  and  stop directions (in degrees
                     counter-clockwise from horizontal) must be given in columns 3-5. See  VECTOR
                     ATTRIBUTES for specifying other attributes.

              -SM    Same  as  -Sm  but  switches  to  straight angle symbol if angles subtend 90
                     degrees exactly.

              -Sn    pentagon. size is diameter of circumscribing circle.

              -Sp    point. No size needs to be specified (1 pixel is used).

              -Sq    quoted  line,  i.e.,  lines  with  annotations  such  as  contours.   Append
                     [d|D|f|l|L|n|N|s|S|x|X]info[:labelinfo].  The required argument controls the
                     placement of labels along the quoted lines.  Choose  among  six  controlling
                     algorithms:

                        ddist[c|i|p] or Ddist[d|e|f|k|m|M|n|s]
                               For  lower  case  d,  give distances between labels on the plot in
                               your preferred measurement unit c (cm), i (inch), or  p  (points),
                               while  for upper case D, specify distances in map units and append
                               the unit; choose among e (m),  f  (foot),  k  (km),  M  (mile),  n
                               (nautical  mile) or u (US survey foot), and d (arc degree), m (arc
                               minute), or s (arc second).  [Default is 10c or 4i]. As an option,
                               you  can  append  /fraction  which is used to place the very first
                               label for each contour when the cumulative along-contour  distance
                               equals fraction * dist [0.25].

                        fffile.d
                               Reads the ASCII file ffile.d and places labels at locations in the
                               file that  matches  locations  along  the  quoted  lines.  Inexact
                               matches and points outside the region are skipped.

                        l|Lline1[,line2,...]
                               Give   the   coordinates  of  the  end  points  for  one  or  more
                               comma-separated straight line segments.   Labels  will  be  placed
                               where  these lines intersect the quoted lines.  The format of each
                               line specification is start_lon/start_lat/stop_lon/stop_lat.  Both
                               start_lon/start_lat  and  stop_lon/stop_lat  can  be replaced by a
                               2-character key that uses the  justification  format  employed  in
                               pstext  to  indicate  a  point  on the frame or center of the map,
                               given as [LCR][BMT].  L will interpret the point pairs as defining
                               great circles [Default is straight line].

                        n|Nn_label
                               Specifies  the  number of equidistant labels for quoted lines [1].
                               Upper case N starts labeling exactly at  the  start  of  the  line
                               [Default  centers  them  along the line]. N-1 places one justified
                               label at start, while N+1 places one justified label at the end of
                               quoted  lines. Optionally, append /min_dist[c|i|p] to enforce that
                               a  minimum  distance  separation  between  successive  labels   is
                               enforced.

                        s|Sn_label
                               Same as n|Nn_label but implies that the input data are first to be
                               converted into a series of 2-point line segments before plotting.

                        x|Xxfile.d
                               Reads the multisegment file  xfile.d  and  places  labels  at  the
                               intersections  between  the quoted lines and the lines in xfile.d.
                               X will resample the  lines  first  along  great-circle  arcs.   In
                               addition,  you  may  optionally  append  +rradius[c|i|p]  to set a
                               minimum label separation in the x-y plane [no limitation].

                        The optional labelinfo controls the specifics of the label formatting and
                        consists of a concatenated string made up of any of the following control
                        arguments:

                        +aangle
                               For annotations at a fixed angle, +an for line-normal, or +ap  for
                               line-parallel [Default].

                        +cdx[/dy]
                               Sets  the  clearance  between  label and optional text box. Append
                               c|i|p to specify the unit or % to indicate  a  percentage  of  the
                               label font size [15%].

                        +d     Turns  on  debug  which  will  draw  helper  points  and  lines to
                               illustrate the workings of the quoted line setup.

                        +e     Delay the plotting of the text. This is used to build a clip  path
                               based  on  the  text, then lay down other overlays while that clip
                               path is in effect, then turning of clipping with psclip -Cs  which
                               finally plots the original text.

                        +ffont Sets  the  desired  font [Default FONT_ANNOT_PRIMARY with its size
                               changed to 9p].

                        +g[color]
                               Selects opaque text boxes  [Default  is  transparent];  optionally
                               specify the color [Default is PS_PAGE_COLOR].

                        +jjust Sets  label justification [Default is MC]. Ignored when -SqN|n+|-1
                               is used.

                        +llabel
                               Sets the constant label text.

                        +Lflag Sets the label text according to the specified flag:

                               +Lh Take the label from the current segment header (first scan for
                               an  embedded  -Llabel  option, if not use the first word following
                               the segment flag). For multiple-word labels, enclose entire  label
                               in double quotes.  +Ld Take the Cartesian plot distances along the
                               line  as  the  label;  append  c|i|p  as  the  unit  [Default   is
                               PROJ_LENGTH_UNIT].   +LD  Calculate  actual  map distances; append
                               d|e|f|k|n|M|n|s as the unit [Default is  d(egrees),  unless  label
                               placement was based on map distances along the lines in which case
                               we use the same unit specified for that algorithm]. Requires a map
                               projection  to  be used.  +Lf Use text after the 2nd column in the
                               fixed label location file as the label. Requires the  fixed  label
                               location  setting.   +Lx As +Lh but use the headers in the xfile.d
                               instead.  Requires the crossing file option.

                        +ndx[/dy]
                               Nudges the placement of labels by  the  specified  amount  (append
                               c|i|p  to  specify  the  units).  Increments are considered in the
                               coordinate system defined by the orientation of the line;  use  +N
                               to  force  increments  in  the  plot  x/y  coordinates  system [no
                               nudging]. Not allowed with +v.

                        +o     Selects rounded rectangular text  box  [Default  is  rectangular].
                               Not  applicable  for  curved  text  (+v)  and only makes sense for
                               opaque text boxes.

                        +p[pen]
                               Draws  the  outline  of  text  boxes  [Default  is  no   outline];
                               optionally  specify  pen  for  outline  [Default is width = 0.25p,
                               color = black, style = solid].

                        +rmin_rad
                               Will not place labels where the line's radius of curvature is less
                               than min_rad [Default is 0].

                        +t[file]
                               Saves line label x, y, and text to file [Line_labels.txt].  Use +T
                               to save x, y, angle, text instead.

                        +uunit Appends unit to all line labels. If unit  starts  with  a  leading
                               hyphen (-) then there will be no space between label value and the
                               unit. [Default is no unit].

                        +v     Specifies curved labels following the path  [Default  is  straight
                               labels].

                        +w     Specifies  how  many  (x,y)  points will be used to estimate label
                               angles [Default is 10].

                        +x[first,last]
                               Append the suffices first and last to  the  corresponding  labels.
                               This  modifier is only available when -SqN2 is in effect.  Used to
                               annotate the start and end of  a  line  (e.g.,  a  cross-section),
                               append  two  text  strings separated by comma [Default just adds a
                               prime to the second label].

                        +=prefix
                               Prepends prefix to all  line  labels.  If  prefix  starts  with  a
                               leading hyphen (-) then there will be no space between label value
                               and the prefix. [Default is no prefix].

                     Note: By placing -Sq options in the segment header you can change the quoted
                     text attributes on a segment-by-segment basis.

              -Sr    rectangle.  No  size needs to be specified, but the x- and y-dimensions must
                     be found in columns 3 and 4.

              -SR    Rounded  rectangle.  No  size  needs  to  be  specified,  but  the  x-   and
                     y-dimensions and corner radius must be found in columns 3, 4, and 5.

              -Ss    square. size is diameter of circumscribing circle.

              -St    triangle. size is diameter of circumscribing circle.

              -Sv    vector.  Direction (in degrees counter-clockwise from horizontal) and length
                     must be found in columns 3  and  4,  and  size,  if  not  specified  on  the
                     command-line, should be  present in column 5.  The size is the length of the
                     vector head.  Vector  width  is  set  by  -W.   See  VECTOR  ATTRIBUTES  for
                     specifying other attributes.

              -SV    Same  as  -Sv,  except  azimuth  (in  degrees east of north) should be given
                     instead of direction. The azimuth will be mapped into an angle based on  the
                     chosen  map  projection  (-Sv  leaves  the directions unchanged.) See VECTOR
                     ATTRIBUTES for specifying other attributes.

              -Sw    pie wedge. Start and stop  directions  (in  degrees  counter-clockwise  from
                     horizontal)  for  pie  slice must be found in columns 3 and 4.  Append +a to
                     just draw the arc line or +r to just draw the radial lines.

              -SW    Same as -Sw, except azimuths (in degrees east  of  north)  should  be  given
                     instead of the two directions. The azimuths will be mapped into angles based
                     on the chosen map projection (-Sw leaves  the  directions  unchanged.)   For
                     geo-wedges,  specify  size as a radial geographical distance.  For allowable
                     geographical units, see UNITS.  Append +a to just draw the arc or +r to just
                     draw the radial lines.

              -Sx    cross (x). size is diameter of circumscribing circle.

              -Sy    y-dash (|). size is the length of a short vertical (y-dir) line segment.

              -S=    geovector. Azimuth (in degrees east from north) and geographical length must
                     be found in columns 3 and 4. The size is the  length  of  the  vector  head.
                     Vector  width is set by -W. See VECTOR ATTRIBUTES for specifying attributes.
                     Note: Geovector stems are drawn  as  thin  filled  polygons  and  hence  pen
                     attributes  like  dashed  and  dotted  are  not  available.   For  allowable
                     geographical units, see UNITS.

              -S~    decorated   line,   i.e.,   lines   with   symbols   along   them.    Append
                     [d|D|f|l|L|n|N|s|S|x|X]info[:symbolinfo].   The  required  argument controls
                     the placement of  symbols  along  the  decorated  lines.  Choose  among  six
                     controlling algorithms:

                        ddist[c|i|p] or Ddist[d|e|f|k|m|M|n|s]
                               For  lower  case  d, give distances between symbols on the plot in
                               your preferred measurement unit c (cm), i (inch), or  p  (points),
                               while  for upper case D, specify distances in map units and append
                               the unit; choose among e (m),  f  (foot),  k  (km),  M  (mile),  n
                               (nautical  mile) or u (US survey foot), and d (arc degree), m (arc
                               minute), or s (arc second).  [Default is 10c or 4i]. As an option,
                               you  can  append  /fraction  which is used to place the very first
                               symbol for each  line  when  the  cumulative  along-line  distance
                               equals fraction * dist [0.25].

                        fffile.d
                               Reads  the  ASCII  file ffile.d and places symbols at locations in
                               the file that matches locations along the decorated lines. Inexact
                               matches and points outside the region are skipped.

                        l|Lline1[,line2,...]
                               Give   the   coordinates  of  the  end  points  for  one  or  more
                               comma-separated straight line segments.  Symbols  will  be  placed
                               where  these  lines  intersect the decorated lines.  The format of
                               each line specification is  start_lon/start_lat/stop_lon/stop_lat.
                               Both  start_lon/start_lat and stop_lon/stop_lat can be replaced by
                               a 2-character key that uses the justification format  employed  in
                               pstext  to  indicate  a  point  on the frame or center of the map,
                               given as [LCR][BMT].  L will interpret the point pairs as defining
                               great circles [Default is straight line].

                        n|Nn_symbol
                               Specifies  the  number  of equidistant symbols for decorated lines
                               [1]. Upper case N starts placing symbols exactly at the  start  of
                               the  line  [Default  centers  them along the line]. N-1 places one
                               symbol at start, while  N+1  places  one  symbol  at  the  end  of
                               decorated  lines.  Optionally,  append /min_dist[c|i|p] to enforce
                               that a minimum distance separation between successive  symbols  is
                               enforced.

                        s|Sn_symbol
                               Same  as  n|Nn_symbol but implies that the input data are first to
                               be converted  into  a  series  of  2-point  line  segments  before
                               plotting.

                        x|Xxfile.d
                               Reads  the  multisegment  file  xfile.d  and places symbols at the
                               intersections  between  the  decorated  lines  and  the  lines  in
                               xfile.d.  X will resample the lines first along great-circle arcs.

                        The  optional  symbolinfo  controls the specifics of the symbol selection
                        and formatting and consists of a concatenated string made up  of  any  of
                        the following control arguments:

                        +aangle
                               For  symbols  at  a  fixed  angle, +an for line-normal, or +ap for
                               line-parallel [Default].

                        +d     Turns on  debug  which  will  draw  helper  points  and  lines  to
                               illustrate the workings of the decorated line setup.

                        +g[fill]
                               Sets the symbol fill [no fill].

                        +ndx[/dy]
                               Nudges  the  placement  of symbols by the specified amount (append
                               c|i|p to specify the units).  Increments  are  considered  in  the
                               coordinate  system  defined by the orientation of the line; use +N
                               to force  increments  in  the  plot  x/y  coordinates  system  [no
                               nudging].

                        +p[pen]
                               Draws  the  outline of symbols [Default is no outline]; optionally
                               specify pen for outline [Default is width = 0.25p, color =  black,
                               style = solid].

                        +s<symbol><size>
                               Specifies the code and size of the decorative symbol.

                        +w     Specifies  how  many  (x,y) points will be used to estimate symbol
                               angles [Default is 10].

                     Note: By placing -S~ options in  the  segment  header  you  can  change  the
                     decorated lines on a segment-by-segment basis.

       -T     Ignore  all  input  files, including standard input. This is the same as specifying
              /dev/null (or NUL for Windows users) as input file.  Use this to activate only  the
              options that are not related to plotting of lines or symbols, such as psxy -R -J -O
              -T to terminate a sequence of GMT plotting commands without producing any  plotting
              output.

       -U[[just]/dx/dy/][c|label] (more ...)
              Draw GMT time stamp logo on plot.

       -V[level] (more ...)
              Select verbosity level [c].

       -W[pen][attr] (more ...)
              Set  pen attributes for lines or the outline of symbols [Defaults: width = default,
              color = black, style = solid]. If the modifier +cl is appended then  the  color  of
              the  line are taken from the CPT (see -C). If instead modifier +cf is appended then
              the color from the cpt file is applied to  symbol  fill.   Use  just  +c  for  both
              effects.   You  can  also  append  one or more additional line attribute modifiers:
              +ooffsetu will start and stop drawing the line the given distance offsets from  the
              end point.  Append unit u from c|i|p to indicate plot distance on the map or append
              map distance units instead (see below) [Cartesian distances]; +s will draw the line
              using a PostScript Bezier spline [linear spline]; +vvspecs will place a vector head
              at the ends of the lines.  You can use +vb and +ve to specify separate vector specs
              at  each  end  [shared  specs].   Because  +v may take additional modifiers it must
              necessarily be given  at  the  end  of  the  pen  specification.   See  the  Vector
              Attributes for more information.

       -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 the required number of columns given the
              chosen settings].

       -acol=name[...] (more ...)
              Set aspatial column associations col=name.

       -dinodata (more ...)
              Replace input columns that equal nodata with NaN.

       -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
              Only accept data records that match the given pattern.

       -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. The -g option is ignored if -S is set.

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

       -icols[+l][+sscale][+ooffset][,...] (more ...)
              Select input columns and transformations (0 is first column).

       -:[i|o] (more ...)
              Swap 1st and 2nd column on input and/or output.

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

       -^ or just -
              Print a short message about the syntax of the command, then exits (NOTE: on Windows
              just use -).

       -+ 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  all  options,
              then exits.

UNITS

       For  map  distance  unit,  append  unit  d for arc degree, m for arc minute, and s for arc
       second, or e for meter [Default], f for foot, k for km, M for statute mile, n for nautical
       mile,  and  u  for  US survey foot. By default we compute such distances using a spherical
       approximation with great circles. Prepend - to a distance (or the unit is no  distance  is
       given)  to  perform  "Flat Earth" calculations (quicker but less accurate) or prepend + to
       perform exact geodesic calculations (slower but more accurate).

VECTOR ATTRIBUTES

       Several modifiers may be appended to the vector-producing options to specify the placement
       of  vector heads, their shapes, and the justification of the vector. Below, left and right
       refers to the side of the vector line when viewed from the start point to the end point of
       the segment:
          +aangle sets the angle of the vector head apex [30].

          +b places a vector head at the beginning of the vector path [none].  Optionally, append
          t for a terminal line, c for a circle, a for arrow [Default], i for tail, A  for  plain
          arrow, and I for plain tail.  Further append l|r to only draw the left or right side of
          this head [both sides].

          +e places a vector head at the end of the vector path [none].  Optionally, append t for
          a  terminal line, c for a circle, a for arrow [Default], i for tail, A for plain arrow,
          and I for plain tail.  Further append l|r to only draw the left or right side  of  this
          head [both sides].

          +g-|fill  turns  off vector head fill (if -) or sets the vector head fill [Default fill
          is used, which may be no fill].

          +hshape sets the shape of the vector  head  (range  -2/2).  Default  is  controlled  by
          MAP_VECTOR_SHAPE [0].

          +l draws half-arrows, using only the left side of specified heads [both sides].

          +m  places  a  vector  head at the mid-point the vector path [none].  Append f or r for
          forward or reverse direction of the vector  [forward].   Optionally,  append  t  for  a
          terminal  line,  c  for a circle, or a for arrow head [Default].  Further append l|r to
          only draw the left or right side of this head [both sides].  Cannot be combined with +b
          or +e.

          +nnorm scales down vector attributes (pen thickness, head size) with decreasing length,
          where vectors shorter than norm will have their attributes scaled by length/norm [arrow
          attributes remains invariant to length].

          +oplon/plat specifies the oblique pole for the great or small circles.  Only needed for
          great circles if +q is given.

          +p[-][pen] sets the vector pen attributes. If pen has a leading - then the head outline
          is not drawn. [Default pen is used, and head outline is drawn]

          +q  means  the  input  angle,  length data instead represent the start and stop opening
          angles of the arc segment relative to the given point.

          +r draws half-arrows, using only the right side of specified heads [both sides].

          +t[b|e]trim will shift the beginning or end point (or both) along the vector segment by
          the  given  trim; append suitable unit. If the modifiers b|e are not used then trim may
          be two values separated by a slash, which is used to specify different  trims  for  the
          two ends.  Positive trims will shorted the vector while negative trims will lengthen it
          [no trim].

       In addition, all but circular vectors may take these modifiers:
          +jjust determines how the input x,y point relates to the vector. Choose from  beginning
          [default], end, or center.

          +s  means  the  input  angle, length are instead the x, y coordinates of the vector end
          point.

       Finally, Cartesian vectors may take these modifiers:
          +zscale[unit] expects input dx,dy vector components and uses the scale  to  convert  to
          polar coordinates with length in given unit.

EXAMPLES

       To plot solid red circles (diameter = 0.2 cm) at the positions listed in the file DSDP.txt
       on a Mercator map at 0.3 cm/degree of the area 100E to 160E, 20S to  30N,  with  automatic
       tick-marks and gridlines, use

              gmt psxy DSDP.txt -R100/160/-20/30 -Jm0.3c -Sc0.2c -Gred -Bafg > map.ps

       To plot the xyz values in the file quakes.xyzm as circles with size given by the magnitude
       in the 4th column and color based on the depth in the third using the  CPT  rgb.cpt  on  a
       linear map, use

              gmt psxy quakes.xyzm -R0/1000/0/1000 -JX6i -Sc -Crgb -B200 > map.ps

       To  plot  the file trench.txt on a Mercator map, with white triangles with sides 0.25 inch
       on the left side of the line, spaced every 0.8 inch, use

              gmt psxy trench.txt -R150/200/20/50 -Jm0.15i -Sf0.8i/0.1i+l+t -Gwhite -W -B10 > map.ps

       To plot the data in the file misc.d as symbols determined by the code in the last  column,
       and  with  size  given  by  the  magnitude in the 4th column, and color based on the third
       column via the CPT chrome on a linear map, use

              gmt psxy misc.d -R0/100/-50/100 -JX6i -S -Cchrome -B20 > map.ps

       If you need to place vectors on a plot you can choose among  straight  Cartesian  vectors,
       math  circular  vectors,  or geo-vectors (these form small or great circles on the Earth).
       These can have optional heads at either end, and heads may be  the  traditional  arrow,  a
       circle,  or  a  terminal  cross-line.   To  place a few vectors with a circle at the start
       location and an arrow head at the end, try

              gmt psxy -R0/50/-50/50 -JX6i -Sv0.15i+bc+ea -Gyellow -W0.5p -Baf << EOF > map.ps
              10 10 45 2i
              30 -20 0 1.5i
              EOF

       To plot vectors (red vector heads, solid stem) from the file data.txt that contains record
       of  the  form  lon, lat, dx, dy, where dx, dy are the Cartesian vector components given in
       user units, and these user units should be converted to cm given the scale 3.60, try

              gmt psxy -R20/40/-20/0 -JM6i -Sv0.15i+e+z3.6c -Gred -W0.25p -Baf data.txt > map.ps

SEGMENT HEADER PARSING

       Segment header records may contain one of more of the following options:

       -Gfill Use the new fill and turn filling on

       -G-    Turn filling off

       -G     Revert to default fill (none if not set on command line)

       -Wpen  Use the new pen and turn outline on

       -W     Revert to default pen MAP_DEFAULT_PEN (if not set on command line)

       -W-    Turn outline off

       -Zzval Obtain fill via cpt lookup using z-value zval

       -ZNaN  Get the NaN color from the CPT

CUSTOM SYMBOLS

       psxy allows users to define and plot their own custom symbols. This is  done  by  encoding
       the  symbol  using our custom symbol macro code described in Appendix N. Put all the macro
       codes for your new symbol in a file whose extension must be .def; you may then address the
       symbol  without  giving  the  extension  (e.g.,  the  symbol  file  tsunami.def is used by
       specifying -Sktsunami/size. The definition file  can  contain  any  number  of  plot  code
       records,  as  well  as blank lines and comment lines (starting with #). psxy will look for
       the definition files in (1) the current directory, (2) the ~/.gmt directory, and  (3)  the
       $GMT_SHAREDIR/custom  directory,  in  that  order.  Freeform polygons (made up of straight
       line segments and arcs of circles) can be designed - these polygons  can  be  painted  and
       filled  with  a  pattern.  Other standard geometric symbols can also be used. See Appendix
       App-custom_symbols for macro definitions.

POLAR CAPS

       psxy will automatically determine if a closed polygon is  containing  a  geographic  pole,
       i.e.,  being  a  polar  cap.   Such  polygons requires special treatment under the hood to
       ensure proper filling.  Many tools such as GIS packages  are  unable  to  handle  polygons
       covering  a  pole and some cannot handle polygons crossing the Dateline.  They work around
       this problem by splitting polygons into a west and east polygon  or  inserting  artificial
       helper  lines  that  makes  a  cut  into the pole and back.  Such doctored polygons may be
       misrepresented in GMT.

SEE ALSO

       gmt, gmt.conf, gmtcolors, psbasemap, psxyz

COPYRIGHT

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