Flags:¶

-t

Do not create attribute table

--overwrite

Allow output files to overwrite existing files

--help

Print usage summary

--verbose

Verbose module output

--quiet

Quiet module output

--ui

Force launching GUI dialog

Parameters:¶

ainput=name [required]

Name of input vector map (A)
Or data source for direct OGR access

alayer=string

Layer number or name (vector map A)
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

atype=string[,string,...]

Feature type (vector map A)
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

blayer=string

Layer number or name (vector map B)
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

btype=string[,string,...]

Feature type (vector map B)
Input feature type
Options: area
Default: area

operator=string [required]

Operator defines features written to output vector map
Feature is written to output if the result of operation ’ainput operator binput’ is true. Input feature is considered to be true, if category of 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

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

AND operator¶

Clipping example (no attribute table is generated here):

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 grey 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 grey 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 grey 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 grey color)

Overlay operations: AND, OR, NOT, XOR¶

ZIP code examples, based on 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 can be seen 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 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