Provided by: grass-doc_7.8.2-1build3_all bug

NAME

       v.generalize  - Performs vector based generalization.

KEYWORDS

       vector,  generalization,  simplification,  smoothing,  displacement,  network  generalization,  topology,
       geometry

SYNOPSIS

       v.generalize
       v.generalize --help
       v.generalize [-lt] input=name   [layer=string]    [type=string[,string,...]]   output=name   [error=name]
       method=string      threshold=float       [look_ahead=integer]       [reduction=float]       [slide=float]
       [angle_thresh=float]    [degree_thresh=integer]    [closeness_thresh=float]     [betweeness_thresh=float]
       [alpha=float]    [beta=float]    [iterations=integer]    [cats=range]   [where=sql_query]   [--overwrite]
       [--help]  [--verbose]  [--quiet]  [--ui]

   Flags:
       -l
           Disable loop support
           Do not modify end points of lines forming a closed loop

       -t
           Do not copy attributes

       --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:
       input=name [required]
           Name of input vector map
           Or data source for direct OGR access

       layer=string
           Layer number or name (’-1’ for all layers)
           A single vector map can be connected to multiple database tables. This number determines which  table
           to use. When used with direct OGR access this is the layer name.
           Default: -1

       type=string[,string,...]
           Input feature type
           Options: line, boundary, area
           Default: line,boundary,area

       output=name [required]
           Name for output vector map

       error=name
           Error map with failed generalizations
           Lines and boundaries causing errors (collapsed to a point or topology errors)

       method=string [required]
           Generalization algorithm
           Options:   douglas,   douglas_reduction,   lang,   reduction,   reumann,   boyle,  sliding_averaging,
           distance_weighting, chaiken, hermite, snakes, network, displacement
           douglas: Douglas-Peucker Algorithm
           douglas_reduction: Douglas-Peucker Algorithm with reduction parameter
           lang: Lang Simplification Algorithm
           reduction: Vertex Reduction Algorithm eliminates points close to each other
           reumann: Reumann-Witkam Algorithm
           boyle: Boyle’s Forward-Looking Algorithm
           sliding_averaging: McMaster’s Sliding Averaging Algorithm
           distance_weighting: McMaster’s Distance-Weighting Algorithm
           chaiken: Chaiken’s Algorithm
           hermite: Interpolation by Cubic Hermite Splines
           snakes: Snakes method for line smoothing
           network: Network generalization
           displacement: Displacement of lines close to each other

       threshold=float [required]
           Maximal tolerance value
           Options: 0-1000000000

       look_ahead=integer
           Look-ahead parameter
           Default: 7

       reduction=float
           Percentage of the points in the output of ’douglas_reduction’ algorithm
           Options: 0-100
           Default: 50

       slide=float
           Slide of computed point toward the original point
           Options: 0-1
           Default: 0.5

       angle_thresh=float
           Minimum angle between two consecutive segments in Hermite method
           Options: 0-180
           Default: 3

       degree_thresh=integer
           Degree threshold in network generalization
           Default: 0

       closeness_thresh=float
           Closeness threshold in network generalization
           Options: 0-1
           Default: 0

       betweeness_thresh=float
           Betweeness threshold in network generalization
           Default: 0

       alpha=float
           Snakes alpha parameter
           Default: 1.0

       beta=float
           Snakes beta parameter
           Default: 1.0

       iterations=integer
           Number of iterations
           Default: 1

       cats=range
           Category values
           Example: 1,3,7-9,13

       where=sql_query
           WHERE conditions of SQL statement without ’where’ keyword
           Example: income < 1000 and population >= 10000

DESCRIPTION

       v.generalize is a module for the generalization of GRASS vector maps. This module consists of  algorithms
       for  line  simplification,  line  smoothing,  network generalization and displacement (new methods may be
       added later).

       The cats and where options are used only if a layer >  0  is  specified,  otherwise,  those  options  are
       ignored.  Be aware that the default is layer=-1, meaning that all layers are processed, ignoring the cats
       and where options.

       If type=area is selected, boundaries of selected areas will be generalized, and the options cats,  where,
       and layer will be used to select areas.

