## NAME

           psxy - Plot lines, polygons, and symbols on maps

## SYNOPSIS

           psxy  files -Jparameters -Rwest/east/south/north[r] [ -A ] [ -Btickinfo
           ] [ -Ccptfile ] [ -Ddx/dy ] [ -E[x|y|X|Y][cap][/pen] ]  [  -Gfill  ]  [
           -H[nrec]  ]  [  -K ] [ -L ] [ -N ] [ -M[flag] ] [ -O ] [ -P ] [ -S[sym-
           bol][size] ] [ -U[/dx/dy/][label] ] [ -V ] [ -W[pen] ] [ -Xx-shift ]  [
           -Yy-shift ] [ -: ] [ -ccopies ] [ -bi[s][n] ] [ -f[i|o]colinfo ]

## 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.  Multiple  segment  files  may  be plotted using the -M
           option.  If -S is not selected, a line connecting the data points  will
           be  drawn instead. To explicitly close polygons, use -L. Select a shade
           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
           color and outline/no outline, respectively.   The  PostScript  code  is
           written to standard output.

           files  List  one  or  more file-names. If no files are given, psxy will
                  read standard input.

           -J     Selects the map projection. Scale is  UNIT/degree,  1:xxxxx,  or
                  width  in  UNIT  (upper case modifier).  UNIT is cm, inch, or m,
                  depending on the MEASURE_UNIT setting in .gmtdefaults4, but this
                  can be overridden on the command line by appending c, i, or m to
                  the scale/width value.  For map height, max  dimension,  or  min
                  dimension, append h, +, or - to the width, respectively.

                  CYLINDRICAL PROJECTIONS:

                  -Jclon0/lat0/scale (Cassini)
                  -Jjlon0/scale (Miller)
                  -Jmscale (Mercator - Greenwich and Equator as origin)
                  -Jmlon0/lat0/scale (Mercator - Give meridian and standard paral-
                  lel)
                  -Joalon0/lat0/azimuth/scale  (Oblique  Mercator  -   point   and
                  azimuth)
                  -Joblon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
                  -Joclon0/lat0/lonp/latp/scale  (Oblique  Mercator  -  point  and
                  pole)
                  -Jqlon0/scale (Equidistant Cylindrical  Projection  (Plate  Car-
                  ree))
                  -Jtlon0/scale (TM - Transverse Mercator, with Equator as y = 0)
                  -Jtlon0/lat0/scale (TM - Transverse Mercator, set origin)
                  -Juzone/scale (UTM - Universal Transverse Mercator)
                  -Jylon0/lats/scale (Basic Cylindrical Projection)

                  AZIMUTHAL PROJECTIONS:

                  -Jalon0/lat0/scale (Lambert).
                  -Jelon0/lat0/scale (Equidistant).
                  -Jflon0/lat0/horizon/scale (Gnomonic).
                  -Jglon0/lat0/scale (Orthographic).
                  -Jslon0/lat0/[slat/]scale (General Stereographic)

                  CONIC PROJECTIONS:

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

                  MISCELLANEOUS PROJECTIONS:

                  -Jhlon0/scale (Hammer)
                  -Jilon0/scale (Sinusoidal)
                  -Jk[f|s]lon0/scale (Eckert IV (f) and VI (s))
                  -Jnlon0/scale (Robinson)
                  -Jrlon0/scale (Winkel Tripel)
                  -Jvlon0/scale (Van der Grinten)
                  -Jwlon0/scale (Mollweide)

                  NON-GEOGRAPHICAL PROJECTIONS:

                  -Jp[a]scale[/origin]  (polar  (theta,r)  coordinates, optional a
                  for azimuths and offset theta [0])
                  -Jxx-scale[l|ppow][/y-scale[l|ppow]][d] (Linear, log, and  power
                  scaling)
                  More details can be found in the psbasemap man pages.

           -R     xmin,  xmax,  ymin, and ymax specify the Region of interest. For
                  geographic regions,  these  limits  correspond  to  west,  east,
                  south,  and north and you may specify them in decimal degrees or
                  in [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r  if  lower  left
                  and  upper  right map coordinates are given instead of wesn. The
                  two shorthands  -Rg  -Rd  stand  for  global  domain  (0/360  or
                  -180/+180  in longitude respectively, with -90/+90 in latitude).
                  For calendar time coordinates you may either give relative  time
                  (relative  to  the  selected  TIME_EPOCH  and  in  the  selected
                  TIME_UNIT; append t to -JX|x), or  absolute  time  of  the  form
                  [date]T[clock]  (append  T  to  -JX|x). At least one of date and
                  clock must be present; the T is always required. The date string
                  must  be  of  the form [-]yyyy[-mm[-dd]] (Gregorian calendar) or
                  yyyy[-Www[-d]] (ISO week calendar), while the clock string  must
                  be  of  the form hh:mm:ss[.xxx]. The use of delimiters and their
                  type and positions must be as indicated  (however,  input/output
                  and plotting formats are flexible).

## OPTIONS

           No space between the option flag and the associated arguments.

           -A     Suppress  drawing  line  segments as great circle Arcs. [Default
                  draws great circle arcs].

           -B     Sets map boundary annotation and  tickmark  intervals;  see  the
                  psbasemap man page for all the details.

           -C     Give  a  color palette file. When used with -S, lets symbol fill
                  color be determined by the z-value in the  third  column.  Addi-
                  tional  fields  are  shifted  over  by one column (optional size
                  would be 4th rather than 3rd field, etc.).  If -S  is  not  set,
                  psxy  expects  the user to supply a multisegment line or polygon
                  file (requires -M) and will look for -Zval strings in each  mul-
                  tisegment  header. The val will control the color of the line or
                  polygon (use -L) via the cpt file.

           -D     Offset the plot symbol locations  by  the  given  amounts  dx/dy
                  [Default is no offset]. Only applies to symbols.

           -E     Draw  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,size) triplet]. The cap parameter indicates the  length  of
                  the  end-cap on the error bars [0.25c (or 0.1i)]. Pen attributes
                  for error bars may also be set. [Defaults: width =  1,  color  =
                  0/0/0,  texture  =  solid].  If upper case X and/or Y is used we
                  will instead draw "box-and-whisker"  (or  "stem-and-leaf")  sym-
                  bols. The x (or y) coordinate is then taken as the median value,
                  and 4 more columns are expected to contain the minimum (0% quar-
                  tile), the 25% quartile, the 75% quartile, and the maximum (100%
                  quartile) values. The 25-75% box may be filled by using -G.

           -G     Select filling  of  polygons  and  symbols.   Append  the  shade
                  (0-255),   color  (r/g/b),  or  P|pdpi/pattern  (polygons  only)
                  [Default is no fill].  Note when -M is chosen, psxy will  search
                  for  -G  and  -W strings in all the subheaders and let any found
                  values over-ride the command line settings.

           -H     Input file(s) has Header record(s). Number of header records can
                  be  changed  by  editing  your  .gmtdefaults4 file. If used, GMT
                  default is 1 header record. Use -Hi if only  input  data  should
                  have  header  records  [Default will write out header records if
                  the input data have them].

           -K     More PostScript code will be appended later [Default  terminates
                  the plot system].

           -L     Force  closed  polygons:  connect the endpoints of the line-seg-
                  ment(s) and draw polygons.

           -M     Multiple segment file. Segments are separated by a record  whose
                  first character is flag.  [Default is ’>’].

           -N     Do  NOT skip symbols that fall outside map border [Default plots
                  points inside border only]. The option does not apply  to  lines
                  and polygons which are always clipped to the map region.

           -O     Selects  Overlay  plot mode [Default initializes a new plot sys-
                  tem].

           -P     Selects Portrait plotting mode [GMT Default  is  Landscape,  see
                  gmtdefaults to change this].

           -S     Plot symbols. If present, size is symbol size in the unit set in
                  .gmtdefaults4 (unless c, i, m, 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
                  -b.  Optionally,  append  c,  i,  m, p to indicate that the size
                  information in the input data is in units of cm, inch, meter, or
                  point, respectively. [Default is MEASURE_UNIT].
                  The uppercase symbols A, C, D, fBG, H, I, N, S, T are normalized
                  to have the same area as a circle with diameter size, while  the
                  corresponding  lowercase  symbols  all  are circumscribed by the
                  circle. Choose between these symbol codes:

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

           -Sa    star. size is diameter of circumscribing circle.

           -Sb    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 = 0. Append bbase to change this value.

           -Sc    circle. size is diameter of circle.

           -Sd    diamond. size is diameter of circumscribing circle.

           -Se    ellipse. Direction (in degrees counter-clockwise  from  horizon-
                  tal),  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  direc-
                  tions unchanged.) Furthermore, the axes lengths must be given in
                  km instead of plot-distance units. An  exception  occurs  for  a
                  linear  projection if which we assume the ellipse axes are given
                  in the same units as -R.

           -Sf    front.  -Sfgap/size[dir][type][:offset].  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. Append dir to plot symbols on the left or right side of
                  the front [Default is centered]. Append type  to  specify  which
                  symbol  to plot: box, circle, fault, slip, or triangle. [Default
                  is fault].  Slip means left-lateral or right-lateral strike-slip
                  arrows (centered is not an option). Append :offset to offset the
                  first symbol from the beginning of  the  front  by  that  amount
                  [Default is 0].

           -Sh    hexagon. size is diameter of circumscribing circle.

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

           -Sk    kustom  symbol. Append <name>/size, and we will look for a defi-
                  nition file called <name>.def in (1) the  current  directory  or
                  (2) in $GMTHOME/share/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 64 characters). Give size,  and
                  append  /string  after  the  size.  Note  that  the size is only
                  approximate; no individual scaling is done for different charac-
                  ters.  Remember to escape special characters like *. Optionally,
                  you may append %font to select a  particular  font  [Default  is
                  ANNOT_FONT_PRIMARY].

           -Sg    octagon. size is diameter of circumscribing circle.

           -Sn    pentagon. size is diameter of circumscribing circle.

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

           -Sq    quoted  line,  i.e.,  lines  with  annotations such as contours.
                  Append [d|f|n|l|x]info[:labelinfo].  The required argument  con-
                  trols the placement of labels along the lines. Choose among four
                  controlling mechanisms:
                  Controls the placement of labels along the quoted lines.  Choose
                  among five controlling algorithms:
                  ddist[c|i|m|p] or Ddist[d|e|k|m|n].  For lower case d, give dis-
                  tances between labels on the plot in your preferred  measurement
                  unit c (cm), i (inch), m (meter), or p (points), while for upper
                  case D, specify distances in map  units  and  append  the  unit;
                  choose  among  e  (m), k (km), m (mile), n (nautical mile), or d
                  (spherical degree). [Default is 10c or 4i].
                  fffile.d reads the ascii file ffile.d and places labels at loca-
                  tions in the file that matches locations along the quoted lines.
                  Inexact mathces and points outside the region are skipped.
                  l|Lline1[,line2,...] Give start and stop coordinates for one  or
                  more  comma-separated  straight  line  segments.  Labels will be
                  placed where these lines intersect the quoted lines. The  format
                  of  each  line specification is start/stop, where start and stop
                  are either a specified point lon/lat or  a  2-character  XY  key
                  that  uses  the justification format employed in pstext to indi-
                  cate a point on the map, given as [LCR][BMT].  L will  interpret
                  the  point  pairs as defining great circles [Default is straight
                  line].
                  nn_label specifies the number of equidistant labels  for  quoted
                  lines  line  [1].   Upper  case N starts labeling exactly at the
                  start of the line [Default centers them along  the  line].   N-1
                  places one justified label at start, while N+1 places one justi-
                  fied label at the  end  of  quoted  lines.   Optionally,  append
                  /min_dist[c|i|m|p] to enforce that a minimum distance separation
                  between successive labels is enforced.
                  x|Xxfile.d reads  the  multi-segment  file  xfile.d  and  places
                  labels  at  the  intersections  between the quoted lines and the
                  lines inxfile.d. X will resample the lines  first  along  great-
                  circle arcs.
                  The  optional labelinfo controls the specifics of the label for-
                  matting 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|m|p to specify the unit or % to indicate a per-
                  centage of the label font size [15%].
                  +ffont sets the desired font [Default ANNOT_FONT_PRIMARY].
                  +g[color] selects opaque text boxes  [Default  is  transparent];
                  optionally specify the color [Default is PAGE_COLOR].
                  +jjust sets label justification [Default is CM].
                  +kcolor sets color of text labels [Default is COLOR_BACKGROUND].
                  +llabel sets the constant label text.
                  +Llflag sets the label text according to the specified flag:
                  flag is h: Take the label from the current  multisegment  header
                  (first scan for an embedded -Llabel option, if not use the first
                  word following the segment flag).
                  flag is d: Take the Cartesian plot distances along the  line  as
                  the label; append c|i|m|p as the unit [Default is MEASURE_UNIT].
                  flag is D: Calculate actual map distances; append  d|e|k|m|n  as
                  the unit [Default is d(egrees), unless label placement was based
                  on map distances along the lines in which case we use  the  same
                  unit  specified  for that algorithm].  Requires a map projection
                  to be used.
                  flag is f: Use text after the 2nd  column  in  the  fixed  label
                  location  file  as  the label. Requires the fixed label location
                  setting.
                  flag is x: As h but use the  headers  in  the  xfile.d  instead.
                  Requires the crossing file option.
                  +o  selects  rounded  rectangular text box [Default is rectangu-
                  lar]. Not applicable for curved text (+v) and only  makes  sense
                  for opaque text boxes.
                  +p[pen]  draws  the  outline of text boxsets [Default is no out-
                  line]; optionally specify pen for outline [Default  is  width  =
                  0.25p, color = black, texture = solid].
                  +rmin_rad  will not place labels where the line’s radius of cur-
                  vature is less than min_rad [Default is 0].
                  +ssize sets the desired font size in points [Default is 9].
                  +uunit appends unit to all line labels. If unit  starts  with  a
                  leading  hypen  (-)  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].
                  +=prefix prepends prefix to all line labels.  If  prefix  starts
                  with  a  leading  hypen  (-) then there will be no space between
                  label value and the prefix. [Default is no prefix].  -Sr rectan-
                  gle.  No size needs to be specified, but the x- and y-dimensions
                  must be found in columns 3 and 4.

           -Ss    square. size is diameter of circumscribing circle.

           -St    triangle. size is diameter of circumscribing circle.

           -Sv    vector. Direction (in degrees counter-clockwise from horizontal)
                  and  length  must be found in columns 3 and 4. size, if present,
                  will be interpreted as arrowwidth/headlength/headwidth  [Default
                  is  0.075c/0.3c/0.25c  (or 0.03i/0.12i/0.1i)].  By default arrow
                  attributes remains invariant to the length of the arrow. To have
                  the  size  of the vector scale down with decreasing size, append
                  nnorm,  where  vectors  shorter  than  norm  will   have   their
                  attributes  scaled  by  length/norm. To center vector on balance
                  point, use -Svb; to align point with the vector head, use  -Svh;
                  to align point with the vector tail, use -Svt [Default]. To give
                  the head point’s coordinates instead of  direction  and  length,
                  use -Svs. Upper case B, H, T, S will draw a double-headed vector
                  [Default is single head].

           -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  direc-
                  tions unchanged.)

           -Sw    pie  wedge. Start and stop directions (in degrees counter-clock-
                  wise from horizontal) for pie slice must be found in  columns  3
                  and 4.

           -Sx    cross. size is diameter of circumscribing circle.

           -Sy    y-dash. size is the length of a short vertical line segment.

           -U     Draw  Unix System time stamp on plot. User may specify where the
                  lower left corner of the stamp should fall on the page  relative
                  to  lower  left corner of plot. Optionally, append a label, or c
                  (which will  plot  the  command  string.).  The  GMT  parameters
                  UNIX_TIME  and  UNIX_TIME_POS can affect the appearance; see the
                  gmtdefaults man page for details.

           -V     Selects verbose mode, which will send progress reports to stderr
                  [Default runs "silently"].

           -W     Set pen attributes. [Defaults: width = 1, color = 0/0/0, texture
                  = solid].  Implicitly draws the outline of symbols with selected
                  pen.

           -X -Y  Shift  origin of plot by (x-shift,y-shift).  Prepend a for abso-
                  lute coordinates; the default (r) will reset plot origin.   Give
                  c to center plot using current page size.

           -:     Toggles  between  (longitude,latitude)  and (latitude,longitude)
                  input and/or output. [Default is (longitude,latitude)].   Append
                  i  to  select  input  only  or o to select output only. [Default
                  affects both].

           -bi    Selects binary input. Append s for single precision [Default  is
                  double].   Append  n  for  the  number  of columns in the binary
                  file(s).
                  [Default is the required number of columns given the chosen set-
                  tings].

           -c     Specifies the number of plot copies. [Default is 1].

           -f     Special  formatting  of  input  and output columns (time or geo-
                  graphical data) Specify i(nput) or  o(utput)  [Default  is  both
                  input  and output].  Give one or more columns (or column ranges)
                  separated by commas.  Append T (Absolute calendar time), t (time
                  relative  to  chosen TIME_EPOCH), x (longitude), y (latitude), g
                  (geographic coordinate), or f (floating point) to each column or
                  column range item.

