1PSLEGEND(1) GMT PSLEGEND(1)
2
6 pslegend - Plot legends on maps
7
9 pslegend [ specfile ]
10 -Drefpoint ] [ -B[p|s]parameters ] [ -Cdx/dy ] [ -Fbox ] [ -Jpa‐
11 rameters ] [ -K ] [ -O ] [ -P ] [ -Rregion ] [ -U[stamp] ] [
12 -V[level] ] [ -Xx_offset ] [ -Yy_offset ] [ -pflags ] [ -ttransp ]
13 Note: No space is allowed between the option flag and the associated
15 arguments.
16
18 pslegend will make legends that can be overlaid on maps. It reads spe‐
19 cific legend-related information from an input file [or stdin]. Unless
20 otherwise noted, annotations will be made using the primary annotation
21 font and size in effect (i.e., FONT_ANNOT_PRIMARY)
22
24 -D[g|j|J|n|x]refpoint+wwidth[/height][+jjustify][+lspacing][+odx[/dy]]
25 Defines the reference point on the map for the legend using one
26 of four coordinate systems: (1) Use -Dg for map (user) coordi‐
27 nates, (2) use -Dj or -DJ for setting refpoint via a 2-char jus‐
28 tification code that refers to the (invisible) map domain rec‐
29 tangle, (3) use -Dn for normalized (0-1) coordinates, or (4) use
30 -Dx for plot coordinates (inches, cm, etc.). All but -Dx
31 requires both -R and -J to be specified. Append
32 +wwidth[/height] to set the width (and height) of the legend box
33 in plot coordinates (inches, cm, etc.). If height is zero or
34 not given then we estimate height based the expected vertical
35 extent of the items to be placed. By default, the anchor point
36 on the legend is assumed to be the bottom left corner (BL), but
37 this can be changed by appending +j followed by a 2-char justi‐
38 fication code justify (see pstext). Note: If -Dj is used then
39 justify defaults to the same as refpoint, if -DJ is used then
40 justify defaults to the mirror opposite of refpoint. Use
41 +lspacing to change the line-spacing factor in units of the cur‐
42 rent font size [1.1]. Finally, add +o to offset the color scale
43 by dx/dy away from the refpoint point in the direction implied
44 by justify (or the direction implied by -Dj or -DJ).
45
47 -B[p|s]parameters (more ...)
48 Set map boundary frame and axes attributes.
49 -Cdx/dy
51 Sets the clearance between the legend frame and the internal
52 items [4p/4p].
53 -F[+cclear‐
55 ances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]][+s[[dx/dy/][shade]]]
56 Without further options, draws a rectangular border around the
57 legend using MAP_FRAME_PEN; specify a different pen with +ppen.
58 Add +gfill to fill the legend box [no fill]. Append +cclearance
59 where clearance is either gap, xgap/ygap, or lgap/rgap/bgap/tgap
60 where these items are uniform, separate in x- and y-direction,
61 or individual side spacings between scale and border. Append +i
62 to draw a secondary, inner border as well. We use a uniform gap
63 between borders of 2p and the MAP_DEFAULTS_PEN unless other val‐
64 ues are specified. Append +r to draw rounded rectangular borders
65 instead, with a 6p corner radius. You can override this radius
66 by appending another value. Finally, append +s to draw an offset
67 background shaded region. Here, dx/dy indicates the shift rela‐
68 tive to the foreground frame [4p/-4p] and shade sets the fill
69 style to use for shading [gray50].
70 -Jparameters (more ...)
72 Select map projection.
73 -K (more ...)
75 Do not finalize the PostScript plot.
76 -O (more ...)
78 Append to existing PostScript plot.
79 -P (more ...)
81 Select "Portrait" plot orientation.
82 -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
84 Specify the region of interest.
85 -U[[just]/dx/dy/][c|label] (more ...)
87 Draw GMT time stamp logo on plot.
88 -V[level] (more ...)
90 Select verbosity level [c].
91 -X[a|c|f|r][x-shift[u]]
93 -Y[a|c|f|r][y-shift[u]] (more ...)
95 Shift plot origin.
96 -p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more ...)
98 Select perspective view.
99 -t[transp] (more ...)
101 Set PDF transparency level in percent.
102 -^ or just -
104 Print a short message about the syntax of the command, then
105 exits (NOTE: on Windows just use -).
106 -+ or just +
108 Print an extensive usage (help) message, including the explana‐
109 tion of any module-specific option (but not the GMT common
110 options), then exits.
111 -? or no arguments
113 Print a complete usage (help) message, including the explanation
114 of all options, then exits.
115
117 specfile
118 This ASCII file contains instructions for the layout of items in
119 the legend. Each legend item is described by a unique record.
120 All records begin with a unique character that is common to all
121 records of the same kind. The order of the legend items is
122 implied by the order of the records. Fourteen different record
123 types are recognized, and the syntax for each of these records
124 are presented below:
125 # comment
127 Records starting with # and blank lines are skipped.
128 A cptname
130 Symbol or cell color fills may be given indirectly via a z-value
131 which can be used for the color look-up via the given CPT cpt‐
132 name. You may switch to other cptname by repeating this com‐
133 mand.
134 B cptname offset height [ optional arguments ]
136 The B record will plot a horizontal color bar, psscale-style in
137 the middle, starting at offset from the left edge, and of the
138 given height. You may add any additional psscale options as
139 well. Any of the modifiers
140 [+e[b|f][<length>]][+h][+ma|c|l|u][+n[<txt>]] may be given
141 height. You may add any additional psscale options as well. Any
142 of the modifiers [+e[b|f][length]][+h][+m[a|c|l|u]][+n[txt]] may
143 be appended to the height argument, while other module options
144 -B -I -L -M -N -S -Z and -p may be appended as optional argu‐
145 ments at the end of the record. See psscale for details on all
146 modifiers and options.
147 C textcolor
149 The C record specifies the color with which the remaining text
150 is to be printed. textcolor can be in the form r/g/b, c/m/y/k, a
151 named color, or an indirect color via z=value* (requires a prior
152 **A* code as well). Use - to reset to default color.
153 D [offset] pen [-|+|=]
155 The D record results in a horizontal line with specified pen
156 across the legend with one quarter of the line-spacing left
157 blank above and below the line. Two gaps of offset units are
158 left blank between the horizontal line and the left and right
159 frame sides [0]. If no pen is given we use MAP_GRID_PEN_PRIMARY,
160 and if pen is set to - then no visible line is drawn (we just
161 remember the location as a possible start/stop point for a ver‐
162 tical line; see V). To not add the quarter line-spacing before
163 the line, add -. To not add the spacing after the line, add +.
164 For no spacing at all, add = [Default places a quarter
165 line-spacing both before and after the line].
166 F fill1 fill2 ... filln
168 Specify fill (color of pattern) for cells. Alternatively, you
169 can specify an indirect color via z=value (requires a prior A
170 code). If only fill1 is given then it is used to fill the
171 entire row, otherwise give one fill value for each active column
172 (see N). If any fill is - then no fill takes place [Default].
173 G gap The G record specifies a vertical gap of the given length. In
175 addition to the standard units (i, c, p) you may use l for
176 lines. A negative gap will move the current line upwards (thus
177 closing a gap).
178 H fontsize|- font|- header
180 The H record plots a centered text string using the specified
181 font parameters. Use - to default to size and type of
182 FONT_TITLE.
183 I imagefile width justification
185 Place an EPS or raster image in the legend justified relative to
186 the current point. The image width determines the size of the
187 image on the page.
188 L fontsize|- font|- justification label
190 The L record plots a (L)eft, (C)entered, or (R)ight-justified
191 text string within a column using the specified font parameters.
192 Use - to default to the size and type of FONT_LABEL.
193 M slon|- slat length [+f][+l[label]][+u] [-Fparam] [ -Rw/e/s/n -Jparam
195 ]
196 Place a map scale in the legend. Specify slon slat, the point on
197 the map where the scale applies (slon is only meaningful for
198 certain oblique projections. If not needed, you must specify -
199 instead). Give length, the length of the scale in km (for other
200 units append e (meter), f (foot), M (mile), n (nautical mile),
201 or u (survey foot)). Append +f for a fancy map scale [Default is
202 plain]. Append +l to the length to select the default label
203 which equals the distance unit (meter, feet, km, miles, nautical
204 miles, survey feet) and is justified on top of the scale [t].
205 Change this by giving your own label (append +llabel). Change
206 label alignment with +aalign (choose among l(eft), r(ight),
207 t(op) , and b(ottom)). Apply +u to append the unit to all dis‐
208 tance annotations along the scale. If you want to place a map
209 panel behind the scale, add a suitable -F panel option (see
210 psbasemap for details on panels as well as map scale modifiers).
211 All +modifiers must be appended to length to make a single
212 string argument. If the -R -J supplied to pslegend is different
213 than the projection needed for the scale (or not given at all,
214 e.g., with -Dx), supply the two optional -R -J settings as well.
215 N [ncolumns or relwidth1 relwidth2 ... relwidthn]
217 Change the number of columns in the legend [1]. This only
218 affects the printing of symbols (S) and labels (L). The number
219 of columns stay in effect until N is used again. To get columns
220 of unequal width, instead provide the relative width of each
221 column separated by whitespace. The sum of these widths are
222 equated to the legend width set via -D. If no argument is given
223 the we set n_columns to 1.
224 P paragraph-mode-header-for-pstext
226 Start a new text paragraph by specifying all the parameters
227 needed (see pstext -M record description). Note that pslegend
228 knows what all those values should be, so normally you can leave
229 the entire record (after P) blank or leave it out all together.
230 If you need to set at least one of the parameters directly, you
231 must specify all and set the ones you want to leave at their
232 default value to -.
233 S [dx1 symbol size fill pen [ dx2 text ]]
235 Plots the selected symbol with specified diameter, fill, and
236 outline (see psxy). The symbol is centered at dx1 from the left
237 margin of the column, with the optional explanatory text start‐
238 ing dx2 from the margin, printed with FONT_ANNOT_PRIMARY. Use -
239 if no fill or outline (pen) is required. Alternatively, the fill
240 may be specified indirectly via z=value and the color is
241 assigned vi the CPT look-up (requires a prior A code). When
242 plotting just a symbol, without text, dx2 and text can be omit‐
243 ted. The dx1 value can also be given as a justification code L,
244 C, R which justifies the symbol with respect to the current col‐
245 umn. If no arguments are given to S then we simply skip to the
246 next column. Three psxy symbols may take special modifiers:
247 front (f), quoted line (q) and vector (v). You can append mod‐
248 ifiers to the symbol and affect how the fronts, quoted lines and
249 vectors are presented (see psxy man page for modifiers). psle‐
250 gend will determine default settings for all modifiers and sec‐
251 ondary arguments if not provided. A few other symbols (the rec‐
252 tangles, ellipse, wedge, mathangle) may take more than a single
253 argument size. Note that for a line segment you should use the
254 horizontal dash symbol (-). If just a single size if given then
255 pslegend will provide reasonable arguments to plot the symbol
256 (See Defaults). Alternatively, combine the required arguments
257 into a single, comma-separated string and use that as the symbol
258 size (again, see psxy for details on the arguments needed).
259 T paragraph-text
261 One or more of these T records with paragraph-text printed with
262 FONT_ANNOT_PRIMARY. To specify special positioning and typeset‐
263 ting arrangements, or to enter a paragraph break, use the
264 optional P record.
265 V [offset] pen
267 The V record draws a vertical line between columns (if more than
268 one) using the selected pen. Here, offset is analogous to the
269 offset for the D records but in the vertical direction [0]. The
270 first time V is used we remember the vertical position of the
271 last D line, and the second time V is set we draw from that past
272 location to the most recent location of the D line. Thus, D
273 must be used to mark the start and stop of a vertical line (so V
274 must follow D). If no horizontal line is desired simply give -
275 as pen to D.
276
278 When attributes are not provided, or extended symbol information (for
279 symbols taking more than just an overall size) are not given as
280 comma-separated quantities, pslegend will provide the following
281 defaults:
282 Front: Front symbol is left-side (here, that means upper side) box,
284 with dimensions 30% of the given symbol size.
285 Vector: Head size is 30% of given symbol size.
287 Ellipse: Minor axis is 65% of major axis (the symbol size), with an
289 azimuth of 0 degrees.
290 Rectangle: Height is 65% of width (the symbol size).
292 Rotated rectangle: Same, with a rotation of 30 degrees.
294 Rounded rectangle: Same as rectangle, but with corner radius of 10% of
296 width.
297 Mathangle: Angles are -10 and 45 degrees, with arrow head size 30% of
299 symbol size.
300 Wedge: Angles are -30 and 30 degrees.
302
304 To add an example of a legend to a Mercator plot (map.ps) with the
305 given specifications, use
306 gmt pslegend -R-10/10/-10/10 -JM6i -F+gazure1 -Dx0.5i/0.5i+w5i/3.3i+jBL+l1.2 \
308 -C0.1i/0.1i -B5f1 << EOF >> map.ps
309 # Legend test for pslegend
310 # G is vertical gap, V is vertical line, N sets # of columns, D draws horizontal line.
311 # H is header, L is label, S is symbol, T is paragraph text, M is map scale.
312 #
313 G -0.1i
314 H 24 Times-Roman My Map Legend
315 D 0.2i 1p
316 N 2
317 V 0 1p
318 S 0.1i c 0.15i p300/12 0.25p 0.3i This circle is hachured
319 S 0.1i e 0.15i yellow 0.25p 0.3i This ellipse is yellow
320 S 0.1i w 0.15i green 0.25p 0.3i This wedge is green
321 S 0.1i f0.1i+l+t 0.25i blue 0.25p 0.3i This is a fault
322 S 0.1i - 0.15i - 0.25p,- 0.3i A dashed contour
323 S 0.1i v0.1i+a40+e 0.25i magenta 0.25p 0.3i This is a vector
324 S 0.1i i 0.15i cyan 0.25p 0.3i This triangle is boring
325 V 0 1p
326 D 0.2i 1p
327 N 1
328 M 5 5 600+u f
329 G 0.05i
330 I SOEST_logo.ras 3i CT
331 G 0.05i
332 B colors.cpt 0.2i 0.2i
333 G 0.05i L 9 4 R Smith et al., @%5%J. Geophys. Res., 99@%%, 2000
334 G 0.1i
335 P
336 T Let us just try some simple text that can go on a few lines.
337 T There is no easy way to predetermine how many lines will be required,
338 T so we may have to adjust the box height to get the right size box.
339 EOF
340
342 As -D suggests, leaving the height off forces a calculation of the
343 expected height. This is an exact calculation except in the case of
344 legends that place paragraph text. Here we simply do a first-order
345 estimate of how many typeset lines might appear. Without access to font
346 metrics this estimate will occasionally be off by 1 line. If so, note
347 the reported height (with -V) and specify a slightly larger or smaller
348 height in -D.
349
351 Note that under Windows, the percent sign (%) is a variable indicator
352 (like $ under Unix). To indicate a plain percentage sign in a batch
353 script you need to repeat it (%%); hence the font switching mechanism
354 (@%font% and @%%) may require twice the number of percent signs. This
355 only applies to text inside a script or that otherwise is processed by
356 DOS. Data files that are opened and read by pslegend do not need such
357 duplication.
358
360 gmt, gmt.conf, gmtcolors, gmtlogo psbasemap, pstext, psxy
361
363 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
3645.4.5 Feb 24, 2019 PSLEGEND(1)