geopandas.GeoDataFrame.overlay

GeoDataFrame.overlay(right, how='intersection', keep_geom_type=None, make_valid=True)

Perform spatial overlay between GeoDataFrames.

Currently only supports data GeoDataFrames with uniform geometry types, i.e. containing only (Multi)Polygons, or only (Multi)Points, or a combination of (Multi)LineString and LinearRing shapes. Implements several methods that are all effectively subsets of the union.

See the User Guide page Set-Operations with Overlay for details.

Parameters
rightGeoDataFrame
howstring

Method of spatial overlay: ‘intersection’, ‘union’, ‘identity’, ‘symmetric_difference’ or ‘difference’.

keep_geom_typebool

If True, return only geometries of the same geometry type the GeoDataFrame has, if False, return all resulting geometries. Default is None, which will set keep_geom_type to True but warn upon dropping geometries.

make_validbool, default True

If True, any invalid input geometries are corrected with a call to buffer(0), if False, a ValueError is raised if any input geometries are invalid.

Returns
dfGeoDataFrame

GeoDataFrame with new set of polygons and attributes resulting from the overlay

See also

GeoDataFrame.sjoin

spatial join

overlay

equivalent top-level function

Notes

Every operation in GeoPandas is planar, i.e. the potential third dimension is not taken into account.

Examples

>>> from shapely.geometry import Polygon
>>> polys1 = geopandas.GeoSeries([Polygon([(0,0), (2,0), (2,2), (0,2)]),
...                               Polygon([(2,2), (4,2), (4,4), (2,4)])])
>>> polys2 = geopandas.GeoSeries([Polygon([(1,1), (3,1), (3,3), (1,3)]),
...                               Polygon([(3,3), (5,3), (5,5), (3,5)])])
>>> df1 = geopandas.GeoDataFrame({'geometry': polys1, 'df1_data':[1,2]})
>>> df2 = geopandas.GeoDataFrame({'geometry': polys2, 'df2_data':[1,2]})
>>> df1.overlay(df2, how='union')
df1_data  df2_data                                           geometry
0       1.0       1.0  POLYGON ((2.00000 2.00000, 2.00000 1.00000, 1....
1       2.0       1.0  POLYGON ((2.00000 2.00000, 2.00000 3.00000, 3....
2       2.0       2.0  POLYGON ((4.00000 4.00000, 4.00000 3.00000, 3....
3       1.0       NaN  POLYGON ((2.00000 0.00000, 0.00000 0.00000, 0....
4       2.0       NaN  MULTIPOLYGON (((3.00000 3.00000, 4.00000 3.000...
5       NaN       1.0  MULTIPOLYGON (((2.00000 2.00000, 3.00000 2.000...
6       NaN       2.0  POLYGON ((3.00000 5.00000, 5.00000 5.00000, 5....
>>> df1.overlay(df2, how='intersection')
df1_data  df2_data                                           geometry
0         1         1  POLYGON ((2.00000 2.00000, 2.00000 1.00000, 1....
1         2         1  POLYGON ((2.00000 2.00000, 2.00000 3.00000, 3....
2         2         2  POLYGON ((4.00000 4.00000, 4.00000 3.00000, 3....
>>> df1.overlay(df2, how='symmetric_difference')
df1_data  df2_data                                           geometry
0       1.0       NaN  POLYGON ((2.00000 0.00000, 0.00000 0.00000, 0....
1       2.0       NaN  MULTIPOLYGON (((3.00000 3.00000, 4.00000 3.000...
2       NaN       1.0  MULTIPOLYGON (((2.00000 2.00000, 3.00000 2.000...
3       NaN       2.0  POLYGON ((3.00000 5.00000, 5.00000 5.00000, 5....
>>> df1.overlay(df2, how='difference')
                                        geometry  df1_data
0  POLYGON ((2.00000 0.00000, 0.00000 0.00000, 0....         1
1  MULTIPOLYGON (((3.00000 3.00000, 4.00000 3.000...         2
>>> df1.overlay(df2, how='identity')
df1_data  df2_data                                           geometry
0       1.0       1.0  POLYGON ((2.00000 2.00000, 2.00000 1.00000, 1....
1       2.0       1.0  POLYGON ((2.00000 2.00000, 2.00000 3.00000, 3....
2       2.0       2.0  POLYGON ((4.00000 4.00000, 4.00000 3.00000, 3....
3       1.0       NaN  POLYGON ((2.00000 0.00000, 0.00000 0.00000, 0....
4       2.0       NaN  MULTIPOLYGON (((3.00000 3.00000, 4.00000 3.000...