1v.overlay(1)                GRASS GIS User's Manual               v.overlay(1)
2
3
4

NAME

6       v.overlay  - Overlays two vector maps offering clip, intersection, dif‐
7       ference, symmetrical difference, union operators.
8

KEYWORDS

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

SYNOPSIS

13       v.overlay
14       v.overlay --help
15       v.overlay          [-t]          ainput=name            [alayer=string]
16       [atype=string[,string,...]]         binput=name         [blayer=string]
17       [btype=string[,string,...]]         operator=string         output=name
18       [olayer=string[,string,...]]    [snap=float]    [--overwrite]  [--help]
19       [--verbose]  [--quiet]  [--ui]
20
21   Flags:
22       -t
23           Do not create attribute table
24
25       --overwrite
26           Allow output files to overwrite existing files
27
28       --help
29           Print usage summary
30
31       --verbose
32           Verbose module output
33
34       --quiet
35           Quiet module output
36
37       --ui
38           Force launching GUI dialog
39
40   Parameters:
41       ainput=name [required]
42           Name of input vector map (A)
43           Or data source for direct OGR access
44
45       alayer=string
46           Layer number or name (vector map A)
47           Vector features can have category values in different layers.  This
48           number determines which layer to use. When used with direct OGR ac‐
49           cess this is the layer name.
50           Default: 1
51
52       atype=string[,string,...]
53           Feature type (vector map A)
54           Input feature type
55           Options: line, area, auto
56           Default: auto
57
58       binput=name [required]
59           Name of input vector map (B)
60           Or data source for direct OGR access
61
62       blayer=string
63           Layer number or name (vector map B)
64           Vector features can have category values in different layers.  This
65           number determines which layer to use. When used with direct OGR ac‐
66           cess this is the layer name.
67           Default: 1
68
69       btype=string[,string,...]
70           Feature type (vector map B)
71           Input feature type
72           Options: area
73           Default: area
74
75       operator=string [required]
76           Operator defines features written to output vector map
77           Feature is written to output if the result of operation ’ainput op‐
78           erator  binput’ is true. Input feature is considered to be true, if
79           category of given layer is defined.
80           Options: and, or, not, xor
81           and: also known as ’intersection’ in GIS
82           or: also known as ’union’ in GIS (only for atype=area)
83           not: also known as ’difference’ (features from ainput not  overlaid
84           by features from binput)
85           xor:  also  known as ’symmetrical difference’ (features from either
86           ainput or binput but not those from ainput overlaid by binput (only
87           for atype=area)
88
89       output=name [required]
90           Name for output vector map
91
92       olayer=string[,string,...]
93           Output layer for new category, ainput and binput
94           If 0 or not given, the category is not written
95           Default: 1,0,0
96
97       snap=float
98           Snapping threshold for boundaries
99           Disable snapping with snap <= 0
100           Default: 1e-8
101

DESCRIPTION

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

NOTES

120       Currently  only  areas in ainput are supported for the operators or and
121       xor! See also v.select.  The operator defines what  kind  of  operation
122       will be done. Features are written to output, if the result of an oper‐
123       ation ainput operator binput is true.
124
125       If the first number of the olayer option is greater than  0,  then  the
126       resulting  output  map  has a merged attribute table in the given layer
127       number. The original column names have a prefix (a_ and b_) correspond‐
128       ing to ainput and binput map.
129
130       If  the  second number of the olayer option is greater than 0, then the
131       categories of ainput in layer alayer  are  transferred  to  the  output
132       layer with the second number.
133
134       If  the  third  number of the olayer option is greater than 0, then the
135       categories of binput in layer blayer  are  transferred  to  the  output
136       layer with the third number.
137
138       If  atype=auto is given than v.overlay determines feature type for ain‐
139       put from the first found feature.
140

EXAMPLES

142       Preparation of example data (North Carolina sample dataset):
143       # Create an empty box for overlaying to ZIP code vector map
144       v.mkgrid map=box grid=1,1 position=coor coordinates=584037,201970 box=50000,50000
145       # set region to ZIP codes and box vector maps
146       g.region vector=zipcodes_wake,box -p res=100 -a
147       # enlarge region a bit for "white border" around map in monitor
148       g.region n=n+1000 s=s-1000 w=w-1000 e=e+1000 -p
149       d.mon wx0
150
151   AND operator
152       Clipping example (no attribute table is generated here):
153       d.vect map=zipcodes_wake fill_color=0:128:0
154       d.vect map=box fill_color=85:130:176
155       v.overlay -t ainput=box binput=zipcodes_wake operator=and output=v_overlay_AND
156       d.vect map=v_overlay_AND
157       Figure: v.overlay with AND operator (selected polygons in grey color)
158
159   OR operator
160       Union example of areas:
161       d.vect map=zipcodes_wake fill_color=0:128:0
162       d.vect map=box fill_color=85:130:176
163       v.overlay -t ainput=box binput=zipcodes_wake operator=or output=v_overlay_OR
164       d.vect map=v_overlay_OR
165       Figure: v.overlay with OR operator (selected polygons in grey color)
166
167   XOR operator
168       Symmetrical difference example:
169       d.vect map=zipcodes_wake fill_color=0:128:0
170       d.vect map=box fill_color=85:130:176
171       v.overlay -t ainput=box binput=zipcodes_wake operator=xor output=v_overlay_XOR
172       d.vect map=v_overlay_XOR
173       Figure: v.overlay with XOR operator (selected polygons in grey color)
174
175   NOT operator
176       Difference example:
177       d.vect map=zipcodes_wake fill_color=0:128:0
178       d.vect map=box fill_color=85:130:176
179       v.overlay -t ainput=box binput=zipcodes_wake operator=not output=v_overlay_NOT
180       d.vect map=v_overlay_NOT
181       Figure: v.overlay with NOT operator (selected polygon in grey color)
182
183   Overlay operations: AND, OR, NOT, XOR
184       ZIP code examples, based on North Carolina sample dataset:
185       # creation of simple dataset
186       v.extract input=zipcodes_wake output=poly1 where="cat = 42"
187       v.extract input=urbanarea output=poly2 where="cat = 55"
188       v.overlay ainput=poly1 binput=poly2 operator=and output=poly_1_2_and
189       v.overlay ainput=poly1 binput=poly2 operator=or  output=poly_1_2_or
190       v.overlay ainput=poly1 binput=poly2 operator=not output=poly_1_2_not
191       v.overlay ainput=poly1 binput=poly2 operator=xor output=poly_1_2_xor
192       Figure: v.overlay operations: original input polygons
193
194       Figure: v.overlay results of AND, OR, NOT, XOR operations
195
196   Polygons overlaid with polygons
197       v.overlay ainput=lake binput=province output=lakeXprovince operator=or
198       Polygon union of urban area  and  Census  2000  areas  (North  Carolina
199       dataset):
200       # input maps
201       d.vect urbanarea
202       d.vect census_wake2000
203       # union
204       v.overlay ain=census_wake2000 bin=urbanarea out=urban_census2000 operator=or
205       # show result, graphically zooming a subset
206       g.region n=230400 s=223800 w=655800 e=662400
207       d.erase
208       d.vect urban_census2000
209       # show merged attribute table
210       v.db.select urban_census2000 where="cat=108" -v
211       cat|108
212       a_cat|98
213       a_AREA|231001264
214       a_PERIMETE|67804.305
215       a_TRACT_|98
216       a_TRACT_ID|98
217       a_RINGS_OK|1
218       a_RINGS_NO|0
219       a_ID|98
220       a_FIPSSTCO|37183
221       a_TRT2000|054108
222       a_STFID|37183054108
223       a_TRACTID|541.08
224       a_TRACT|541.08
225       b_cat|55
226       b_OBJECTID|55
227       b_UA|73261
228       b_NAME|Raleigh
229       b_UA_TYPE|UA
230       Figure:  v.overlay: Polygon union (right) of urban area (left) and Cen‐
231       sus 2000 (middle) areas (North Carolina dataset)
232
233       As can be seen by the resulting large number  of  centroids  on  bound‐
234       aries,  the  urban areas do not match exactly the Census 2000 areas. In
235       this case a clean result can be obtained by snapping with  a  threshold
236       of 0.1 m.
237
238   Lines overlaid with polygons
239       Using  the  North Carolina sample dataset, we clip the roads map to the
240       area of city of Raleigh, preserving road attributes in layer 1:
241       g.region vector=zipcodes_wake
242       # extract Raleigh city:
243       v.extract in=zipcodes_wake out=raleigh where="ZIPNAME = ’RALEIGH’"
244       # clip road network to city polygon:
245       v.overlay ainput=roadsmajor atype=line binput=raleigh out=roadsmajor_raleigh operator=and olayer=0,1,0
246
247       Figure: v.overlay: Line to polygon clipping
248
249

SEE ALSO

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

AUTHORS

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

SOURCE CODE

259       Available at: v.overlay source code (history)
260
261       Accessed: Saturday Jan 21 21:16:17 2023
262
263       Main index | Vector index | Topics index | Keywords index  |  Graphical
264       index | Full index
265
266       © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
267
268
269
270GRASS 8.2.1                                                       v.overlay(1)
Impressum