1v.overlay(1) GRASS GIS User's Manual v.overlay(1)
2
6 v.overlay - Overlays two vector maps offering clip, intersection, dif‐
7 ference, symmetrical difference, union operators.
8
10 vector, geometry, spatial query, clip, difference, intersection, union
11
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 Flags:
22 -t
23 Do not create attribute table
24 --overwrite
26 Allow output files to overwrite existing files
27 --help
29 Print usage summary
30 --verbose
32 Verbose module output
33 --quiet
35 Quiet module output
36 --ui
38 Force launching GUI dialog
39 Parameters:
41 ainput=name [required]
42 Name of input vector map (A)
43 Or data source for direct OGR access
44 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 atype=string[,string,...]
53 Feature type (vector map A)
54 Input feature type
55 Options: line, area, auto
56 Default: auto
57 binput=name [required]
59 Name of input vector map (B)
60 Or data source for direct OGR access
61 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 btype=string[,string,...]
70 Feature type (vector map B)
71 Input feature type
72 Options: area
73 Default: area
74 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 output=name [required]
90 Name for output vector map
91 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 snap=float
98 Snapping threshold for boundaries
99 Disable snapping with snap <= 0
100 Default: 1e-8
101
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 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
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 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 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 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 If atype=auto is given than v.overlay determines feature type for ain‐
139 put from the first found feature.
140
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 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 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 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 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 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 Figure: v.overlay results of AND, OR, NOT, XOR operations
195 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 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 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 Figure: v.overlay: Line to polygon clipping
248
251 v.clip, v.db.connect, v.select, g.copy
252
254 Radim Blazek, ITC-Irst, Trento, Italy
255 Markus Metz
256 Speedup for large, complex input areas sponsored by mundialis
257
259 Available at: v.overlay source code (history)
260 Accessed: Saturday Jan 21 21:16:17 2023
262 Main index | Vector index | Topics index | Keywords index | Graphical
264 index | Full index
265 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
267GRASS 8.2.1 v.overlay(1)