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