d.legend(1)

1d.legend(1)                   Grass User's Manual                  d.legend(1)
2
3
4

NAME

6       d.legend   -  Displays a legend for a raster map in the active frame of
7       the graphics monitor.
8

KEYWORDS

10       display
11

SYNOPSIS

13       d.legend
14       d.legend help
15       d.legend   [-mvcnsf]   map=string    [color=string]     [lines=integer]
16       [thin=integer]       [labelnum=integer]      [at=bottom,top,left,right]
17       [use=catnum[,catnum,...]]   [range=min,max]   [--verbose]  [--quiet]
18
19   Flags:
20       -m
21           Use mouse to size & place legend
22
23       -v
24           Do not show category labels
25
26       -c
27           Do not show category numbers
28
29       -n
30           Skip categories with no label
31
32       -s
33           Draw smooth gradient
34
35       -f
36           Flip legend
37
38       --verbose
39           Verbose module output
40
41       --quiet
42           Quiet module output
43
44   Parameters:
45       map=string
46           Name of raster map
47
48       color=string
49           Sets the legend's text color
50           Options:                   red,orange,yellow,green,blue,indigo,vio‐
51           let,white,black,gray,brown,magenta,aqua,grey,cyan,purple
52           Default: black
53
54       lines=integer
55           Number of text lines (useful for truncating long legends)
56           Options: 0-1000
57           Default: 0
58
59       thin=integer
60           Thinning factor (thin=10 gives cats 0,10,20...)
61           Options: 1-1000
62           Default: 1
63
64       labelnum=integer
65           Number of text labels for smooth gradient legend
66           Options: 2-100
67           Default: 5
68
69       at=bottom,top,left,right
70           Placement as percentage of screen coordinates (0,0 is lower left)
71           bottom,top,left,right
72           Options: 0-100
73
74       use=catnum[,catnum,...]
75           List of discrete category numbers/values for legend
76
77       range=min,max
78           Use a subset of the map range for the legend (min,max)
79

DESCRIPTION

81       d.legend displays a legend for a user-specified raster map layer in the
82       active frame on the graphics monitor.
83
84       The user can run d.legend either  non-interactively  or  interactively.
85       If  the  user  specifies  the name of a raster map layer on the command
86       line, the program will  run  non-interactively.   Default  legend  text
87       color  and position will be used unless the user specifies other values
88       on the command line.
89
90       Alternately, the user can simply type d.legend on the command line;  in
91       this  case, the program will prompt the user for parameter values using
92       the standard GRASS GUI interface.
93

NOTES

95       The legend's default size is based on  the  dimensions  of  the  active
96       frame,  specifically its height.  d.legend will only obscure those por‐
97       tions of the active frame that directly underlie the legend.
98
99       When using the mouse or at to size & place the legend, a user may  cre‐
100       ate a horizontal legend by making the box wider than it is tall.
101
102       Raster  maps based on floating point values will display smoothed, from
103       greatest to smallest value, while categorial raster maps  will  display
104       in  order,  from  top  to  bottom.  Horizontal  legends  will always be
105       smoothed. If the box is defined with inverted y-values or  an  inverted
106       range,  the  legend will automatically flip. If this is not the desired
107       result, the -f flag may be used to flip it back.
108
109       If the user attempts to display a very  long  legend  in  a  relatively
110       short display frame, the legend may appear in unreadably small text, or
111       even revert to a smooth gradient legend.  Use  the  lines,  thin,  use,
112       range,  and/or -n options to reduce the number of categories to be dis‐
113       played, or the -s flag to force a smooth gradient legend.
114
115       The lines option will  display  the  first  number  of  categories,  as
116       defined  by  value,  contained in the raster map. When used with the -n
117       flag, it takes on a new meaning: "up to category  #".  When  used  with
118       both thin and the -n flag, its meaning becomes more obscure. When using
119       lines, auto-scaled text similar to "4 of 16 categories" will be  placed
120       at the bottom of the legend.
121
122       The  thin  option  sets the thinning factor. For raster maps with a 0th
123       category, thin=10 gives cats [0,10,20,...]. For raster maps starting at
124       category 1, thin=10 gives cats [1,11,21,...].
125
126       The use option lets the user create a legend made up of arbitrary cate‐
127       gory values. e.g. use=1000,100,10,0,-10,-100,-1000
128
129       The range option lets the user define the  minimum  and  maximum  cate‐
130       gories to be used in the legend. It may also be used to define the lim‐
131       its of a smooth gradient legend created from a raster containing float‐
132       ing point values. Note the color scale will remain faithful to the cat‐
133       egory values as defined with r.colors, and the range may be extended to
134       the limits defined by the r.colors color map.
135
136       The flag -n is useful for categorial maps, as it suppresses the drawing
137       of non-existing categories (otherwise the full range is shown).
138
139       Vertical legends produced with d.legend will place text labels  to  the
140       right of the legend box, horizontal legends will place text below. This
141       text will be auto-scaled to fit within the frame, reducing the size  of
142       the  legend if necessary. Legends positioned with the mouse or with the
143       at option will not auto-scale text, in order to provide more control to
144       the  user.   Smaller  text may be obtained in this case by reducing the
145       height of the box. The -c and -v flags may be used to suppress the dis‐
146       play  of  category numbers and labels respectively, or used together to
147       suppress all text of categorial raster maps.
148
149       The text produced from floating-point raster  maps  will  automatically
150       create  output with a meaningful number of significant digits. For very
151       small values, numbers will be expressed in  scientific  notation,  e.g.
152       "1.7e-9".
153
154       Legends  placed  with  the  mouse are not saved to the display window's
155       history for automatic redraw. By setting the  Debug  level  to  1  (see
156       g.gisenv) the corresponding at setting can be determined.
157
158       Note  that  old  scripts which relied on setting lines greater than the
159       number of categories to scale the legend  may  no  longer  produce  the
160       desired  output,  although  the auto-scaling should still produce some‐
161       thing that looks good in this case.
162

AUTHORS

181       Bill Brown, U.S. Army Construction Engineering Research Laboratories
182       Late 2002: Rewrite of much of the code. Hamish  Bowman,  Otago  Univer‐
183       sity, New Zealand
184       Additional improvements from various authors
185
186       Last changed: $Date: 2005-10-28 01:20:21 +0200 (Fri, 28 Oct 2005) $
187
188       Full index
189
190       © 2003-2008 GRASS Development Team
191
192
193
194GRASS 6.3.0                                                        d.legend(1)

NAME

KEYWORDS

SYNOPSIS

DESCRIPTION

NOTES

SEE ALSO

AUTHORS