1PSLEGEND(1) Generic Mapping Tools PSLEGEND(1)
2
6 pslegend - To plot a map legend
7
9 pslegend textfile -D[x]lon/lat/width/height/just -Jparameters
10 -Rwest/east/south/north[r] [ -Cdx/dy ] [ -F ] [ -Gfill ] [ -K ] [
11 -Lspacing ] [ -O ] [ -P ] [ -S[script] ] [ -U[just/dx/dy/][c|label] ] [
12 -V ] [ -X[a|c|r][x-shift[u]] ] [ -ccopies ] [ -Y[a|c|r][y-shift[u]] ]
13
15 pslegend will make legends that can be overlaid on maps. It reads spe‐
16 cific legend-related information from an input file [or stdin].
17 Because all the elements of the legend can already be created with
18 other tools (psxy, pstext) we use those tools by creating a batch job
19 of commands that are executed to make the final PostScript overlay.
20 Because of this process, the option exists to just output the script
21 which can then be fine-tuned manually. Unless otherwise noted, annota‐
22 tions will be made using the annotation font and size in effect.
23 textfile
25 This file contains instruction for the layout of items in the
26 legend. Each legend item is described by a unique record. All
27 records begin with a unique character that is common to all
28 records of the same kind. The order of the legend items is
29 implied by the order of the records. Ten different record types
30 are recognized, and the syntax for each of these records are
31 presented below:
32 # Comment records
34 Records starting with # and blank lines are skipped.
35 B cptname offset height [ optional arguments ]
37 The B record will plot a horizontal color bar, psscale-style in
38 the middle, starting at offset from the left edge, and of the
39 given height. You may add any additional psscale options from
40 the list: -A -B -E -I -L -M -N -S and -Z.
41 C textcolor
43 The C record specifies the color with which the remaining text
44 is to be printed. textcolor can be in the form r/g/b, c/m/y/k,
45 or a named color.
46 D offset pen
48 The D record results in a horizontal line across the legend.
49 The line starts and stops offset units from the frame sides, and
50 is drawn using the specified pen. (See SPECIFYING PENS below).
51 G gap The G record specifies a vertical gap of the given length. In
53 addition to the standard units (i, c, p) you may use l for
54 lines.
55 H fontsize font Header
57 The H record plots a centered text string using the specified
58 font parameters.
59 I imagefile width justification
61 Place an EPS or Sun raster image in the legend justified rela‐
62 tive to the current point. The image width determines the size
63 of the image on the page.
64 L fontsize font justification Label
66 The L record plots a (L)eft, (C)entered, or (R)ight-justified
67 text string using the specified font parameters.
68 M slon|- slat length f|p [ -Rw/e/s/n -Jparam ]
70 Place a map scale in the legend. Specify slon slat, the point
71 on the map where the scale applies (slon is only meaningful for
72 certain oblique projections. If not needed, you must specify -
73 instead), length, the length of the scale in km (append m or n
74 for miles or nautical miles), and f|p for fancy or plain scale.
75 If the -R -J supplied to pslegend is different than the projec‐
76 tion needed for the scale, supply the optional -R -J settings as
77 well. Note that length can have :label:just appended, where
78 label replaces the default label (unless - is given) and just
79 (l|r|t|b) dictates where the label is placed [Default is t].
80 Use u to treat the label as distance units appended to each
81 annotation.
82 N ncolums
84 Change the number of columns in the legend [1].
85 S dx1 symbol size fill pen dx2 text
87 Plots the selected symbol with specified size, fill, and out‐
88 line. The symbol is centered at dx1 from the left margin of the
89 column, with the explanatory text starting dx2 from the margin.
90 Use - if no fill is required. Two psxy symbols front (f) and
91 vector (v) require special attention. You must prepend the
92 length of the desired item to the rest of the symbol argument;
93 this will be used internally to set the correct fault or vector
94 length and will be stripped before passing the arguments to
95 psxy.
96 > <paragraph mode header for pstext>
98 Start a new text paragraph by specifying all the parameters
99 needed (see pstext -M description). Note that pslegend knows
100 what all those values should be, so normally you can leave the
101 entire record (after >) blank. If you need to set at least one
102 of the parameters directly, you must specify all and set the
103 ones you want to leave at their default value to -.
104 T paragraph-text
106 One or more of these T records with text must follow after the >
107 record.
108 V offset pen
110 The V record draws a vertical line between columns (if more than
111 one) using the selected pen (See SPECIFYING PENS below). offset
112 is analogous to the offset for the D records but in the vertical
113 direction.
114 -D Positions the legend and specifies its size. The just is a
116 2-char justification string (see pstext) that relates the given
117 position to a point on the rectangular legend box. If you want
118 to specify the position in projected units (i.e., inches or cm),
119 use -Dx.
120 -J Selects the map projection. Scale is UNIT/degree, 1:xxxxx, or
122 width in UNIT (upper case modifier). UNIT is cm, inch, or m,
123 depending on the MEASURE_UNIT setting in .gmtdefaults4, but this
124 can be overridden on the command line by appending c, i, or m to
125 the scale/width value. When central meridian is optional,
126 default is center of longitude range on -R option. Default
127 standard parallel is the equator. For map height, max dimen‐
128 sion, or min dimension, append h, +, or - to the width, respec‐
129 tively.
130 More details can be found in the psbasemap man pages.
131 CYLINDRICAL PROJECTIONS:
133 -Jclon0/lat0/scale (Cassini)
135 -Jcyl_stere/[lon0/[lat0/]]scale (Cylindrical Stereographic)
136 -Jj[lon0/]scale (Miller)
137 -Jm[lon0/[lat0/]]scale (Mercator)
138 -Jmlon0/lat0/scale (Mercator - Give meridian and standard paral‐
139 lel)
140 -Jo[a]lon0/lat0/azimuth/scale (Oblique Mercator - point and
141 azimuth)
142 -Jo[b]lon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
143 -Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point and
144 pole)
145 -Jq[lon0/[lat0/]]scale (Cylindrical Equidistant)
146 -Jtlon0/[lat0/]scale (TM - Transverse Mercator)
147 -Juzone/scale (UTM - Universal Transverse Mercator)
148 -Jy[lon0/[lat0/]]scale (Cylindrical Equal-Area)
149 CONIC PROJECTIONS:
151 -Jblon0/lat0/lat1/lat2/scale (Albers)
153 -Jdlon0/lat0/lat1/lat2/scale (Conic Equidistant)
154 -Jllon0/lat0/lat1/lat2/scale (Lambert Conic Conformal)
155 AZIMUTHAL PROJECTIONS:
157 -Jalon0/lat0[/horizon]/scale (Lambert Azimuthal Equal-Area)
159 -Jelon0/lat0[/horizon]/scale (Azimuthal Equidistant)
160 -Jflon0/lat0[/horizon]/scale (Gnomonic)
161 -Jglon0/lat0[/horizon]/scale (Orthographic)
162 -Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale
163 (General Perspective).
164 -Jslon0/lat0[/horizon][/slat]/scale (General Stereographic)
165 MISCELLANEOUS PROJECTIONS:
167 -Jh[lon0/]scale (Hammer)
169 -Ji[lon0/]scale (Sinusoidal)
170 -Jkf[lon0/]scale (Eckert IV)
171 -Jk[s][lon0/]scale (Eckert IV)
172 -Jn[lon0/]scale (Robinson)
173 -Jr[lon0/]scale (Winkel Tripel)
174 -Jv[lon0/]scale (Van der Grinten)
175 -Jw[lon0/]scale (Mollweide)
176 NON-GEOGRAPHICAL PROJECTIONS:
178 -Jp[a]scale[/origin][r|z] (Polar coordinates (theta,r))
180 -Jxx-scale[d|l|ppow|t|T][/y-scale[d|l|ppow|t|T]] (Linear, log,
181 and power scaling)
182 -R xmin, xmax, ymin, and ymax specify the Region of interest. For
184 geographic regions, these limits correspond to west, east,
185 south, and north and you may specify them in decimal degrees or
186 in [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r if lower left
187 and upper right map coordinates are given instead of w/e/s/n.
188 The two shorthands -Rg and -Rd stand for global domain (0/360
189 and -180/+180 in longitude respectively, with -90/+90 in lati‐
190 tude). For calendar time coordinates you may either give (a)
191 relative time (relative to the selected TIME_EPOCH and in the
192 selected TIME_UNIT; append t to -JX|x), or (b) absolute time of
193 the form [date]T[clock] (append T to -JX|x). At least one of
194 date and clock must be present; the T is always required. The
195 date string must be of the form [-]yyyy[-mm[-dd]] (Gregorian
196 calendar) or yyyy[-Www[-d]] (ISO week calendar), while the clock
197 string must be of the form hh:mm:ss[.xxx]. The use of delim‐
198 iters and their type and positions must be exactly as indicated
199 (however, input, output and plot formats are customizable; see
200 gmtdefaults).
201
203 No space between the option flag and the associated arguments.
204 -C Sets the clearance between the legend frame and the internal
206 items [0.15c/0.15c (or 0.05i/0.05i)].
207 -F Draws a border around the legend using FRAME_PEN.
209 -G Select fill shade, color or pattern of the legend box [Default
211 is no fill]. (See SPECIFYING FILL below).
212 -K More PostScript code will be appended later [Default terminates
214 the plot system].
215 -L Sets the linespacing factor in units of the current annotation
217 font size [1.1].
218 -O Selects Overlay plot mode [Default initializes a new plot sys‐
220 tem].
221 -P Selects Portrait plotting mode [Default is Landscape, see gmtde‐
223 faults to change this].
224 -S Instead of writing the PostScript plot [Default], output the GMT
226 script used to make the legend to standard output, or optionally
227 to the file script.
228 -U Draw Unix System time stamp on plot. By adding just/dx/dy/, the
230 user may specify the justification of the stamp and where the
231 stamp should fall on the page relative to lower left corner of
232 the plot. For example, BL/0/0 will align the lower left corner
233 of the time stamp with the lower left corner of the plot.
234 Optionally, append a label, or c (which will plot the command
235 string.). The GMT parameters UNIX_TIME, UNIX_TIME_POS, and
236 UNIX_TIME_FORMAT can affect the appearance; see the gmtdefaults
237 man page for details. The time string will be in the locale set
238 by the environment variable TZ (generally local time).
239 -V Selects verbose mode, which will send progress reports to stderr
241 [Default runs "silently"].
242 -X -Y Shift plot origin relative to the current origin by (x-shift,y-
244 shift) and optionally append the length unit (c, i, m, p). You
245 can prepend a to shift the origin back to the original position
246 after plotting, or prepend r [Default] to reset the current
247 origin to the new location. If -O is used then the default (x-
248 shift,y-shift) is (0,0), otherwise it is (r1i, r1i) or (r2.5c,
249 r2.5c). Alternatively, give c to align the center coordinate (x
250 or y) of the plot with the center of the page based on current
251 page size.
252 -c Specifies the number of plot copies. [Default is 1].
254 SPECIFYING PENS
256 pen The attributes of lines and symbol outlines as defined by pen is
257 a comma delimetered list of width, color and texture, each of
258 which is optional. width can be indicated as a measure (points,
259 centimeters, inches) or as faint, thin[ner|nest], thick[er|est],
260 fat[ter|test], or obese. color specifies a grey shade or color
261 (see SPECIFYING COLOR below). texture is a combination of
262 dashes `-' and dots `.'.
263 SPECIFYING FILL
265 fill The attribute fill specifies the solid shade or solid color (see
266 SPECIFYING COLOR below) or the pattern used for filling poly‐
267 gons. Patterns are specified as pdpi/pattern, where pattern
268 gives the number of the built-in pattern (1-90) or the name of a
269 Sun 1-, 8-, or 24-bit raster file. The dpi sets the resolution
270 of the image. For 1-bit rasters: use Pdpi/pattern for inverse
271 video, or append :Fcolor[B[color]] to specify fore- and back‐
272 ground colors (use color = - for transparency). See GMT Cook‐
273 book & Technical Reference Appendix E for information on indi‐
274 vidual patterns.
275 SPECIFYING COLOR
277 color The color of lines, areas and patterns can be specified by a
278 valid color name; by a grey shade (in the range 0-255); by a
279 decimal color code (r/g/b, each in range 0-255; h-s-v, ranges
280 0-360, 0-1, 0-1; or c/m/y/k, each in range 0-1); or by a hexa‐
281 decimal color code (#rrggbb, as used in HTML). See the gmtcol‐
282 ors manpage for more information and a full list of color names.
283
285 To add an example of a legend to a Mercator plot (map.ps) with the
286 given specifications, use
287 pslegend -R-10/10/-10/10 -JM4i -G255 -D0/0/4i/3i/BL << EOF >> map.ps
289 G -0.15i
290 H 24 Times-Roman My Map Legend
291 G 0.05i
292 D 0.2i 1p
293 N 2
294 V 0 1p
295 S 0.1i c 0.15i p300/12 0.25p 0.3i This circle is hachured
296 S 0.1i t 0.15i yellow 0.25p 0.3i This triangle is yellow
297 S 0.1i h 0.15i green 0.25p 0.3i This hexagon is green
298 S 0.1i d 0.15i blue 0.25p 0.3i This diamond is blue
299 S 0.1i - 0.15i - 0.25tap 0.3i A contour
300 V 0 1p
301 D 0.2i 1p
302 N 1
303 I SOEST_logo.ras 3 CT
304 L 9 4 R Smith et al., @%5%J. Geophys. Res., 99@%%, 2000
305 G 0.5i
306 >
307 T Let us just try some simple text that can go on a few lines.
308 T There is no easy way to predetermine how many lines will be required,
309 T so we may need to adjust the box height to get the right size.
310 G -0.3i
311 M 5 5 1000:km:l f
312 EOF
313 SPECIFYING FILL
315 fill The attribute fill specifies the solid shade or solid color (see
316 SPECIFYING COLOR below) or the pattern used for filling poly‐
317 gons. Patterns are specified as pdpi/pattern, where pattern
318 gives the number of the built-in pattern (1-90) or the name of a
319 Sun 1-, 8-, or 24-bit raster file. The dpi sets the resolution
320 of the image. For 1-bit rasters: use Pdpi/pattern for inverse
321 video, or append :Fcolor[B[color]] to specify fore- and back‐
322 ground colors (use color = - for transparency). See GMT Cook‐
323 book & Technical Reference Appendix E for information on indi‐
324 vidual patterns.
325 SPECIFYING COLOR
327 color The color of lines, areas and patterns can be specified by a
328 valid color name; by a grey shade (in the range 0-255); by a
329 decimal color code (r/g/b, each in range 0-255; h-s-v, ranges
330 0-360, 0-1, 0-1; or c/m/y/k, each in range 0-1); or by a hexa‐
331 decimal color code (#rrggbb, as used in HTML). See the gmtcol‐
332 ors manpage for more information and a full list of color names.
333
335 Note that under Windows, the percent sign (%) is a variable indicator
336 (like $ under Unix). To indicate a plain percentage sign in a batch
337 script you need to repeat it (%%); hence the font switching mechanism
338 (@%font% and @%%) may require twice the number of percent signs. This
339 only applies to text inside a script or that otherwise is processed by
340 DOS. Data files that are opened and read by pslegend do not need such
341 duplication.
342
344 GMT(1), psbasemap(1), pstext(1), psxy(1)
345GMT 4.3.1 15 May 2008 PSLEGEND(1)