NAME¶
d.legend - Displays a legend for a raster map in the active frame
of the graphics monitor.
KEYWORDS¶
display, cartography
SYNOPSIS¶
d.legend
d.legend help
d.legend [-
mvcnsf]
map=
name
[
color=
name] [
lines=
integer]
[
thin=
integer] [
labelnum=
integer]
[
at=
bottom,top,left,right] [
use=
catnum[,
catnum,...]] [
range=
min,max]
[--
verbose] [--
quiet]
Flags:¶
- -m
-
Use mouse to size & place legend
- -v
-
Do not show category labels
- -c
-
Do not show category numbers
- -n
-
Skip categories with no label
- -s
-
Draw smooth gradient
- -f
-
Flip legend
- --verbose
-
Verbose module output
- --quiet
-
Quiet module output
Parameters:¶
- map=name
-
Name of raster map
- color=name
-
Text color
Either a standard color name or R:G:B triplet
Default: black
- lines=integer
-
Number of text lines (useful for truncating long legends)
Options: 0-1000
Default: 0
- thin=integer
-
Thinning factor (thin=10 gives cats 0,10,20...)
Options: 1-1000
Default: 1
- labelnum=integer
-
Number of text labels for smooth gradient legend
Options: 2-100
Default: 5
- at=bottom,top,left,right
-
Size and placement as percentage of screen coordinates (0,0 is lower left)
bottom,top,left,right
Options: 0-100
- use=catnum[,catnum,...]
-
List of discrete category numbers/values for legend
- range=min,max
-
Use a subset of the map range for the legend (min,max)
DESCRIPTION¶
d.legend displays a legend for a user-specified raster map layer in the
active frame on the graphics monitor.
The user can run
d.legend either non-interactively or interactively. If
the user specifies the name of a raster
map layer on the command line,
the program will run non-interactively. Default legend text
color and
position will be used unless the user specifies other values on the command
line.
Alternately, the user can simply type
d.legend on the command line; in
this case, the program will prompt the user for parameter values using the
standard GRASS GUI interface.
NOTES¶
The legend's default size is based on the dimensions of the active frame,
specifically its height.
d.legend will only obscure those portions of
the active frame that directly underlie the legend.
When using the mouse or
at to size & place the legend, a user may
create a horizontal legend by making the box wider than it is tall.
Raster maps based on floating point values will display smoothed, from greatest
to smallest value, while categorial raster maps will display in order, from
top to bottom. Horizontal legends will always be smoothed. If the box is
defined with inverted y-values or an inverted
range, the legend will
automatically flip. If this is not the desired result, the
-f flag may
be used to flip it back.
If the user attempts to display a very long legend in a relatively short display
frame, the legend may appear in unreadably small text, or even revert to a
smooth gradient legend. Use the
lines,
thin,
use,
range, and/or
-n options to reduce the number of categories to
be displayed, or the
-s flag to force a smooth gradient legend.
The
lines option will display the first number of categories, as defined
by
value, contained in the raster map. When used with the
-n
flag, it takes on a new meaning: "up to category #". When used with
both
thin and the
-n flag, its meaning becomes more obscure.
When using
lines, auto-scaled text similar to "4 of 16
categories" will be placed at the bottom of the legend.
The
thin option sets the thinning factor. For raster maps with a 0th
category,
thin=10 gives cats [0,10,20,...]. For raster maps
starting at category 1,
thin=10 gives cats [1,11,21,...].
The
use option lets the user create a legend made up of arbitrary
category values. e.g.
use=1000,100,10,0,-10,-100,-1000
The
range option lets the user define the minimum and maximum categories
to be used in the legend. It may also be used to define the limits of a smooth
gradient legend created from a raster containing floating point values. Note
the color scale will remain faithful to the category values as defined with
r.colors, and the
range may be extended to the limits defined by
the
r.colors color map.
The flag
-n is useful for categorial maps, as it suppresses the drawing
of non-existing categories (otherwise the full range is shown).
Vertical legends produced with
d.legend will place text labels to the
right of the legend box, horizontal legends will place text below. This text
will be auto-scaled to fit within the frame, reducing the size of the legend
if necessary. Legends positioned with the mouse or with the
at option
will not auto-scale text, in order to provide more control to the user.
Smaller text may be obtained in this case by reducing the height of the box.
The
-c and
-v flags may be used to suppress the display of
category numbers and labels respectively, or used together to suppress all
text of categorial raster maps.
The text produced from floating-point raster maps will automatically create
output with a meaningful number of significant digits. For very small values,
numbers will be expressed in scientific notation, e.g. "1.7e-9".
Legends placed with the mouse are not saved to the display window's history for
automatic redraw. By setting the Debug level to 1 (see
g.gisenv) the
corresponding
at setting can be determined.
Note that old scripts which relied on setting
lines greater than the
number of categories to scale the legend may no longer produce the desired
output, although the auto-scaling should still produce something that looks
good in this case.
SEE ALSO¶
d.barscale
d.colors
d.colortable
d.erase
d.font
d.font.freetype
d.grid
d.rast
d.rast.leg
d.text
d.text.freetype
d.vect.thematic
d.what.rast
g.gisenv
r.reclass
AUTHORS¶
Bill Brown, U.S. Army Construction Engineering Research Laboratories
Late 2002: Rewrite of much of the code. Hamish Bowman, Otago University, New
Zealand
Additional improvements from various authors
Last changed: $Date: 2011-11-08 12:29:50 +0100 (Tue, 08 Nov 2011) $
Full index
© 2003-2014 GRASS Development Team