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

NAME

6       v.generalize  - Performs vector based generalization.
7

KEYWORDS

9       vector,  generalization,  simplification, smoothing, displacement, net‐
10       work generalization, topology, geometry
11

SYNOPSIS

13       v.generalize
14       v.generalize --help
15       v.generalize         [-lt]          input=name           [layer=string]
16       [type=string[,string,...]]   output=name   [error=name]   method=string
17       threshold=float         [look_ahead=integer]          [reduction=float]
18       [slide=float]        [angle_thresh=float]       [degree_thresh=integer]
19       [closeness_thresh=float]    [betweeness_thresh=float]     [alpha=float]
20       [beta=float]    [iterations=integer]   [cats=range]   [where=sql_query]
21       [--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]
22
23   Flags:
24       -l
25           Disable loop support
26           Do not modify end points of lines forming a closed loop
27
28       -t
29           Do not copy attributes
30
31       --overwrite
32           Allow output files to overwrite existing files
33
34       --help
35           Print usage summary
36
37       --verbose
38           Verbose module output
39
40       --quiet
41           Quiet module output
42
43       --ui
44           Force launching GUI dialog
45
46   Parameters:
47       input=name [required]
48           Name of input vector map
49           Or data source for direct OGR access
50
51       layer=string
52           Layer number or name (’-1’ for all layers)
53           A single vector map can be connected to multiple  database  tables.
54           This  number  determines  which table to use. When used with direct
55           OGR access this is the layer name.
56           Default: -1
57
58       type=string[,string,...]
59           Input feature type
60           Options: line, boundary, area
61           Default: line,boundary,area
62
63       output=name [required]
64           Name for output vector map
65
66       error=name
67           Error map with failed generalizations
68           Lines and boundaries causing errors (collapsed to a point or topol‐
69           ogy errors)
70
71       method=string [required]
72           Generalization algorithm
73           Options:  douglas,  douglas_reduction,  lang,  reduction,  reumann,
74           boyle,  sliding_averaging,  distance_weighting,  chaiken,  hermite,
75           snakes, network, displacement
76           douglas: Douglas-Peucker Algorithm
77           douglas_reduction: Douglas-Peucker Algorithm with reduction parame‐
78           ter
79           lang: Lang Simplification Algorithm
80           reduction: Vertex Reduction Algorithm eliminates  points  close  to
81           each other
82           reumann: Reumann-Witkam Algorithm
83           boyle: Boyle’s Forward-Looking Algorithm
84           sliding_averaging: McMaster’s Sliding Averaging Algorithm
85           distance_weighting: McMaster’s Distance-Weighting Algorithm
86           chaiken: Chaiken’s Algorithm
87           hermite: Interpolation by Cubic Hermite Splines
88           snakes: Snakes method for line smoothing
89           network: Network generalization
90           displacement: Displacement of lines close to each other
91
92       threshold=float [required]
93           Maximal tolerance value
94           Options: 0-1000000000
95
96       look_ahead=integer
97           Look-ahead parameter
98           Default: 7
99
100       reduction=float
101           Percentage of the points in the output of ’douglas_reduction’ algo‐
102           rithm
103           Options: 0-100
104           Default: 50
105
106       slide=float
107           Slide of computed point toward the original point
108           Options: 0-1
109           Default: 0.5
110
111       angle_thresh=float
112           Minimum angle between two consecutive segments in Hermite method
113           Options: 0-180
114           Default: 3
115
116       degree_thresh=integer
117           Degree threshold in network generalization
118           Default: 0
119
120       closeness_thresh=float
121           Closeness threshold in network generalization
122           Options: 0-1
123           Default: 0
124
125       betweeness_thresh=float
126           Betweeness threshold in network generalization
127           Default: 0
128
129       alpha=float
130           Snakes alpha parameter
131           Default: 1.0
132
133       beta=float
134           Snakes beta parameter
135           Default: 1.0
136
137       iterations=integer
138           Number of iterations
139           Default: 1
140
141       cats=range
142           Category values
143           Example: 1,3,7-9,13
144
145       where=sql_query
146           WHERE conditions of SQL statement without ’where’ keyword
147           Example: income < 1000 and population >= 10000
148

DESCRIPTION

150       v.generalize is a module for the generalization of GRASS  vector  maps.
151       This  module  consists  of  algorithms  for  line  simplification, line
152       smoothing, network generalization and displacement (new methods may  be
153       added later).
154
155       The  cats  and where options are used only if a layer > 0 is specified,
156       otherwise, those options are ignored. Be  aware  that  the  default  is
157       layer=-1,  meaning that all layers are processed, ignoring the cats and
158       where options.
159
160       If type=area is selected, boundaries of selected areas will be general‐
161       ized, and the options cats, where, and layer will be used to select ar‐
162       eas.
163

NOTES

165       (Line) simplification is a process of reducing the complexity of vector
166       features.  The module transforms a line into another line consisting of
167       fewer vertices, that still approximate the original line. Most  of  the
168       algorithms  described  below  select a subset of points on the original
169       line.
170
171       (Line) smoothing is a "reverse" process which takes as input a line and
172       produces a smoother approximate of the original. In some cases, this is
173       achieved by inserting new vertices into the original line, and can  to‐
174       tal  up  to 4000% of the number of vertices in the original. In such an
175       instance, it is always a good idea to simplify the line  after  smooth‐
176       ing.
177
178       Smoothing and simplification algorithms implemented in this module work
179       line by line, i.e. simplification/smoothing of one line does not affect
180       the other lines; they are treated separately. For isolated loops formed
181       by a single  line/boundary,  he  first  and  the  last  point  of  each
182       line/boundary  can  be translated and/or deleted, unless the -l flag is
183       used to disable loop support.
184
185       Lines and boundaries are not translated if they  would  collapse  to  a
186       single  point.  Boundaries  are  not translated if they would intersect
187       with themselves or other boundaries. Such erroneous features are  writ‐
188       ten  to an optional error vector map. Overlaying the error map over the
189       generalized map indicates the kind of error.  Lines/boundaries collaps‐
190       ing to a point are written out as points, boundaries violating topology
191       are written out as boundaries. The error map can be overlaid  over  the
192       generalized map to understand why some features were not generalized.
193
194   SIMPLIFICATION
195       Simplification  can  fail for many boundaries if the simplification pa‐
196       rameters would result  in  a  large  reduction  of  vertices.  If  many
197       lines/boundaries could not be simplified, try different parameters that
198       would cause a lower degree of simplification.
199
200       v.generalize contains following line simplification algorithms:
201
202           •   Douglas-Peucker Algorithm
203
204           •   Douglas-Peucker Reduction Algorithm
205
206           •   Lang Algorithm
207
208           •   Vertex Reduction
209
210           •   Reumann-Witkam Algorithm
211       Different algorithms require different parameters, but  all  the  algo‐
212       rithms  have one parameter in common: the threshold parameter, given in
213       map units (for latitude-longitude locations:  in  decimal  degree).  In
214       general,  the  degree  of  simplification increases with the increasing
215       value of threshold.
216
217   ALGORITHM DESCRIPTIONS
218Douglas-Peucker - "Quicksort" of line simplification, the  most
219               widely  used algorithm. Input parameters: input, threshold. For
220               more information, see:
221               http://geomalgorithms.com/a16-_decimate-1.html.
222
223Douglas-Peucker Reduction Algorithm is essentially the same al‐
224               gorithm  as  the  algorithm above, the difference being that it
225               takes an additional reduction parameter which denotes the  per‐
226               centage of the number of points on the new line with respect to
227               the number of points on the original  line.  Input  parameters:
228               input, threshold, reduction.
229
230Lang  -  Another  standard  algorithm. Input parameters: input,
231               threshold, look_ahead.  For an excellent description, see:
232               http://www.sli.unimelb.edu.au/gisweb/LGmodule/LGLangVisualisa
233               tion.htm.
234
235Vertex Reduction - Simplest among the algorithms. Input parame‐
236               ters: input, threshold.  Given a line, this  algorithm  removes
237               the  points  of  this  line which are closer to each other than
238               threshold. More precisely, if p1 and  p2  are  two  consecutive
239               points, and the distance between p2 and p1 is less than thresh‐
240               old, it removes p2 and repeats the same process on the  remain‐
241               ing points.
242
243Reumann-Witkam  - Input parameters: input, threshold.  This al‐
244               gorithm quite reasonably preserves the  global  characteristics
245               of the lines. For more information, see for example:
246               http://psimpl.sourceforge.net/reumann-witkam.html.
247       Douglas-Peucker  and  Douglas-Peucker  Reduction Algorithm use the same
248       method to simplify the lines. Note that
249       v.generalize input=boundary_county output=boundary_county_dp20 method=douglas threshold=20
250       is equivalent to
251       v.generalize input=boundary_county output=boundary_county_dp_red20_100 \
252                    method=douglas_reduction threshold=20 reduction=100
253       However, in this case, the first method is faster.  Also  observe  that
254       douglas_reduction  never  outputs more vertices than douglas, and that,
255       in general, douglas is more efficient than douglas_reduction. More  im‐
256       portantly, the effect of
257       v.generalize input=boundary_county output=boundary_county_dp_red0_30 \
258                    method=douglas_reduction threshold=0 reduction=30
259       is that ’out’ contains approximately only 30% of points of ’in’.
260
261   SMOOTHING
262       The following smoothing algorithms are implemented in v.generalize:
263
264Boyle’s  Forward-Looking Algorithm - The position of each point
265               depends on the position of the previous points  and  the  point
266               look_ahead  ahead. look_ahead consecutive points. Input parame‐
267               ters: input, look_ahead.
268
269McMaster’s Sliding Averaging Algorithm - Input Parameters:  in‐
270               put,  slide, look_ahead.  The new position of each point is the
271               average of the look_ahead points  around.  Parameter  slide  is
272               used for linear interpolation between old and new position (see
273               below).
274
275McMaster’s Distance-Weighting Algorithm -  Takes  the  weighted
276               average  of  look_ahead  consecutive points where the weight is
277               the reciprocal of the distance from the point to the  currently
278               smoothed point. The parameter slide is used for linear interpo‐
279               lation between the original position of  the  point  and  newly
280               computed  position  where  value 0 means the original position.
281               Input parameters: input, slide, look_ahead.
282
283Chaiken’s Algorithm - "Inscribes" a line touching the  original
284               line such that the points on this new line are at least thresh‐
285               old apart. Input parameters: input, threshold.  This  algorithm
286               approximates the given line very well.
287
288Hermite  Interpolation - This algorithm takes the points of the
289               given line as the control points of hermite  cubic  spline  and
290               approximates  this spline by the points approximately threshold
291               apart. This method has excellent results for  small  values  of
292               threshold,  but  in  this case it produces a huge number of new
293               points and some simplification is usually needed.  Input param‐
294               eters:  input,  threshold,  angle_thresh.  Angle_thresh is used
295               for reducing the number of the points.  It denotes the  minimal
296               angle (in degrees) between two consecutive segments of a line.
297
298Snakes is the method of minimisation of the "energy" of a line.
299               This method preserves the general characteristics of the  lines
300               but smooths the "sharp corners" of a line. Input parameters in‐
301               put, alpha, beta.  This algorithm works  very  well  for  small
302               values  of  alpha  and beta (between 0 and 5). These parameters
303               affect the "sharpness" and the curvature of the computed line.
304       One of the key advantages of Hermite Interpolation is the fact that the
305       computed  line  always  passes through the points of the original line,
306       whereas the lines produced  by  the  remaining  algorithms  never  pass
307       through  these  points.  In  some  sense, this algorithm outputs a line
308       which "circumscribes" the input line.
309
310       On the other hand, Chaiken’s Algorithm outputs a line which "inscribes"
311       a  given  line. The output line always touches/intersects the centre of
312       the input line segment between two consecutive points. For more  itera‐
313       tions,  the  property  above  does not hold, but the computed lines are
314       very similar to the Bezier Splines. The disadvantage of the  two  algo‐
315       rithms  given  above  is that they increase the number of points.  How‐
316       ever, Hermite Interpolation can be used as another simplification algo‐
317       rithm.  To  achieve this, it is necessary to set angle_thresh to higher
318       values (15 or so).
319
320       One restriction on both McMasters’ Algorithms is that look_ahead param‐
321       eter  must  be  odd.  Also note that these algorithms have no effect if
322       look_ahead = 1.
323
324       Note that Boyle’s, McMasters’ and Snakes algorithm are  sometimes  used
325       in  the  signal  processing  to  smooth the signals.  More importantly,
326       these algorithms never change the number of points on the  lines;  they
327       only translate the points, and do not insert any new points.
328
329       Snakes  Algorithm  is (asymptotically) the slowest among the algorithms
330       presented above. Also, it requires quite a lot of memory.   This  means
331       that  it  is  not  very efficient for maps with the lines consisting of
332       many segments.
333
334   DISPLACEMENT
335       The displacement is used when the lines overlap  and/or  are  close  to
336       each  other  at  the  current level of detail. In general, displacement
337       methods move the conflicting features apart so that they do not  inter‐
338       act and can be distinguished.
339
340       This module implements an algorithm for displacement of linear features
341       based on the Snakes approach. This method generally  yields  very  good
342       results;  however,  it  requires  a lot of memory and is not very effi‐
343       cient.
344
345       Displacement is selected by method=displacement. It uses the  following
346       parameters:
347
348threshold  - specifies critical distance. Two features interact
349               if they are closer than threshold apart.
350
351alpha, beta - These parameters define the  rigidity  of  lines.
352               For  larger  values  of alpha, beta (>=1), the algorithm does a
353               better job at retaining the original shape of the lines, possi‐
354               bly  at  the expense of displacement distance. If the values of
355               alpha, beta are too small (<=0.001), then the lines  are  moved
356               sufficiently, but the geometry and topology of lines can be de‐
357               stroyed.  Most likely the best way to find the good  values  of
358               alpha, beta is by trial and error.
359
360iterations  - denotes the number of iterations the interactions
361               between the lines are resolved. Good starting points for values
362               of iterations are between 10 and 100.
363       The lines affected by the algorithm can be specified by the layer, cats
364       and where parameters.
365
366   NETWORK GENERALIZATION
367       Used for selecting "the most important" part of the  network.  This  is
368       based  on  the  graph  algorithms. Network generalization is applied if
369       method=network.  The algorithm calculates three centrality measures for
370       each  line  in  the  network and only the lines with the values greater
371       than thresholds are selected.  The behaviour of algorithm  can  be  al‐
372       tered by the following parameters:
373
374degree_thresh  - algorithm selects only the lines which share a
375               point with at least degree_thresh different lines.
376
377closeness_thresh - is always in the  range  (0,  1].  Only  the
378               lines  with  the  closeness  centrality  value  at least close‐
379               ness_thresh apart are selected. The lines in the  centre  of  a
380               network have greater values of this measure than the lines near
381               the border of a network. This means that this parameter can  be
382               used  for  selecting  the  centre(s) of a network. Note that if
383               closeness_thresh=0 then everything is selected.
384
385betweeness_thresh - Again, only the  lines  with  a  betweeness
386               centrality  measure  at  least  betweeness_thresh are selected.
387               This value is always positive and is larger for large networks.
388               It  denotes to what extent a line is in between the other lines
389               in the network. This value is large for the lines which lie be‐
390               tween  other  lines and lie on the paths between two parts of a
391               network. In the terminology of road networks, these  are  high‐
392               ways, bypasses, main roads/streets, etc.
393       All  three  parameters above can be presented at the same time. In that
394       case, the algorithm selects only the lines which meet each criterion.
395
396       Also, the outputed network may not be connected if the value of betwee‐
397       ness_thresh is too large.
398

