d.legend(1grass) GRASS GIS User's Manual d.legend(1grass)
NAME
d.legend - Displays a legend for a 2D or 3D raster map in the active
frame of the graphics monitor.
KEYWORDS
display, cartography, legend
SYNOPSIS
d.legend
d.legend --help
d.legend [-vctnsfdbl] [raster=name] [raster_3d=name] [ti-
tle=string] [title_fontsize=float] [lines=integer] [thin=integer]
[units=string] [labelnum=integer] [label_values=float[,float,...]]
[label_step=float] [digits=integer] [at=bottom,top,left,right]
[use=float[,float,...]] [range=min,max] [color=name]
[font=string] [fontsize=float] [path=name] [charset=string]
[border_color=name] [bgcolor=name] [--help] [--verbose] [--quiet]
[--ui]
Flags:
-v
Do not show category labels
-c
Do not show category numbers
-t
Draw legend ticks for labels
-n
Skip categories with no label
-s
Draw smooth gradient
-f
Flip legend
-d
Add histogram to smoothed legend
-b
Show background
-l
Use logarithmic scale
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog
Parameters:
raster=name
Name of raster map
raster_3d=name
Name of 3D raster map
title=string
Legend title
title_fontsize=float
Title font size
Default: Same as fontsize
Options: 1-360
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
units=string
Units to display after labels (e.g. meters)
labelnum=integer
Number of text labels for smooth gradient legend
Options: 2-100
Default: 5
label_values=float[,float,...]
Specific values to draw ticks
label_step=float
Display label every step
digits=integer
Number of digits after decimal point
Options: 0-6
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=float[,float,...]
List of discrete category numbers/values for legend
range=min,max
Use a subset of the map range for the legend (min,max)
color=name
Text color
Either a standard color name or R:G:B triplet
Default: black
font=string
Font name
fontsize=float
Font size
Default: Auto-scaled
Options: 1-360
path=name
Path to font file
charset=string
Text encoding (only applicable to TrueType fonts)
border_color=name
Border color
Either a standard color name, R:G:B triplet, or "none"
Default: black
bgcolor=name
Background color
Either a standard color name, R:G:B triplet, or "none"
Default: white
DESCRIPTION
d.legend displays a legend for a user-specified raster map or 3D raster
map layer in the active frame on the graphics monitor.
The legend’s default size is based on the dimensions of the active
frame, specifically its height. d.legend will only obscure those por-
tions of the active frame that directly underlie the legend.
NOTES
When using the at to size & place the legend, a user may create a hori-
zontal 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 categorical 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 dis-
played, or the -s flag to force a smooth gradient legend.
The lines option will display the first number of categories, as de-
fined 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 cate-
gory values. e.g. use=1000,100,10,0,-10,-100,-1000
The range option lets the user define the minimum and maximum cate-
gories to be used in the legend. It may also be used to define the lim-
its of a smooth gradient legend created from a raster containing float-
ing point values. Note the color scale will remain faithful to the cat-
egory 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 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 or
by using the fontsize option. The -c and -v flags may be used to sup-
press 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". Option digits can be used to determine how many digits
after decimal point will be displayed.
When the -d flag is used to display a histogram distribution along side
the smoothed gradient legend, note that the statistics are calculated
on the current computational region settings set by g.region. The de-
fault range however covers the entire natural bounds of the input map.
If the histogram appears empty, check your region settings.
If the raster map’s units metadata has been set with the r.support mod-
ule then it will be displayed along side the legend.
The option title will display the custom title at the top of the leg-
end. In case of vertical legend the title is aligned to the left edge
of legend, in case of horizontal legend the title is aligned to the
center. title_fontsize can be used to set the size of legend title. By
default the legend title font size is the same as labels font size.
There are different options to customize displayed labels. The labelnum
set the number of labels which are displayed in regular intervals. The
label_values will specify the values where the labels will be dis-
played. The label_step will display labels at values which are divisi-
ble by this value.
The flag -t will show ticks at labels.
The flag -b will show the background. Options bgcolor and border_color
can be used to choose the color of border and background fill.
The flag -l will switch to logarithmic scale. In case this flag is
used, the provided step in label_step is interpreted in the logarithmic
space.
EXAMPLE
Displaying the legend along with a histogram (North Carolina Sample
dataset):
g.region raster=elevation -p
d.rast elevation
d.legend -d elevation
Displaying the legend with custom labels and background:
g.region raster=elevation -p
d.rast elevation
d.legend raster=elevation -t label_step=20 label_values=108 title=Legend -b bgcolor=255:255:204 border_color=gray
Displaying the legend with logarithmic scale:
g.region raster=elevation -p
r.watershed -a elevation=elevation threshold=1000 accumulation=flowacc
d.rast flowacc
d.legend raster=flowacc -t -l label_step=1
SEE ALSO
d.barscale, d.colortable, d.font, d.grid, d.rast, d.rast.leg, d.text,
d.vect.thematic, r.reclass, r.stats, r3.stats
AUTHORS
Bill Brown, U.S. Army Construction Engineering Research Laboratories
Late 2002: Rewrite of much of the code. Hamish Bowman, Otago Univer-
sity, New Zealand
Additional improvements from various authors
SOURCE CODE
Available at: d.legend source code (history)
Accessed: unknown
Main index | Display index | Topics index | Keywords index | Graphical
index | Full index
© 2003-2022 GRASS Development Team, GRASS GIS 7.8.7 Reference Manual
GRASS 7.8.7 d.legend(1grass)
Generated by dwww version 1.14 on Sun Dec 29 19:33:34 CET 2024.