1d.legend(1) GRASS GIS User's Manual d.legend(1)
2
6 d.legend - Displays a legend for a 2D or 3D raster map in the active
7 frame of the graphics monitor.
8
10 display, cartography, legend
11
13 d.legend
14 d.legend --help
15 d.legend [-vctnsfdbl] [raster=name] [raster_3d=name] [ti‐
16 tle=string] [title_fontsize=float] [lines=integer] [thin=integer]
17 [units=string] [labelnum=integer] [label_values=float[,float,...]]
18 [label_step=float] [digits=integer] [at=bottom,top,left,right]
19 [use=float[,float,...]] [range=min,max] [color=name]
20 [font=string] [fontsize=float] [path=name] [charset=string]
21 [border_color=name] [bgcolor=name] [--help] [--verbose] [--quiet]
22 [--ui]
23 Flags:
25 -v
26 Do not show category labels
27 -c
29 Do not show category numbers
30 -t
32 Draw legend ticks for labels
33 -n
35 Skip categories with no label
36 -s
38 Draw smooth gradient
39 -f
41 Flip legend
42 -d
44 Add histogram to smoothed legend
45 -b
47 Show background
48 -l
50 Use logarithmic scale
51 --help
53 Print usage summary
54 --verbose
56 Verbose module output
57 --quiet
59 Quiet module output
60 --ui
62 Force launching GUI dialog
63 Parameters:
65 raster=name
66 Name of raster map
67 raster_3d=name
69 Name of 3D raster map
70 title=string
72 Legend title
73 title_fontsize=float
75 Title font size
76 Default: Same as fontsize
77 Options: 1-360
78 lines=integer
80 Number of text lines (useful for truncating long legends)
81 Options: 0-1000
82 Default: 0
83 thin=integer
85 Thinning factor (thin=10 gives cats 0,10,20...)
86 Options: 1-1000
87 Default: 1
88 units=string
90 Units to display after labels (e.g. meters)
91 labelnum=integer
93 Number of text labels for smooth gradient legend
94 Options: 2-100
95 Default: 5
96 label_values=float[,float,...]
98 Specific values to draw ticks
99 label_step=float
101 Display label every step
102 digits=integer
104 Number of digits after decimal point
105 Options: 0-6
106 at=bottom,top,left,right
108 Size and placement as percentage of screen coordinates (0,0 is
109 lower left)
110 bottom,top,left,right
111 Options: 0-100
112 use=float[,float,...]
114 List of discrete category numbers/values for legend
115 range=min,max
117 Use a subset of the map range for the legend (min,max)
118 color=name
120 Text color
121 Either a standard color name or R:G:B triplet
122 Default: black
123 font=string
125 Font name
126 fontsize=float
128 Font size
129 Default: Auto-scaled
130 Options: 1-360
131 path=name
133 Path to font file
134 charset=string
136 Text encoding (only applicable to TrueType fonts)
137 border_color=name
139 Border color
140 Either a standard color name, R:G:B triplet, or "none"
141 Default: black
142 bgcolor=name
144 Background color
145 Either a standard color name, R:G:B triplet, or "none"
146 Default: white
147
149 d.legend displays a legend for a user-specified raster map or 3D raster
150 map layer in the active frame on the graphics monitor.
151 The legend’s default size is based on the dimensions of the active
153 frame, specifically its height. d.legend will only obscure those por‐
154 tions of the active frame that directly underlie the legend.
155
157 When using the at to size & place the legend, a user may create a hori‐
158 zontal legend by making the box wider than it is tall.
159 Raster maps based on floating point values will display smoothed, from
161 greatest to smallest value, while categorical raster maps will display
162 in order, from top to bottom. Horizontal legends will always be
163 smoothed. If the box is defined with inverted y-values or an inverted
164 range, the legend will automatically flip. If this is not the desired
165 result, the -f flag may be used to flip it back.
166 If the user attempts to display a very long legend in a relatively
168 short display frame, the legend may appear in unreadably small text, or
169 even revert to a smooth gradient legend. Use the lines, thin, use,
170 range, and/or -n options to reduce the number of categories to be dis‐
171 played, or the -s flag to force a smooth gradient legend.
172 The lines option will display the first number of categories, as de‐
174 fined by value, contained in the raster map. When used with the -n
175 flag, it takes on a new meaning: "up to category #". When used with
176 both thin and the -n flag, its meaning becomes more obscure. When using
177 lines, auto-scaled text similar to "4 of 16 categories" will be placed
178 at the bottom of the legend.
179 The thin option sets the thinning factor. For raster maps with a 0th
181 category, thin=10 gives cats [0,10,20,...]. For raster maps starting at
182 category 1, thin=10 gives cats [1,11,21,...].
183 The use option lets the user create a legend made up of arbitrary cate‐
185 gory values. e.g. use=1000,100,10,0,-10,-100,-1000
186 The range option lets the user define the minimum and maximum cate‐
188 gories to be used in the legend. It may also be used to define the lim‐
189 its of a smooth gradient legend created from a raster containing float‐
190 ing point values. Note the color scale will remain faithful to the cat‐
191 egory values as defined with r.colors, and the range may be extended to
192 the limits defined by the r.colors color map.
193 The flag -n is useful for categorial maps, as it suppresses the drawing
195 of non-existing categories (otherwise the full range is shown).
196 Vertical legends produced with d.legend will place text labels to the
198 right of the legend box, horizontal legends will place text below. This
199 text will be auto-scaled to fit within the frame, reducing the size of
200 the legend if necessary. Legends positioned with the at option will not
201 auto-scale text, in order to provide more control to the user. Smaller
202 text may be obtained in this case by reducing the height of the box or
203 by using the fontsize option. The -c and -v flags may be used to sup‐
204 press the display of category numbers and labels respectively, or used
205 together to suppress all text of categorial raster maps.
206 The text produced from floating-point raster maps will automatically
208 create output with a meaningful number of significant digits. For very
209 small values, numbers will be expressed in scientific notation,
210 e.g. "1.7e-9". Option digits can be used to determine how many digits
211 after decimal point will be displayed.
212 When the -d flag is used to display a histogram distribution along side
214 the smoothed gradient legend, note that the statistics are calculated
215 on the current computational region settings set by g.region. The de‐
216 fault range however covers the entire natural bounds of the input map.
217 If the histogram appears empty, check your region settings.
218 If the raster map’s units metadata has been set with the r.support mod‐
220 ule then it will be displayed along side the legend.
221 The option title will display the custom title at the top of the leg‐
223 end. In case of vertical legend the title is aligned to the left edge
224 of legend, in case of horizontal legend the title is aligned to the
225 center. title_fontsize can be used to set the size of legend title. By
226 default the legend title font size is the same as labels font size.
227 There are different options to customize displayed labels. The labelnum
229 set the number of labels which are displayed in regular intervals. The
230 label_values will specify the values where the labels will be dis‐
231 played. The label_step will display labels at values which are divisi‐
232 ble by this value.
233 The flag -t will show ticks at labels.
235 The flag -b will show the background. Options bgcolor and border_color
237 can be used to choose the color of border and background fill.
238 The flag -l will switch to logarithmic scale. In case this flag is
240 used, the provided step in label_step is interpreted in the logarithmic
241 space.
242
244 Displaying the legend along with a histogram (North Carolina Sample
245 dataset):
246 g.region raster=elevation -p
247 d.rast elevation
248 d.legend -d elevation
249 Displaying the legend with custom labels and background:
250 g.region raster=elevation -p
251 d.rast elevation
252 d.legend raster=elevation -t label_step=20 label_values=108 title=Legend -b bgcolor=255:255:204 border_color=gray
253 Displaying the legend with logarithmic scale:
254 g.region raster=elevation -p
255 r.watershed -a elevation=elevation threshold=1000 accumulation=flowacc
256 d.rast flowacc
257 d.legend raster=flowacc -t -l label_step=1
258
260 d.barscale, d.colortable, d.font, d.grid, d.rast, d.rast.leg, d.text,
261 d.vect.thematic, r.reclass, r.stats, r3.stats
262
264 Bill Brown, U.S. Army Construction Engineering Research Laboratories
265 Late 2002: Rewrite of much of the code. Hamish Bowman, Otago Univer‐
266 sity, New Zealand
267 Additional improvements from various authors
268
270 Available at: d.legend source code (history)
271 Accessed: Saturday Jan 21 20:38:07 2023
273 Main index | Display index | Topics index | Keywords index | Graphical
275 index | Full index
276 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
278GRASS 8.2.1 d.legend(1)