Usage:
[set ]posexpr=`echo text |\
.................addlegend
-yposexpr [-ddy]
[-ttempfile].............\
...........................[+yespace][ [-llength]....................\
-psxy options ............................\
+pstext options ... [+ffont[/size]]
[+oyoff]`
Auxiliary:
[set ]posexpr=`echo
text | addlegpos -yposexpr
[-ddy][+yespace]`
for adding a text line
without a symbol
[set ]posexpr=`backsplegend posexpr`
before overwriting a line, e.g. composing a symbol.
Note: psxy-options mark is minus-sign, e.g. -W[pen[/color[type]]Purpose:
pstext- " " plus-sign, e.g. +Wcolor
Adds a pair of psxy and pstext commands to a tempfile, which can be used with source (csh) or . (sh/ksh) to draw the legend. Recommended procedure is pslegend. A number of curve features are saved and repeated in the legend, and explanatory text is expected on STDIN. The basic idea is that you repeat the options of a psxy command, add a few simple legend options on the command line, and supply a text line. To this end addlegend tolerates but ignores some psxy options like -R -J.
Example (we're in the middle of a GMT script):
set yloc=0
psxy file.xy -R
-Jx -Sc0.1 -G100/0/0 -W1/0 -K -O -P >> out.ps
psxy file.xy
-R -Jx -W3/255/0/0 -K -O -P >> out.ps
set yloc=`echo Heartbeat | addlegend
-y$yloc -d1 -R -Jx -Sc0.1
-G100/0/0 -W1/0 -w3/255/0/0 -K -O -P`
# ...
# finally
pslegend -y$yloc -JX2/1 >> out.ps
echo Ready out.ps
Here, the new options control the location and spacing (
-y -d ), the psxy options for symbol type, symbol
fill and symbol outline ( -G -S -W ) and for
line weight and color ( -w ) are significant, and
the -R -Jx -K -O -P options are convenient
nuisance options
(in csh you could copy the psxy arguments using an array variable
and add the few extra needed).
Drawing the legend with pslegend will overcore the settings of the -R and -J options, therefore you will need to set them aside for later use. See also pslegend -h
/usr/local/GMT/bin/pslegend is
a
symbolic
link to
/home/hgs/perlproc/pslegend.pl
The addlegpos command aids in incrementing the position
expression and obtaining updated limits. Useful in situations
where a user
for instance wants to add extra space above the legend text.
I/O:
Reads from STDOUT: The explanatory text for the legend.
Prints to STDOUT: <posexpr>, new position
expression, a suggested next legend position, and current box
limits parameters.
Prints to STDERR: Runtime messages.
Therefore, a typical call from within a sh or ksh script would
read:
newy=`echo legend-comment |
addlegend -y$oldy ...`
or
ypos=0
ypos=`echo legend-comment |
addlegend -y$ypos ...`
However, also the following will work, of course:
#!/bin/sh
...
oldy=`cat temp.val`
addlegend -y$oldy ... << END
> temp.val
legend-comment
END
...
More than one line of text can be entered, but is not recommended for beginners.
Options:
Options that are proprietary to addlegend:
-yposexpr - to place a legend
entry at position posexpr. The next
..................legend
line will be dy above posexpr.
..................In
general
..................<posexpr>
:= <pos>[/<min>/<max>[/<mypos>]]
..................Obs!
If only pos is specified, min and max
are reset;
..................then
it's your job to keep track of the extrema.
..................To
keep min and max while
requesting a specific
..................mypos,
use anything/min/max/mypos;
..................then
mypos will be taken and anything ignored.
..................Since
a suggestion for the next expression in the form
..................pos/min/max
is returned on STDOUT, you can call
.....................y=`addlegend -y$y
...` for
automatic increment
..................or
y=`addlegend -y$y/mypos ...` for user
control.
..................Default
posexpr = 0
+yespace - Above
the top line of the legend some extra space may be
.................
needed. Specify espace in units of
lines (-ddy)
-ddy
- Vertical increment; default dy = -1 (implying
downward
..................extension).
dy is needed also with the last legend
..................entry
as addlegend must reserve space around it.
..................Units
are arbitrary internal data units. The -R option
..................of
pslegend will have to refer to these units though.
-tfile -
name of the command file that is assembled by addlegend.
..................Default
<file> = .gmtlegend.cmd or, if existent,
..................environment
parameter
GMTLEGENDCMD
+ffont[/size][/placement]
...............-
If given, must start with + (plus!) Default is +f0/12/5
-llength - Endpoint of the line sample. Begin is always 0.1. Default 0.25
+ldash
- for dash-dot lines: implies increased length by
0.2, symbol x-offset far left,
............... ..text
x-offset +0.1. Can
be overridden with subsequent +o -o
-o[xoff/]yoff -
Offset sample symbol vertically, in units of -ddy.
..................Default
xoff = 0.
+o[xoff/]yoff
- Offset sample text vertically, in units of -ddy.
..................Default
xoff = 0.
-v
- vector sample (symbol is drawn with GMT psvelo)
-si
- strain symbols (drawn with GMT psvelo,
probably never tested)
-m
- "mechanism" sample (symbol is draw with GMT
psmeca,
not really finished)
-Wpen
- Symbol outline
-wpen
- Line weight and colour
+Wfill
- Text filling option (pstext)
Options that apply to both psxy AND
pstext:
-P -N can be given as +P +N
addlegend has the ambition to show in the legend:
* line color, thickness, morse-code (from psxy
-Wpen)
* symbols (from psxy -Ssymbol)
including vectors, eventually with error circle
* error bars (from psxy -Ebar)
To obtain a specific vector size (to show a representative sample), append :size to option -Sv
To tailor the error bar or the error circle, append
:scale to the -E
or the -Se option, respectively. The scale factor
is measured in
fractions of the line spacing, dy. Default is 16
(i.e. results in error bar half width resp. radius = dy/16)
Symbols (error bars) and lines are often plotted in two separate
runs of psxy. For the legend, the line attributes can be specified
to addlegend after option -w and the symbol
outline attributes after option -W. See example
'perspiration' below.
However, addlegend can also compose a symbol; you simply call
addlegend several times while avoiding to update the position
expression.
If you need to tell a legend of bars (-Sb) the following will work:
sb=`awk -v y=$ypos 'BEGIN{print y+0.5}'`
... addlegend ... -Sbthick/$sb ...
where 0.5 is the height of the bar, in spite of the "value/value/value" form of $ypos.
Example:
psxy -R -JX
-W0.2
\
-G255/0/0
-Sb0.1/${base} \
-V
-K -O
-P
>> $psout
sb=`awk -v y=$ypos 'BEGIN{print y+0.5}'`
ypos=`echo "Schwiderski" |
addlegend -y$ypos -d1 +o.2 -Sb0.1/$sb -w -R -JX -W0.2
-G255/0/0 -P -K -O`
If you don't need to distinguish symbol and line pens, use the -Wpen option.
If you don't want a line through the
symbol, use an empty -w option.
If legend entries are to be superimposed (most likely for the
curve symbol), two calls are needed. Incrementing with -d0 does
not seem to work.
The following does:
set yloco=$yloc
set yloc=`echo text | addlegend -y$yloc ... +G255 ... `
(introducing
one symbol, text colour = background colour)
set yloc=`echo text | addlegend -y$yloco ...'
(superimposing
another symbol, text colour = black by default)
Example:
The light-gray strings are redundant
#!/bin/sh
psxy
bp.dat
-R1998.7/80/1998.8/180 -JX5/5 -Sc0.1 -W3/255/0/0 -P -K -O >>
psout.ps
yl=`echo blood pressure |\
addlegend
-y0 -R1998.7/80/1998.8/180
-JX5/5 -Sc0.1 -W3/255/0/0
-P -K -O`
psxy hb.dat -R -JX -Ss0.1 -W3/0/255/0 -P -K -O >> psout.ps
yl=`echo heart beat |\
addlegend -y$yl -R -JX -Ss0.1 -W3/0/255/0 -P -K -O`
psxy psp.dat -R -JX -Sa0.1 -W1/0/127/127 -P -K -O >> psout.ps
psxy psp.dat -R -JX -W3/0/255/255 -P -K -O >> psout.ps
yl=`echo perspiration |\
addlegend -y$yl -R -JX -Sa0.1 -W1/0/127/127
-w3/0/255/255 -P -K -O`
pslegend -y$yl -JX1/1 -X4 -Y4 -P -K -O >> psout.ps