## NAME

v.overlay - Overlays two vector maps.

## KEYWORDS

vector, geometry

## SYNOPSIS

v.overlay
v.overlay help
v.overlay [-t] ainput=name [atype=string[,string,...]] [alayer=integer] binput=name [btype=string[,string,...]] [blayer=integer] output=name [operator=string] [olayer=integer[,integer,...]] [snap=float] [--overwrite] [--verbose] [--quiet]

### Flags:

-t
  Do not create attribute table
--overwrite
  Allow output files to overwrite existing files
--verbose
  Verbose module output
--quiet
  Quiet module output

### Parameters:

ainput=name
  Name of input vector map (A)
  Name of input vector map
atype=string[,string,...]
  Feature type (vector map A)
  Feature type
  Options: line,area
  Default: area
alayer=integer
  Layer number (vector map A)
  A single vector map can be connected to multiple database tables. This number determines which table to use.
  Default: 1
binput=name
  Name of input vector map (B)
  Name of input vector map
btype=string[,string,...]
  Feature type (vector map B)
  Feature type
  Options: area
  Default: area
blayer=integer
  Layer number (vector map B)
  A single vector map can be connected to multiple database tables. This number determines which table to use.
  Default: 1
output=name
  Name for output vector map
operator=string
  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
  Default: or
  and: also known as 'intersection' in GIS
  or: also known as 'union' in GIS (only for atype=area)
  not: features from ainput not overlayed by features from binput
  xor: features from either ainput or binput but not those from ainput overlayed by binput (only for atype=area)
olayer=integer[,integer,...]
  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

## DESCRIPTION

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.

If the first number of the olayer option is > 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 > 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 > 0, then the categories of binput in layer blayer are transferred to the output layer with the third number.

## NOTES

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 > 0, then attributes of the tables from ainput and binput are joined into a new table linked to the output map with a new cat column.

If the second number of the olayer option is > 0, then the attribute table of ainput is copied to the output map.

If the third number of the olayer option is > 0, then the attribute table of binput is copied to the output map.

## EXAMPLES

#### Polygons overlaid with ploygons

    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

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.

#### Lines overlaid with polygons

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 vect=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

v.overlay: Line to polygon clipping

## SEE ALSO

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

## AUTHORS

Radim Blazek, ITC-Irst, Trento, Italy
Markus Metz

Last changed: $Date: 2014-03-16 17:58:53 +0100 (ne, 16 III 2014) $

Main index - vector index - Full index

© 2003-2014 GRASS Development Team