d.legend.vect(1grass)

📦
version 8.5.0 · 10 versions
, in alpine 3.24, ubuntu stonking

💖 d.legend.vect — the vector legend bestie 💖

okay so you want a legend for your vector maps, in the active graphics frame? bestie, this is literally the module. it's d.legend.vect, from the GRASS User's Manual, and she ate. 👑

✨ NAME ✨

d.legend.vect — draws a vector legend in the active graphics frame. that's it, that's the whole job, and she does it flawlessly. 💅

🌸 KEYWORDS 🌸

display, cartography, vector, legend

🎀 SYNOPSIS 🎀

d.legend.vect
d.legend.vect --help
d.legend.vect [-b]  [at=left,top]   [columns=integer]   [title=string]
[symbol_size=integer]   [border_color=name]   [bgcolor=name]
[border_width=integer]   [font=string]   [fontsize=float]
[title_font=string]   [title_fontsize=float]   [sub_font=string]
[sub_fontsize=float]   [fontcolor=name]   [separator=character]
[input=name]   [output=name]   [--overwrite]  [--help]  [--verbose]
[--quiet]  [--ui]

🚩 Flags

  • -b — display legend background. give her a little backdrop, she deserves it. ✨
  • --overwrite — allow output files to overwrite existing files. no cap, this one will absolutely replace what's already there.
  • --help — print usage summary. your friendly lil cheat sheet.
  • --verbose — verbose module output. she will not stop talking and honestly? we love that.
  • --quiet — quiet module output. she's giving mysterious, silent, unbothered.
  • --ui — force launching GUI dialog. for when you simply cannot with the terminal today. 🫶

🧚 Parameters

  • at=left,top — screen position of legend to be drawn (percentage, [0,0] is lower left)
    • Options: 0-100
    • Default: 10,40
  • columns=integer — number of legend columns
    • Default: 1
  • title=string — legend title
  • symbol_size=integer — symbol size
    • Default: 20
  • 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
  • border_width=integer — background border width
    • Default: 2
  • font=string — font name
  • fontsize=float — font size
    • Default: 12
    • Options: 1-360
  • title_font=string — title font name
  • title_fontsize=float — title font size
    • Default: 18
    • Options: 1-360
  • sub_font=string — subtitle font name
  • sub_fontsize=float — subtitle font size
    • Default: 14
    • Options: 1-360
  • fontcolor=name — font color
    • Either a standard color name or R:G:B triplet
    • Default: black
  • separator=character — field separator for input file
    • Special characters: pipe, comma, space, tab, newline
    • Default: pipe
  • input=name — input legend file
    • Path to legend file
  • output=name — output csv file
    • Path to output file or '-' for standard output

💜 DESCRIPTION 💜

bestie, d.legend.vect draws the vector legend of the vector maps that are currently displayed. no extras, no nonsense.

The parameter at defines the screen position of the upper-left legend corner. The parameter columns defines the number of legend columns. You can specify a title for the legend with the parameter title. The font of the title can be changed with title_font and title_fontsize. The flag -b is used to draw the background of the specified color (bgcolor), its border color and border width (border_color and border_width). The parameter symbol_size defines the size of line and area symbols. The size of point symbols is based on the currently set symbology of vector maps using d.vect or d.vect.thematic. 👑

The module d.vect.legend supports subtitles (peep the section Notes). Their font and font size can be set using the parameters sub_font and sub_fontsize. 🌸

🦋 Changing legend symbols and labels

Symbols for vector areas and lines, and labels for individual vector labels, can be changed in the symbology setting of each vector map in d.vect or d.vect.thematic (it's in the Legend tab, iykyk). Use its parameters icon_area and icon_line to pick from the available symbols. And by using the parameter legend_label of the d.vect module, users can change the default label, which is the map name. glow-up complete. ✨

🌈 Modifying the order of legend entries and omitting certain vector maps from legend

Modules d.vect and d.vect.thematic have a flag -s which removes that particular vector or thematic vector from the vector legend. not me ghosting a whole layer 💀

The order of the entries is defined by the order in the Layer Manager (if used in the GRASS GUI). If that's not desired, one can export the legend file into a text file using the parameter output, change the order of the entries (check the section Notes for the format description) and then upload the modified file with the parameter input. The parameter output defines the path to the file where the internal legend file will be saved to; input defines the input file which the vector legend will be based on (and bestie, that input file must have the correct format). 🫶

🎀 NOTES 🎀

The module d.legend.vect draws the vector legend based on the legend file defined in the shell environment variable GRASS_LEGEND_FILE. This file is automatically created and updated whenever the d.vect command is used. A user can create a custom legend file and then use export GRASS_LEGEND_FILE=path/to/file in the shell. The GRASS GUI and MONITORS create the legend file automatically. By default the legend file is stored in the grassdata/project/mapset/.tmp/user directory (in case of d.mon, deeper, in the /monitor_name directory). 🗂️

The legend file has this format:

label|symbol_name|size|color_type|feature_color|fill_color|line_width|geometry_type|feature_count

The color type can be 'lf' or 'ps'. Based on the color type, the color columns are interpreted as line color and fill colors (lf), or primary and secondary colors (ps). The module d.vect always uses 'lf' and d.vect.thematic uses 'ps'. 👑

Here is an example of a legend file with subtitles:

Infrastructure||||||||
major roads|legend/line|5|lf|black|200:200:200|2|line|355
bridges|extra/bridge|15|lf|black|black|1|point|10938
Hydrology||||||||
streams|legend/line_crooked|5|lf|30:144:255|200:200:200|3|line|8554
water bodies|legend/area_curved|5|lf|none|30:144:255|1|area|27764

literally the blueprint. 🦋

⭐ EXAMPLES ⭐

open a cairo monitor to render to a file:

g.region vector=nc_state
d.mon cairo
d.vect map=nc_state color=26:26:26 fill_color=229:229:229 width=2 legend_label="state boundaries"
d.vect map=urbanarea color=none fill_color=127:127:127 width=1 legend_label="urban areas"
d.vect map=railroads color=red width=1
d.vect map=hospitals color=77:77:77 fill_color=0:187:0 width=1 icon=basic/cross3 size=10
d.legend.vect -b at=2,40 title="Hospitals in North Carolina" symbol_size=26 fontsize=16 title_fontsize=20

she's giving map, she's giving legend, she's giving iconic. 🔥

👑 SEE ALSO 👑

d.vect, d.vect.thematic, d.legend

Also check out the Python module from AddOns: d.vect.thematic2

💖 AUTHORS 💖

Adam Laza, during GSoC 2016 Mentors: Anna Petrasova, Vaclav Petras, Martin Landa

🌟 SOURCE CODE 🌟

Available at: d.legend.vect source code (history)

Latest change: Friday Jan 30 10:35:22 2026 in commit: ad41fefc6cca34964bc4d1057a72aa32b91780bc

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

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual GRASS 8.5.0 — d.legend.vect(1grass)

okay bestie that's the whole page, every flag, every default, every color triplet, literally all of it. go draw your legend and slay 💅✨🌸💖🦋

📦 where this page comes from