pslegend(1) GMT pslegend(1)
NAME
pslegend - Plot legends on maps
SYNOPSIS
pslegend [ specfile ]
-Drefpoint ] [ -B[p|s]parameters ] [ -Cdx/dy ] [ -Fbox ] [ -Jpa-
rameters ] [ -K ] [ -O ] [ -P ] [ -Rregion ] [ -U[stamp] ] [
-V[level] ] [ -Xx_offset ] [ -Yy_offset ] [ -pflags ] [ -ttransp ]
Note: No space is allowed between the option flag and the associated
arguments.
DESCRIPTION
pslegend will make legends that can be overlaid on maps. It reads spe-
cific legend-related information from an input file [or stdin]. Unless
otherwise noted, annotations will be made using the primary annotation
font and size in effect (i.e., FONT_ANNOT_PRIMARY)
REQUIRED ARGUMENTS
-D[g|j|J|n|x]refpoint+wwidth[/height][+jjustify][+lspacing][+odx[/dy]]
Defines the reference point on the map for the legend using one
of four coordinate systems: (1) Use -Dg for map (user) coordi-
nates, (2) use -Dj or -DJ for setting refpoint via a 2-char jus-
tification code that refers to the (invisible) map domain rec-
tangle, (3) use -Dn for normalized (0-1) coordinates, or (4) use
-Dx for plot coordinates (inches, cm, etc.). All but -Dx
requires both -R and -J to be specified. Append
+wwidth[/height] to set the width (and height) of the legend box
in plot coordinates (inches, cm, etc.). If height is zero or
not given then we estimate height based the expected vertical
extent of the items to be placed. By default, the anchor point
on the legend is assumed to be the bottom left corner (BL), but
this can be changed by appending +j followed by a 2-char justi-
fication code justify (see pstext). Note: If -Dj is used then
justify defaults to the same as refpoint, if -DJ is used then
justify defaults to the mirror opposite of refpoint. Use
+lspacing to change the line-spacing factor in units of the cur-
rent font size [1.1]. Finally, add +o to offset the color scale
by dx/dy away from the refpoint point in the direction implied
by justify (or the direction implied by -Dj or -DJ).
OPTIONAL ARGUMENTS
-B[p|s]parameters (more a|)
Set map boundary frame and axes attributes.
-Cdx/dy
Sets the clearance between the legend frame and the internal
items [4p/4p].
-F[+cclear-
ances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]][+s[[dx/dy/][shade]]]
Without further options, draws a rectangular border around the
legend using MAP_FRAME_PEN; specify a different pen with +ppen.
Add +gfill to fill the legend box [no fill]. Append +cclearance
where clearance is either gap, xgap/ygap, or lgap/rgap/bgap/tgap
where these items are uniform, separate in x- and y-direction,
or individual side spacings between scale and border. Append +i
to draw a secondary, inner border as well. We use a uniform gap
between borders of 2p and the MAP_DEFAULTS_PEN unless other val-
ues are specified. Append +r to draw rounded rectangular borders
instead, with a 6p corner radius. You can override this radius
by appending another value. Finally, append +s to draw an offset
background shaded region. Here, dx/dy indicates the shift rela-
tive to the foreground frame [4p/-4p] and shade sets the fill
style to use for shading [gray50].
-Jparameters (more a|)
Select map projection.
-K (more a|)
Do not finalize the PostScript plot.
-O (more a|)
Append to existing PostScript plot.
-P (more a|)
Select aPortraita plot orientation.
-Rxmin/xmax/ymin/ymax[+r][+uunit] (more a|)
Specify the region of interest.
-U[[just]/dx/dy/][c|label] (more a|)
Draw GMT time stamp logo on plot.
-V[level] (more a|)
Select verbosity level [c].
-X[a|c|f|r][x-shift[u]]
-Y[a|c|f|r][y-shift[u]] (more a|)
Shift plot origin.
-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more a|)
Select perspective view.
-t[transp] (more a|)
Set PDF transparency level in percent.
-^ or just -
Print a short message about the syntax of the command, then
exits (NOTE: on Windows just use -).
-+ or just +
Print an extensive usage (help) message, including the explana-
tion of any module-specific option (but not the GMT common
options), then exits.
-? or no arguments
Print a complete usage (help) message, including the explanation
of all options, then exits.
PSLEGEND CODES
specfile
This ASCII file contains instructions for the layout of items in
the legend. Each legend item is described by a unique record.
All records begin with a unique character that is common to all
records of the same kind. The order of the legend items is
implied by the order of the records. Fourteen different record
types are recognized, and the syntax for each of these records
are presented below:
# comment
Records starting with # and blank lines are skipped.
A cptname
Symbol or cell color fills may be given indirectly via a z-value
which can be used for the color look-up via the given CPT cpt-
name. You may switch to other cptname by repeating this com-
mand.
B cptname offset height [ optional arguments ]
The B record will plot a horizontal color bar, psscale-style in
the middle, starting at offset from the left edge, and of the
given height. You may add any additional psscale options as
well. Any of the modifiers
[+e[b|f][<length>]][+h][+ma|c|l|u][+n[<txt>]] may be given
height. You may add any additional psscale options as well. Any
of the modifiers [+e[b|f][length]][+h][+m[a|c|l|u]][+n[txt]] may
be appended to the height argument, while other module options
-B -I -L -M -N -S -Z and -p may be appended as optional argu-
ments at the end of the record. See psscale for details on all
modifiers and options.
C textcolor
The C record specifies the color with which the remaining text
is to be printed. textcolor can be in the form r/g/b, c/m/y/k, a
named color, or an indirect color via z=value* (requires a prior
**A* code as well). Use - to reset to default color.
D [offset] pen [-|+|=]
The D record results in a horizontal line with specified pen
across the legend with one quarter of the line-spacing left
blank above and below the line. Two gaps of offset units are
left blank between the horizontal line and the left and right
frame sides [0]. If no pen is given we use MAP_GRID_PEN_PRIMARY,
and if pen is set to - then no visible line is drawn (we just
remember the location as a possible start/stop point for a ver-
tical line; see V). To not add the quarter line-spacing before
the line, add -. To not add the spacing after the line, add +.
For no spacing at all, add = [Default places a quarter
line-spacing both before and after the line].
F fill1 fill2 ^<i>a| filln
Specify fill (color of pattern) for cells. Alternatively, you
can specify an indirect color via z=value (requires a prior A
code). If only fill1 is given then it is used to fill the
entire row, otherwise give one fill value for each active column
(see N). If any fill is - then no fill takes place [Default].
G gap The G record specifies a vertical gap of the given length. In
addition to the standard units (i, c, p) you may use l for
lines. A negative gap will move the current line upwards (thus
closing a gap).
H fontsize|- font|- header
The H record plots a centered text string using the specified
font parameters. Use - to default to size and type of
FONT_TITLE.
I imagefile width justification
Place an EPS or raster image in the legend justified relative to
the current point. The image width determines the size of the
image on the page.
L fontsize|- font|- justification label
The L record plots a (L)eft, (C)entered, or (R)ight-justified
text string within a column using the specified font parameters.
Use - to default to the size and type of FONT_LABEL.
M slon|- slat length [+f][+l[label]][+u] [-Fparam] [ -Rw/e/s/n -Jparam
]
Place a map scale in the legend. Specify slon slat, the point on
the map where the scale applies (slon is only meaningful for
certain oblique projections. If not needed, you must specify -
instead). Give length, the length of the scale in km (for other
units append e (meter), f (foot), M (mile), n (nautical mile),
or u (survey foot)). Append +f for a fancy map scale [Default is
plain]. Append +l to the length to select the default label
which equals the distance unit (meter, feet, km, miles, nautical
miles, survey feet) and is justified on top of the scale [t].
Change this by giving your own label (append +llabel). Change
label alignment with +aalign (choose among l(eft), r(ight),
t(op) , and b(ottom)). Apply +u to append the unit to all dis-
tance annotations along the scale. If you want to place a map
panel behind the scale, add a suitable -F panel option (see
psbasemap for details on panels as well as map scale modifiers).
All +modifiers must be appended to length to make a single
string argument. If the -R -J supplied to pslegend is different
than the projection needed for the scale (or not given at all,
e.g., with -Dx), supply the two optional -R -J settings as well.
N [ncolumns or relwidth1 relwidth2 ^<i>a| relwidthn]
Change the number of columns in the legend [1]. This only
affects the printing of symbols (S) and labels (L). The number
of columns stay in effect until N is used again. To get columns
of unequal width, instead provide the relative width of each
column separated by whitespace. The sum of these widths are
equated to the legend width set via -D. If no argument is given
the we set n_columns to 1.
P paragraph-mode-header-for-pstext
Start a new text paragraph by specifying all the parameters
needed (see pstext -M record description). Note that pslegend
knows what all those values should be, so normally you can leave
the entire record (after P) blank or leave it out all together.
If you need to set at least one of the parameters directly, you
must specify all and set the ones you want to leave at their
default value to -.
S [dx1 symbol size fill pen [ dx2 text ]]
Plots the selected symbol with specified diameter, fill, and
outline (see psxy). The symbol is centered at dx1 from the left
margin of the column, with the optional explanatory text start-
ing dx2 from the margin, printed with FONT_ANNOT_PRIMARY. Use -
if no fill or outline (pen) is required. Alternatively, the fill
may be specified indirectly via z=value and the color is
assigned vi the CPT look-up (requires a prior A code). When
plotting just a symbol, without text, dx2 and text can be omit-
ted. The dx1 value can also be given as a justification code L,
C, R which justifies the symbol with respect to the current col-
umn. If no arguments are given to S then we simply skip to the
next column. Three psxy symbols may take special modifiers:
front (f), quoted line (q) and vector (v). You can append mod-
ifiers to the symbol and affect how the fronts, quoted lines and
vectors are presented (see psxy man page for modifiers). psle-
gend will determine default settings for all modifiers and sec-
ondary arguments if not provided. A few other symbols (the rec-
tangles, ellipse, wedge, mathangle) may take more than a single
argument size. Note that for a line segment you should use the
horizontal dash symbol (-). If just a single size if given then
pslegend will provide reasonable arguments to plot the symbol
(See Defaults). Alternatively, combine the required arguments
into a single, comma-separated string and use that as the symbol
size (again, see psxy for details on the arguments needed).
T paragraph-text
One or more of these T records with paragraph-text printed with
FONT_ANNOT_PRIMARY. To specify special positioning and typeset-
ting arrangements, or to enter a paragraph break, use the
optional P record.
V [offset] pen
The V record draws a vertical line between columns (if more than
one) using the selected pen. Here, offset is analogous to the
offset for the D records but in the vertical direction [0]. The
first time V is used we remember the vertical position of the
last D line, and the second time V is set we draw from that past
location to the most recent location of the D line. Thus, D
must be used to mark the start and stop of a vertical line (so V
must follow D). If no horizontal line is desired simply give -
as pen to D.
DEFAULTS
When attributes are not provided, or extended symbol information (for
symbols taking more than just an overall size) are not given as
comma-separated quantities, pslegend will provide the following
defaults:
Front: Front symbol is left-side (here, that means upper side) box,
with dimensions 30% of the given symbol size.
Vector: Head size is 30% of given symbol size.
Ellipse: Minor axis is 65% of major axis (the symbol size), with an
azimuth of 0 degrees.
Rectangle: Height is 65% of width (the symbol size).
Rotated rectangle: Same, with a rotation of 30 degrees.
Rounded rectangle: Same as rectangle, but with corner radius of 10% of
width.
Mathangle: Angles are -10 and 45 degrees, with arrow head size 30% of
symbol size.
Wedge: Angles are -30 and 30 degrees.
EXAMPLES
To add an example of a legend to a Mercator plot (map.ps) with the
given specifications, use
gmt pslegend -R-10/10/-10/10 -JM6i -F+gazure1 -Dx0.5i/0.5i+w5i/3.3i+jBL+l1.2 \
-C0.1i/0.1i -B5f1 << EOF >> map.ps
# Legend test for pslegend
# G is vertical gap, V is vertical line, N sets # of columns, D draws horizontal line.
# H is header, L is label, S is symbol, T is paragraph text, M is map scale.
#
G -0.1i
H 24 Times-Roman My Map Legend
D 0.2i 1p
N 2
V 0 1p
S 0.1i c 0.15i p300/12 0.25p 0.3i This circle is hachured
S 0.1i e 0.15i yellow 0.25p 0.3i This ellipse is yellow
S 0.1i w 0.15i green 0.25p 0.3i This wedge is green
S 0.1i f0.1i+l+t 0.25i blue 0.25p 0.3i This is a fault
S 0.1i - 0.15i - 0.25p,- 0.3i A dashed contour
S 0.1i v0.1i+a40+e 0.25i magenta 0.25p 0.3i This is a vector
S 0.1i i 0.15i cyan 0.25p 0.3i This triangle is boring
V 0 1p
D 0.2i 1p
N 1
M 5 5 600+u f
G 0.05i
I SOEST_logo.ras 3i CT
G 0.05i
B colors.cpt 0.2i 0.2i
G 0.05i L 9 4 R Smith et al., @%5%J. Geophys. Res., 99@%%, 2000
G 0.1i
P
T Let us just try some simple text that can go on a few lines.
T There is no easy way to predetermine how many lines will be required,
T so we may have to adjust the box height to get the right size box.
EOF
NOTE ON LEGEND HEIGHT
As -D suggests, leaving the height off forces a calculation of the
expected height. This is an exact calculation except in the case of
legends that place paragraph text. Here we simply do a first-order
estimate of how many typeset lines might appear. Without access to font
metrics this estimate will occasionally be off by 1 line. If so, note
the reported height (with -V) and specify a slightly larger or smaller
height in -D.
WINDOWS REMARKS
Note that under Windows, the percent sign (%) is a variable indicator
(like $ under Unix). To indicate a plain percentage sign in a batch
script you need to repeat it (%%); hence the font switching mechanism
(@%font% and @%%) may require twice the number of percent signs. This
only applies to text inside a script or that otherwise is processed by
DOS. Data files that are opened and read by pslegend do not need such
duplication.
SEE ALSO
gmt(1), gmt.conf(5), gmtcolors(5), gmtlogo(1), psbasemap(1), pstext(1),
psxy(1)
COPYRIGHT
2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
5.4.2 Jun 24, 2017 pslegend(1)
gmt5 5.4.2 - Generated Thu Jun 29 15:15:49 CDT 2017