## NAME

           psxyz - Plot lines, polygons, and symbols in 3-D

## SYNOPSIS

           psxyz files -Jparameters -Rwest/east/south/north/zmin/zmax[r] [ -Btick-
           info ] [ -Ccptfile ] [ -Eazimuth/elevation ] [ -Gfill ] [ -H[nrec] ]  [
           -K  ]  [  -L ] [ -M[flag] ] [ -N ] [ -O ] [ -P ] [ -S[symbol][size] ] [
           -U[/dx/dy/][label] ] [ -V ] [ -W[pen] ] [ -Xx-shift ] [ -Yy-shift  ]  [
           -Zzlevel ] [ -: ] [ -ccopies ] [ -bi[s][n] ] [ -f[i|o]colinfo ]

## DESCRIPTION

           psxyz  reads (x,y,z) triplets from files [or standard input] and gener-
           ates PostScript code that will plot  lines,  polygons,  or  symbols  at
           those  locations  in  3-D.   If a symbol is selected and no symbol size
           given, then psxyz will interpret the fourth column of the input data as
           symbol  size. Symbols whose size is <= 0 are skipped. If no symbols are
           specified then the symbol code (see -S below) must be present  as  last
           column in the input. Multiple segment files may be plotted using the -M
           option.  If no symbols are selected, a line will be drawn.  To  explic-
           itly  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 out-
           line, respectively.  The PostScript code is written to standard output.

           files  List  one  or more file-names. If no files are given, psxyz 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.

           -Jz    Sets the vertical scaling (for 3-D maps). Same syntax as -Jx.

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

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

           -C     Give a color palette file. If -S is set, let symbol  fill  color
                  be  determined  by  the t-value in the fourth column. Additional
                  fields are shifted over by one column (optional size would be in
                  5th  rather than 4th field, etc.).  If -S is not set, then psxyz
                  expects a multisegment line or polygon file (requires -M)  where
                  each  segment  header contains a -Zval string. The val will con-
                  trol the color of the line or polygon (use -L) via the cpt file.

           -E     Sets the viewpoint’s azimuth and elevation [180/90].

           -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, psxyz 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: will connect the endpoints of  the  line-
                  segment(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].

           -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.  size  is  symbol size in the unit set in .gmtde-
                  faults4 (unless c, i, m, or p is appended). If the  symbol  code
                  (see below) is not given it will be read from the last column in
                  the input data; this cannot be  used  in  conjunction  with  -b.
                  Optionally, append c, i, m, p to indicate that the size informa-
                  tion in the input data is in units of cm, inch, meter, or point,
                  respectively.  [Default is MEASURE_UNIT].  The uppercase symbols
                  A, C, D, G, H, I, N, S, T are normalized to have the  same  area
                  as  a  circle  of  given size, while the corresponding lowercase
                  symbols are circumscribed by the circle.  Choose between:

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

           -Sa    star. size is diameter of circumscribing circle.

           -Sb    (b)ar  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    (c)ircle. size is diameter of circle.

           -Sd    (d)iamond. size is diameter of circumscribing circle.

           -Se    ellipse.  Direction  (in  degrees counterclockwise from horizon-
                  tal), major_axis, and minor_axis must be found in columns 4,  5,
                  and 6.

           -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 [0].

           -Sg    octagon. size is diameter of circumscribing circle.

           -Sh    hexagon. size is diameter of circumscribing circle.

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

           -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.  The symbols are plotted in the x-y  plane.   Users
                  may  add their own custom *.def files; see CUSTOM SYMBOLS in the
                  psxy man page.

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

           -Sn    pentagon. size is diameter of circumscribing circle.

           -So    c(o)lumn  (3-D)  extending  from base to z. size sets base width
                  (Use xsize/ysize if not the same). Append u if  size  is  in  x-
                  units  [Default  is  plot-distance units]. By default, base = 0.
                  Append bbase to change this value.

           -Sp    (p)oint. No size needs to be specified.

           -Sq    quoted line, i.e., lines with annotations such as  contours.  It
                  is  assumed  that  each  individual  line has a constant z level
                  (i.e.,  each  line  must  lie  in   the   x-y   plane).   Append
                  [d|f|n|l|x]info[:labelinfo].  The required argument controls the
                  placement of labels along the lines. Choose among four  control-
                  ling 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    rectangle.  No  size  needs  to  be specified, but the x- and y-
                  dimensions must be found in columns 4 and 5.

           -Ss    (s)quare. size is diameter of circumscribing circle.

           -St    (t)riangle. size is diameter of circumscribing circle.

           -Su    c(u)be (3-D). size sets length of all sides. Append u if size is
                  in x-units [Default is plot-distance units].

           -Sv    (v)ector. Direction and length must be found in columns 4 and 5.
                  size  means  arrowwidth/headlength/headwidth  in  [[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 should be given  instead  of  direc-
                  tion. The azimuth will be mapped into an angle based on the cho-
                  sen map projection (-Sv leaves the directions unchanged.)

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

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

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

           -Sz    zdash.  size is the length of a short vertical (z-dir) line seg-
                  ment.

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

           -Z     For 3-D projections: Sets the z-level of the basemap [0].

           -:     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 settings].

           -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 blue columns (width = 1.25 cm) at the positions listed  in  the
           file  heights.xyz  on  a  3-D  projection  of the space (0-10), (0-10),
           (0-100), with tickmarks every  2,  2,  and  10,  viewing  it  from  the
           southeast at 30 degree elevation, use:

           psxyz   heights.xyz   -R0/10/0/10/0/100   -Jx1.25c  -Jz0.125c  -So1.25c
           -G0/0/255 -B2:XLABEL:/2:YLABEL:/10:ZLABEL::."3-D PLOT":15 -E135/30  -Uc
           -W -P > heights.ps

## BUGS

           No  hidden  line  removal  is employed for polygons and lines. Symbols,
           however, are first sorted according to their distance  from  the  view-
           point  so  that  nearby symbols will overprint more distant ones should
           they project to the same x,y position.
           psxyz 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.
           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.

## SEE ALSO

           gmt(l), psbasemap(l), psxy(l)

    GMT4.0                            1 Oct 2004                          PSXYZ(l)