## NAME

d.legend - Displays a legend for a raster map layer in the active frame on the graphics monitor.
(GRASS Display Program)

## SYNOPSIS

d.legend
d.legend help
d.legend [-vcnsmf] map=name [color=name] [lines=value] [thin=value] [labelnum=value] [at=bottom,top,left,right] [range=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 parser interface.

## OPTIONS

### Flags:

-v
  Do not show category labels
-c
  Do not show category numbers
-n
  Skip categories with no label (ignored for floating point maps)
-s
  Draw smooth gradient (forced automatically for floating point rasters)
-m
  Use mouse to size & place legend
-f
  Flip legend vertically or horizontally

### Parameters:

map=name
  Name of raster map.
color=name
  Sets the legend's text color.
  Options: red, orange, yellow, green, blue, indigo, white, black, brown, magenta, aqua, gray, grey
  Default: white
lines=value
  Number of lines in the legend (useful for truncating long legends)
  Options: 0-1000
  Default: all
thin=value
  Thinning factor (thin=10 gives cats 0,10,20...)
  Options: 0-1000
  Default: 1
labelnum=value
  Number of text labels for smooth gradient legend
  Options: 2-100
  Default: 5
at=bottom,top,left,right
  Placement coordinates, as 0-100% of graphics frame height/width. 0,0 is lower left.
  Options: 0-100
  Default: automatically placed and scaled
range=min,max
  Category range
  Default: all

## 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, if the user makes a horizontal box the values run from left to right and no category values are printed (you may want to use d.label for that). A horizontal legend is created if the box is 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. 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, 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 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.

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 produce text labels to the right of the legend box. 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".

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.

## TODO

- Add use option for legends of discrete category numbers/values only.
- Text labels for horizontal legends.

## SEE ALSO

d.colormode
d.colors
d.colortable
d.display
d.erase
d.grid
d.rast
d.rast.labels
d.rast.leg
d.vect
d.what.rast
r.reclass
parser

## AUTHORS

Bill Brown, U.S. Army Construction Engineering Research Laboratories
Late 2002: Rewrite of much of the code. Hamish Bowman, Otago University, New Zealand
Additional improvements from various authors

Last changed: $Date: 2003/03/16 12:25:19 $