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)

Man(1) output converted with man2html