v.overlay(1)

📦

version 8.4.2 · 8 versions

v.overlay 💅✨

okay bestie, this is v.overlay from the GRASS GIS User's Manual — and she is that girl. She overlays two vector maps and serves you clip, intersection, difference, symmetrical difference and union operators. all of them. no crumbs. 🦋

✨ KEYWORDS ✨

vector, geometry, spatial query, clip, difference, intersection, union

🌸 SYNOPSIS 🌸

v.overlay
v.overlay --help
v.overlay [-t] ainput=name  [alayer=string]
[atype=string[,string,...]]  binput=name  [blayer=string]
[btype=string[,string,...]]  operator=string output=name
[olayer=string[,string,...]]   [snap=float]   [--overwrite]  [--help]
[--verbose]  [--quiet]  [--ui]

🎀 Flags 🎀

-t — do NOT create an attribute table. she's giving minimalism, we love her for it.
--overwrite — let the output files go ahead and bulldoze any existing files with the same name. allowed. permitted. 💥
--help — print the usage summary, aka the lil cheat sheet.
--verbose — verbose module output, she will simply tell you everything.
--quiet — quiet module output. shhh. 🤫
--ui — force launching the GUI dialog, for when you want the pretty buttons.

🫶 Parameters 🫶

ainput=name [required] — name of input vector map (A). or, plot twist, the data source for direct OGR access.
alayer=string — layer number or name (vector map A). vector features can have category values in different layers, and this number decides which layer to use. when you're on direct OGR access, this is the layer name instead. Default: 1
atype=string[,string,...] — feature type (vector map A), aka the input feature type. Options: line, area, auto. Default: auto
binput=name [required] — name of input vector map (B). or data source for direct OGR access, same deal as A.
blayer=string — layer number or name (vector map B). vector features can have category values in different layers, and this number picks which layer. with direct OGR access it's the layer name. Default: 1
btype=string[,string,...] — feature type (vector map B), input feature type. Options: area. Default: area
operator=string [required] — the operator defines which features get written to the output vector map. a feature gets written to output if the result of the operation ainput operator binput is true. an input feature counts as true if the category of the given layer is defined. Options: and, or, not, xor
- and: also known as 'intersection' in GIS
- or: also known as 'union' in GIS (only for atype=area)
- not: also known as 'difference' (features from ainput not overlaid by features from binput)
- xor: also known as 'symmetrical difference' (features from either ainput or binput but not those from ainput overlaid by binput (only for atype=area)
output=name [required] — name for output vector map. your baby. name her well. 👑
olayer=string[,string,...] — output layer for new category, ainput and binput. if 0 or not given, the category is not written. Default: 1,0,0
snap=float — snapping threshold for boundaries. disable snapping with snap <= 0. Default: 1e-8

💖 DESCRIPTION 💖

v.overlay lets you overlay two vector maps, no cap. features in ainput can be lines or areas, and they get cut with areas in binput. and if all you want is a simple clip? the and operator has you covered. slay. ✂️

if areas in ainput are overlaid with areas in binput, sometimes you have to snap areas of binput to those of ainput — otherwise areas can just go missing (gone, vanished, ghosted 😭) or you get a whole army of sliver areas spawned into existence. snapping is enabled by default and you can turn it off by setting the snap option to a negative value. recommended values live between 0.00000001 and 0.0001. using larger values for snapping can have undesired side-effects, but sometimes it's genuinely necessary to get a clean output (there's an example below, iykyk). in general, start small with your snapping threshold and gradually increase it until the result is reasonably clean. 💅

snapping modifies only boundaries in binput, which get snapped to boundaries in ainput. boundaries in ainput are not modified. periodt.

🌈 NOTES 🌈

currently only areas in ainput are supported for the operators or and xor! 💀 see also v.select. the operator defines what kind of operation will be done. features are written to output if the result of an operation ainput operator binput is true.

if the first number of the olayer option is greater than 0, then the resulting output map has a merged attribute table in the given layer number. the original column names get a prefix (a_ and b_) matching ainput and binput respectively.

if the second number of the olayer option is greater than 0, then the categories of ainput in layer alayer are transferred to the output layer with the second number.

if the third number of the olayer option is greater than 0, then the categories of binput in layer blayer are transferred to the output layer with the third number.

if atype=auto is given, then v.overlay determines the feature type for ainput from the first found feature. ✨

🍓 EXAMPLES 🍓

