d.legend(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

d.legend 💖

okay bestie, gather round, because this is the GRASS GIS User's Manual page for d.legend(1) and it is lowkey the most iconic way to put a legend on your map. ✨

🌸 NAME 🌸

d.legend — it draws a legend for a 2D or 3D raster map, right there in the active frame of your graphics monitor. no cap, that's the whole job. 👑

🎀 KEYWORDS 🎀

display, cartography, legend

✨ SYNOPSIS ✨

d.legend
d.legend --help
d.legend [-vctnsfdbl]  [raster=name]   [raster_3d=name]   [title=string]
[title_fontsize=float]   [lines=integer]   [thin=integer]
[units=string]   [labelnum=integer]   [label_values=float[,float,...]]
[label_step=float]   [digits=integer]   [at=bottom,top,left,right]
[use=float[,float,...]]   [range=min,max]   [color=name]   [font=string]
[fontsize=float]   [path=name]   [charset=string]   [border_color=name]
[bgcolor=name]   [--help]  [--verbose]  [--quiet]  [--ui]

🦋 Flags 🦋

  • -v — bestie do NOT show category labels 🙈
  • -c — and do NOT show category numbers either
  • -t — draw legend ticks for the labels ✏️
  • -n — skip categories that have no label, we're not doing filler content
  • -s — draw a smooth gradient, it's giving ombré 🌈
  • -f — flip the legend 🔄
  • -d — add a histogram to the smoothed legend 📊
  • -b — show the background 🎨
  • -l — use logarithmic scale 📈
  • --help — print the usage summary
  • --verbose — verbose module output, she's chatty
  • --quiet — quiet module output, she's mysterious
  • --ui — force launching the GUI dialog 🖥️

💜 Parameters 💜

  • raster=name — Name of raster map
  • raster_3d=name — Name of 3D raster map
  • title=string — Legend title
  • title_fontsize=float — Title font size
    • Default: Same as fontsize
    • Options: 1-360
  • lines=integer — Number of text lines (super 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
  • units=string — Units to display after labels (e.g. meters)
  • labelnum=integer — Number of text labels for smooth gradient legend
    • Options: 2-100
    • Default: 5
  • label_values=float[,float,...] — Specific values to draw ticks
  • label_step=float — Display label every step
  • digits=integer — Number of digits after decimal point
    • Options: 0-6
  • 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=float[,float,...] — List of discrete category numbers/values for legend
  • range=min,max — Use a subset of the map range for the legend (min,max)
  • color=name — Text color
    • Either a standard color name or R:G:B triplet
    • Default: black
  • font=string — Font name
  • fontsize=float — Font size
    • Default: Auto-scaled
    • Options: 1-360
  • path=name — Path to font file
  • charset=string — Text encoding (only applicable to TrueType fonts)
  • border_color=name — Border color
    • Either a standard color name, R:G:B triplet, or "none"
    • Default: black
  • bgcolor=name — Background color
    • Either a standard color name, R:G:B triplet, or "none"
    • Default: white

💅 DESCRIPTION 💅

So d.legend displays a legend for a user-specified raster map or 3D raster map layer, and it does it in the active frame on the graphics monitor. main character behavior honestly.

The legend's default size is based on the dimensions of the active frame — specifically its height. And d.legend will only obscure those portions of the active frame that directly underlie the legend. it's polite like that. 🫶

🌈 NOTES 🌈

When using the at to size & place the legend, a user may create a horizontal legend by making the box wider than it is tall. it's giving landscape mode bestie.

Raster maps based on floating point values will display smoothed, from greatest to smallest value, while categorical 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 that's not the vibe you wanted, 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). we love a minimalist.

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 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 or by using the fontsize option. 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". Option digits can be used to determine how many digits after decimal point will be displayed.

When the -d flag is used to display a histogram distribution along side the smoothed gradient legend, note that the statistics are calculated on the current computational region settings set by g.region. The default range however covers the entire natural bounds of the input map. If the histogram appears empty, check your region settings. 💀

If the raster map's units metadata has been set with the r.support module then it will be displayed along side the legend. 👑

The option title will display the custom title at the top of the legend. In case of vertical legend the title is aligned to the left edge of legend, in case of horizontal legend the title is aligned to the center. title_fontsize can be used to set the size of legend title. By default the legend title font size is the same as labels font size.

There are different options to customize displayed labels. The labelnum set the number of labels which are displayed in regular intervals. The label_values will specify the values where the labels will be displayed. The label_step will display labels at values which are divisible by this value.

The flag -t will show ticks at labels.

The flag -b will show the background. Options bgcolor and border_color can be used to choose the color of border and background fill. 🎨

The flag -l will switch to logarithmic scale. In case this flag is used, the provided step in label_step is interpreted in the logarithmic space.

🍓 EXAMPLE 🍓

Displaying the legend along with a histogram (North Carolina Sample dataset):

g.region raster=elevation -p
d.rast elevation
d.legend -d elevation

Displaying the legend with custom labels and background:

g.region raster=elevation -p
d.rast elevation
d.legend raster=elevation -t label_step=20 label_values=108 title=Legend -b bgcolor=255:255:204 border_color=gray

Displaying the legend with logarithmic scale:

g.region raster=elevation -p
r.watershed -a elevation=elevation threshold=1000 accumulation=flowacc
d.rast flowacc
d.legend raster=flowacc -t -l label_step=1

💖 SEE ALSO 💖

d.barscale, d.colortable, d.font, d.grid, d.rast, d.rast.leg, d.text, d.vect.thematic, r.reclass, r.stats, r3.stats

👑 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

🌟 SOURCE CODE 🌟

Available at: d.legend source code (history)

Accessed: Saturday Jan 17 05:40:36 2026

Main index | Display index | Topics index | Keywords index | Graphical index | Full index

and that's the whole thing bestie, we ate and left absolutely no crumbs. 🧚 the source is the GRASS Development Team, © 2003-2025, from the GRASS GIS 8.4.2 Reference Manual — and the manual itself is running GRASS 8.4.2, d.legend(1). slay. 💅✨

📦 where this page comes from