NOTES

       (Line) simplification is a process of reducing the complexity of vector features. The module transforms a
       line into another line consisting of fewer vertices, that still approximate the original  line.  Most  of
       the algorithms described below select a subset of points on the original line.

       (Line)  smoothing  is a "reverse" process which takes as input a line and produces a smoother approximate
       of the original. In some cases, this is achieved by inserting new vertices into the  original  line,  and
       can total up to 4000% of the number of vertices in the original. In such an instance, it is always a good
       idea to simplify the line after smoothing.

       Smoothing  and  simplification  algorithms  implemented  in  this  module  work  line   by   line,   i.e.
       simplification/smoothing  of  one  line does not affect the other lines; they are treated separately. For
       isolated loops formed by a single line/boundary, he first and the last point of each line/boundary can be
       translated and/or deleted, unless the -l flag is used to disable loop support.

       Lines  and  boundaries  are  not  translated if they would collapse to a single point. Boundaries are not
       translated if they would intersect with themselves or  other  boundaries.  Such  erroneous  features  are
       written  to an optional error vector map. Overlaying the error map over the generalized map indicates the
       kind of error.  Lines/boundaries collapsing to a point are written out as  points,  boundaries  violating
       topology  are  written  out  as  boundaries.  The  error  map can be overlaid over the generalized map to
       understand why some features were not generalized.

   SIMPLIFICATION
       Simplification can fail for many boundaries if the simplification parameters  would  result  in  a  large
       reduction  of  vertices.  If many lines/boundaries could not be simplified, try different parameters that
       would cause a lower degree of simplification.

       v.generalize contains following line simplification algorithms:

           •   Douglas-Peucker Algorithm

           •   Douglas-Peucker Reduction Algorithm

           •   Lang Algorithm

           •   Vertex Reduction

           •   Reumann-Witkam Algorithm

           •   Remove Small Lines/Areas
       Different algorithms require different parameters, but all the algorithms have one parameter  in  common:
       the  threshold  parameter,  given  in map units (for latitude-longitude locations: in decimal degree). In
       general, the degree of simplification increases with the increasing value of threshold.

   ALGORITHM DESCRIPTIONSDouglas-Peucker - "Quicksort" of line simplification,  the  most  widely  used  algorithm.  Input
               parameters: input, threshold. For more information, see:
               http://geomalgorithms.com/a16-_decimate-1.html.

           •   Douglas-Peucker Reduction Algorithm is essentially the same algorithm as the algorithm above, the
               difference being that it takes an additional reduction parameter which denotes the percentage  of
               the  number  of points on the new line with respect to the number of points on the original line.
               Input parameters: input, threshold, reduction.

           •   Lang - Another standard algorithm.  Input  parameters:  input,  threshold,  look_ahead.   For  an
               excellent description, see:
               http://www.sli.unimelb.edu.au/gisweb/LGmodule/LGLangVisualisation.htm.

           •   Vertex  Reduction  -  Simplest among the algorithms. Input parameters: input, threshold.  Given a
               line, this algorithm removes the points of  this  line  which  are  closer  to  each  other  than
               threshold.  More  precisely, if p1 and p2 are two consecutive points, and the distance between p2
               and p1 is less than threshold, it removes p2 and  repeats  the  same  process  on  the  remaining
               points.

           •   Reumann-Witkam  -  Input parameters: input, threshold.  This algorithm quite reasonably preserves
               the global characteristics of the lines. For more information, see for example:
               http://psimpl.sourceforge.net/reumann-witkam.html.
       Douglas-Peucker and Douglas-Peucker Reduction Algorithm use the same method to simplify the  lines.  Note
       that
       v.generalize input=boundary_county output=boundary_county_dp20 method=douglas threshold=20
       is equivalent to
       v.generalize input=boundary_county output=boundary_county_dp_red20_100 \
                    method=douglas_reduction threshold=20 reduction=100
       However, in this case, the first method is faster. Also observe that douglas_reduction never outputs more
       vertices than douglas, and that, in general, douglas  is  more  efficient  than  douglas_reduction.  More
       importantly, the effect of
       v.generalize input=boundary_county output=boundary_county_dp_red0_30 \
                    method=douglas_reduction threshold=0 reduction=30
       is that ’out’ contains approximately only 30% of points of ’in’.

   SMOOTHING
       The following smoothing algorithms are implemented in v.generalize:

           •   Boyle’s  Forward-Looking  Algorithm  -  The position of each point depends on the position of the
               previous points and the point look_ahead ahead. look_ahead consecutive points. Input  parameters:
               input, look_ahead.

           •   McMaster’s  Sliding  Averaging  Algorithm  - Input Parameters: input, slide, look_ahead.  The new
               position of each point is the average of the look_ahead points around. Parameter  slide  is  used
               for linear interpolation between old and new position (see below).

           •   McMaster’s  Distance-Weighting  Algorithm  - Takes the weighted average of look_ahead consecutive
               points where the weight is the reciprocal of  the  distance  from  the  point  to  the  currently
               smoothed  point.  The  parameter  slide  is  used  for  linear interpolation between the original
               position of the point and newly computed position where value  0  means  the  original  position.
               Input parameters: input, slide, look_ahead.

           •   Chaiken’s  Algorithm - "Inscribes" a line touching the original line such that the points on this
               new line are at least  threshold  apart.  Input  parameters:  input,  threshold.  This  algorithm
               approximates the given line very well.

           •   Hermite  Interpolation  - This algorithm takes the points of the given line as the control points
               of hermite cubic spline and approximates this spline by the points approximately threshold apart.
               This  method  has excellent results for small values of threshold, but in this case it produces a
               huge number of new points and some simplification is usually needed.   Input  parameters:  input,
               threshold, angle_thresh.  Angle_thresh is used for reducing the number of the points.  It denotes
               the minimal angle (in degrees) between two consecutive segments of a line.

           •   Snakes is the method of minimisation of the "energy" of a line. This method preserves the general
               characteristics  of  the lines but smooths the "sharp corners" of a line. Input parameters input,
               alpha, beta.  This algorithm works very well for small values of alpha and beta  (between  0  and
               5). These parameters affect the "sharpness" and the curvature of the computed line.
       One  of  the  key  advantages  of  Hermite Interpolation is the fact that the computed line always passes
       through the points of the original line, whereas the lines produced by  the  remaining  algorithms  never
       pass  through  these points. In some sense, this algorithm outputs a line which "circumscribes" the input
       line.

       On the other hand, Chaiken’s Algorithm outputs a line which "inscribes" a given  line.  The  output  line
       always  touches/intersects  the centre of the input line segment between two consecutive points. For more
       iterations, the property above does not hold, but the computed lines  are  very  similar  to  the  Bezier
       Splines.  The  disadvantage of the two algorithms given above is that they increase the number of points.
       However, Hermite Interpolation can be used as another simplification algorithm. To achieve  this,  it  is
       necessary to set angle_thresh to higher values (15 or so).

       One  restriction  on  both McMasters’ Algorithms is that look_ahead parameter must be odd. Also note that
       these algorithms have no effect if look_ahead = 1.

       Note that Boyle’s, McMasters’ and Snakes algorithm are sometimes used in the signal processing to  smooth
       the  signals.   More  importantly,  these algorithms never change the number of points on the lines; they
       only translate the points, and do not insert any new points.

       Snakes Algorithm is (asymptotically) the slowest among the algorithms presented above. Also, it  requires
       quite  a  lot  of memory.  This means that it is not very efficient for maps with the lines consisting of
       many segments.

   DISPLACEMENT
       The displacement is used when the lines overlap and/or are close to each other at the  current  level  of
       detail. In general, displacement methods move the conflicting features apart so that they do not interact
       and can be distinguished.

       This module implements an algorithm for displacement of linear features based  on  the  Snakes  approach.
       This  method  generally  yields  very  good results; however, it requires a lot of memory and is not very
       efficient.

       Displacement is selected by method=displacement. It uses the following parameters:

           •   threshold - specifies critical distance. Two features interact if they are closer than  threshold
               apart.

           •   alpha,  beta  -  These parameters define the rigidity of lines.  For larger values of alpha, beta
               (>=1), the algorithm does a better job at retaining the original shape of the lines, possibly  at
               the  expense of displacement distance. If the values of alpha, beta are too small (<=0.001), then
               the lines are moved sufficiently, but the geometry and topology of lines can be destroyed.   Most
               likely the best way to find the good values of alpha, beta is by trial and error.

           •   iterations  -  denotes  the number of iterations the interactions between the lines are resolved.
               Good starting points for values of iterations are between 10 and 100.
       The lines affected by the algorithm can be specified by the layer, cats and where parameters.

   NETWORK GENERALIZATION
       Used for selecting "the most important" part of the network. This  is  based  on  the  graph  algorithms.
       Network  generalization is applied if method=network.  The algorithm calculates three centrality measures
       for each line in the network and only the lines with the values greater  than  thresholds  are  selected.
       The behaviour of algorithm can be altered by the following parameters:

           •   degree_thresh  - algorithm selects only the lines which share a point with at least degree_thresh
               different lines.

           •   closeness_thresh - is always in the range (0, 1]. Only the lines with  the  closeness  centrality
               value  at  least  closeness_thresh  apart are selected. The lines in the centre of a network have
               greater values of this measure than the lines near the border of a network. This means that  this
               parameter  can  be used for selecting the centre(s) of a network. Note that if closeness_thresh=0
               then everything is selected.

           •   betweeness_thresh - Again,  only  the  lines  with  a  betweeness  centrality  measure  at  least
               betweeness_thresh  are  selected. This value is always positive and is larger for large networks.
               It denotes to what extent a line is in between the other lines in  the  network.  This  value  is
               large  for  the  lines  which lie between other lines and lie on the paths between two parts of a
               network. In the terminology of road networks, these are highways, bypasses,  main  roads/streets,
               etc.
       All  three  parameters  above can be presented at the same time. In that case, the algorithm selects only
       the lines which meet each criterion.

       Also, the outputed network may not be connected if the value of betweeness_thresh is too large.

EXAMPLES

   SIMPLIFICATION EXAMPLE
       Simplification of county boundaries with DP method (North Carolina sample dataset),  threshold  given  in
       mapset units (here: meters):
       v.generalize input=boundary_county output=boundary_county_dp20 \
         method=douglas threshold=20 error=boundary_county_dp20_leftover
       Figure:  Vector  simplification example (spatial subset: original map shown in black, simplified map with
       26% remaining vertices shown in red)

   SMOOTHING EXAMPLE
       Smoothing of road network with Chaiken method (North Carolina sample dataset), threshold given in  mapset
       units (here: meters):
       v.generalize input=roads output=roads_chaiken method=chaiken \
         threshold=1 error=roads_chaiken_leftover
       Figure:  Vector  smoothing  example  (spatial subset: original map shown in black, smoothed map with 500%
       increased number of vertices shown in red)

SEE ALSO

        v.clean, v.dissolve

       v.generalize Tutorial (GRASS-Wiki)

AUTHORS

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

SOURCE CODE

       Available at: v.generalize source code (history)

       Main index | Vector index | Topics index | Keywords index | Graphical index | Full index

       © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual