1PSTEXT(1) GMT PSTEXT(1)
2
6 pstext - Plot or typeset text on maps
7
9 pstext [ textfiles ] -Jparameters
10 -Rwest/east/south/north[/zmin/zmax][+r] [ -A ]
11 -B[p|s]parameters [ -D[j|J]dx[/dy][+v[pen]] ] [
12 -F[+a[angle]][+c[justify]][+f[font]][+j[justify]][+h|+l|+r[first]
13 |+ttext|+z[format]] ] [ -Gcolor ] [ -K ] [ -L ] [ -M ] [ -N ] [
14 -O ] [ -P ] [ -Ql|u ] [ -To|O|c|C ] [ [ -Wpen ] [ -Xx_offset ] [
15 -Yy_offset ] [ -U[stamp] ] [ -Z ] [ -acol=name[...] ] [ -eregexp ] [
16 -fflags ] [ -hheaders ] [ -pflags ] [ -ttransp ] [ -:[i|o] ]
17 Note: No space is allowed between the option flag and the associated
19 arguments.
20
22 pstext plots text strings of variable size, font type, and orientation.
23 Various map projections are provided, with the option to draw and anno‐
24 tate the map boundaries. PostScript code is written to standard output.
25 Greek characters, subscript, superscript, and small caps are supported
26 as follows: The sequence @~ toggles between the selected font and Greek
27 (Symbol). @%no% sets the font to no; @%% resets the font to the start‐
28 ing font, @- toggles subscripts on/off, @+ toggles superscript on/off,
29 @# toggles small caps on/off, @;color; changes the font color (@;;
30 resets it), @:size: changes the font size (@:: resets it), and @_ tog‐
31 gles underline on/off. @@ prints the @ sign. @e, @o, @a, @E, @O, @A
32 give the accented Scandinavian characters. Composite characters (over‐
33 strike) may be indicated with the @!<char1><char2> sequence, which will
34 print the two characters on top of each other. To learn the octal codes
35 for symbols not available on the keyboard and some accented European
36 characters, see Section Char-esc-seq and Appendix
37 Chart-Octal-Codes-for-Chars in the GMT Technical Reference and Cook‐
38 book. Note that PS_CHAR_ENCODING must be set to an extended character
39 set in your gmt.conf file in order to use the accented characters.
40 Using the -G or -W options, a rectangle underlying the text may be
41 plotted (does not work for strings with sub/super scripts, symbols, or
42 composite characters, except in paragraph mode (-M)).
43
45 -Jparameters (more ...)
46 Select map projection.
47 -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
49 Specify the region of interest.
50 For perspective view p, optionally append /zmin/zmax. (more ...)
52
54 textfiles
55 This is one or more files containing 1 or more records with (x,
56 y[, font, angle, justify], text). The attributes in brackets can
57 alternatively be set directly via -F. If no files are given,
58 pstext will read standard input. font is a font specification
59 with format [size,][font,][color] where size is text size in
60 points, font is the font to use, and color sets the font color.
61 To draw outline fonts you append =pen to the font specification.
62 The angle is measured in degrees counter-clockwise from horizon‐
63 tal, and justify sets the alignment. If font is not an integer,
64 then it is taken to be a text string with the desired font name
65 (see -L for available fonts). The alignment refers to the part
66 of the text string that will be mapped onto the (x,y) point.
67 Choose a 2 character combination of L, C, R (for left, center,
68 or right) and T, M, B for top, middle, or bottom. e.g., BL for
69 lower left.
70 -A Angles are given as azimuths; convert them to directions using
72 the current projection.
73 -B[p|s]parameters (more ...)
75 Set map boundary frame and axes attributes.
76 -Cdx/dy
78 Sets the clearance between the text and the surrounding box
79 [15%]. Only used if -W or -G are specified. Append the unit you
80 want (cm, inch, or point; if not given we consult
81 PROJ_LENGTH_UNIT) or % for a percentage of the font size.
82 -D[j|J]dx[/dy][+v[pen]]
84 Offsets the text from the projected (x,y) point by dx,dy [0/0].
85 If dy is not specified then it is set equal to dx. Use -Dj to
86 offset the text away from the point instead (i.e., the text jus‐
87 tification will determine the direction of the shift). Using -DJ
88 will shorten diagonal offsets at corners by sqrt(2). Optionally,
89 append +v which will draw a line from the original point to the
90 shifted point; append a pen to change the attributes for this
91 line.
92 -F[+a[angle]][+c[justify]][+f[font]][+j[justify]][+h|+l|+r[first]
94 |+ttext|+z[format]]
95 By default, text will be placed horizontally, using the primary
96 annotation font attributes (FONT_ANNOT_PRIMARY), and centered on
97 the data point. Use this option to override these defaults by
98 specifying up to three text attributes (font, angle, and justi‐
99 fication) directly on the command line. Use +f to set the font
100 (size,fontname,color); if no font info is given then the input
101 file must have this information in one of its columns. Use +a to
102 set the angle; if no angle is given then the input file must
103 have this as a column. Alternatively, use +A to force text-base‐
104 lines to convert into the -90/+90 range. Use +j to set the jus‐
105 tification; if no justification is given then the input file
106 must have this as a column. Items read from the data file should
107 be in the same order as specified with the -F option. Example:
108 -F+f12p,Helvetica-Bold,red+j+a selects a 12p red Helvetica-Bold
109 font and expects to read the justification and angle from the
110 file, in that order, after x, y and before text. In addition,
111 the +c justification lets us use x,y coordinates extracted from
112 the -R string instead of providing them in the input file. For
113 example -F+cTL gets the x_min, y_max from the -R string and
114 plots the text at the Upper Left corner of the map. Normally,
115 the text to be plotted comes from the data record. Instead, use
116 +h or +l to select the text as the most recent segment header or
117 segment label, respectively in a multisegment input file, +r to
118 use the record number (counting up from first), +ttext to set a
119 fixed text string, or +z to format incoming z values to a string
120 using the supplied format [use FORMAT_FLOAT_MAP].
121 -Gcolor
123 Sets the shade or color used for filling the text box [Default
124 is no fill]. Alternatively, use -Gc to plot the text and then
125 use the text dimensions (and -C) to build clip paths and turn
126 clipping on. This clipping can then be turned off later with
127 psclip -C. To not plot the text but activate clipping, use -GC
128 instead.
129 -Jz|Zparameters (more ...)
131 Set z-axis scaling; same syntax as -Jx.
132 -K (more ...)
134 Do not finalize the PostScript plot.
135 -L Lists the font-numbers and font-names available, then exits.
137 -M Paragraph mode. Files must be multiple segment files. Segments
139 are separated by a special record whose first character must be
140 flag [Default is >]. Starting in the 3rd column, we expect to
141 find information pertaining to the typesetting of a text para‐
142 graph (the remaining lines until next segment header). The
143 information expected is (x y [font angle justify] linespace par‐
144 width parjust), where x y font angle justify are defined above
145 (font, angle, and justify can be set via -F), while linespace
146 and parwidth are the linespacing and paragraph width, respec‐
147 tively. The justification of the text paragraph is governed by
148 parjust which may be l(eft), c(enter), r(ight), or j(ustified).
149 The segment header is followed by one or more lines with para‐
150 graph text. Text may contain the escape sequences discussed
151 above. Separate paragraphs with a blank line. Note that here,
152 the justification set via -F+j applies to the box alignment
153 since the text justification is set by parjust.
154 -N Do NOT clip text at map boundaries [Default will clip].
156 -O (more ...)
158 Append to existing PostScript plot.
159 -P (more ...)
161 Select "Portrait" plot orientation.
162 -Q Change all text to either lower or upper case [Default leaves
164 all text as is].
165 -T Specify the shape of the textbox when using -G and/or -W.
167 Choose lower case o to get a straight rectangle [Default].
168 Choose upper case O to get a rounded rectangle. In paragraph
169 mode (-M) you can also choose lower case c to get a concave rec‐
170 tangle or upper case C to get a convex rectangle.
171 -U[[just]/dx/dy/][c|label] (more ...)
173 Draw GMT time stamp logo on plot.
174 -V[level] (more ...)
176 Select verbosity level [c].
177 -Wpen Sets the pen used to draw a rectangle around the text string
179 (see -T) [Default is width = default, color = black, style =
180 solid].
181 -X[a|c|f|r][x-shift[u]]
183 -Y[a|c|f|r][y-shift[u]] (more ...)
185 Shift plot origin.
186 -Z For 3-D projections: expect each item to have its own level
188 given in the 3rd column, and -N is implicitly set. (Not imple‐
189 mented for paragraph mode).
190 -acol=name[...] (more ...)
192 Set aspatial column associations col=name.
193 -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
195 Only accept data records that match the given pattern.
196 -f[i|o]colinfo (more ...)
198 Specify data types of input and/or output columns.
199 -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
201 Skip or produce header record(s).
202 -:[i|o] (more ...)
204 Swap 1st and 2nd column on input and/or output.
205 -p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more ...)
207 Select perspective view. (Not implemented for paragraph mode).
208 -t[transp] (more ...)
210 Set PDF transparency level in percent.
211 -^ or just -
213 Print a short message about the syntax of the command, then
214 exits (NOTE: on Windows just use -).
215 -+ or just +
217 Print an extensive usage (help) message, including the explana‐
218 tion of any module-specific option (but not the GMT common
219 options), then exits.
220 -? or no arguments
222 Print a complete usage (help) message, including the explanation
223 of all options, then exits.
224
226 To plot just the red outlines of the (lon lat text strings) stored in
227 the file text.d on a Mercator plot with the given specifications, use
228 gmt pstext text.d -R-30/30/-10/20 -Jm0.1i -P -F+f18p,Helvetica,-=0.5p,red -B5 > plot.ps
230 To plot a text at the upper left corner of a 10 cm map
232 echo TopLeft | gmt pstext -R1/10/1/10 -JX10 -F+cTL -P > plot.ps
234 To add a typeset figure caption for a 3-inch wide illustration, use
236 gmt pstext -R0/3/0/5 -JX3i -O -h1 -M -N -F+f12,Times-Roman+jLT << EOF >> figure.ps
238 This is an unmarked header record not starting with #
240 > 0 -0.5 13p 3i j
241 @%5%Figure 1.@%% This illustration shows nothing useful, but it still needs
242 a figure caption. Highlighted in @;255/0/0;red@;; you can see the locations
243 of cities where it is @\_impossible@\_ to get any good Thai food; these are to be avoided.
244 EOF
245
247 Note that under Windows, the percent sign (%) is a variable indicator
248 (like $ under Unix). To indicate a plain percentage sign in a batch
249 script you need to repeat it (%%); hence the font switching mechanism
250 (@%font% and @%%) may require twice the number of percent signs. This
251 only applies to text inside a script or that otherwise is processed by
252 DOS. Data files that are opened and read by pstext do not need such
253 duplication.
254
256 In paragraph mode, the presence of composite characters and other
257 escape sequences may lead to unfortunate word splitting. Also, if a
258 font is requested with an outline pen it will not be used in paragraph
259 mode. Note if any single word is wider than your chosen paragraph
260 width then the paragraph width is automatically enlarged to fit the
261 widest word.
262
264 gmt, gmt.conf, psclip, gmtcolors, psconvert, psbasemap, pslegend, psxy
265
267 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
2685.4.5 Feb 24, 2019 PSTEXT(1)