EXAMPLES

400   SIMPLIFICATION EXAMPLE
401       Simplification of county boundaries with DP method (North Carolina sam‐
402       ple dataset), threshold given in mapset units (here: meters):
403       v.generalize input=boundary_county output=boundary_county_dp20 \
404         method=douglas threshold=20 error=boundary_county_dp20_leftover
405       Figure: Vector simplification example  (spatial  subset:  original  map
406       shown  in  black,  simplified  map with 26% remaining vertices shown in
407       red)
408
409   SMOOTHING EXAMPLE
410       Smoothing of road network with Chaiken method  (North  Carolina  sample
411       dataset), threshold given in mapset units (here: meters):
412       v.generalize input=roads output=roads_chaiken method=chaiken \
413         threshold=1 error=roads_chaiken_leftover
414       Figure: Vector smoothing example (spatial subset: original map shown in
415       black, smoothed map with 500% increased number  of  vertices  shown  in
416       red)
417

SEE ALSO

419        v.clean, v.dissolve
420
421       v.generalize Tutorial (GRASS-Wiki)
422

AUTHORS

424       Daniel Bundala, Google Summer of Code 2007, Student
425       Wolf Bergenheim, Mentor
426       Partial rewrite: Markus Metz
427

SOURCE CODE

429       Available at: v.generalize source code (history)
430
431       Accessed: Saturday Jan 21 21:16:03 2023
432
433       Main  index  | Vector index | Topics index | Keywords index | Graphical
434       index | Full index
435
436       © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
437
438
439
440GRASS 8.2.1                                                    v.generalize(1)
Impressum