Ubuntu Manpage: d.legend - Displays a legend for a raster map in the active frame of the graphics

NAME

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

KEYWORDS

       display, cartography

SYNOPSIS

       d.legend
       d.legend help
       d.legend   [-mvcnsf]    map=name     [color=name]      [lines=integer]      [thin=integer]
       [labelnum=integer]           [at=bottom,top,left,right]          [use=catnum[,catnum,...]]
       [range=min,max]   [--verbose]  [--quiet]

   Flags:
       -m
           Use mouse to size & place legend

       -v
           Do not show category labels

       -c
           Do not show category numbers

       -n
           Skip categories with no label

       -s
           Draw smooth gradient

       -f
           Flip legend

       --verbose
           Verbose module output

       --quiet
           Quiet module output

   Parameters:
       map=name
           Name of raster map

       color=name
           Text color
           Either a standard color name or R:G:B triplet
           Default: black

       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

       labelnum=integer
           Number of text labels for smooth gradient legend
           Options: 2-100
           Default: 5

       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=catnum[,catnum,...]
           List of discrete category numbers/values for legend

       range=min,max
           Use a subset of the map range for the legend (min,max)

DESCRIPTION

       d.legend displays a legend for a user-specified raster map layer in the  active  frame  on
       the graphics monitor.

       The  user  can  run  d.legend  either  non-interactively  or  interactively.   If the user
       specifies the name of a raster map layer on the command line, the program  will  run  non-
       interactively.   Default  legend  text  color  and  position  will be used unless the user
       specifies other values on the command line.

       Alternately, the user can simply type d.legend on the command  line;  in  this  case,  the
       program will prompt the user for parameter values using the standard GRASS GUI interface.

NOTES

The legend's default size is based on the dimensions of the active frame, specifically its
height. d.legend will only obscure those portions of the active frame that directly
underlie the legend.

When using the mouse or at to size & place the legend, a user may create a horizontal
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 categorial 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 displayed, or the -s flag to force a smooth gradient legend.

The lines option will display the first number of categories, as defined 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 category values. e.g.
use=1000,100,10,0,-10,-100,-1000

The range option lets the user define the minimum and maximum categories to be used in the
legend. It may also be used to define the limits of a smooth gradient legend created from
a raster containing floating point values. Note the color scale will remain faithful to
the category 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 mouse
or 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. The -c
and -v flags may be used to suppress 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".

Legends placed with the mouse are not saved to the display window's history for automatic
redraw. By setting the Debug level to 1 (see g.gisenv) the corresponding at setting can be
determined.

Note that old scripts which relied on setting lines greater than the number of categories
to scale the legend may no longer produce the desired output, although the auto-scaling
should still produce something that looks good in this case.

AUTHORS