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