v.label.sa(1)

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: 32a143358df26b2e518b03c7e0d79541e8d1e5b1

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

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual