1PSXY(1)                               GMT                              PSXY(1)
2
3
4

NAME

6       psxy - Plot lines, polygons, and symbols on maps
7

SYNOPSIS

9       psxy [ table ]  -Jparameters
10        -Rwest/east/south/north[/zmin/zmax][+r]    [     -A[m|p|x|y]    ]    [
11       -B[p|s]parameters    ]    [     -Ccpt    ]    [     -Ddx/dy     ]     [
12       -E[x|y|X|Y][+a][+cl|f][+n][+wcap][+ppen]  ]  [  -F[c|n|r][refpoint] ] [
13       -Gfill ] [  -Iintens ] [  -K ] [  -L[+b|d|D][+xl|r|x0][+yl|r|y0][+ppen]
14       ]  [   -N[c|r]  ]  [   -O  ]  [  -P ] [  -S[symbol][size[u] ] [  -T ] [
15       -U[stamp] ] [  -V[level]  ]  [   -W[pen][attr]  ]  [   -Xx_offset  ]  [
16       -Yy_offset  ]  [  -aflags  ] [ -bibinary ] [ -dinodata ] [ -eregexp ] [
17       -fflags ] [ -ggaps ] [ -hheaders ] [ -iflags ] [ -pflags ] [ -ttransp ]
18       [ -:[i|o] ]
19
20       Note:  No  space  is allowed between the option flag and the associated
21       arguments.
22

DESCRIPTION

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

REQUIRED ARGUMENTS

38       -Jparameters (more ...)
39              Select map projection.
40
41       -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
42              Specify the region of interest.
43
44       For perspective view p, optionally append /zmin/zmax. (more ...)
45

OPTIONAL ARGUMENTS

47       table  One  or  more ASCII (or binary, see -bi[ncols][type]) data table
48              file(s) holding a number of data columns. If no tables are given
49              then  we  read  from  standard input. Use -T to ignore all input
50              files, including standard input (see below).
51
52       -A[m|p|x|y]
53              By default, geographic line segments are drawn as  great  circle
54              arcs. To draw them as straight lines, use the -A flag.  Alterna‐
55              tively, add m to draw the line by first  following  a  meridian,
56              then a parallel. Or append p to start following a parallel, then
57              a meridian. (This can be practical to draw a line  along  paral‐
58              lels,  for example).  For Cartesian data, points are simply con‐
59              nected, unless you append x or y to draw stair-case curves  that
60              whose first move is along x or y, respectively.
61
62       -B[p|s]parameters (more ...)
63              Set map boundary frame and axes attributes.
64
65       -Ccpt  Give  a  CPT or specify -Ccolor1,color2[,color3,...]  to build a
66              linear continuous CPT from those colors automatically.  In  this
67              case  colorn  can  be  a r/g/b triplet, a color name, or an HTML
68              hexadecimal color (e.g. #aabbcc ).  If -S  is  set,  let  symbol
69              fill  color  be  determined  by the z-value in the third column.
70              Additional fields are shifted over by one column (optional  size
71              would  be  4th  rather  than 3rd field, etc.). If -S is not set,
72              then psxy expects the user to supply a multisegment  file  where
73              each  segment  header contains a -Zval string. The val will con‐
74              trol the color of the line or polygon (if -L  is  set)  via  the
75              CPT.
76
77       -Ddx/dy
78              Offset  the  plot  symbol or line locations by the given amounts
79              dx/dy [Default is no offset]. If dy is not given it is set equal
80              to dx.
81
82       -E[x|y|X|Y][+a][+cl|f][+n][+wcap][+ppen]
83              Draw symmetrical error bars. Append x and/or y to indicate which
84              bars you want to draw (Default is both x and y). The x and/or  y
85              errors  must  be  stored in the columns after the (x,y) pair [or
86              (x,y,z) triplet]. If +a is appended then we will draw asymmetri‐
87              cal  error  bars;  these requires two rather than one extra data
88              column, with the low and high value.  If upper case X  and/or  Y
89              are   used   we   will   instead   draw   "box-and-whisker"  (or
90              "stem-and-leaf") symbols. The x (or y) coordinate is then  taken
91              as  the median value, and four more columns are expected to con‐
92              tain the minimum (0% quantile), the 25% quantile, the 75%  quan‐
93              tile, and the maximum (100% quantile) values. The 25-75% box may
94              be filled by using -G. If +n is appended the we draw  a  notched
95              "box-and-whisker"  symbol  where  the  notch  width reflects the
96              uncertainty in the median. This symbol requires a 5th extra data
97              column to contain the number of points in the distribution.  The
98              +w modifier sets the cap width that indicates the length of  the
99              end-cap  on  the  error bars [7p]. Pen attributes for error bars
100              may also be set via +ppen.  [Defaults: width = default, color  =
101              black,  style  =  solid]. When -C is used we can control how the
102              look-up color is applied to our symbol.  Append +cf to use it to
103              fill the symbol, while +cl will just set the error pen color and
104              turn off symbol fill.  Giving +c will set both color items.
105
106       -F[c|n|r][a|f|s|r|refpoint]
107              Alter the way points are connected (by specifying a scheme)  and
108              data  are grouped (by specifying a method).  Append one of three
109              line connection schemes: c: Draw continuous  line  segments  for
110              each  group  [Default].   r: Draw line segments from a reference
111              point reset for each group.  n: Draw networks of  line  segments
112              between all points in each group.  Optionally, append the one of
113              four segmentation methods to define the  group:  a:  Ignore  all
114              segment  headers, i.e., let all points belong to a single group,
115              and set group reference point to the very  first  point  of  the
116              first  file.   f:  Consider all data in each file to be a single
117              separate group and reset the group reference point to the  first
118              point  of  each  group.   s: Segment headers are honored so each
119              segment is a group; the group reference point is  reset  to  the
120              first  point  of each incoming segment [Default].  r: Same as s,
121              but the group reference point is reset after each record to  the
122              previous  point  (this  method  is  only  available with the -Fr
123              scheme).  Instead of the codes a|f|s|r you may append the  coor‐
124              dinates  of a refpoint which will serve as a fixed external ref‐
125              erence point for all groups.
126
127       -Gfill Select color or pattern  for  filling  of  symbols  or  polygons
128              [Default  is no fill].  Note that psxy will search for -G and -W
129              strings in all the segment headers and let any values thus found
130              over-ride the command line settings.
131
132       -Iintens
133              Use the supplied intens value (nominally in the -1 to + 1 range)
134              to modulate the fill color by simulating illumination [none].
135
136       -K (more ...)
137              Do not finalize the PostScript plot.
138
139       -L[+b|d|D][+xl|r|x0][+yl|r|y0][+ppen]
140              Force closed polygons.  Alternatively, append modifiers to build
141              a  polygon  from a line segment.  Append +d to build symmetrical
142              envelope around y(x) using deviations dy(x) given in extra  col‐
143              umn  3.   Append  +D  to build asymmetrical envelope around y(x)
144              using deviations dy1(x)  and  dy2(x)  from  extra  columns  3-4.
145              Append  +b  to  build  asymmetrical  envelope  around y(x) using
146              bounds yl(x) and yh(x) from extra columns 3-4.  Append  +xl|r|x0
147              to connect first and last point to anchor points at either xmin,
148              xmax, or x0, or append +yb|t|y0 to connect first and last  point
149              to  anchor  points  at either ymin, ymax, or y0.  Polygon may be
150              painted (-G) and optionally outlined by adding  +ppen  [no  out‐
151              line].
152
153       -N[c|r]
154              Do  NOT clip symbols that fall outside map border [Default plots
155              points whose coordinates are  strictly  inside  the  map  border
156              only]. The option does not apply to lines and polygons which are
157              always clipped to the map region. For  periodic  (360-longitude)
158              maps  we must plot all symbols twice in case they are clipped by
159              the repeating boundary. The -N will turn off  clipping  and  not
160              plot repeating symbols.  Use -Nr to turn off clipping but retain
161              the plotting of such repeating symbols, or  use  -Nc  to  retain
162              clipping but turn off plotting of repeating symbols.
163
164       -O (more ...)
165              Append to existing PostScript plot.
166
167       -P (more ...)
168              Select "Portrait" plot orientation.
169
170       -S[symbol][size[u]]
171              Plot  symbols  (including vectors, pie slices, fronts, decorated
172              or quoted lines).  If present, size is symbol size in  the  unit
173              set  in  gmt.conf (unless c, i, or p is appended). If the symbol
174              code (see below) is not given it will be read from the last col‐
175              umn  in  the input data; this cannot be used in conjunction with
176              binary input.  Optionally, append c, i, or p  to  indicate  that
177              the  size information in the input data is in units of cm, inch,
178              or point, respectively [Default is PROJ_LENGTH_UNIT].  Note:  if
179              you provide both size and symbol via the input file you must use
180              PROJ_LENGTH_UNIT to indicate the unit used for the  symbol  size
181              or  append  the units to the sizes in the file.  If symbol sizes
182              are expected via the third data  column  then  you  may  convert
183              those values to suitable symbol sizes via the -i mechanism.
184
185              The  uppercase  symbols A, C, D, G, H, I, N, S, T are normalized
186              to have the same area as a circle with diameter size, while  the
187              size of the corresponding lowercase symbols refers to the diame‐
188              ter of a circumscribed circle.
189
190              You can change symbols by adding the required -S option  to  any
191              of your multisegment headers.
192
193              Choose between these symbol codes:
194
195              -S-    x-dash  (-).  size  is  the  length of a short horizontal
196                     (x-dir) line segment.
197
198              -S+    plus (+). size is diameter of circumscribing circle.
199
200              -Sa    star. size is diameter of circumscribing circle.
201
202              -Sb[size[c|i|p|u]][b[base]]
203                     Vertical bar extending from base to y. size is bar width.
204                     Append  u if size is in x-units [Default is plot-distance
205                     units].  By default,  base  =  ymin.  Append  b[base]  to
206                     change  this  value. If base is not appended then we read
207                     it from the last input data column.
208
209              -SB[size[c|i|p|u]][b[base]]
210                     Horizontal bar extending from base  to  x.  size  is  bar
211                     width.   Append  u  if  size  is  in  y-units [Default is
212                     plot-distance units].  By default, base  =  xmin.  Append
213                     b[base]  to  change  this  value. If base is not appended
214                     then we read it from the last input data column.
215
216              -Sc    circle. size is diameter of circle.
217
218              -Sd    diamond. size is diameter of circumscribing circle.
219
220              -Se    ellipse. Direction  (in  degrees  counter-clockwise  from
221                     horizontal),  major_axis, and minor_axis must be found in
222                     columns 3, 4, and 5.
223
224              -SE    Same as -Se, except azimuth (in degrees  east  of  north)
225                     should be given instead of direction. The azimuth will be
226                     mapped into an angle based on the chosen  map  projection
227                     (-Se  leaves the directions unchanged.)  Furthermore, the
228                     axes lengths must be given  in  geographical  instead  of
229                     plot-distance  units.  An  exception  occurs for a linear
230                     projection in which we assume the ellipse axes are  given
231                     in  the  same units as -R.  For degenerate ellipses (cir‐
232                     cles) with just the diameter given, use -SE-.  The diame‐
233                     ter  is excepted to be given in column 3.  Alternatively,
234                     append the desired diameter to -SE- and this fixed diame‐
235                     ter  is  used instead.  For allowable geographical units,
236                     see UNITS.
237
238              -Sfgap[/size][+l|+r][+b+c+f+s+t][+ooffset][+p[pen]].
239                     Draw a front. Supply distance  gap  between  symbols  and
240                     symbol  size.  If  gap  is negative, it is interpreted to
241                     mean the number of symbols along the  front  instead.  If
242                     size  is missing it is set to 30% of the gap, except when
243                     gap is negative and size is thus required.  Append +l  or
244                     +r to plot symbols on the left or right side of the front
245                     [Default is centered]. Append +type to specify which sym‐
246                     bol  to  plot:  box,  circle,  fault,  slip, or triangle.
247                     [Default is fault]. Slip means left-lateral or right-lat‐
248                     eral  strike-slip arrows (centered is not an option). The
249                     +s modifier optionally accepts the angle used to draw the
250                     vector  [20].   Alternatively, use +S which draws arcuate
251                     arrow heads.  Append +ooffset to offset the first  symbol
252                     from  the  beginning of the front by that amount [0]. The
253                     chosen symbol is drawn with the same pen as set  for  the
254                     line  (i.e.,  via  -W).  The use an alternate pen, append
255                     +ppen.  To skip the outline, just use +p.  Note: By plac‐
256                     ing  -Sf options in the segment header you can change the
257                     front types on a segment-by-segment basis.
258
259              -Sg    octagon. size is diameter of circumscribing circle.
260
261              -Sh    hexagon. size is diameter of circumscribing circle.
262
263              -Si    inverted triangle. size  is  diameter  of  circumscribing
264                     circle.
265
266              -Sj    Rotated  rectangle.  Direction (in degrees counter-clock‐
267                     wise from horizontal), x-dimension, and y-dimension  must
268                     be found in columns 3, 4, and 5.
269
270              -SJ    Same  as  -Sj,  except azimuth (in degrees east of north)
271                     should be given instead of direction. The azimuth will be
272                     mapped  into  an angle based on the chosen map projection
273                     (-Sj leaves the directions unchanged.)  Furthermore,  the
274                     dimensions  must  be  given  in  geographical  instead of
275                     plot-distance units.  For a degenerate rectangle (square)
276                     with  one  dimension  given,  use -SJ-.  The dimension is
277                     excepted to be given in column 3.  Alternatively,  append
278                     the  dimension  diameter to -SJ- and this fixed dimension
279                     is used instead.  An exception occurs for a  linear  pro‐
280                     jection  in  which  we assume the dimensions are given in
281                     the same units as -R.  For allowable geographical  units,
282                     see UNITS.
283
284              -Sk    kustom  symbol.  Append name/size, and we will look for a
285                     definition file called name.def in (1) the current direc‐
286                     tory or (2) in ~/.gmt or (3) in $GMT_SHAREDIR/custom. The
287                     symbol as defined in that file is of size 1.0 by default;
288                     the  appended  size  will scale symbol accordingly. Users
289                     may add their own custom *.def files; see CUSTOM  SYMBOLS
290                     below.
291
292              -Sl    letter  or  text  string (less than 256 characters). Give
293                     size, and append +tstring after the size. Note  that  the
294                     size  is  only approximate; no individual scaling is done
295                     for different  characters.  Remember  to  escape  special
296                     characters  like  *. Optionally, you may append +ffont to
297                     select a particular font [Default is  FONT_ANNOT_PRIMARY]
298                     and +jjustify to change justification [CM].
299
300              -Sm    math  angle  arc,  optionally with one or two arrow heads
301                     [Default is no arrow heads]. The size is  the  length  of
302                     the  vector  head.  Arc width is set by -W. The radius of
303                     the arc and its start and  stop  directions  (in  degrees
304                     counter-clockwise  from horizontal) must be given in col‐
305                     umns 3-5. See  VECTOR  ATTRIBUTES  for  specifying  other
306                     attributes.
307
308              -SM    Same  as  -Sm  but  switches  to straight angle symbol if
309                     angles subtend 90 degrees exactly.
310
311              -Sn    pentagon. size is diameter of circumscribing circle.
312
313              -Sp    point. No size needs to be specified (1 pixel is used).
314
315              -Sq    quoted line, i.e., lines with annotations  such  as  con‐
316                     tours.   Append  [d|D|f|l|L|n|N|s|S|x|X]info[:labelinfo].
317                     The required argument controls the  placement  of  labels
318                     along  the  quoted  lines.  Choose  among six controlling
319                     algorithms:
320
321                        ddist[c|i|p] or Ddist[d|e|f|k|m|M|n|s]
322                               For lower case d, give distances between labels
323                               on  the plot in your preferred measurement unit
324                               c (cm), i (inch),  or  p  (points),  while  for
325                               upper  case  D,  specify distances in map units
326                               and append the unit;  choose  among  e  (m),  f
327                               (foot),  k (km), M (mile), n (nautical mile) or
328                               u (US survey foot), and d (arc degree), m  (arc
329                               minute), or s (arc second).  [Default is 10c or
330                               4i]. As an option,  you  can  append  /fraction
331                               which is used to place the very first label for
332                               each contour when the cumulative  along-contour
333                               distance equals fraction * dist [0.25].
334
335                        fffile.d
336                               Reads  the ASCII file ffile.d and places labels
337                               at locations in the file that matches locations
338                               along  the  quoted  lines.  Inexact matches and
339                               points outside the region are skipped.
340
341                        l|Lline1[,line2,...]
342                               Give the coordinates of the end points for  one
343                               or more comma-separated straight line segments.
344                               Labels will be placed where these lines  inter‐
345                               sect the quoted lines.  The format of each line
346                               specification                                is
347                               start_lon/start_lat/stop_lon/stop_lat.     Both
348                               start_lon/start_lat and  stop_lon/stop_lat  can
349                               be  replaced by a 2-character key that uses the
350                               justification  format  employed  in  pstext  to
351                               indicate  a point on the frame or center of the
352                               map, given as [LCR][BMT].  L will interpret the
353                               point  pairs as defining great circles [Default
354                               is straight line].
355
356                        n|Nn_label
357                               Specifies the number of equidistant labels  for
358                               quoted  lines [1]. Upper case N starts labeling
359                               exactly at the start of the line [Default  cen‐
360                               ters  them along the line]. N-1 places one jus‐
361                               tified label at start,  while  N+1  places  one
362                               justified  label  at  the  end of quoted lines.
363                               Optionally, append /min_dist[c|i|p] to  enforce
364                               that a minimum distance separation between suc‐
365                               cessive labels is enforced.
366
367                        s|Sn_label
368                               Same as n|Nn_label but implies that  the  input
369                               data are first to be converted into a series of
370                               2-point line segments before plotting.
371
372                        x|Xxfile.d
373                               Reads the multisegment file xfile.d and  places
374                               labels  at the intersections between the quoted
375                               lines and the lines in xfile.d.  X will  resam‐
376                               ple  the  lines  first along great-circle arcs.
377                               In addition, you may  optionally  append  +rra‐
378                               dius[c|i|p]  to  set a minimum label separation
379                               in the x-y plane [no limitation].
380
381                        The optional labelinfo controls the specifics  of  the
382                        label formatting and consists of a concatenated string
383                        made up of any of the following control arguments:
384
385                        +aangle
386                               For annotations  at  a  fixed  angle,  +an  for
387                               line-normal,    or    +ap   for   line-parallel
388                               [Default].
389
390                        +cdx[/dy]
391                               Sets the clearance between label  and  optional
392                               text box. Append c|i|p to specify the unit or %
393                               to indicate a percentage of the label font size
394                               [15%].
395
396                        +d     Turns  on  debug  which will draw helper points
397                               and lines to illustrate  the  workings  of  the
398                               quoted line setup.
399
400                        +e     Delay the plotting of the text. This is used to
401                               build a clip path based on the text,  then  lay
402                               down  other overlays while that clip path is in
403                               effect, then turning of  clipping  with  psclip
404                               -Cs which finally plots the original text.
405
406                        +ffont Sets  the desired font [Default FONT_ANNOT_PRI‐
407                               MARY with its size changed to 9p].
408
409                        +g[color]
410                               Selects opaque text boxes [Default is transpar‐
411                               ent];  optionally specify the color [Default is
412                               PS_PAGE_COLOR].
413
414                        +jjust Sets  label  justification  [Default  is   MC].
415                               Ignored when -SqN|n+|-1 is used.
416
417                        +llabel
418                               Sets the constant label text.
419
420                        +Lflag Sets  the label text according to the specified
421                               flag:
422
423                               +Lh Take the label  from  the  current  segment
424                               header  (first  scan  for  an  embedded -Llabel
425                               option, if not use the first word following the
426                               segment   flag).   For   multiple-word  labels,
427                               enclose entire label  in  double  quotes.   +Ld
428                               Take  the  Cartesian  plot  distances along the
429                               line as the label; append  c|i|p  as  the  unit
430                               [Default  is  PROJ_LENGTH_UNIT].  +LD Calculate
431                               actual map distances; append d|e|f|k|n|M|n|s as
432                               the  unit  [Default  is d(egrees), unless label
433                               placement was based on map distances along  the
434                               lines in which case we use the same unit speci‐
435                               fied for that algorithm]. Requires a  map  pro‐
436                               jection to be used.  +Lf Use text after the 2nd
437                               column in the fixed label location file as  the
438                               label.  Requires  the fixed label location set‐
439                               ting.  +Lx As +Lh but use the  headers  in  the
440                               xfile.d  instead.   Requires  the crossing file
441                               option.
442
443                        +ndx[/dy]
444                               Nudges the placement of labels by the specified
445                               amount  (append  c|i|p  to  specify the units).
446                               Increments are  considered  in  the  coordinate
447                               system  defined by the orientation of the line;
448                               use +N to force  increments  in  the  plot  x/y
449                               coordinates  system  [no  nudging]. Not allowed
450                               with +v.
451
452                        +o     Selects rounded rectangular text  box  [Default
453                               is  rectangular].   Not  applicable  for curved
454                               text (+v) and only makes sense for opaque  text
455                               boxes.
456
457                        +p[pen]
458                               Draws  the outline of text boxes [Default is no
459                               outline]; optionally specify  pen  for  outline
460                               [Default is width = 0.25p, color = black, style
461                               = solid].
462
463                        +rmin_rad
464                               Will not place labels where the  line's  radius
465                               of  curvature  is less than min_rad [Default is
466                               0].
467
468                        +t[file]
469                               Saves  line  label  x,  y,  and  text  to  file
470                               [Line_labels.txt].  Use +T to save x, y, angle,
471                               text instead.
472
473                        +uunit Appends unit to all line labels. If unit starts
474                               with a leading hyphen (-) then there will be no
475                               space  between  label  value  and   the   unit.
476                               [Default is no unit].
477
478                        +v     Specifies  curved  labels  following  the  path
479                               [Default is straight labels].
480
481                        +w     Specifies how many (x,y) points will be used to
482                               estimate label angles [Default is 10].
483
484                        +x[first,last]
485                               Append  the suffices first and last to the cor‐
486                               responding  labels.   This  modifier  is   only
487                               available  when  -SqN2  is  in effect.  Used to
488                               annotate the start and end of a line  (e.g.,  a
489                               cross-section),  append  two text strings sepa‐
490                               rated by comma [Default just adds  a  prime  to
491                               the second label].
492
493                        +=prefix
494                               Prepends  prefix  to all line labels. If prefix
495                               starts with a leading  hyphen  (-)  then  there
496                               will  be  no  space between label value and the
497                               prefix. [Default is no prefix].
498
499                     Note: By placing -Sq options in the  segment  header  you
500                     can   change   the  quoted  text  attributes  on  a  seg‐
501                     ment-by-segment basis.
502
503              -Sr    rectangle. No size needs to be specified, but the x-  and
504                     y-dimensions must be found in columns 3 and 4.
505
506              -SR    Rounded rectangle. No size needs to be specified, but the
507                     x- and y-dimensions and corner radius must  be  found  in
508                     columns 3, 4, and 5.
509
510              -Ss    square. size is diameter of circumscribing circle.
511
512              -St    triangle. size is diameter of circumscribing circle.
513
514              -Sv    vector. Direction (in degrees counter-clockwise from hor‐
515                     izontal) and length must be found in columns 3 and 4, and
516                     size,  if  not  specified  on the command-line, should be
517                     present in column 5.  The size is the length of the  vec‐
518                     tor  head.  Vector  width  is  set  by  -W.   See  VECTOR
519                     ATTRIBUTES for specifying other attributes.
520
521              -SV    Same as -Sv, except azimuth (in degrees  east  of  north)
522                     should be given instead of direction. The azimuth will be
523                     mapped into an angle based on the chosen  map  projection
524                     (-Sv   leaves   the  directions  unchanged.)  See  VECTOR
525                     ATTRIBUTES for specifying other attributes.
526
527              -Sw    pie  wedge.  Start  and  stop  directions   (in   degrees
528                     counter-clockwise  from horizontal) for pie slice must be
529                     found in columns 3 and 4.  Append +a to just draw the arc
530                     line or +r to just draw the radial lines.
531
532              -SW    Same  as  -Sw, except azimuths (in degrees east of north)
533                     should be  given  instead  of  the  two  directions.  The
534                     azimuths  will  be mapped into angles based on the chosen
535                     map projection (-Sw  leaves  the  directions  unchanged.)
536                     For  geo-wedges,  specify  size  as a radial geographical
537                     distance.  For allowable geographical units,  see  UNITS.
538                     Append  +a  to  just  draw the arc or +r to just draw the
539                     radial lines.
540
541              -Sx    cross (x). size is diameter of circumscribing circle.
542
543              -Sy    y-dash (|). size  is  the  length  of  a  short  vertical
544                     (y-dir) line segment.
545
546              -S=    geovector.  Azimuth (in degrees east from north) and geo‐
547                     graphical length must be found in columns 3  and  4.  The
548                     size  is  the  length of the vector head. Vector width is
549                     set  by  -W.  See  VECTOR   ATTRIBUTES   for   specifying
550                     attributes.   Note:  Geovector  stems  are  drawn as thin
551                     filled polygons and hence pen attributes like dashed  and
552                     dotted  are  not  available.   For allowable geographical
553                     units, see UNITS.
554
555              -S~    decorated line, i.e.,  lines  with  symbols  along  them.
556                     Append   [d|D|f|l|L|n|N|s|S|x|X]info[:symbolinfo].    The
557                     required argument controls the placement of symbols along
558                     the  decorated  lines. Choose among six controlling algo‐
559                     rithms:
560
561                        ddist[c|i|p] or Ddist[d|e|f|k|m|M|n|s]
562                               For lower case d, give distances  between  sym‐
563                               bols  on the plot in your preferred measurement
564                               unit c (cm), i (inch), or p (points), while for
565                               upper  case  D,  specify distances in map units
566                               and append the unit;  choose  among  e  (m),  f
567                               (foot),  k (km), M (mile), n (nautical mile) or
568                               u (US survey foot), and d (arc degree), m  (arc
569                               minute), or s (arc second).  [Default is 10c or
570                               4i]. As an option,  you  can  append  /fraction
571                               which  is  used  to place the very first symbol
572                               for each line when  the  cumulative  along-line
573                               distance equals fraction * dist [0.25].
574
575                        fffile.d
576                               Reads the ASCII file ffile.d and places symbols
577                               at locations in the file that matches locations
578                               along  the decorated lines. Inexact matches and
579                               points outside the region are skipped.
580
581                        l|Lline1[,line2,...]
582                               Give the coordinates of the end points for  one
583                               or more comma-separated straight line segments.
584                               Symbols will be placed where these lines inter‐
585                               sect  the  decorated lines.  The format of each
586                               line              specification              is
587                               start_lon/start_lat/stop_lon/stop_lat.     Both
588                               start_lon/start_lat and  stop_lon/stop_lat  can
589                               be  replaced by a 2-character key that uses the
590                               justification  format  employed  in  pstext  to
591                               indicate  a point on the frame or center of the
592                               map, given as [LCR][BMT].  L will interpret the
593                               point  pairs as defining great circles [Default
594                               is straight line].
595
596                        n|Nn_symbol
597                               Specifies the number of equidistant symbols for
598                               decorated  lines [1]. Upper case N starts plac‐
599                               ing symbols exactly at the start  of  the  line
600                               [Default  centers  them  along  the  line]. N-1
601                               places one symbol at start,  while  N+1  places
602                               one  symbol  at  the  end  of  decorated lines.
603                               Optionally, append /min_dist[c|i|p] to  enforce
604                               that a minimum distance separation between suc‐
605                               cessive symbols is enforced.
606
607                        s|Sn_symbol
608                               Same as n|Nn_symbol but implies that the  input
609                               data are first to be converted into a series of
610                               2-point line segments before plotting.
611
612                        x|Xxfile.d
613                               Reads the multisegment file xfile.d and  places
614                               symbols  at the intersections between the deco‐
615                               rated lines and the lines in xfile.d.   X  will
616                               resample  the  lines  first  along great-circle
617                               arcs.
618
619                        The optional symbolinfo controls the specifics of  the
620                        symbol selection and formatting and consists of a con‐
621                        catenated string made up of any of the following  con‐
622                        trol arguments:
623
624                        +aangle
625                               For symbols at a fixed angle, +an for line-nor‐
626                               mal, or +ap for line-parallel [Default].
627
628                        +d     Turns on debug which will  draw  helper  points
629                               and  lines  to  illustrate  the workings of the
630                               decorated line setup.
631
632                        +g[fill]
633                               Sets the symbol fill [no fill].
634
635                        +ndx[/dy]
636                               Nudges the placement of symbols by  the  speci‐
637                               fied   amount  (append  c|i|p  to  specify  the
638                               units). Increments are considered in the  coor‐
639                               dinate system defined by the orientation of the
640                               line; use +N to force increments  in  the  plot
641                               x/y coordinates system [no nudging].
642
643                        +p[pen]
644                               Draws  the  outline  of  symbols [Default is no
645                               outline]; optionally specify  pen  for  outline
646                               [Default is width = 0.25p, color = black, style
647                               = solid].
648
649                        +s<symbol><size>
650                               Specifies the code and size of  the  decorative
651                               symbol.
652
653                        +w     Specifies how many (x,y) points will be used to
654                               estimate symbol angles [Default is 10].
655
656                     Note: By placing -S~ options in the  segment  header  you
657                     can  change  the  decorated lines on a segment-by-segment
658                     basis.
659
660       -T     Ignore all input files, including standard input.  This  is  the
661              same as specifying /dev/null (or NUL for Windows users) as input
662              file.  Use this to  activate  only  the  options  that  are  not
663              related  to  plotting of lines or symbols, such as psxy -R -J -O
664              -T to terminate a sequence of GMT plotting commands without pro‐
665              ducing any plotting output.
666
667       -U[[just]/dx/dy/][c|label] (more ...)
668              Draw GMT time stamp logo on plot.
669
670       -V[level] (more ...)
671              Select verbosity level [c].
672
673       -W[pen][attr] (more ...)
674              Set   pen  attributes  for  lines  or  the  outline  of  symbols
675              [Defaults: width = default, color = black, style  =  solid].  If
676              the  modifier  +cl  is  appended  then the color of the line are
677              taken from the CPT (see -C). If instead modifier +cf is appended
678              then the color from the cpt file is applied to symbol fill.  Use
679              just +c for both effects.  You can also append one or more addi‐
680              tional  line  attribute modifiers: +ooffsetu will start and stop
681              drawing the line the given distance offsets from the end  point.
682              Append unit u from c|i|p to indicate plot distance on the map or
683              append map distance units instead (see  below)  [Cartesian  dis‐
684              tances];  +s will draw the line using a PostScript Bezier spline
685              [linear spline]; +vvspecs will place a vector head at  the  ends
686              of  the lines.  You can use +vb and +ve to specify separate vec‐
687              tor specs at each end [shared specs].  Because +v may take addi‐
688              tional  modifiers it must necessarily be given at the end of the
689              pen specification.  See the Vector Attributes for more  informa‐
690              tion.
691
692       -X[a|c|f|r][x-shift[u]]
693
694       -Y[a|c|f|r][y-shift[u]] (more ...)
695              Shift plot origin.
696
697       -bi[ncols][t] (more ...)
698              Select  native  binary input. [Default is the required number of
699              columns given the chosen settings].
700
701       -acol=name[...] (more ...)
702              Set aspatial column associations col=name.
703
704       -dinodata (more ...)
705              Replace input columns that equal nodata with NaN.
706
707       -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
708              Only accept data records that match the given pattern.
709
710       -f[i|o]colinfo (more ...)
711              Specify data types of input and/or output columns.
712
713       -g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more ...)
714              Determine data gaps and line breaks. The -g option is ignored if
715              -S is set.
716
717       -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
718              Skip or produce header record(s).
719
720       -icols[+l][+sscale][+ooffset][,...] (more ...)
721              Select input columns and transformations (0 is first column).
722
723       -:[i|o] (more ...)
724              Swap 1st and 2nd column on input and/or output.
725
726       -p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more ...)
727              Select perspective view.
728
729       -t[transp] (more ...)
730              Set PDF transparency level in percent.
731
732       -^ or just -
733              Print  a  short  message  about  the syntax of the command, then
734              exits (NOTE: on Windows just use -).
735
736       -+ or just +
737              Print an extensive usage (help) message, including the  explana‐
738              tion  of  any  module-specific  option  (but  not the GMT common
739              options), then exits.
740
741       -? or no arguments
742              Print a complete usage (help) message, including the explanation
743              of all options, then exits.
744

UNITS

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

VECTOR ATTRIBUTES

756       Several modifiers may be appended to the  vector-producing  options  to
757       specify the placement of vector heads, their shapes, and the justifica‐
758       tion of the vector. Below, left and right refers to  the  side  of  the
759       vector  line  when  viewed from the start point to the end point of the
760       segment:
761          +aangle sets the angle of the vector head apex [30].
762
763          +b places a vector head at the beginning of the vector path  [none].
764          Optionally,  append  t  for  a  terminal line, c for a circle, a for
765          arrow [Default], i for tail, A for plain  arrow,  and  I  for  plain
766          tail.   Further  append  l|r  to only draw the left or right side of
767          this head [both sides].
768
769          +e places a vector head at  the  end  of  the  vector  path  [none].
770          Optionally,  append  t  for  a  terminal line, c for a circle, a for
771          arrow [Default], i for tail, A for plain  arrow,  and  I  for  plain
772          tail.   Further  append  l|r  to only draw the left or right side of
773          this head [both sides].
774
775          +g-|fill turns off vector head fill (if -) or sets the  vector  head
776          fill [Default fill is used, which may be no fill].
777
778          +hshape  sets  the shape of the vector head (range -2/2). Default is
779          controlled by MAP_VECTOR_SHAPE [0].
780
781          +l draws half-arrows, using only the left side  of  specified  heads
782          [both sides].
783
784          +m  places  a  vector  head at the mid-point the vector path [none].
785          Append f or r for forward or reverse direction of the  vector  [for‐
786          ward].  Optionally, append t for a terminal line, c for a circle, or
787          a for arrow head [Default].  Further append l|r  to  only  draw  the
788          left  or  right  side of this head [both sides].  Cannot be combined
789          with +b or +e.
790
791          +nnorm scales down vector attributes (pen thickness, head size) with
792          decreasing  length,  where vectors shorter than norm will have their
793          attributes scaled by length/norm [arrow attributes remains invariant
794          to length].
795
796          +oplon/plat  specifies  the oblique pole for the great or small cir‐
797          cles.  Only needed for great circles if +q is given.
798
799          +p[-][pen] sets the vector pen attributes. If pen has  a  leading  -
800          then  the  head outline is not drawn. [Default pen is used, and head
801          outline is drawn]
802
803          +q means the input angle, length data instead  represent  the  start
804          and  stop  opening  angles  of the arc segment relative to the given
805          point.
806
807          +r draws half-arrows, using only the right side of  specified  heads
808          [both sides].
809
810          +t[b|e]trim  will  shift  the beginning or end point (or both) along
811          the vector segment by the given trim; append suitable unit.  If  the
812          modifiers  b|e are not used then trim may be two values separated by
813          a slash, which is used to specify different trims for the two  ends.
814          Positive  trims  will  shorted  the vector while negative trims will
815          lengthen it [no trim].
816
817       In addition, all but circular vectors may take these modifiers:
818          +jjust determines how the input x,y point  relates  to  the  vector.
819          Choose from beginning [default], end, or center.
820
821          +s means the input angle, length are instead the x, y coordinates of
822          the vector end point.
823
824       Finally, Cartesian vectors may take these modifiers:
825          +zscale[unit] expects input dx,dy vector  components  and  uses  the
826          scale to convert to polar coordinates with length in given unit.
827

EXAMPLES

829       To  plot  solid red circles (diameter = 0.2 cm) at the positions listed
830       in the file DSDP.txt on a Mercator map at 0.3  cm/degree  of  the  area
831       100E to 160E, 20S to 30N, with automatic tick-marks and gridlines, use
832
833              gmt psxy DSDP.txt -R100/160/-20/30 -Jm0.3c -Sc0.2c -Gred -Bafg > map.ps
834
835       To  plot  the  xyz  values in the file quakes.xyzm as circles with size
836       given by the magnitude in the 4th column and color based on  the  depth
837       in the third using the CPT rgb.cpt on a linear map, use
838
839              gmt psxy quakes.xyzm -R0/1000/0/1000 -JX6i -Sc -Crgb -B200 > map.ps
840
841       To  plot  the  file  trench.txt on a Mercator map, with white triangles
842       with sides 0.25 inch on the left side of the  line,  spaced  every  0.8
843       inch, use
844
845              gmt psxy trench.txt -R150/200/20/50 -Jm0.15i -Sf0.8i/0.1i+l+t -Gwhite -W -B10 > map.ps
846
847       To  plot  the data in the file misc.d as symbols determined by the code
848       in the last column, and with size given by the  magnitude  in  the  4th
849       column,  and  color  based  on the third column via the CPT chrome on a
850       linear map, use
851
852              gmt psxy misc.d -R0/100/-50/100 -JX6i -S -Cchrome -B20 > map.ps
853
854       If you need to place vectors on a plot you can  choose  among  straight
855       Cartesian  vectors,  math  circular vectors, or geo-vectors (these form
856       small or great circles on the Earth).  These can have optional heads at
857       either end, and heads may be the traditional arrow, a circle, or a ter‐
858       minal cross-line.  To place a few vectors with a circle  at  the  start
859       location and an arrow head at the end, try
860
861              gmt psxy -R0/50/-50/50 -JX6i -Sv0.15i+bc+ea -Gyellow -W0.5p -Baf << EOF > map.ps
862              10 10 45 2i
863              30 -20 0 1.5i
864              EOF
865
866       To  plot  vectors (red vector heads, solid stem) from the file data.txt
867       that contains record of the form lon, lat, dx, dy, where dx, dy are the
868       Cartesian  vector  components given in user units, and these user units
869       should be converted to cm given the scale 3.60, try
870
871              gmt psxy -R20/40/-20/0 -JM6i -Sv0.15i+e+z3.6c -Gred -W0.25p -Baf data.txt > map.ps
872

SEGMENT HEADER PARSING

874       Segment header records  may  contain  one  of  more  of  the  following
875       options:
876
877       -Gfill Use the new fill and turn filling on
878
879       -G-    Turn filling off
880
881       -G     Revert to default fill (none if not set on command line)
882
883       -Wpen  Use the new pen and turn outline on
884
885       -W     Revert  to  default  pen  MAP_DEFAULT_PEN (if not set on command
886              line)
887
888       -W-    Turn outline off
889
890       -Zzval Obtain fill via cpt lookup using z-value zval
891
892       -ZNaN  Get the NaN color from the CPT
893

CUSTOM SYMBOLS

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

POLAR CAPS

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

SEE ALSO

921       gmt, gmt.conf, gmtcolors, psbasemap, psxyz
922
924       2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
925
926
927
928
9295.4.5                            Feb 24, 2019                          PSXY(1)
Impressum