## EXAMPLES

           To  plot solid red circles (diameter = 0.25 cm) at the positions listed
           in the file DSDP.xy on a Mercator map at 5 cm/degree of the  area  150E
           to  154E, 18N to 23N, with tickmarks every 1 degree and gridlines every
           15 minutes, use

           psxy DSDP.xy -R150/154/18/23 -Jm5c -Sc0.25c -G255/0/0 -B1g15m | lpr

           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 color palette cpt on a linear map, use

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

           To plot the file trench.xy 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

           psxy trench.xy -R150/200/20/50 -Jm0.15i -Sf0.8i/0.1ilt -G255 -W -B10  |
           lpr br

           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 color palette cpt
           on a linear map, use

           psxy misc.d -R0/100/-50/100 -JX6i -S -Ccpt -B20 > t.ps

## BUGS

           The -N option does not adjust the BoundingBox information  so  you  may
           have  to  post-process the PostScript outout with epstool or ps2epsi to
           obtain a correct BoundingBox.
           psxy cannot handle filling of polygons that contain the south or  north
           pole.  For  such  a polygon, make a copy and split it into two and make
           each explicitly contain the polar point. The two polygons will  combine
           to  give the desired effect when filled; to draw outline use the origi-
           nal polygon.

## CUSTOM SYMBOLS

           psxy and psxyz allows users to define and plot their  own  custom  sym-
           bols.  This is done by encoding the symbol using a simple plotting code
           described below. Put all the plotting codes for your new  symbol  in  a
           file  whose  extension  must  be  .def; you may then address the symbol
           without giving the extension (e.g., the symbol file tsunami.def is used
           by  specifying  -Sktsunami/size.   The  definition file can contain any
           number of plot code records, as well as blank lines and  comment  lines
           (starting  with  #).  psxy and psxyz will look for the definition files
           in (1) the current directory and (2) the $GMTHOME/share/custom, 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. With
           the exception of the circle, these can only be painted, not filled with
           a  pattern (use the freeform polygons to include a triangle that can be
           filled with a pattern). Generate freeform polygons by starting with  an
           anchor point:
                   x0 y0 M [ -Wpen ] [ -Gfill ]
           and draw a straight line from the current point to the next point with
                   x y D
           or add an arc by using
                   xc yc r dir1 dir2 A
           When  a  record  other  than  the D or A is encountered, the polygon is
           closed and considered complete.  The  optional  pen  and  fill  setting
           hardwires  particular values for this feature. If not present the poly-
           gon’s characteristics are determined by the command line  settings  for
           pen and fill. To deactivate fill or outline for any given polygon, give
           -G- or -W-. To add other geometric shapes to your  custom  symbol,  add
           any number of the following plot code records:

                   star: x y size a [ -Wpen ] [ -Gfill ]
                   circle: x y size c [ -Wpen ] [ -Gfill ]
                   cross: x y size x [ -Wpen ]
                   diamond: x y size d [ -Wpen ] [ -Gfill ]
                   ellipse: x y dir major minor e [ -Wpen ] [ -Gfill ]
                   hexagon: x y size h [ -Wpen ] [ -Gfill ]
                   invtriangle: x y size i [ -Wpen ] [ -Gfill ]
                   letter: x y size string l [ -Wpen ] [ -Gfill ]
                   octagon: x y size g [ -Wpen ] [ -Gfill ]
                   pentagon: x y size n [ -Wpen ] [ -Gfill ]
                   rect: x y xwidth ywidth r [ -Wpen ] [ -Gfill ]
                   square: x y size s [ -Wpen ] [ -Gfill ]
                   triangle: x y size t [ -Wpen ] [ -Gfill ]
                   wedge: x y radius dir1 dir2 w [ -Wpen ] [ -Gfill ]

           When  designing your symbol, the x, y and other dimensions are relative
           to a symbol of size 1, and all the dimensions will  be  scaled  by  the
           actual  symbol size chosen at run-time. To design a symbol, make a grid
           paper with psbasemap -R-0.5/0.5/-0.5/0.5 -JX4i -Ba0.1g0.05 -P > grid.ps
           and  draw  your symbol, centering it on (0,0). For examples of symbols,
           see the set supplied with GMT in $GMTHOME/share/custom.

## SEE ALSO

           gmt(l), psbasemap(l), psxyz(l)

    GMT4.0                            1 Oct 2004                           PSXY(l)