manpagez: man pages & more
man pstext(1)
Home | html | info | man
pstext(1)                             GMT                            pstext(1)




NAME

       pstext - Plot or typeset text on maps


SYNOPSIS

       pstext [ textfiles ]  -Jparameters
        -Rwest/east/south/north[/zmin/zmax][+r] [  -A ]
        -B[p|s]parameters       [        -D[j|J]dx[/dy][+v[pen]]      ]      [
       -F[+a[angle]][+c[justify]][+f[font]][+j[justify]][+h|+l|+r[first]
       |+ttext|+z[format]]  ] [  -Gcolor ] [  -Jparameters ] [  -K ] [  -L ] [
       -M ] [  -N ] [  -O ] [  -P ] [  -Ql|u ] [  -To|O|c|C ] [ [  -Wpen  ]  [
       -Xx_offset  ] [  -Yy_offset ] [  -U[stamp] ] [  -Z ] [ -acol=name[a|] ]
       [ -eregexp ] [ -fflags ] [ -hheaders ] [  -pflags  ]  [  -ttransp  ]  [
       -:[i|o] ]

       Note:  No  space  is allowed between the option flag and the associated
       arguments.


DESCRIPTION

       pstext plots text strings of variable size, font type, and orientation.
       Various map projections are provided, with the option to draw and anno-
       tate the map boundaries. PostScript code is written to standard output.
       Greek  characters, subscript, superscript, and small caps are supported
       as follows: The sequence @~ toggles between the selected font and Greek
       (Symbol).  @%no% sets the font to no; @%% resets the font to the start-
       ing font, @- toggles subscripts on/off, @+ toggles superscript  on/off,
       @#  toggles  small  caps  on/off,  @;color; changes the font color (@;;
       resets it), @:size: changes the font size (@:: resets it), and @_  tog-
       gles  underline  on/off.  @@  prints the @ sign. @e, @o, @a, @E, @O, @A
       give the accented Scandinavian characters.  Composite characters (over-
       strike) may be indicated with the @!<char1><char2> sequence, which will
       print the two characters on top of each other. To learn the octal codes
       for  symbols  not  available on the keyboard and some accented European
       characters,     see     Section     Char-esc-seq      and      Appendix
       Chart-Octal-Codes-for-Chars  in  the  GMT Technical Reference and Cook-
       book. Note that PS_CHAR_ENCODING must be set to an  extended  character
       set  in  your  gmt.conf  file  in order to use the accented characters.
       Using the -G or -W options, a rectangle  underlying  the  text  may  be
       plotted  (does not work for strings with sub/super scripts, symbols, or
       composite characters, except in paragraph mode (-M)).


REQUIRED ARGUMENTS

       -Jparameters (more a|)
              Select map projection.

       -Rxmin/xmax/ymin/ymax[+r][+uunit] (more a|)
              Specify the region of interest.

       For perspective view p, optionally append /zmin/zmax. (more a|)


OPTIONAL ARGUMENTS

       textfiles
              This is one or more files containing 1 or more records with  (x,
              y[, font, angle, justify], text). The attributes in brackets can
              alternatively be set directly via -F. If  no  files  are  given,
              pstext  will  read  standard input. font is a font specification
              with format [size,][font,][color] where size  is  text  size  in
              points,  font is the font to use, and color sets the font color.
              To draw outline fonts you append =pen to the font specification.
              The angle is measured in degrees counter-clockwise from horizon-
              tal, and justify sets the alignment.  If font is not an integer,
              then  it is taken to be a text string with the desired font name
              (see -L for available fonts). The alignment refers to  the  part
              of  the  text  string  that will be mapped onto the (x,y) point.
              Choose a 2 character combination of L, C, R (for  left,  center,
              or  right)  and T, M, B for top, middle, or bottom. e.g., BL for
              lower left.

       -A     Angles are given as azimuths; convert them to  directions  using
              the current projection.

       -B[p|s]parameters (more a|)
              Set map boundary frame and axes attributes.

       -Cdx/dy
              Sets  the  clearance  between  the  text and the surrounding box
              [15%].  Only used if -W or -G are specified. Append the unit you
              want   (cm,   inch,   or   point;   if   not  given  we  consult
              PROJ_LENGTH_UNIT) or % for a percentage of the font size.

       -D[j|J]dx[/dy][+v[pen]]
              Offsets the text from the projected (x,y) point by dx,dy  [0/0].
              If  dy  is  not specified then it is set equal to dx. Use -Dj to
              offset the text away from the point instead (i.e., the text jus-
              tification will determine the direction of the shift). Using -DJ
              will shorten diagonal offsets at corners by sqrt(2). Optionally,
              append  +v which will draw a line from the original point to the
              shifted point; append a pen to change the  attributes  for  this
              line.

       -F[+a[angle]][+c[justify]][+f[font]][+j[justify]][+h|+l|+r[first]
       |+ttext|+z[format]]
              By  default, text will be placed horizontally, using the primary
              annotation font attributes (FONT_ANNOT_PRIMARY), and centered on
              the  data  point.  Use this option to override these defaults by
              specifying up to three text attributes (font, angle, and  justi-
              fication)  directly  on the command line. Use +f to set the font
              (size,fontname,color); if no font info is given then  the  input
              file must have this information in one of its columns. Use +a to
              set the angle; if no angle is given then  the  input  file  must
              have this as a column. Alternatively, use +A to force text-base-
              lines to convert into the -90/+90 range.  Use +j to set the jus-
              tification;  if  no  justification  is given then the input file
              must have this as a column. Items read from the data file should
              be  in  the same order as specified with the -F option. Example:
              -F+f12p,Helvetica-Bold,red+j+a selects a 12p red  Helvetica-Bold
              font  and  expects  to read the justification and angle from the
              file, in that order, after x, y and before text.   In  addition,
              the  +c justification lets us use x,y coordinates extracted from
              the -R string instead of providing them in the input  file.  For
              example  -F+cTL  gets  the  x_min,  y_max from the -R string and
              plots the text at the Upper Left corner of the  map.   Normally,
              the text to be plotted comes from the data record.  Instead, use
              +h or +l to select the text as the most recent segment header or
              segment  label, respectively in a multisegment input file, +r to
              use the record number (counting up from first), +ttext to set  a
              fixed text string, or +z to format incoming z values to a string
              using the supplied format [use FORMAT_FLOAT_MAP].

       -Gcolor
              Sets the shade or color used for filling the text  box  [Default
              is  no  fill].  Alternatively, use -Gc to plot the text and then
              use the text dimensions (and -C) to build clip  paths  and  turn
              clipping  on.   This  clipping can then be turned off later with
              psclip -C.  To not plot the text but activate clipping, use  -GC
              instead.

       -Jz|Zparameters (more a|)
              Set z-axis scaling; same syntax as -Jx.

       -K (more a|)
              Do not finalize the PostScript plot.

       -L     Lists the font-numbers and font-names available, then exits.

       -M     Paragraph  mode.  Files must be multiple segment files. Segments
              are separated by a special record whose first character must  be
              flag  [Default  is  >]. Starting in the 3rd column, we expect to
              find information pertaining to the typesetting of a  text  para-
              graph  (the  remaining  lines  until  next  segment header). The
              information expected is (x y [font angle justify] linespace par-
              width  parjust),  where x y font angle justify are defined above
              (font, angle, and justify can be set via  -F),  while  linespace
              and  parwidth  are  the linespacing and paragraph width, respec-
              tively.  The justification of the text paragraph is governed  by
              parjust  which may be l(eft), c(enter), r(ight), or j(ustified).
              The segment header is followed by one or more lines  with  para-
              graph  text.  Text  may  contain  the escape sequences discussed
              above. Separate paragraphs with a blank line.  Note  that  here,
              the  justification  set  via  -F+j  applies to the box alignment
              since the text justification is set by parjust.

       -N     Do NOT clip text at map boundaries [Default will clip].

       -O (more a|)
              Append to existing PostScript plot.

       -P (more a|)
              Select aPortraita plot orientation.

       -Q     Change all text to either lower or upper  case  [Default  leaves
              all text as is].

       -T     Specify  the  shape  of  the  textbox  when  using -G and/or -W.
              Choose lower case o  to  get  a  straight  rectangle  [Default].
              Choose  upper  case  O  to get a rounded rectangle. In paragraph
              mode (-M) you can also choose lower case c to get a concave rec-
              tangle or upper case C to get a convex rectangle.

       -U[[just]/dx/dy/][c|label] (more a|)
              Draw GMT time stamp logo on plot.

       -V[level] (more a|)
              Select verbosity level [c].

       -Wpen  Sets  the  pen  used  to draw a rectangle around the text string
              (see -T) [Default is width = default, color  =  black,  style  =
              solid].

       -X[a|c|f|r][x-shift[u]]

       -Y[a|c|f|r][y-shift[u]] (more a|)
              Shift plot origin.

       -Z     For  3-D  projections:  expect  each  item to have its own level
              given in the 3rd column, and -N is implicitly set.  (Not  imple-
              mented for paragraph mode).

       -acol=name[^<i>a|] (more a|)
              Set aspatial column associations col=name.

       -e[~]^<i>apattern^<i>a | -e[~]/regexp/[i] (more a|)
              Only accept data records that match the given pattern.

       -f[i|o]colinfo (more a|)
              Specify data types of input and/or output columns.

       -h[i|o][n][+c][+d][+rremark][+rtitle] (more a|)
              Skip or produce header record(s).

       -:[i|o] (more a|)
              Swap 1st and 2nd column on input and/or output.

       -p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more a|)
              Select perspective view. (Not implemented for paragraph mode).

       -t[transp] (more a|)
              Set PDF transparency level in percent.

       -^ or just -
              Print  a  short  message  about  the syntax of the command, then
              exits (NOTE: on Windows just use -).

       -+ or just +
              Print an extensive usage (help) message, including the  explana-
              tion  of  any  module-specific  option  (but  not the GMT common
              options), then exits.

       -? or no arguments
              Print a complete usage (help) message, including the explanation
              of all options, then exits.


EXAMPLES

       To  plot  just the red outlines of the (lon lat text strings) stored in
       the file text.d on a Mercator plot with the given specifications, use

              gmt pstext text.d -R-30/30/-10/20 -Jm0.1i -P -F+f18p,Helvetica,-=0.5p,red -B5 > plot.ps

       To plot a text at the upper left corner of a 10 cm map

              echo TopLeft | gmt pstext -R1/10/1/10 -JX10 -F+cTL -P > plot.ps

       To add a typeset figure caption for a 3-inch wide illustration, use

              gmt pstext -R0/3/0/5 -JX3i -O -h1 -M -N -F+f12,Times-Roman+jLT << EOF >> figure.ps

              This is an unmarked header record not starting with #
              > 0 -0.5 13p 3i j
              @%5%Figure 1.@%% This illustration shows nothing useful, but it still needs
              a figure caption. Highlighted in @;255/0/0;red@;; you can see the locations
              of cities where it is @\_impossible@\_ to get any good Thai food; these are to be avoided.
              EOF


WINDOWS REMARKS

       Note that under Windows, the percent sign (%) is a  variable  indicator
       (like  $  under  Unix).  To indicate a plain percentage sign in a batch
       script you need to repeat it (%%); hence the font  switching  mechanism
       (@%font%  and @%%) may require twice the number of percent signs.  This
       only applies to text inside a script or that otherwise is processed  by
       DOS.  Data  files  that  are opened and read by pstext do not need such
       duplication.


LIMITATIONS

       In paragraph mode, the  presence  of  composite  characters  and  other
       escape  sequences  may  lead  to unfortunate word splitting. Also, if a
       font is requested with an outline pen it will not be used in  paragraph
       mode.   Note  if  any  single  word is wider than your chosen paragraph
       width then the paragraph width is automatically  enlarged  to  fit  the
       widest word.


SEE ALSO

       gmt(1), gmt.conf(5), psclip(1), gmtcolors(5), psconvert(1),
       psbasemap(1), pslegend(1), psxy(1)


COPYRIGHT

       2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe



5.4.2                            Jun 24, 2017                        pstext(1)

gmt5 5.4.2 - Generated Thu Jun 29 16:01:40 CDT 2017
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.