GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
v.overlay(1) Grass User's Manual v.overlay(1)

v.overlay - Overlays two vector maps offering clip, intersection, difference, symmetrical difference, union operators.

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

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]

-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

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

v.overlay allows the user to overlay two vector maps. Features in ainput can be lines or areas and are cut with areas in binput. Simple clipping can be performed with the and operator.
If areas in ainput are overlaid with areas in binput, it is sometimes necessary to snap areas of binput to those of ainput, otherwise areas can go missing or many sliver areas can be created. Snapping is enabled by default and can be disabled by setting the snap option to a negative value. Recommended values are between 0.00000001 and 0.0001. Using larger values for snapping can have undesired side-effects, but may sometimes be necessary to get a clean output (see example below). In general, it is recommended to start with a small snapping threshold, gradually increasing the threshold until the result is reasonably clean. Snapping modifies only boundaries in binput, which are snapped to boundaries in ainput. Boundaries in ainput are not modified.

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 have a prefix ( a_ and b_) corresponding to ainput and binput map.
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 than v.overlay determines feature type for ainput from the first found feature.

Preparation of example data (North Carolina sample dataset):
 
# 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

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)

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)

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)

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)

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

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.

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
 
Figure: v.overlay: Line to polygon clipping

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

Radim Blazek, ITC-Irst, Trento, Italy
 
Markus Metz
Last changed: $Date: 2017-11-03 17:54:37 +0100 (Fri, 03 Nov 2017) $

Available at: v.overlay source code (history)
Main index | Vector index | Topics index | Keywords index | Graphical index | Full index
© 2003-2018 GRASS Development Team, GRASS GIS 7.4.3 Reference Manual
GRASS 7.4.3

Search for    or go to Top of page |  Section 1 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.