| 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 & 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. <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. "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 |