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)

Man(1) output converted with man2html