.\" Man page generated from reStructuredText.
.
.TH "PSLEGEND" "1gmt" "May 21, 2019" "5.4.5" "GMT"
.SH NAME
pslegend \- Plot legends on maps
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fBpslegend\fP [ \fIspecfile\fP ]
 \fB\-D\fP\fIrefpoint\fP ]
[  \fB\-B\fP[\fBp\fP|\fBs\fP]\fIparameters\fP ]
[  \fB\-C\fP\fIdx\fP/\fIdy\fP ]
[  \fB\-F\fP\fIbox\fP ]
[  \fB\-J\fP\fIparameters\fP ]
[  \fB\-K\fP ] [  \fB\-O\fP ]
[  \fB\-P\fP ]
[  \fB\-R\fP\fIregion\fP ]
[  \fB\-U\fP[\fIstamp\fP] ]
[  \fB\-V\fP[\fIlevel\fP] ]
[  \fB\-X\fP\fIx_offset\fP ]
[  \fB\-Y\fP\fIy_offset\fP ]
[ \fB\-p\fPflags ]
[ \fB\-t\fPtransp ]
.sp
\fBNote:\fP No space is allowed between the option flag and the associated arguments.
.SH DESCRIPTION
.sp
\fBpslegend\fP will make legends that can be overlaid on maps. It reads
specific 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)
.SH REQUIRED ARGUMENTS
.INDENT 0.0
.TP
\fB\-D\fP[\fBg\fP|\fBj\fP|\fBJ\fP|\fBn\fP|\fBx\fP]\fIrefpoint\fP\fB+w\fP\fIwidth\fP[/\fIheight\fP][\fB+j\fP\fIjustify\fP][\fB+l\fP\fIspacing\fP][\fB+o\fP\fIdx\fP[/\fIdy\fP]]
Defines the reference point on the map for the legend using one of four coordinate systems:
(1) Use \fB\-Dg\fP for map (user) coordinates, (2) use \fB\-Dj\fP or \fB\-DJ\fP for setting \fIrefpoint\fP via
a 2\-char justification code that refers to the (invisible) map domain rectangle,
(3) use \fB\-Dn\fP for normalized (0\-1) coordinates, or (4) use \fB\-Dx\fP for plot coordinates
(inches, cm, etc.).  All but \fB\-Dx\fP requires both \fB\-R\fP and \fB\-J\fP to be specified.
Append \fB+w\fP\fIwidth\fP[/\fIheight\fP] to set
the width (and height) of the legend box in plot coordinates (inches, cm, etc.).
If \fIheight\fP is zero or not given then we estimate \fIheight\fP 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 \fB+j\fP followed by a 2\-char justification code \fIjustify\fP (see pstext).
Note: If \fB\-Dj\fP is used then \fIjustify\fP defaults to the same as \fIrefpoint\fP,
if \fB\-DJ\fP is used then \fIjustify\fP defaults to the mirror opposite of \fIrefpoint\fP\&.
Use \fB+l\fP\fIspacing\fP to change the line\-spacing factor in units of the current
font size [1.1].
Finally, add \fB+o\fP to offset the color scale by \fIdx\fP/\fIdy\fP away from the \fIrefpoint\fP point in
the direction implied by \fIjustify\fP (or the direction implied by \fB\-Dj\fP or \fB\-DJ\fP).
.UNINDENT
.SH OPTIONAL ARGUMENTS
.INDENT 0.0
.TP
\fB\-B\fP[\fBp\fP|\fBs\fP]\fIparameters\fP (more ...)
Set map boundary frame and axes attributes.
.UNINDENT
.INDENT 0.0
.TP
\fB\-C\fP\fIdx\fP/\fIdy\fP
Sets the clearance between the legend frame and the internal items [4\fBp\fP/4\fBp\fP].
.UNINDENT
.INDENT 0.0
.TP
\fB\-F\fP[\fB+c\fP\fIclearances\fP][\fB+g\fP\fIfill\fP][\fB+i\fP[[\fIgap\fP/]\fIpen\fP]][\fB+p\fP[\fIpen\fP]][\fB+r\fP[\fIradius\fP]][\fB+s\fP[[\fIdx\fP/\fIdy\fP/][\fIshade\fP]]]
Without further options, draws a rectangular border around the legend using
\fBMAP_FRAME_PEN\fP; specify a different pen with \fB+p\fP\fIpen\fP\&.
Add \fB+g\fP\fIfill\fP to fill the legend box [no fill].
Append \fB+c\fP\fIclearance\fP where \fIclearance\fP is either \fIgap\fP, \fIxgap\fP/\fIygap\fP,
or \fIlgap\fP/\fIrgap\fP/\fIbgap\fP/\fItgap\fP where these items are uniform, separate in
x\- and y\-direction, or individual side spacings between scale and border.
Append \fB+i\fP to draw a secondary, inner border as well. We use a uniform
\fIgap\fP between borders of 2\fBp\fP and the \fBMAP_DEFAULTS_PEN\fP
unless other values are specified. Append \fB+r\fP to draw rounded
rectangular borders instead, with a 6\fBp\fP corner radius. You can
override this radius by appending another value. Finally, append
\fB+s\fP to draw an offset background shaded region. Here, \fIdx\fP/\fIdy\fP
indicates the shift relative to the foreground frame
[4\fBp\fP/\-4\fBp\fP] and \fIshade\fP sets the fill style to use for shading [gray50].
.UNINDENT
.INDENT 0.0
.TP
\fB\-J\fP\fIparameters\fP (more ...)
Select map projection.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-K\fP (more ...)
Do not finalize the PostScript plot.
.UNINDENT
.INDENT 0.0
.TP
\fB\-O\fP (more ...)
Append to existing PostScript plot.
.UNINDENT
.INDENT 0.0
.TP
\fB\-P\fP (more ...)
Select "Portrait" plot orientation.
.UNINDENT
.INDENT 0.0
.TP
\fB\-R\fP\fIxmin\fP/\fIxmax\fP/\fIymin\fP/\fIymax\fP[\fB+r\fP][\fB+u\fP\fIunit\fP] (more ...)
Specify the region of interest.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-U\fP[[\fIjust\fP]/\fIdx\fP/\fIdy\fP/][\fBc\fP|\fIlabel\fP] (more ...)
Draw GMT time stamp logo on plot.
.UNINDENT
.INDENT 0.0
.TP
\fB\-V\fP[\fIlevel\fP] (more ...)
Select verbosity level [c].  
.UNINDENT
.sp
\fB\-X\fP[\fBa\fP|\fBc\fP|\fBf\fP|\fBr\fP][\fIx\-shift\fP[\fBu\fP]]
.INDENT 0.0
.TP
\fB\-Y\fP[\fBa\fP|\fBc\fP|\fBf\fP|\fBr\fP][\fIy\-shift\fP[\fBu\fP]] (more ...)
Shift plot origin.
.UNINDENT
.INDENT 0.0
.TP
\fB\-p\fP[\fBx\fP|\fBy\fP|\fBz\fP]\fIazim\fP[/\fIelev\fP[/\fIzlevel\fP]][\fB+w\fP\fIlon0\fP/\fIlat0\fP[/\fIz0\fP]][\fB+v\fP\fIx0\fP/\fIy0\fP] (more ...)
Select perspective view.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-t\fP[\fItransp\fP] (more ...)
Set PDF transparency level in percent.
.UNINDENT
.INDENT 0.0
.TP
\fB\-^\fP or just \fB\-\fP
Print a short message about the syntax of the command, then exits (NOTE: on Windows just use \fB\-\fP).
.TP
\fB\-+\fP or just \fB+\fP
Print an extensive usage (help) message, including the explanation of
any module\-specific option (but not the GMT common options), then exits.
.TP
\fB\-?\fP or no arguments
Print a complete usage (help) message, including the explanation of all options, then exits.
.UNINDENT
.SH PSLEGEND CODES
.INDENT 0.0
.TP
.B \fIspecfile\fP
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:
.TP
\fB#\fP \fIcomment\fP
Records starting with # and blank lines are skipped.
.TP
\fBA\fP \fIcptname\fP
Symbol or cell color fills may be given indirectly via a \fIz\fP\-value
which can be used for the color look\-up via the given CPT \fIcptname\fP\&.
You may switch to other \fIcptname\fP by repeating this command.
.TP
\fBB\fP \fIcptname offset height\fP [ \fIoptional arguments\fP ]
The \fBB\fP record will plot a horizontal color bar, psscale\-style
in the middle, starting at \fIoffset\fP from the left edge, and of the
given \fIheight\fP\&. 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 \fIheight\fP\&. You may add any additional psscale options as well.
Any of the modifiers
[\fB+e\fP[\fBb\fP|\fBf\fP][\fIlength\fP]][\fB+h\fP][\fB+m\fP[\fBa\fP|\fBc\fP|\fBl\fP|\fBu\fP]][\fB+n\fP[\fItxt\fP]] may be
appended to the \fIheight\fP argument, while other module options
\fB\-B\fP \fB\-I\fP \fB\-L\fP \fB\-M\fP \fB\-N\fP \fB\-S\fP \fB\-Z\fP and \fB\-p\fP may be appended as
\fIoptional arguments\fP at the end of the record.
See psscale for details on all modifiers and options.
.TP
\fBC\fP \fItextcolor\fP
The \fBC\fP record specifies the color with which the remaining text
is to be printed. \fItextcolor\fP can be in the form \fIr/g/b\fP, \fIc/m/y/k\fP,
a named color, or an indirect color via z=\fIvalue* (requires a prior **A*\fP code as well).
Use \fB\-\fP to reset to default color.
.TP
\fBD\fP [\fIoffset\fP] \fIpen\fP [\fB\-\fP|\fB+\fP|\fB=\fP]
The \fBD\fP record results in a horizontal line with specified \fIpen\fP
across the legend with one quarter of the line\-spacing left blank
above and below the line. Two gaps of \fIoffset\fP 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 \fIpen\fP is
set to \fB\-\fP then no visible line is drawn (we just remember the location
as a possible start/stop point for a vertical line; see \fBV\fP).  To \fInot\fP add the
quarter line\-spacing before the line, add \fB\-\fP\&.  To \fInot\fP add the spacing
after the line, add \fB+\fP\&.  For no spacing at all, add \fB=\fP
[Default places a quarter line\-spacing both before and after the line].
.TP
\fBF\fP \fIfill1 fill2 ... filln\fP
Specify fill (color of pattern) for cells.  Alternatively, you can
specify an indirect color via z=\fIvalue\fP (requires a prior \fBA\fP code).
If only \fIfill1\fP is given
then it is used to fill the entire row, otherwise give one fill value
for each active column (see \fBN\fP).  If any fill is \- then no fill
takes place [Default].
.TP
\fBG\fP \fIgap\fP
The \fBG\fP record specifies a vertical gap of the given length. In
addition to the standard units (\fBi\fP, \fBc\fP, \fBp\fP) you may use
\fBl\fP for lines. A negative \fIgap\fP will move the current line upwards (thus closing a gap).
.TP
\fBH\fP \fIfontsize\fP|\fB\-\fP \fIfont\fP|\fB\-\fP \fIheader\fP
The \fBH\fP record plots a centered text string using the specified
font parameters. Use \fB\-\fP to default to size and type of \fBFONT_TITLE\fP\&.
.TP
\fBI\fP \fIimagefile width justification\fP
Place an EPS or raster image in the legend justified relative to
the current point. The image \fIwidth\fP determines the size of the image on the page.
.TP
\fBL\fP \fIfontsize\fP|\fB\-\fP \fIfont\fP|\fB\-\fP \fIjustification label\fP
The \fBL\fP record plots a (L)eft, (C)entered, or (R)ight\-justified
text string within a column using the specified font parameters. Use
\fB\-\fP to default to the size and type of \fBFONT_LABEL\fP\&.
.TP
\fBM\fP \fIslon\fP|\fB\-\fP \fIslat length\fP [\fB+f\fP][\fB+l\fP[\fIlabel\fP]][\fB+u\fP] [\fB\-F\fP\fIparam\fP] [ \fB\-R\fP\fIw/e/s/n\fP \fB\-J\fP\fIparam\fP ]
Place a map scale in the legend. Specify \fIslon slat\fP, the point on
the map where the scale applies (\fIslon\fP is only meaningful for
certain oblique projections. If not needed, you must specify \fB\-\fP
instead). Give \fIlength\fP, the length of the scale in km (for other units
append \fBe\fP (meter), \fBf\fP (foot), \fBM\fP (mile), \fBn\fP (nautical
mile), or \fBu\fP (survey foot)). Append \fB+f\fP for a fancy map scale
[Default is plain].
Append \fB+l\fP to the \fIlength\fP 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 \fB+l\fP\fIlabel\fP). Change label
alignment with \fB+a\fP\fIalign\fP (choose among \fBl\fP(eft),
\fBr\fP(ight), \fBt\fP(op) , and \fBb\fP(ottom)).
Apply \fB+u\fP to append the unit to all distance annotations along
the scale. If you want to place a map panel behind the scale,
add a suitable \fB\-F\fP panel option (see psbasemap for details
on panels as well as map scale modifiers).
All \fB+\fP\fImodifiers\fP must be appended to \fIlength\fP to make a single
string argument.  If the \fB\-R\fP \fB\-J\fP supplied to \fBpslegend\fP is
different than the projection needed for the scale (or not given at
all, e.g., with \fB\-Dx\fP), supply the two optional \fB\-R\fP \fB\-J\fP settings
as well.
.TP
\fBN\fP [\fIncolumns\fP or \fIrelwidth1 relwidth2 ... relwidthn\fP]
Change the number of columns in the legend [1]. This only affects
the printing of symbols (\fBS\fP) and labels (\fBL\fP). The number of
columns stay in effect until \fBN\fP 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 \fB\-D\fP\&.  If no argument is given the we set
\fIn_columns\fP to 1.
.TP
\fBP\fP \fIparagraph\-mode\-header\-for\-pstext\fP
Start a new text paragraph by specifying all the parameters needed
(see pstext \fB\-M\fP record description). Note that \fBpslegend\fP 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 \fB\-\fP\&.
.TP
\fBS\fP [\fIdx1 symbol size fill pen\fP [ \fIdx2 text\fP ]]
Plots the selected symbol with specified diameter, fill, and outline
(see psxy). The symbol is centered at \fIdx1\fP from the left margin
of the column, with the optional explanatory \fItext\fP starting \fIdx2\fP
from the margin, printed with \fBFONT_ANNOT_PRIMARY\fP\&. Use \fB\-\fP if
no \fIfill\fP or outline (\fIpen\fP) is required. Alternatively, the \fIfill\fP
may be specified indirectly via z=\fIvalue\fP and the color is assigned
vi the CPT look\-up (requires a prior \fBA\fP code).
When plotting just a
symbol, without text, \fIdx2\fP and \fItext\fP can be omitted.  The \fIdx1\fP value
can also be given as a justification code L, C, R which justifies the
symbol with respect to the current column.  If no arguments are given
to \fBS\fP then we simply skip to the next column.  Three psxy
symbols may take special modifiers: front (\fBf\fP), quoted line (\fBq\fP)  and vector (\fBv\fP).
You can append modifiers to the symbol and affect how the fronts, quoted lines and
vectors are presented (see psxy man page for modifiers).
\fBpslegend\fP will determine default settings for all modifiers and
secondary arguments if not provided.  A few other symbols (the rectangles,
ellipse, wedge, mathangle) may take more than a single argument size.
Note that for a line segment you should use the horizontal dash symbol (\fB\-\fP).
If just a single size if given then \fBpslegend\fP will provide reasonable
arguments to plot the symbol  (See \fI\%Defaults\fP).
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).
.TP
\fBT\fP \fIparagraph\-text\fP
One or more of these \fBT\fP records with \fIparagraph\-text\fP printed
with \fBFONT_ANNOT_PRIMARY\fP\&. To specify special positioning and
typesetting arrangements, or to enter a paragraph break, use the
optional \fBP\fP record.
.TP
\fBV\fP [\fIoffset\fP] \fIpen\fP
The \fBV\fP record draws a vertical line between columns (if more than
one) using the selected \fIpen\fP\&.  Here, \fIoffset\fP is analogous to the offset
for the \fBD\fP records but in the vertical direction [0].  The first time
\fBV\fP is used we remember the vertical position of the last \fBD\fP line,
and the second time \fBV\fP is set we draw from that past location to the
most recent location of the \fBD\fP line.  Thus, \fBD\fP must be used to
mark the start and stop of a vertical line (so \fBV\fP must follow \fBD\fP).
If no horizontal line is desired simply give \- as \fIpen\fP to \fBD\fP\&.
.UNINDENT
.SH DEFAULTS
.sp
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, \fBpslegend\fP will provide the following defaults:
.sp
Front: Front symbol is left\-side (here, that means upper side) box, with dimensions 30% of the given symbol size.
.sp
Vector: Head size is 30% of given symbol size.
.sp
Ellipse: Minor axis is 65% of major axis (the symbol size), with an azimuth of 0 degrees.
.sp
Rectangle: Height is 65% of width (the symbol size).
.sp
Rotated rectangle: Same, with a rotation of 30 degrees.
.sp
Rounded rectangle: Same as rectangle, but with corner radius of 10% of width.
.sp
Mathangle: Angles are \-10 and 45 degrees, with arrow head size 30% of symbol size.
.sp
Wedge: Angles are \-30 and 30 degrees.
.SH EXAMPLES
.sp
To add an example of a legend to a Mercator plot (map.ps) with the given
specifications, use
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt pslegend \-R\-10/10/\-10/10 \-JM6i \-F+gazure1 \-Dx0.5i/0.5i+w5i/3.3i+jBL+l1.2 \e
\-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
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH NOTE ON LEGEND HEIGHT
.sp
As \fB\-D\fP suggests, leaving the \fIheight\fP 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 \fB\-V\fP) and specify a slightly larger or
smaller height in \fB\-D\fP\&.
.SH WINDOWS REMARKS
.sp
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
(@%\fIfont\fP% 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 \fBpslegend\fP do not need
such duplication.
.SH SEE ALSO
.sp
gmt, gmt.conf,
gmtcolors, gmtlogo
psbasemap, pstext,
psxy
.SH COPYRIGHT
2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
.\" Generated by docutils manpage writer.
.