prep of the example data (North Carolina sample dataset, she's iconic):

# Create an empty box for overlaying to ZIP code vector map
v.mkgrid map=box grid=1,1 position=coor coordinates=584037,201970 box=50000,50000
# set region to ZIP codes and box vector maps
g.region vector=zipcodes_wake,box -p res=100 -a
# enlarge region a bit for "white border" around map in monitor
g.region n=n+1000 s=s-1000 w=w-1000 e=e+1000 -p
d.mon wx0

⭐ AND operator

clipping example (no attribute table is generated here, we're going bare):

d.vect map=zipcodes_wake fill_color=0:128:0
d.vect map=box fill_color=85:130:176
v.overlay -t ainput=box binput=zipcodes_wake operator=and output=v_overlay_AND
d.vect map=v_overlay_AND

Figure: v.overlay with AND operator (selected polygons in yellow color)

⭐ OR operator

union example of areas:

d.vect map=zipcodes_wake fill_color=0:128:0
d.vect map=box fill_color=85:130:176
v.overlay -t ainput=box binput=zipcodes_wake operator=or output=v_overlay_OR
d.vect map=v_overlay_OR

Figure: v.overlay with OR operator (selected polygons in yellow color)

⭐ XOR operator

symmetrical difference example:

d.vect map=zipcodes_wake fill_color=0:128:0
d.vect map=box fill_color=85:130:176
v.overlay -t ainput=box binput=zipcodes_wake operator=xor output=v_overlay_XOR
d.vect map=v_overlay_XOR

Figure: v.overlay with XOR operator (selected polygons in yellow color)

⭐ NOT operator

difference example:

d.vect map=zipcodes_wake fill_color=0:128:0
d.vect map=box fill_color=85:130:176
v.overlay -t ainput=box binput=zipcodes_wake operator=not output=v_overlay_NOT
d.vect map=v_overlay_NOT

Figure: v.overlay with NOT operator (selected polygon in yellow color)

🧚 Overlay operations: AND, OR, NOT, XOR

ZIP code examples, based on the North Carolina sample dataset:

# creation of simple dataset
v.extract input=zipcodes_wake output=poly1 where="cat = 42"
v.extract input=urbanarea output=poly2 where="cat = 55"
v.overlay ainput=poly1 binput=poly2 operator=and output=poly_1_2_and
v.overlay ainput=poly1 binput=poly2 operator=or  output=poly_1_2_or
v.overlay ainput=poly1 binput=poly2 operator=not output=poly_1_2_not
v.overlay ainput=poly1 binput=poly2 operator=xor output=poly_1_2_xor

Figure: v.overlay operations: original input polygons

Figure: v.overlay results of AND, OR, NOT, XOR operations

🧚 Polygons overlaid with polygons

v.overlay ainput=lake binput=province output=lakeXprovince operator=or

polygon union of urban area and Census 2000 areas (North Carolina dataset):

# input maps
d.vect urbanarea
d.vect census_wake2000
# union
v.overlay ain=census_wake2000 bin=urbanarea out=urban_census2000 operator=or
# show result, graphically zooming a subset
g.region n=230400 s=223800 w=655800 e=662400
d.erase
d.vect urban_census2000
# show merged attribute table
v.db.select urban_census2000 where="cat=108" -v
cat|108
a_cat|98
a_AREA|231001264
a_PERIMETE|67804.305
a_TRACT_|98
a_TRACT_ID|98
a_RINGS_OK|1
a_RINGS_NO|0
a_ID|98
a_FIPSSTCO|37183
a_TRT2000|054108
a_STFID|37183054108
a_TRACTID|541.08
a_TRACT|541.08
b_cat|55
b_OBJECTID|55
b_UA|73261
b_NAME|Raleigh
b_UA_TYPE|UA

Figure: v.overlay: Polygon union (right) of urban area (left) and Census 2000 (middle) areas (North Carolina dataset)

as you can literally see by the resulting large number of centroids on boundaries, the urban areas do not match exactly the Census 2000 areas. in this case a clean result can be obtained by snapping with a threshold of 0.1 m. 💅

🧚 Lines overlaid with polygons

using the North Carolina sample dataset, we clip the roads map to the area of the city of Raleigh, preserving road attributes in layer 1:

g.region vector=zipcodes_wake
# extract Raleigh city:
v.extract in=zipcodes_wake out=raleigh where="ZIPNAME = ’RALEIGH’"
# clip road network to city polygon:
v.overlay ainput=roadsmajor atype=line binput=raleigh out=roadsmajor_raleigh operator=and olayer=0,1,0

Figure: v.overlay: Line to polygon clipping

👀 SEE ALSO 👀

v.clip, v.db.connect, v.select, g.copy

👑 AUTHORS 👑

Radim Blazek, ITC-Irst, Trento, Italy
Markus Metz
Speedup for large, complex input areas sponsored by mundialis

💜 SOURCE CODE 💜

available at: v.overlay source code (history)

accessed: Saturday Jan 17 05:41:29 2026

okay that's the whole thing, bestie — every flag, every default, every number, all of it, untouched. go overlay something gorgeous. 🫶✨

📦 where this page comes from

fedora 44: grass 8.4.2-4.fc44 · GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms