v.label.sa - GRASS manual
Author: GRASS Development Team
Description: v.label.sa: Create optimally placed labels for vector map(s)
Keywords: vector, paint labels

## NAME

v.label.sa - Create optimally placed labels for vector map(s)

## KEYWORDS

vector, paint labels

## SYNOPSIS

v.label.sa
v.label.sa --help
v.label.sa map=name [type=string[,string,...]] [layer=string] column=string labels=name font=string [size=float] [isize=float] [charset=string] [color=string] [hcolor=string] [hwidth=float] [background=string] [opaque=yes|no] [border=string] [width=float] [--help] [--verbose] [--quiet] [--ui]

### Flags:

--help
  Print usage summary
--verbose
  Verbose module output
--quiet
  Quiet module output
--ui
  Force launching GUI dialog

### Parameters:

map=name [required]
  Name of vector map
  Or data source for direct OGR access
type=string[,string,...]
  Input feature type
  Options: point, line, area
  Default: point,line,area
layer=string
  Layer number or name
  Vector features can have category values in different layers. This number determines which layer to use. When used with direct OGR access this is the layer name.
  Default: 1
column=string [required]
  Name of attribute column to be used for labels
labels=name [required]
  Name for new paint-label file
font=string [required]
  Name of TrueType font (as listed in the fontcap)
size=float
  Label size (in map-units)
  Default: 100
isize=float
  Icon size of point features (in map-units)
  Default: 10
charset=string
  Character encoding (default: UTF-8)
  Default: UTF-8
color=string
  Text color
  Options: aqua, black, blue, brown, cyan, gray, green, grey, indigo, magenta, orange, purple, red, violet, white, yellow
  Default: black
hcolor=string
  Highlight color for text
  Options: none, aqua, black, blue, brown, cyan, gray, green, grey, indigo, magenta, orange, purple, red, violet, white, yellow
  Default: none
hwidth=float
  Width of highlight coloring
  Default: 0
background=string
  Background color
  Options: none, aqua, black, blue, brown, cyan, gray, green, grey, indigo, magenta, orange, purple, red, violet, white, yellow
  Default: none
opaque=yes|no
  Opaque to vector (only relevant if background color is selected)
  Options: yes, no
  Default: yes
border=string
  Border color
  Options: none, aqua, black, blue, brown, cyan, gray, green, grey, indigo, magenta, orange, purple, red, violet, white, yellow
  Default: none
width=float
  Border width (only for ps.map output)
  Default: 0

## DESCRIPTION

v.label.sa makes a label-file from a GRASS vector map with labels created from attributes in the attached table. The labels are placed in as optimal place as possible. The label file has the same syntax as the one created by v.label

## EXAMPLE

North Carolina example:

    # get font names:
    d.font -L

    v.label.sa roadsmajor labels=roads_labels column=ROAD_NAME color=red \
               background=white size=250 font=Vera

    # set region:
    g.region raster=lsat7_2002_10 -p

    # display:
    d.rgb b=lsat7_2002_10 g=lsat7_2002_20 r=lsat7_2002_30
    d.vect roadsmajor col=yellow
    d.labels roads_labels

Road labeling with v.label.sa (Raleigh, North Carolina, USA, area)

## REFERENCES

Edmondson, Christensen, Marks and Shieber: A General Cartographic Labeling Algorithm, Cartographica, Vol. 33, No. 4, Winter 1996, pp. 13-23 The algorithm works by the principle of Simulated Annealing.

## SEE ALSO

d.label
d.labels
ps.map Wikipedia article on simulated annealing

## AUTHOR

Wolf Bergenheim

## SOURCE CODE

Available at: v.label.sa source code (history)

Latest change: Friday Apr 17 01:04:26 2026 in commit: 5a31d549cc0150239894bd2b9e67250af87d38b5

Main index | Vector index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.6.0dev Reference Manual