pstext
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]][+h][+j[justify]][+l] ]
[ -Gcolor ] [ -Jz|Zparameters ] [ -K ]
[ -L ] [ -M ] [ -N ] [ -O ] [ -P ] [
-Ql|u ] [
-To|O|c|C ] [
[ -Wpen ]
[ -X[a|c|f|r][x-shift[u]] ]
[ -Y[a|c|f|r][y-shift[u]] ]
[ -U[just/dx/dy/][c|label] ]
[ -Z ] [ -acol=name[...] ]
[ -ccopies ]
[ -f[i|o]colinfo ]
[ -h[i|o][n][+c][+d][+rremark][+rtitle] ]
[ -icols[l][sscale][ooffset][,...] ]
[ -p[x|y|z]azim/elev[/zlevel][+wlon0/lat0[/z0]][+vx0/y0] ]
[ -t[transp] ]
[ -ocols[,...] ]
[ -:[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 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 4.16 and
Appendix F 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)).
Required Arguments
- -Jparameters (more ...)
- Select map projection.
- -R[unit]xmin/xmax/ymin/ymax[r] (more ...)
- Specify the region of interest.
For perspective view p, optionally append /zmin/zmax. (more ...)
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 filo. 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 fontname (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 ...)
- Set map boundary intervals.
- -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]][+h][+j[justify]][+l]
- 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. 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.
- -Gcolor
- Sets the shade or color used for filling the text box [Default is no
fill]. Alternatively, use -Gc to use text (and -C) to build
clip paths and turn clipping on. This clipping can then be turned
off later and the text may be finally plotted using psclip -Ct
(provided only one pstext call was issued).
- -Jz|Zparameters (more ...)
- Set z-axis scaling; same syntax as -Jx.
- -K (more ...)
- 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 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.
- -N
- Do NOT clip text at map boundaries [Default will clip].
- -O (more ...)
- Append to existing PostScript plot.
- -P (more ...)
- Select “Portrait” 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
rectangle or upper case C to get a convex rectangle.
- -U[just/dx/dy/][c|label] (more ...)
- Draw GMT time stamp logo on plot.
- -V[level] (more ...)
- 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 ...)
- 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 implemented for
paragraph mode).
- -acol=name[...] (more ...)
- Set aspatial column associations col=name.
- -ccopies (more ...)
- Specify number of plot copies [Default is 1].
- -f[i|o]colinfo (more ...)
- Specify data types of input and/or output columns.
- -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
- Skip or produce header record(s).
- -:[i|o] (more ...)
- Swap 1st and 2nd column on input and/or output.
- -p[x|y|z]azim/elev[/zlevel][+wlon0/lat0[/z0]][+vx0/y0] (more ...)
- Select perspective view. (Not implemented for paragraph mode).
- -t[transp] (more ...)
- Set PDF transparency level in percent.
- -^
- Print a short message about the syntax of the command, then exits (NOTE: on Windows use just -).
- +
- Print an extensive usage (help) message, including the explanation of
any module-specific option (but not the GMT common options), then exits.
- -?
- Print a complete usage (help) message, including the explanation of
options, then exits.
- --version
- Print GMT version and exit.
- --show-datadir
- Print full path to GMT share directory and exit.
Examples
To plot just the red outlines of the (lon at 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 -H -M -N << EOF >> figure.ps
This is an optional header record
> 0 -0.5 12 0 4 LT 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
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.
The -N option does not adjust the BoundingBox information so you may
have to post-process the PostScript output with ps2raster to obtain a
correct BoundingBox.