Debian Codegraph @

display/d.legend/d.legend.html

raw
1 <h2>DESCRIPTION</h2>
2
3 <em>d.legend</em> displays a legend for a user-specified raster map or
4 3D raster map layer in the active frame on the graphics monitor.
5 <p>
6 The legend's default size is based on the dimensions of the
7 active frame, specifically its height. <em>d.legend</em> will only
8 obscure those portions of the active frame that directly underlie the legend.
9
10 <h2>NOTES</h2>
11
12 When using the <b>at</b> to size &amp; place the legend, a user may
13 create a horizontal legend by making the box wider than it is tall.
14 <p>
15 Raster maps based on floating point values will display smoothed, from greatest
16 to smallest value, while categorical raster maps will display in order, from
17 top to bottom. Horizontal legends will always be smoothed. If the box is defined
18 with inverted y-values or an inverted <b>range</b>, the legend will automatically
19 flip. If this is not the desired result, the <b>-f</b> flag may be used to flip
20 it back.
21 <p>
22 If the user attempts to display a very long legend in a relatively short
23 display frame, the legend may appear in unreadably small text, or even revert
24 to a smooth gradient legend. Use the <b>lines</b>, <b>thin</b>, <b>use</b>, <b>range</b>,
25 and/or <b>-n</b> options to reduce the number of categories to be displayed,
26 or the <b>-s</b> flag to force a smooth gradient legend.
27 <p>
28 The <b>lines</b> option will display the first number of categories, as defined
29 by <em>value</em>, contained in the raster map. When used with the <b>-n</b> flag,
30 it takes on a new meaning: "up to category #". When used with both
31 <b>thin</b> and the <b>-n</b> flag, its meaning becomes more obscure. When
32 using <b>lines</b>, auto-scaled text similar to "4 of 16 categories" will be placed at
33 the bottom of the legend.
34 <p>
35 The <b>thin</b> option sets the thinning factor. For raster maps with a 0th
36 category, <b>thin=</b><em>10</em> gives cats [0,10,20,...]. For raster maps
37 starting at category 1, <b>thin=</b><em>10</em> gives cats [1,11,21,...].
38 <p>
39 The <b>use</b> option lets the user create a legend made up of arbitrary category
40 values. e.g.&nbsp;<b>use=</b><em>1000,100,10,0,-10,-100,-1000</em>
41 <p>
42 The <b>range</b> option lets the user define the minimum and maximum categories
43 to be used in the legend. It may also be used to define the limits of a smooth
44 gradient legend created from a raster containing floating point values. Note
45 the color scale will remain faithful to the category values as defined with
46 <em><a href="r.colors.html">r.colors</a></em>, and the <b>range</b> may be
47 extended to the limits defined by the <em><a href="r.colors.html">r.colors</a></em>
48 color map.
49 <p>
50 The flag <b>-n</b> is useful for categorial maps, as it suppresses the
51 drawing of non-existing categories (otherwise the full range is shown).
52 <p>
53 Vertical legends produced with <em>d.legend</em> will place text labels to the
54 right of the legend box, horizontal legends will place text below. This text
55 will be auto-scaled to fit within the frame, reducing the size of the legend
56 if necessary. Legends positioned with the <b>at</b> option
57 will not auto-scale text, in order to provide more control to the user.
58 Smaller text may be obtained in this case by reducing the height of the box
59 or by using the <b>fontsize</b> option. The <b>-c</b> and <b>-v</b> flags may
60 be used to suppress the display of category numbers and labels respectively,
61 or used together to suppress all text of categorial raster maps.
62 <p>
63 The text produced from floating-point raster maps will automatically create
64 output with a meaningful number of significant digits. For very small values,
65 numbers will be expressed in scientific notation, e.g.&nbsp;"1.7e-9". Option
66 <b>digits</b> can be used to determine how many digits after decimal point
67 will be displayed.
68 <p>
69 When the <b>-d</b> flag is used to display a histogram distribution along
70 side the smoothed gradient legend, note that the statistics are calculated
71 on the <i>current computational region</i> settings set by <em>g.region</em>.
72 The default <b>range</b> however covers the entire natural bounds of the input map.
73 If the histogram appears empty, check your region settings.
74 <p>
75 If the raster map's <i>units</i> metadata has been set with the
76 <em>r.support</em> module then it will be displayed along side the legend.
77 <p>
78 The option <b>title</b> will display the custom title at the top of the legend.
79 In case of vertical legend the title is aligned to the left edge of legend, in case
80 of horizontal legend the title is aligned to the center. <b>title_fontsize</b> can
81 be used to set the size of legend title. By default the legend title font size is
82 the same as labels font size.
83 <p>
84 There are different options to customize displayed labels. The <b>labelnum</b> set
85 the number of labels which are displayed in regular intervals. The <b>label_values</b>
86 will specify the values where the labels will be displayed. The <b>label_step</b> will
87 display labels at values which are divisible by this value.
88 <p>
89 The flag <b>-t</b> will show ticks at labels.
90 <p>
91 The flag <b>-b</b> will show the background. Options <b>bgcolor</b> and <b>border_color</b> can be
92 used to choose the color of border and background fill.
93 <p>
94 The flag <b>-l</b> will switch to logarithmic scale. In case this flag is used,
95 the provided step in <b>label_step</b> is interpreted in the logarithmic space.
96 <h2>EXAMPLE</h2>
97
98 Displaying the legend along with a histogram (North Carolina Sample dataset):
99
100 <div class="code"><pre>
101 g.region raster=elevation -p
102 d.rast elevation
103 d.legend -d elevation
104 </pre></div>
105
106 <center>
107 <img src="d_legend.png" alt="Elevation map with legend" border="1">
108 </center>
109
110 Displaying the legend with custom labels and background:
111
112 <div class="code"><pre>
113 g.region raster=elevation -p
114 d.rast elevation
115 d.legend raster=elevation -t label_step=20 label_values=108 title=Legend -b bgcolor=255:255:204 border_color=gray
116 </pre></div>
117
118 <center>
119 <img src="d_legend_custom_labels_and_background.png" alt="Elevation map with custom legend" border="1">
120 </center>
121
122 Displaying the legend with logarithmic scale:
123
124 <div class="code"><pre>
125 g.region raster=elevation -p
126 r.watershed -a elevation=elevation threshold=1000 accumulation=flowacc
127 d.rast flowacc
128 d.legend raster=flowacc -t -l label_step=1
129 </pre></div>
130
131 <center>
132 <img src="d_legend_logarithmic.png" alt="Flow accumulation map with logarithmic legend" border="1">
133 </center>
134
135
136 <h2>SEE ALSO</h2>
137
138 <em>
139 <a href="d.barscale.html">d.barscale</a>,
140 <a href="d.colortable.html">d.colortable</a>,
141 <a href="d.font.html">d.font</a>,
142 <a href="d.grid.html">d.grid</a>,
143 <a href="d.rast.html">d.rast</a>,
144 <a href="d.rast.leg.html">d.rast.leg</a>,
145 <a href="d.text.html">d.text</a>,
146 <a href="d.vect.thematic.html">d.vect.thematic</a>,
147 <a href="r.reclass.html">r.reclass</a>,
148 <a href="r.stats.html">r.stats</a>,
149 <a href="r3.stats.html">r3.stats</a>
150 </em>
151
152 <h2>AUTHORS</h2>
153
154 Bill Brown, U.S. Army Construction Engineering Research Laboratories
155 <br>Late 2002: Rewrite of much of the code. Hamish Bowman,
156 Otago University, New Zealand
157 <br>Additional improvements from various authors