1PSTEXT(1) Generic Mapping Tools PSTEXT(1)
2
6 pstext - To plot text strings on maps
7
9 pstext textfile -Jparameters -Rwest/east/south/north[r] [ -A ] [
10 -B[p|s]parameters ] [ -Cdx/dy ] [ -D[j]dx[/dy][v[pen] ] [
11 -Eazim/elev[+wlon/lat[/z]][+vx0/y0] ] [ -Gcolor ] [ -H[i][nrec] ] [
12 -Jz|Zparameters ] [ -K ] [ -L ] [ -N ] [ -O ] [ -P ] [ -Spen ] [
13 -U[just/dx/dy/][c|label] ] [ -V ] [ -W[color,][o|O|c|C[pen]] ] [
14 -X[a|c|r][x-shift[u]] ] [ -Y[a|c|r][y-shift[u]] ] [ -Z[zlevel|+] ] [
15 -:[i|o] ] [ -ccopies ] [ -f[i|o]colinfo ] [ -m[flag] ]
16
18 pstext plots text strings of variable size, font type, and orientation.
19 Various map projections are provided, with the option to draw and anno‐
20 tate the map boundaries. PostScript code is written to standard output.
21 Greek characters, subscript, superscript, and small caps are supported
22 as follows: The sequence @~ toggles between the selected font and Greek
23 (Symbol). @%no% sets the font to no; @%% resets the font to the start‐
24 ing font, @- toggles subscripts on/off, @+ toggles superscript on/off,
25 @# toggles small caps on/off, @;color; changes the font color (@;;
26 resets it), @:size: changes the font size (@:: resets it), and @_ tog‐
27 gles underline on/off. @@ prints the @ sign. @e, @o, @a, @E, @O, @A
28 give the accented Scandinavian characters. Composite characters (over‐
29 strike) may be indicated with the @!<char1><char2> sequence, which will
30 print the two characters on top of each other. To learn the octal
31 codes for symbols not available on the keyboard and some accented Euro‐
32 pean characters, see Section 4.16 and Appendix F in the GMT Technical
33 Reference and Cookbook. Note that CHAR_ENCODING must be set to an
34 extended character set in your .gmtdefaults4 file in order to use the
35 accented characters. Using the -W option, a colored rectangle underly‐
36 ing the text may be plotted (Does not work for strings with sub/super
37 scripts, symbols, or composite characters, except in paragraph mode
38 (-m)).
39 textfile
41 This file contains 1 or more records with (x, y, size, angle,
42 fontno, justify, text). If no file is given, pstext will read
43 standard input. size is text size in points, angle is measured
44 in degrees counter-clockwise from horizontal, fontno sets the
45 font type, justify sets the alignment. If fontno is not an
46 integer, then it is taken to be a text string with the desired
47 fontname. See the gmtdefaults man page for names and numbers of
48 available fonts (or run pstext -L). The alignment refers to the
49 part of the text string that will be mapped onto the (x,y)
50 point. Choose a 2 character combination of L, C, R (for left,
51 center, or right) and T, M, B for top, middle, or bottom. e.g.,
52 BL for lower left.
53 -J Selects the map projection. Scale is UNIT/degree, 1:xxxxx, or
55 width in UNIT (upper case modifier). UNIT is cm, inch, or m,
56 depending on the MEASURE_UNIT setting in .gmtdefaults4, but this
57 can be overridden on the command line by appending c, i, or m to
58 the scale/width value. When central meridian is optional,
59 default is center of longitude range on -R option. Default
60 standard parallel is the equator. For map height, max dimen‐
61 sion, or min dimension, append h, +, or - to the width, respec‐
62 tively.
63 More details can be found in the psbasemap man pages.
64 CYLINDRICAL PROJECTIONS:
66 -Jclon0/lat0/scale (Cassini)
68 -Jcyl_stere/[lon0/[lat0/]]scale (Cylindrical Stereographic)
69 -Jj[lon0/]scale (Miller)
70 -Jm[lon0/[lat0/]]scale (Mercator)
71 -Jmlon0/lat0/scale (Mercator - Give meridian and standard paral‐
72 lel)
73 -Jo[a]lon0/lat0/azimuth/scale (Oblique Mercator - point and
74 azimuth)
75 -Jo[b]lon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
76 -Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point and
77 pole)
78 -Jq[lon0/[lat0/]]scale (Cylindrical Equidistant)
79 -Jtlon0/[lat0/]scale (TM - Transverse Mercator)
80 -Juzone/scale (UTM - Universal Transverse Mercator)
81 -Jy[lon0/[lat0/]]scale (Cylindrical Equal-Area)
82 CONIC PROJECTIONS:
84 -Jblon0/lat0/lat1/lat2/scale (Albers)
86 -Jdlon0/lat0/lat1/lat2/scale (Conic Equidistant)
87 -Jllon0/lat0/lat1/lat2/scale (Lambert Conic Conformal)
88 -Jpoly/[lon0/[lat0/]]scale ((American) Polyconic)
89 AZIMUTHAL PROJECTIONS:
91 -Jalon0/lat0[/horizon]/scale (Lambert Azimuthal Equal-Area)
93 -Jelon0/lat0[/horizon]/scale (Azimuthal Equidistant)
94 -Jflon0/lat0[/horizon]/scale (Gnomonic)
95 -Jglon0/lat0[/horizon]/scale (Orthographic)
96 -Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale
97 (General Perspective).
98 -Jslon0/lat0[/horizon]/scale (General Stereographic)
99 MISCELLANEOUS PROJECTIONS:
101 -Jh[lon0/]scale (Hammer)
103 -Ji[lon0/]scale (Sinusoidal)
104 -Jkf[lon0/]scale (Eckert IV)
105 -Jk[s][lon0/]scale (Eckert VI)
106 -Jn[lon0/]scale (Robinson)
107 -Jr[lon0/]scale (Winkel Tripel)
108 -Jv[lon0/]scale (Van der Grinten)
109 -Jw[lon0/]scale (Mollweide)
110 NON-GEOGRAPHICAL PROJECTIONS:
112 -Jp[a]scale[/origin][r|z] (Polar coordinates (theta,r))
114 -Jxx-scale[d|l|ppow|t|T][/y-scale[d|l|ppow|t|T]] (Linear, log,
115 and power scaling)
116 -Jz Sets the vertical scaling (for 3-D maps). Same syntax as -Jx.
118 -R xmin, xmax, ymin, and ymax specify the Region of interest. For
120 geographic regions, these limits correspond to west, east,
121 south, and north and you may specify them in decimal degrees or
122 in [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r if lower left
123 and upper right map coordinates are given instead of w/e/s/n.
124 The two shorthands -Rg and -Rd stand for global domain (0/360
125 and -180/+180 in longitude respectively, with -90/+90 in lati‐
126 tude). Alternatively, specify the name of an existing grid file
127 and the -R settings (and grid spacing, if applicable) are copied
128 from the grid. For calendar time coordinates you may either
129 give (a) relative time (relative to the selected TIME_EPOCH and
130 in the selected TIME_UNIT; append t to -JX|x), or (b) absolute
131 time of the form [date]T[clock] (append T to -JX|x). At least
132 one of date and clock must be present; the T is always required.
133 The date string must be of the form [-]yyyy[-mm[-dd]] (Gregorian
134 calendar) or yyyy[-Www[-d]] (ISO week calendar), while the clock
135 string must be of the form hh:mm:ss[.xxx]. The use of delim‐
136 iters and their type and positions must be exactly as indicated
137 (however, input, output and plot formats are customizable; see
138 gmtdefaults).
139
141 No space between the option flag and the associated arguments.
142 -A Angles are given as azimuths; convert them to directions using
144 the current projection.
145 -B Sets map boundary annotation and tickmark intervals; see the
147 psbasemap man page for all the details.
148 -C Sets the clearance between the text and the surrounding box
150 [15%]. Only used if -W is specified. Append the unit you want
151 (cm, inch, meter. or point; if not given we consult MEA‐
152 SURE_UNIT) or % for a percentage of the font size.
153 -D Offsets the text from the projected (x,y) point by dx,dy [0/0].
155 If dy is not specified then it is set equal to dx. Use -Dj to
156 offset the text away from the point instead (i.e. the text's
157 justification will determine the direction of the shift).
158 Optionally, append v which will draw a line from the original
159 point to the shifted point; append a pen to change the
160 attributes for this line. (See SPECIFYING PENS below).
161 -E Sets the viewpoint's azimuth and elevation (for perspective
163 view) [180/90]. For frames used for animation, you may want to
164 append + to fix the center of your data domain (or specify a
165 particular world coordinate point with +wlon0/lat[/z]) which
166 will project to the center of your page size (or specify the
167 coordinates of the projected veiw point with +vx0/y0). (Not
168 implemented for paragraph mode).
169 -G Sets the shade or color used for drawing the text [Default is
171 BASEMAP_FRAME_RGB, the current frame color (by default black)]
172 (See SPECIFYING COLOR below).
173 -H Input file(s) has header record(s). If used, the default number
175 of header records is N_HEADER_RECS. Use -Hi if only input data
176 should have header records [Default will write out header
177 records if the input data have them]. Blank lines and lines
178 starting with # are always skipped.
179 -K More PostScript code will be appended later [Default terminates
181 the plot system].
182 -L Lists the font-numbers and font-names available, then exits.
184 -N Do NOT clip text at map boundaries [Default will clip].
186 -O Selects Overlay plot mode [Default initializes a new plot sys‐
188 tem].
189 -P Selects Portrait plotting mode [Default is Landscape, see gmtde‐
191 faults to change this].
192 -S Draw text outline. Append pen attributes. (Not implemented for
194 paragraph mode).
195 -U Draw Unix System time stamp on plot. By adding just/dx/dy/, the
197 user may specify the justification of the stamp and where the
198 stamp should fall on the page relative to lower left corner of
199 the plot. For example, BL/0/0 will align the lower left corner
200 of the time stamp with the lower left corner of the plot.
201 Optionally, append a label, or c (which will plot the command
202 string.). The GMT parameters UNIX_TIME, UNIX_TIME_POS, and
203 UNIX_TIME_FORMAT can affect the appearance; see the gmtdefaults
204 man page for details. The time string will be in the locale set
205 by the environment variable TZ (generally local time).
206 -V Selects verbose mode, which will send progress reports to stderr
208 [Default runs "silently"].
209 -W Paint a rectangle beneath the text string. Set color [Default
211 is no fill]. Append o to draw rectangle outline, add a pen to
212 specify pen attributes [width = 1, color = black, texture =
213 solid]. use a comma to separate the fill information from the
214 outline information if both are present. Choose upper case O to
215 get a rounded rectangle. Choose lower case c to get a concave
216 rectangle (only in paragraph mode). Choose upper case C to get
217 a convex rectangle (only in paragraph mode). (See also SPECIFY‐
218 ING PENS and SPECIFYING COLOR below).
219 -X -Y Shift plot origin relative to the current origin by (x-shift,y-
221 shift) and optionally append the length unit (c, i, m, p). You
222 can prepend a to shift the origin back to the original position
223 after plotting, or prepend r [Default] to reset the current
224 origin to the new location. If -O is used then the default (x-
225 shift,y-shift) is (0,0), otherwise it is (r1i, r1i) or (r2.5c,
226 r2.5c). Alternatively, give c to align the center coordinate (x
227 or y) of the plot with the center of the page based on current
228 page size.
229 -Z For 3-D projections: Sets the z-level of the basemap [0]. If
231 -Z+ is given we expect each item to have its own level given in
232 the 3rd column, and -N is implicitly set. (Not implemented for
233 paragraph mode).
234 -: Toggles between (longitude,latitude) and (latitude,longitude)
236 input and/or output. [Default is (longitude,latitude)]. Append
237 i to select input only or o to select output only. [Default
238 affects both].
239 -c Specifies the number of plot copies. [Default is 1].
241 -f Special formatting of input and/or output columns (time or geo‐
243 graphical data). Specify i or o to make this apply only to
244 input or output [Default applies to both]. Give one or more
245 columns (or column ranges) separated by commas. Append T (abso‐
246 lute calendar time), t (relative time in chosen TIME_UNIT since
247 TIME_EPOCH), x (longitude), y (latitude), or f (floating point)
248 to each column or column range item. Shorthand -f[i|o]g means
249 -f[i|o]0x,1y (geographic coordinates).
250 -m Paragraph mode. Files must be multiple segment files. Segments
252 are separated by a special record whose first character must be
253 flag [Default is '>']. Starting in the 3rd column, we expect to
254 find information pertaining to the typesetting of a text para‐
255 graph (the remaining lines until next segment header). The
256 information expected is (x y size angle fontno justify linespace
257 parwidth parjust), where x y size angle fontno justify are
258 defined above, while linespace and parwidth are the linespacing
259 and paragraph width, respectively. The justification of the
260 text paragraph is governed by parjust which may be l(eft),
261 c(enter), r(ight), or j(ustified). The segment header is fol‐
262 lowed by one or more lines with paragraph text. Text may con‐
263 tain the escape sequences discussed above. Separate paragraphs
264 with a blank line.
265 SPECIFYING PENS
267 pen The attributes of lines and symbol outlines as defined by pen is
268 a comma delimetered list of width, color and texture, each of
269 which is optional. width can be indicated as a measure (points,
270 centimeters, inches) or as faint, thin[ner|nest], thick[er|est],
271 fat[ter|test], or obese. color specifies a gray shade or color
272 (see SPECIFYING COLOR below). texture is a combination of
273 dashes `-' and dots `.'.
274 SPECIFYING COLOR
276 color The color of lines, areas and patterns can be specified by a
277 valid color name; by a gray shade (in the range 0-255); by a
278 decimal color code (r/g/b, each in range 0-255; h-s-v, ranges
279 0-360, 0-1, 0-1; or c/m/y/k, each in range 0-1); or by a hexa‐
280 decimal color code (#rrggbb, as used in HTML). See the gmtcol‐
281 ors manpage for more information and a full list of color names.
282
284 To plot the outlines of the text strings stored in the file text.d on a
285 Mercator plot with the given specifications, use
286 pstext text.d -R-30/30/-10/20 -Jm0.1i -P -B5 -S0.5p > plot.ps
288 To add a typeset figure caption for a 3-inch wide illustration, use
290 pstext -R0/3/0/5 -JX3i -O -H -m -N << EOF >> figure.ps
292 This is an optional header record
293 > 0 -0.5 12 0 4 LT 13p 3i j
294 @%5%Figure 1.@%% This illustration shows nothing useful, but it still
295 needs
296 a figure caption. Highlighted in @;255/0/0;red@;; you can see the
297 locations
298 of cities where it is @_impossible@_ to get any good Thai food; these
299 are to be avoided.
300 EOF
301
303 Note that under Windows, the percent sign (%) is a variable indicator
304 (like $ under Unix). To indicate a plain percentage sign in a batch
305 script you need to repeat it (%%); hence the font switching mechanism
306 (@%font% and @%%) may require twice the number of percent signs. This
307 only applies to text inside a script or that otherwise is processed by
308 DOS. Data files that are opened and read by pstext do not need such
309 duplication.
310
312 In paragraph mode, the presence of composite characters and other
313 escape sequences may lead to unfortunate word splitting.
314 The -N option does not adjust the BoundingBox information so you may
315 have to post-process the PostScript output with epstool or ps2epsi to
316 obtain a correct BoundingBox.
317
319 GMT(1), gmtcolors(5), psbasemap(1), pslegend(1), psxy(1)
320GMT 4.5.6 10 Mar 2011 PSTEXT(1)