manpagez: man pages & more
man psxy(1)
Home | html | info | man
psxy(1)                               GMT                              psxy(1)




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  speci-
       fied 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 a|)
              Select map projection.

       -Rxmin/xmax/ymin/ymax[+r][+uunit] (more a|)
              Specify the region of interest.

       For perspective view p, optionally append /zmin/zmax. (more a|)


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.  Alterna-
              tively, 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  paral-
              lels,  for example).  For Cartesian data, points are simply con-
              nected, 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 a|)
              Set map boundary frame and axes attributes.

       -Ccpt  Give  a  CPT  or  specify -Ccolor1,color2[,color3,a|] 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 con-
              trol 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 asymmetri-
              cal  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   abox-and-whiskera  (or
              astem-and-leafa) symbols. The x (or y) coordinate is then  taken
              as  the median value, and four more columns are expected to con-
              tain the minimum (0% quantile), the 25% quantile, the 75%  quan-
              tile, 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
              abox-and-whiskera  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  coor-
              dinates  of a refpoint which will serve as a fixed external ref-
              erence 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 a|)
              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  col-
              umn  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  out-
              line].

       -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 a|)
              Append to existing PostScript plot.

       -P (more a|)
              Select aPortraita 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 col-
              umn  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 diame-
              ter 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 (cir-
                     cles) with just the diameter given, use -SE-.  The diame-
                     ter  is excepted to be given in column 3.  Alternatively,
                     append the desired diameter to -SE- and this fixed diame-
                     ter  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 sym-
                     bol  to  plot:  box,  circle,  fault,  slip, or triangle.
                     [Default is fault]. Slip means left-lateral or right-lat-
                     eral  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 plac-
                     ing  -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-clock-
                     wise 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  pro-
                     jection  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 direc-
                     tory 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 col-
                     umns 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  con-
                     tours.   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,a|]
                               Give the coordinates of the end points for  one
                               or more comma-separated straight line segments.
                               Labels will be placed where these lines  inter-
                               sect 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  cen-
                               ters  them along the line]. N-1 places one jus-
                               tified 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 suc-
                               cessive 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  resam-
                               ple  the  lines  first along great-circle arcs.
                               In addition, you may  optionally  append  +rra-
                               dius[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_PRI-
                               MARY with its size changed to 9p].

                        +g[color]
                               Selects opaque text boxes [Default is transpar-
                               ent];  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 speci-
                               fied for that algorithm]. Requires a  map  pro-
                               jection to be used.  +Lf Use text after the 2nd
                               column in the fixed label location file as  the
                               label.  Requires  the fixed label location set-
                               ting.  +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  lineas  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 cor-
                               responding  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 sepa-
                               rated 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  seg-
                     ment-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 hor-
                     izontal) 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  vec-
                     tor  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 geo-
                     graphical 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 algo-
                     rithms:

                        ddist[c|i|p] or Ddist[d|e|f|k|m|M|n|s]
                               For lower case d, give distances  between  sym-
                               bols  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,a|]
                               Give the coordinates of the end points for  one
                               or more comma-separated straight line segments.
                               Symbols will be placed where these lines inter-
                               sect  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 plac-
                               ing 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 suc-
                               cessive 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 deco-
                               rated 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 con-
                        catenated string made up of any of the following  con-
                        trol arguments:

                        +aangle
                               For symbols at a fixed angle, +an for line-nor-
                               mal, 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  speci-
                               fied   amount  (append  c|i|p  to  specify  the
                               units). Increments are considered in the  coor-
                               dinate 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 pro-
              ducing any plotting output.

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

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

       -W[pen][attr] (more a|)
              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 addi-
              tional  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  dis-
              tances];  +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 vec-
              tor specs at each end [shared specs].  Because +v may take addi-
              tional  modifiers it must necessarily be given at the end of the
              pen specification.  See the Vector Attributes for more  informa-
              tion.

       -X[a|c|f|r][x-shift[u]]

       -Y[a|c|f|r][y-shift[u]] (more a|)
              Shift plot origin.

       -bi[ncols][t] (more a|)
              Select  native  binary input. [Default is the required number of
              columns given the chosen settings].

       -acol=name[^<i>a|] (more a|)
              Set aspatial column associations col=name.

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

       -e[~]^<i>apattern^<i>a | -e[~]/regexp/[i] (more a|)
              Only accept data records that match the given pattern.

       -f[i|o]colinfo (more a|)
              Specify data types of input and/or output columns.

       -g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more a|)
              Determine data gaps and line breaks. The -g option is ignored if
              -S is set.

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

       -icols[+l][+sscale][+ooffset][,^<i>a|] (more a|)
              Select input columns and transformations (0 is first column).

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

       -p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more a|)
              Select perspective view.

       -t[transp] (more a|)
              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  explana-
              tion  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 aFlat Eartha 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 justifica-
       tion 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  [for-
          ward].  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 cir-
          cles.  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 ter-
       minal 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 num-
       ber 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  spe-
       cial  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(1), gmt.conf(5), gmtcolors(5), psbasemap(1), psxyz(1)


COPYRIGHT

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



5.4.2                            Jun 24, 2017                          psxy(1)

gmt5 5.4.2 - Generated Thu Jun 29 16:04:26 CDT 2017
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.