pstext - Plot or typeset text on maps
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 ]
[ -K ] [ -L ] [ -M ] [ -N ] [ -O ] [
-P ] [ -Ql|u ] [
-To|O|c|C ] [ [ -Wpen ] [
-Xx_offset ] [ -Yy_offset ] [
-U[stamp] ] [ -Z ] [
-acol=name[...] ] [ -eregexp ] [ -fflags
] [ -hheaders ] [ -pflags ] [ -ttransp ] [
-:[i|o] ]
Note: No space is allowed between the option flag and the
associated arguments.
pstext plots text strings of variable size, font type, and
orientation. Various map projections are provided, with the option to draw
and annotate 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 starting 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
@_ toggles underline on/off. @@ prints the @ sign. @e, @o, @a, @E, @O, @A
give the accented Scandinavian characters. Composite characters (overstrike)
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 Cookbook. 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)).
For perspective view p, optionally append
/zmin/zmax. (more ...)
- 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 horizontal, 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.
- -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 justification 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 justification) 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-baselines to convert into the -90/+90 range. Use +j to
set the justification; 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.
- -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 paragraph (the
remaining lines until next segment header). The information expected is
(x y [font angle justify] linespace parwidth
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, respectively. 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 paragraph 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].
- -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
rectangle or upper case C to get a convex rectangle.
- -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]]
- -Z
- For 3-D projections: expect each item to have its own level given in the
3rd column, and -N is implicitly set. (Not implemented for
paragraph mode).
- -:[i|o] (more ...)
- Swap 1st and 2nd column on input and/or output.
- -^ 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 explanation 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.
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
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.
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.
gmt, gmt.conf, psclip, gmtcolors, psconvert, psbasemap, pslegend,
psxy
2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F.
Wobbe